OpenAI - Thrindex docs

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

Python
TypeScript

pip install 'thrindex[openai]'

npm install thrindex openai

Usage

Python
TypeScript

Synchronous

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

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?"}],
)

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?' }],
});

Options

Python
TypeScript

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

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

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.

Python
TypeScript

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,
)

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>`,
});

​Install

​Usage

​Synchronous

​Asynchronous

​Options

​Custom memory format