> ## Documentation Index
> Fetch the complete documentation index at: https://docs.recallrai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Google Gemini Integration

> Add persistent memory to your Google Gemini applications using Recallr's forward proxy

<Info>
  Recallr seamlessly integrates with Google Gemini by acting as a forward proxy. Configure your Gemini client to use our proxy URL and we'll inject relevant context from user memory into each request.
</Info>

## Quick Start

```python theme={null}
from google import genai
from google.genai import types

client = genai.Client(
    api_key='YOUR_GEMINI_API_KEY',  # Your Google Gemini API key
    http_options={
        'api_version': 'v1beta',
        'base_url': 'https://api.recallrai.com/api/v1/forward/https://generativelanguage.googleapis.com',
        'headers': {
            'X-Recallr-API-Key': 'rai-...',
            'X-Recallr-Project-Id': 'your-project-id',
            'X-Recallr-User-Id': 'user-123',
            'X-Recallr-Allow-New-User-Creation': 'true',
            'X-Recallr-Session-Timeout-Seconds': '600',
            'X-Recallr-Recall-Strategy': 'low_latency',  # Optional
        }
    }
)

# Use normally - memory is automatically injected
response = client.models.generate_content(
    model='gemini-2.5-pro',
    contents='My name is Alice',
    config=types.GenerateContentConfig(
        system_instruction='You are a helpful assistant.',
    )
)

print(response.text)
```

## Supported APIs

<CardGroup cols={2}>
  <Card title="Generate Content" icon="sparkles" href="#generate-content-non-streaming">
    Standard text generation with non-streaming support
  </Card>

  <Card title="Generate Content Stream" icon="wave-pulse" href="#generate-content-streaming">
    Real-time streaming responses for interactive experiences
  </Card>
</CardGroup>

## Required Headers

These headers must be included via the `http_options` configuration:

<ParamField header="X-Recallr-API-Key" type="string" required>
  Your Recallr API key. Get it from the [dashboard](https://app.recallrai.com).
</ParamField>

<ParamField header="X-Recallr-Project-Id" type="string" required>
  Your Recallr Project ID. Get it from the [dashboard](https://app.recallrai.com).
</ParamField>

<ParamField header="X-Recallr-User-Id" type="string" required>
  Unique identifier for the user. Used to maintain separate memory graphs per user.

  <Note>
    Must be passed in the headers configuration when initializing the Gemini client.
  </Note>
</ParamField>

## Optional Headers

### Session Management

<ParamField header="X-Recallr-Allow-New-User-Creation" type="boolean" default="false">
  Automatically create a new user if the specified User-ID doesn't exist. Set to `true` to avoid errors for new users.
</ParamField>

<ParamField header="X-Recallr-Session-Timeout-Seconds" type="integer" default="600">
  Inactivity period (in seconds) before creating a new session. Minimum value is 600 (10 minutes).

  <Info>
    Messages within a session are always passed directly to the LLM. Only memories from previous sessions are retrieved and injected as context.
  </Info>
</ParamField>

### Recall Configuration

<ParamField header="X-Recallr-Recall-Strategy" type="string" default="balanced">
  Controls the recall method used for retrieving memories. Affects latency and accuracy.

  <Tabs>
    <Tab title="low_latency">
      **Best for:** Voice agents and real-time applications

      * Fastest response time
      * Retrieves more memories to compensate for reduced accuracy
      * Use when sub-second latency is critical
    </Tab>

    <Tab title="balanced">
      **Best for:** Standard chatbots and applications

      * Good balance between speed and accuracy
      * Default strategy for most use cases
      * Recommended for general applications
    </Tab>

    <Tab title="Agentic">
      **Best for:** Complex queries requiring comprehensive context

      * Runs agents to browse the knowledge graph
      * Most accurate but slowest
      * Use for questions like "What do you know about my preferences?"
    </Tab>
  </Tabs>
</ParamField>

<ParamField header="X-Recallr-Min-Top-K" type="integer" default="10">
  Minimum number of memories to retrieve from the knowledge graph.
</ParamField>

<ParamField header="X-Recallr-Max-Top-K" type="integer" default="50">
  Maximum number of memories to retrieve from the knowledge graph.
</ParamField>

<ParamField header="X-Recallr-Memories-Threshold" type="float" default="0.7">
  Similarity threshold for retrieving individual memories (0.0 to 1.0). Lower values retrieve more memories.
</ParamField>

<ParamField header="X-Recallr-Summaries-Threshold" type="float" default="0.6">
  Similarity threshold for retrieving session summaries (0.0 to 1.0). Lower values retrieve more summaries.
</ParamField>

<ParamField header="X-Recallr-Last-N-User-Messages" type="integer">
  Include last N messages from past sessions when building context.
</ParamField>

<ParamField header="X-Recallr-Last-N-Summaries" type="integer">
  Include last N session summaries when building context.
</ParamField>

<ParamField header="X-Recallr-Timezone" type="string" default="UTC">
  User's timezone for formatting timestamps in memory context (e.g., "America/New\_York", "Europe/London"). Defaults to UTC if not specified.

  <Tip>
    Providing the user's timezone improves temporal context by showing memories with locally-formatted timestamps.
  </Tip>
</ParamField>

<ParamField header="X-Recallr-Include-System-Prompt" type="boolean" default="true">
  Whether to include Recallr AI's system prompt (\~ 3k tokens) in the context. This prompt includes instructions for how to use the injected memories. Set to `false` if you already have those instructions in your system prompt.
</ParamField>

## Response Headers

Recallr returns these headers in the response for debugging and session tracking:

<ResponseField name="X-Recallr-Session-Id" type="string">
  The internal session ID used by Recallr. Use this to continue the same session in future requests.
</ResponseField>

<ResponseField name="X-Recallr-User-Id" type="string">
  Unique identifier for the user. Matches the `X-Recallr-User-Id` sent in the request.
</ResponseField>

<ResponseField name="X-Recallr-Request-Id" type="string">
  Unique identifier for this request. Use for debugging and tracing.
</ResponseField>

<ResponseField name="X-Recallr-Process-Time" type="string">
  Time taken to process the request on Recallr's side (in milliseconds).
</ResponseField>

## Examples

### Generate Content - Non-Streaming

<CodeGroup>
  ```python Python theme={null}
  from google import genai
  from google.genai import types

  client = genai.Client(
      api_key='YOUR_GEMINI_API_KEY',  # Your Google Gemini API key
      http_options={
          'api_version': 'v1beta',
          'base_url': 'https://api.recallrai.com/api/v1/forward/https://generativelanguage.googleapis.com',
          'headers': {
              'X-Recallr-API-Key': 'rai-...',
              'X-Recallr-Project-Id': 'project-id',
              'X-Recallr-User-Id': 'alice-123',
              'X-Recallr-Allow-New-User-Creation': 'true',
              'X-Recallr-Session-Timeout-Seconds': '600',
              'X-Recallr-Recall-Strategy': 'low_latency',  # Optional
          }
      }
  )

  # Store user information in memory
  response = client.models.generate_content(
      model='gemini-2.5-pro',
      contents='My name is Alice and I love Python programming.',
      config=types.GenerateContentConfig(
          system_instruction='You are a helpful assistant.',
      )
  )

  print(response.text)
  ```

  ```javascript Node.js theme={null}
  import { GoogleGenAI } from '@google/genai';

  // Create custom fetch to proxy through RecallrAI
  const createRecallrFetch = (recallrConfig) => {
    return async (url, options = {}) => {
      const proxiedUrl = url.replace(
        'https://generativelanguage.googleapis.com',
        'https://api.recallrai.com/api/v1/forward/https://generativelanguage.googleapis.com'
      );
      
      const headers = {
        ...options.headers,
        'X-Recallr-API-Key': recallrConfig.apiKey,
        'X-Recallr-Project-Id': recallrConfig.projectId,
        'X-Recallr-User-Id': recallrConfig.userId,
        'X-Recallr-Allow-New-User-Creation': recallrConfig.allowNewUserCreation || 'true',
        'X-Recallr-Session-Timeout-Seconds': recallrConfig.sessionTimeout || '600',
      };
      
      if (recallrConfig.recallStrategy) {
        headers['X-Recallr-Recall-Strategy'] = recallrConfig.recallStrategy;
      }
      
      return fetch(proxiedUrl, { ...options, headers });
    };
  };

  // Initialize with RecallrAI proxy
  const customFetch = createRecallrFetch({
    apiKey: 'rai-...',
    projectId: 'project-id',
    userId: 'alice-123',
    recallStrategy: 'low_latency',  // Optional
  });

  const ai = new GoogleGenAI({
    apiKey: 'YOUR_GEMINI_API_KEY',  // Your Google Gemini API key
    fetch: customFetch,
  });

  // Store user information in memory
  const response = await ai.models.generateContent({
    model: 'gemini-2.5-pro',
    contents: 'My name is Alice and I love Python programming.',
    config: {
      systemInstruction: 'You are a helpful assistant.',
    }
  });

  console.log(response.text);
  ```
</CodeGroup>

### Generate Content - Streaming

<CodeGroup>
  ```python Python theme={null}
  from google import genai
  from google.genai import types

  client = genai.Client(
      api_key='YOUR_GEMINI_API_KEY',  # Your Google Gemini API key
      http_options={
          'api_version': 'v1beta',
          'base_url': 'https://api.recallrai.com/api/v1/forward/https://generativelanguage.googleapis.com',
          'headers': {
              'X-Recallr-API-Key': 'rai-...',
              'X-Recallr-Project-Id': 'project-id',
              'X-Recallr-User-Id': 'alice-123',
              'X-Recallr-Allow-New-User-Creation': 'true',
              'X-Recallr-Session-Timeout-Seconds': '600',
              'X-Recallr-Recall-Strategy': 'low_latency',  # Optional
          }
      }
  )

  # Recall stored information about the user with streaming
  response = client.models.generate_content_stream(
      model='gemini-2.5-pro',
      contents='What do you know about me and my interests?',
      config=types.GenerateContentConfig(
          system_instruction='You are a helpful assistant.',
      )
  )

  for chunk in response:
      if chunk.text:
          print(chunk.text, end='', flush=True)
  ```

  ```javascript Node.js theme={null}
  import { GoogleGenAI } from '@google/genai';

  // Create custom fetch to proxy through RecallrAI
  const createRecallrFetch = (recallrConfig) => {
    return async (url, options = {}) => {
      const proxiedUrl = url.replace(
        'https://generativelanguage.googleapis.com',
        'https://api.recallrai.com/api/v1/forward/https://generativelanguage.googleapis.com'
      );
      
      const headers = {
        ...options.headers,
        'X-Recallr-API-Key': recallrConfig.apiKey,
        'X-Recallr-Project-Id': recallrConfig.projectId,
        'X-Recallr-User-Id': recallrConfig.userId,
        'X-Recallr-Allow-New-User-Creation': recallrConfig.allowNewUserCreation || 'true',
        'X-Recallr-Session-Timeout-Seconds': recallrConfig.sessionTimeout || '600',
      };
      
      if (recallrConfig.recallStrategy) {
        headers['X-Recallr-Recall-Strategy'] = recallrConfig.recallStrategy;
      }
      
      return fetch(proxiedUrl, { ...options, headers });
    };
  };

  // Initialize with RecallrAI proxy
  const customFetch = createRecallrFetch({
    apiKey: 'rai-...',
    projectId: 'project-id',
    userId: 'alice-123',
    recallStrategy: 'low_latency',  // Optional
  });

  const ai = new GoogleGenAI({
    apiKey: 'YOUR_GEMINI_API_KEY',  // Your Google Gemini API key
    fetch: customFetch,
  });

  // Recall stored information about the user with streaming
  const response = await ai.models.generateContentStream({
    model: 'gemini-2.5-pro',
    contents: 'What do you know about me and my interests?',
    config: {
      systemInstruction: 'You are a helpful assistant.',
    }
  });

  for await (const chunk of response) {
    if (chunk.text) {
      process.stdout.write(chunk.text);
    }
  }
  ```
</CodeGroup>

## How It Works

```mermaid theme={null}
sequenceDiagram
    participant Client
    participant Recallr
    participant Gemini
    
    Client->>Recallr: Request with X-Recallr headers
    Recallr->>Recallr: Validate API Key + Project ID
    Recallr->>Recallr: Resolve User ID (create if allowed)
    Recallr->>Recallr: Retrieve relevant memories from knowledge graph
    Recallr->>Recallr: Inject context into request
    Recallr->>Gemini: Forward enhanced request
    Gemini->>Recallr: Response stream
    Recallr->>Recallr: Store conversation in knowledge graph
    Recallr->>Client: Return response with Recallr headers
```

<Card title="Need Help?" icon="question" href="mailto:devasheesh@recallrai.com">
  Contact our support team for assistance with Gemini integration
</Card>