> ## 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.

# OpenAI Integration

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

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

## Quick Start

```python theme={null}
from openai import OpenAI

client = OpenAI(
    base_url='https://api.recallrai.com/api/v1/forward/https://api.openai.com/v1',
    api_key='sk-...',  # Your OpenAI API key
    default_headers={
        'X-Recallr-API-Key': 'rai-...',
        'X-Recallr-Project-Id': 'your-project-id',
        'X-Recallr-Allow-New-User-Creation': 'true',
        'X-Recallr-Session-Timeout-Seconds': '600',
    }
)

# Use normally - memory is automatically injected
response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "My name is Alice"}],
    extra_headers={
        'X-Recallr-User-Id': 'user-123',
        'X-Recallr-Recall-Strategy': 'low_latency',  # Optional
    }
)

print(response.choices[0].message.content)
```

## Supported APIs

<CardGroup cols={2}>
  <Card title="Chat Completions" icon="messages" href="#chat-completions-non-streaming">
    Standard conversational API with streaming and non-streaming support
  </Card>

  <Card title="Responses API" icon="robot" href="#responses-api-non-streaming">
    OpenAI's new Responses API with streaming and non-streaming support
  </Card>
</CardGroup>

## Required Headers

These headers must be included with every request:

<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>
    Can also be passed as `user` field in the request body for OpenAI compatibility.
  </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

### Chat Completions - Non-Streaming

<CodeGroup>
  ```python Python theme={null}
  from openai import OpenAI

  client = OpenAI(
      base_url='https://api.recallrai.com/api/v1/forward/https://api.openai.com/v1',
      api_key='sk-...',
      default_headers={
          'X-Recallr-API-Key': 'rai-...',
          'X-Recallr-Project-Id': 'project-id',
          'X-Recallr-Allow-New-User-Creation': 'true',
          'X-Recallr-Session-Timeout-Seconds': '600',
      }
  )

  # Get raw response with headers
  raw_response = client.chat.completions.with_raw_response.create(
      model="gpt-4o-mini",
      messages=[
          {"role": "system", "content": "You are a helpful assistant."},
          {"role": "user", "content": "My name is Alice and I love Python programming."}
      ],
      extra_headers={
          'X-Recallr-User-Id': 'alice-123',
          'X-Recallr-Recall-Strategy': 'low_latency', # Optional
      }
  )

  # Access headers
  session_id = raw_response.headers.get('X-Recallr-Session-Id')
  request_id = raw_response.headers.get('X-Recallr-Request-Id')

  # Parse response
  response = raw_response.parse()
  print(response.choices[0].message.content)
  ```

  ```javascript Node.js theme={null}
  import OpenAI from 'openai';

  const client = new OpenAI({
    baseURL: 'https://api.recallrai.com/api/v1/forward/https://api.openai.com/v1',
    apiKey: 'sk-...',
    defaultHeaders: {
      'X-Recallr-API-Key': 'rai-...',
      'X-Recallr-Project-Id': 'project-id',
      'X-Recallr-Allow-New-User-Creation': 'true',
      'X-Recallr-Session-Timeout-Seconds': '600', // Optional
    },
  });

  const response = await client.chat.completions.create({
    model: 'gpt-4o-mini',
    messages: [
      { role: 'system', content: 'You are a helpful assistant.' },
      { role: 'user', content: 'My name is Alice and I love Python programming.' }
    ],
  }, {
    headers: { 
      'X-Recallr-User-Id': 'alice-123',
      'X-Recallr-Recall-Strategy': 'low_latency', // Optional
    }
  });

  console.log(response.choices[0].message.content);
  ```
</CodeGroup>

### Chat Completions - Streaming

<CodeGroup>
  ```python Python theme={null}
  from openai import OpenAI

  client = OpenAI(
      base_url='https://api.recallrai.com/api/v1/forward/https://api.openai.com/v1',
      api_key='sk-...',
      default_headers={
          'X-Recallr-API-Key': 'rai-...',
          'X-Recallr-Project-Id': 'project-id',
          'X-Recallr-Allow-New-User-Creation': 'true',
          'X-Recallr-Session-Timeout-Seconds': '600', # Optional
      }
  )

  response = client.chat.completions.create(
      model="gpt-4o-mini",
      messages=[
          {"role": "user", "content": "What do you know about me and my interests?"}
      ],
      stream=True,
      extra_headers={
          'X-Recallr-User-Id': 'alice-123',
          'X-Recallr-Recall-Strategy': 'low_latency',
      }
  )

  for chunk in response:
      if chunk.choices[0].delta.content:
          print(chunk.choices[0].delta.content, end='', flush=True)
  ```

  ```javascript Node.js theme={null}
  import OpenAI from 'openai';

  const client = new OpenAI({
    baseURL: 'https://api.recallrai.com/api/v1/forward/https://api.openai.com/v1',
    apiKey: 'sk-...',
    defaultHeaders: {
      'X-Recallr-API-Key': 'rai-...',
      'X-Recallr-Project-Id': 'project-id',
      'X-Recallr-Allow-New-User-Creation': 'true',
      'X-Recallr-Session-Timeout-Seconds': '600', // Optional
    },
  });

  const stream = await client.chat.completions.create({
    model: 'gpt-4o-mini',
    messages: [
      { role: 'user', content: 'What do you know about me and my interests?' }
    ],
    stream: true,
  }, {
    headers: {
      'X-Recallr-User-Id': 'alice-123',
      'X-Recallr-Recall-Strategy': 'low_latency', // Optional
    }
  });

  for await (const chunk of stream) {
    const content = chunk.choices[0]?.delta?.content;
    if (content) process.stdout.write(content);
  }
  ```
</CodeGroup>

### Responses API - Non-Streaming

<CodeGroup>
  ```python Python theme={null}
  from openai import OpenAI

  client = OpenAI(
      base_url='https://api.recallrai.com/api/v1/forward/https://api.openai.com/v1',
      api_key='sk-...',
      default_headers={
          'X-Recallr-API-Key': 'rai-...',
          'X-Recallr-Project-Id': 'project-id',
          'X-Recallr-Allow-New-User-Creation': 'true',
          'X-Recallr-Session-Timeout-Seconds': '600', # Optional
      }
  )

  response = client.responses.create(
      model="gpt-4o-mini",
      input="I'm allergic to peanuts and love Italian food",
      max_output_tokens=150,
      extra_headers={
          'X-Recallr-User-Id': 'alice-123',
          'X-Recallr-Recall-Strategy': 'low_latency',
      }
  )

  print(response.output[0].content[0].text)
  ```

  ```javascript Node.js theme={null}
  import OpenAI from 'openai';

  const client = new OpenAI({
    baseURL: 'https://api.recallrai.com/api/v1/forward/https://api.openai.com/v1',
    apiKey: 'sk-...',
    defaultHeaders: {
      'X-Recallr-API-Key': 'rai-...',
      'X-Recallr-Project-Id': 'project-id',
      'X-Recallr-Allow-New-User-Creation': 'true',
      'X-Recallr-Session-Timeout-Seconds': '600', // Optional
    },
  });

  const response = await client.responses.create({
    model: 'gpt-4o-mini',
    input: "I'm allergic to peanuts and love Italian food",
    max_output_tokens: 150,
  }, {
    headers: {
      'X-Recallr-User-Id': 'alice-123',
      'X-Recallr-Recall-Strategy': 'low_latency', // Optional
    }
  });

  console.log(response.output[0].content[0].text);
  ```
</CodeGroup>

### Responses API - Streaming

<CodeGroup>
  ```python Python theme={null}
  from openai import OpenAI

  client = OpenAI(
      base_url='https://api.recallrai.com/api/v1/forward/https://api.openai.com/v1',
      api_key='sk-...',
      default_headers={
          'X-Recallr-API-Key': 'rai-...',
          'X-Recallr-Project-Id': 'project-id',
          'X-Recallr-Allow-New-User-Creation': 'true',
          'X-Recallr-Session-Timeout-Seconds': '600', # Optional
      }
  )

  response = client.responses.create(
      model="gpt-4o-mini",
      input="What are my food preferences?",
      stream=True,
      extra_headers={
          'X-Recallr-User-Id': 'alice-123',
          'X-Recallr-Recall-Strategy': 'low_latency',
      }
  )

  for event in response:
      if event.type == 'response.output_text.delta':
          print(event.delta, end='', flush=True)
  ```

  ```javascript Node.js theme={null}
  import OpenAI from 'openai';

  const client = new OpenAI({
    baseURL: 'https://api.recallrai.com/api/v1/forward/https://api.openai.com/v1',
    apiKey: 'sk-...',
    defaultHeaders: {
      'X-Recallr-API-Key': 'rai-...',
      'X-Recallr-Project-Id': 'project-id',
      'X-Recallr-Allow-New-User-Creation': 'true',
      'X-Recallr-Session-Timeout-Seconds': '600', // Optional
    },
  });

  const stream = await client.responses.create({
    model: 'gpt-4o-mini',
    input: 'What are my food preferences?',
    stream: true,
  }, {
    headers: {
      'X-Recallr-User-Id': 'alice-123',
      'X-Recallr-Recall-Strategy': 'low_latency', // Optional
    }
  });

  for await (const event of stream) {
    if (event.type === 'response.output_text.delta') {
      process.stdout.write(event.delta);
    }
  }
  ```
</CodeGroup>

## How It Works

```mermaid theme={null}
sequenceDiagram
    participant Client
    participant Recallr
    participant OpenAI
    
    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->>OpenAI: Forward enhanced request
    OpenAI->>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 OpenAI integration
</Card>