Official @wolbarg/openai Session — persist AgentInputItem history, semantic remember, and recall injection via createWolbargSessionInputCallback.

What is it?

@wolbarg/openai is the official OpenAI Agents SDK Session for Wolbarg shared memory.

It automatically:

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

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

Requires @openai/agents ≥ 0.13.0 and Node ≥ 22.

Install

npm install wolbarg @wolbarg/openai @openai/agents

Peers: wolbarg >= 0.5.3, @openai/agents >= 0.13.0.

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

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) constructs WolbargSession and awaits hydration.

Semantic recall injection

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

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

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

Options

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

Soft-fail

Snapshot persistence and semantic remember never throw into the Agents SDK run path. Wire onError for observability.

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).
Multimodal user parts become text + [attachment:…] placeholders for semantic remember / recall queries.

OpenAI Agents SDK

On this page