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

# OpenAI

> Drop-in wrapper for the OpenAI client that automatically injects memories into every chat completion and captures conversation turns.

The `ThrindexOpenAI` wrapper replaces your `OpenAI` instance. Every `chat.completions.create` call automatically retrieves relevant memories and injects them into the system prompt before the call, then captures the conversation turn as a new memory after it.

Memory retrieval failures are always silent — if Thrindex is unreachable, the underlying OpenAI call proceeds unaffected.

***

## Install

<Tabs>
  <Tab title="Python">
    ```bash theme={null}
    pip install 'thrindex[openai]'
    ```
  </Tab>

  <Tab title="TypeScript">
    ```bash theme={null}
    npm install thrindex openai
    ```
  </Tab>
</Tabs>

***

## Usage

<Tabs>
  <Tab title="Python">
    ### Synchronous

    ```python theme={null}
    from openai import OpenAI
    from thrindex import Thrindex
    from thrindex.integrations.openai import ThrindexOpenAI

    thrindex = Thrindex(api_key="th_live_...")
    openai = OpenAI()

    client = ThrindexOpenAI(
        thrindex_client=thrindex,
        openai_client=openai,
        agent_id="support-agent",
        user_id="user-42",
    )

    # Use exactly like openai.chat.completions.create — memory is automatic
    response = client.chat.completions.create(
        model="gpt-4o",
        messages=[{"role": "user", "content": "What notification style do I prefer?"}],
    )
    ```

    ### Asynchronous

    ```python theme={null}
    from openai import AsyncOpenAI
    from thrindex import AsyncThrindex
    from thrindex.integrations.openai import ThrindexAsyncOpenAI

    client = ThrindexAsyncOpenAI(
        thrindex_client=AsyncThrindex(api_key="th_live_..."),
        openai_client=AsyncOpenAI(),
        agent_id="support-agent",
        user_id="user-42",
    )

    response = await client.chat.completions.create(
        model="gpt-4o",
        messages=[{"role": "user", "content": "What notification style do I prefer?"}],
    )
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    import OpenAI from 'openai';
    import { ThrindexClient } from 'thrindex';
    import { ThrindexOpenAI } from 'thrindex/integrations/openai';

    const client = new ThrindexOpenAI({
      thrindex: new ThrindexClient({ apiKey: 'th_live_...' }),
      openai: new OpenAI(),
      agentId: 'support-agent',
      userId: 'user-42',
    });

    // Drop-in for openai.chat.completions.create
    const response = await client.chat.completions.create({
      model: 'gpt-4o',
      messages: [{ role: 'user', content: 'What notification style do I prefer?' }],
    });
    ```
  </Tab>
</Tabs>

***

## Options

<Tabs>
  <Tab title="Python">
    | Parameter           | Type                        | Default                        | Description                                                                                                                                                        |
    | ------------------- | --------------------------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
    | `thrindex_client`   | `Thrindex \| AsyncThrindex` | required                       | A configured Thrindex client instance                                                                                                                              |
    | `openai_client`     | `OpenAI \| AsyncOpenAI`     | `None` (auto-creates from env) | Your OpenAI client instance                                                                                                                                        |
    | `agent_id`          | `str`                       | required                       | Agent identifier for memory scoping                                                                                                                                |
    | `user_id`           | `str`                       | required                       | User identifier for memory scoping                                                                                                                                 |
    | `inject_k`          | `int`                       | `5`                            | Number of memories to retrieve and inject per call                                                                                                                 |
    | `inject`            | `bool`                      | `True`                         | Whether to inject memories before the call                                                                                                                         |
    | `capture`           | `bool`                      | `True`                         | Whether to store conversation turns after the call                                                                                                                 |
    | `capture_assistant` | `bool`                      | `True`                         | When `True`, captures both the user message and the assistant reply as a single turn (richer extraction context). Set to `False` to capture only the user message. |
    | `format_memories`   | `Callable`                  | bullet list                    | Custom formatter taking a `list[SearchHit]` and returning a `str`.                                                                                                 |
  </Tab>

  <Tab title="TypeScript">
    | Option             | Type                            | Default     | Description                                                    |
    | ------------------ | ------------------------------- | ----------- | -------------------------------------------------------------- |
    | `thrindex`         | `ThrindexClient`                | required    | A configured ThrindexClient                                    |
    | `openai`           | `OpenAI`                        | required    | Your OpenAI client instance                                    |
    | `agentId`          | `string`                        | required    | Agent identifier for memory scoping                            |
    | `userId`           | `string`                        | required    | User identifier for memory scoping                             |
    | `injectK`          | `number`                        | `5`         | Number of memories to retrieve and inject per call             |
    | `inject`           | `boolean`                       | `true`      | Whether to inject memories before the call                     |
    | `capture`          | `boolean`                       | `true`      | Whether to store conversation turns after the call             |
    | `captureAssistant` | `boolean`                       | `true`      | Capture both user message and assistant reply as a single turn |
    | `formatMemories`   | `(hits: SearchHit[]) => string` | bullet list | Custom memory formatter                                        |
  </Tab>
</Tabs>

***

## Custom memory format

You can fully control how memories are formatted in the system prompt. This is useful when you want XML tags, numbered lists, or any format your model responds to best.

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    def xml_formatter(hits):
        lines = ["<memory_context>"]
        for hit in hits:
            lines.append(f"  <memory importance='{hit.importance:.2f}'>{hit.content}</memory>")
        lines.append("</memory_context>")
        return "\n".join(lines)

    client = ThrindexOpenAI(
        thrindex_client=thrindex,
        openai_client=openai,
        agent_id="support-agent",
        user_id="user-42",
        format_memories=xml_formatter,
    )
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    const client = new ThrindexOpenAI({
      thrindex: new ThrindexClient({ apiKey: 'th_live_...' }),
      openai: new OpenAI(),
      agentId: 'support-agent',
      userId: 'user-42',
      formatMemories: (hits) =>
        `<memory_context>\n${hits.map(h => `  <memory>${h.content}</memory>`).join('\n')}\n</memory_context>`,
    });
    ```
  </Tab>
</Tabs>