@wolbarg/openai

Official OpenAI Agents SDK Session for Wolbarg shared memory.

Automatically:

1. Persists conversation AgentInputItem[] as a single Wolbarg session snapshot
2. Hydrates that snapshot when you resume with the same sessionId
3. Remembers user/assistant text as semantic memories on addItems (optional)
4. Recalls relevant memories via createWolbargSessionInputCallback before the model call

Drop-in for MemorySession — implement the same Session surface the runner expects.

Requires @openai/agents ≥ 0.13.0.

Installation

npm install wolbarg @wolbarg/openai @openai/agents

Peers: wolbarg >= 0.5.4, @openai/agents >= 0.13.0. Node ≥ 22.

Quick Start

import { Agent, run } from "@openai/agents";
import { wolbarg, sqlite, openaiEmbedding } from "wolbarg";
import {
  createWolbargSession,
  createWolbargSessionInputCallback,
} from "@wolbarg/openai";

const memory = wolbarg({
  organization: "my-app",
  storage: sqlite("./memory.db"),
  embedding: openaiEmbedding({
    apiKey: process.env.OPENAI_API_KEY!,
    model: "text-embedding-3-small",
  }),
});
await memory.ready();

const session = await createWolbargSession({
  memory,
  agent: "assistant",
  sessionId: "chat-1",
});

const agent = new Agent({
  name: "Assistant",
  instructions: "Be concise.",
});

await run(agent, "What UI theme do I prefer?", {
  session,
  sessionInputCallback: createWolbargSessionInputCallback({
    memory,
    agent: "assistant",
  }),
});

API Reference

WolbargSession

Implements the Agents SDK Session interface:

| Method | Behavior | | --- | --- | | getSessionId() | Returns the stable session id | | getItems(limit?) | Returns cloned history (most recent limit when set) | | addItems(items) | Append locally → persist snapshot → optional semantic remember | | popItem() | Pop newest locally → persist snapshot | | clearSession() | Clear local items + soft-fail forget snapshot |

import { WolbargSession } from "@wolbarg/openai";

const session = new WolbargSession({
  memory,
  agent: "assistant",
  sessionId: "chat-1", // omit to auto-generate (no hydrate)
  semanticRemember: true, // default
  userId: "u1",
  tags: ["support"],
  onError: (err, phase) => console.warn(phase, err),
});
await session.ready(); // await soft-fail hydration

createWolbargSession(options)

Factory that constructs WolbargSession and awaits hydration.

createWolbargSessionInputCallback(options)

Returns a SessionInputCallback for run(..., { sessionInputCallback }):

1. Takes the last user text from newItems
2. Soft-fail memory.recall
3. Injects { role: "system", content } when hits exist
4. Returns [system?, ...historyItems, ...newItems]

Use when the turn input is an AgentInputItem[] (string inputs merge history automatically; the callback is optional then).

Configuration

| Option | Default | Notes | | --- | --- | --- | | memory | required | Wolbarg instance | | agent | required | Agent id for snapshot + semantic memories | | sessionId | random UUID | When provided, constructor hydrates from Wolbarg | | semanticRemember | true | Store user/assistant text on addItems | | topK | 5 | Used by createWolbargSessionInputCallback | | userId / tags / namespace / metadata | — | Copied onto stored metadata | | onError | — | Soft-fail hook (recall | remember | persist | hydrate | forget) |

Provenance metadata always includes source: "wolbarg-openai". Session snapshots also set kind: "wolbarg-session".

Production Notes

• Keep one WolbargSession per conversation; reuse the same sessionId across process restarts to resume.
• Snapshot persistence and semantic remember soft-fail — they never throw into the Agents SDK run path. Wire onError for observability.
• Session snapshots are stored as one memory row and updated in place (remember then update). Disable content dedupe for snapshots so turns do not collapse.
• Pair with createWolbargSessionInputCallback when you want cross-session semantic memory in the model prompt (in addition to Session history).
• Node ≥ 22 (matches Wolbarg and Agents SDK tooling).

Limitations

• Hydration finds the snapshot via filtered recall (metadata kind + sessionId). Extremely noisy corpora may need a dedicated agent namespace for session rows.
• forget({ filter: { agent } }) would wipe all agent memories — clearSession forgets by snapshot id only.
• Does not implement optional Session extensions (applyHistoryMutations, compaction hooks). Use the core Session methods only.
• Multimodal user parts become text + [attachment:…] placeholders for semantic remember / recall queries.
• Illustrative examples/ scripts need API keys and are not run in CI.

Migration Guide

| From | To | | --- | --- | | MemorySession | createWolbargSession({ memory, agent, sessionId }) | | Manual history stitching | Same session across run() calls | | Ad-hoc RAG injection | createWolbargSessionInputCallback({ memory, agent }) |

Examples

See packages/openai/examples/ and the runnable adapter at examples/adapters/openai/:

| File | Topic | | --- | --- | | minimal.ts | Session + run | | streaming.ts | Streaming via run | | chatbot.ts | Multi-turn chat loop | | multi-agent.ts | Shared memory across agents | | persistence.ts | Resume with sessionId | | memory-recall.ts | sessionInputCallback recall | | long-conversation.ts | Growing history + getItems(limit) |

Docs

https://wolbarg.com/docs/integrations/openai

License

MIT