mem01session

Native long-term belief memory for OpenAI Agents SDK agents. Delivering bounded, user-scoped recall with lifecycle, provenance, and clean per-conversation history.

Comment

Inspiration

The OpenAI Agents SDK provides a strong Session abstraction for preserving conversation history. But when an agent needs to remember a user across multiple conversations, developers still face a difficult choice:

  • Start a fresh session and lose access to facts shared previously.
  • Reuse one session and continue replaying an increasingly large transcript.
  • Add a separate memory tool and rely on the model to decide when to call it.

I wanted another option: preserve the raw history of the current conversation while automatically recalling only the relevant, durable beliefs from earlier conversations.

That became Mem01Session.

What it does

Mem01Session is a custom Session implementation for the OpenAI Agents SDK.

Each conversation receives its own session_id, while conversations belonging to the same person share a stable user_id. This creates two distinct memory layers:

  1. The SDK’s SQLiteSession preserves the raw history of the current conversation.
  2. An embedded memory runtime stores durable, user-scoped beliefs in Postgres with pgvector.

Before a model call, Mem01Session retrieves relevant active beliefs, packs them into a configurable token budget, and supplies them to the agent without adding them to the raw conversation transcript.

Stored beliefs have a lifecycle—ADD, UPDATE, SUPERSEDE, INVALIDATE, and MERGE. This allows a new fact to replace an outdated fact without silently deleting the historical evidence. Recalled beliefs also include provenance so developers can inspect where the information came from.

The demo follows one user across three conversations:

  • On Monday, the user says they live in New York City and pay $2,400 in rent.
  • On Wednesday, they say they moved to San Francisco.
  • On Friday, they start a fresh conversation and ask where they live now and what their earlier rent was.

Friday’s SQLite history contains only its own question and answer. The Monday and Wednesday transcripts are not replayed. However, Mem01Session recalls the active San Francisco belief and the earlier rent from durable memory. New York remains visible in the lifecycle history as a superseded belief.

How Mem01Session works

Mem01Session orchestrates both paths in application code; the model does not decide whether to call a memory tool. Recall happens before generation because the current answer needs that context. Belief extraction happens after the answer is ready, so long-term memory processing does not add unnecessary response latency. Recalled beliefs are supplied only to model input; they are not written into the raw SQLite transcript.

How we built it

I built Mem01Session against the official OpenAI Agents SDK Session protocol.

The inner SQLiteSession continues to own normal conversation operations such as get_items, add_items, pop_item, and clear_session. A session-input callback captures the current user query, while a model-input filter performs query-aware recall immediately before the model call.

The recall pipeline:

  1. Captures the current user query.
  2. Searches for relevant beliefs belonging to the same user_id.
  3. Excludes superseded and invalidated beliefs from current-truth recall.
  4. Preserves provenance and timestamps.
  5. Packs the selected beliefs into a configurable token budget.
  6. Injects the memory block into model input without persisting it to SQLite.

The memory engine runs in-process, so the default integration does not require a separate memory server, localhost port, or Docker service. Durable beliefs and embeddings remain in the developer’s Postgres database.

GPT-5.6 powers the demonstrated agent-answering path and the configured belief-extraction path.

I used Codex throughout Build Week to inspect the Agents SDK, implement the integration, create tests, diagnose failures, package the project, build the demo interface, generate deterministic evidence, and document the system.

The central product decisions remained human decisions: composing with the SDK’s existing SQLite implementation, separating short-term transcripts from long-term beliefs, selecting the correct memory-injection point, defining truth precedence, and designing a demo based on inspectable evidence rather than a scripted model failure.

Challenges we ran into

Preventing recalled memory from becoming conversation history

One of the most important challenges was finding the correct point in the Agents SDK pipeline for injecting memory.

A synthetic item returned from a session merge callback can be classified as a new conversation item and persisted into the Session. That would cause the recalled memory block itself to become part of the raw SQLite transcript.

I solved this by using the session-input callback only to capture the user’s query. The memory block is injected later through the per-model-call input filter, after Session persistence has identified the real conversation items.

Preserving history while correcting outdated facts

Rewriting old conversations would destroy useful context and auditability. Instead, Mem01Session leaves raw transcripts unchanged while allowing newer durable beliefs to supersede older ones.

The model receives a defined evidence order:

  1. The current user message.
  2. Active recalled beliefs.
  3. Older user claims in the current transcript.

This allows a newer correction to take precedence without rewriting history.

Keeping asynchronous memory writes consistent

Belief extraction occurs after an answer is ready so memory processing does not unnecessarily delay every response. This introduced consistency and deletion challenges.

I added same-user consistency barriers so a later conversation can wait for an unfinished write when necessary. Memory deletion also waits for accepted writes to finish, preventing an in-flight extraction from recreating data after deletion returns.

Building a truthful and reproducible demo

Generated model wording is nondeterministic, so the demo does not pass or fail based on forcing GPT-5.6 to produce a particular sentence.

Instead, it verifies inspectable state:

  • Which raw items belong to Friday.
  • Which beliefs were recalled.
  • Which belief was superseded.
  • Where each belief came from.
  • How prepared input changes across the compared strategies.

Generated answers are presented as observed behavior, not manipulated proof.

Accomplishments that we're proud of

I built a native OpenAI Agents SDK Session integration that combines ordinary short-term conversation history with durable, user-scoped belief memory behind one public object.

The strongest accomplishment is the working, inspectable demonstration. Friday’s fresh conversation contains only its own question and answer in SQLite, yet the agent recalls the user’s current city and earlier rent without replaying Monday or Wednesday.

The lifecycle ledger preserves New York as a superseded belief while treating San Francisco as current. This provides both useful current truth and an auditable history.

I am also proud of the engineering behind the demo:

  • Bounded query-aware recall.
  • Belief lifecycle and provenance.
  • Explicit transcript and durable-memory deletion scopes.
  • Same-user consistency barriers.
  • Secret-safe configuration and failures.
  • Deterministic tests and reproducible evidence.
  • A packaged developer experience built around the Agents SDK.
  • A complete narrated demonstration under three minutes.

What we learned

The biggest lesson was that useful agent memory is not just storage. A practical memory system needs clear user scope, lifecycle, provenance, deletion semantics, consistency behavior, and a defined place in the framework’s execution flow.

I also learned that composition was better than replacement. Keeping the SDK’s tested short-term Session implementation and adding a separate durable-belief layer resulted in a smaller API and a clearer trust boundary.

The project also reinforced the importance of testing framework behavior rather than assuming it. Understanding when synthetic items could be persisted changed the architecture and prevented recalled memory from contaminating raw conversation history.

Finally, building deterministic evidence alongside the product made the product stronger. It exposed weak assumptions, prevented exaggerated claims, and produced a demo that judges can inspect rather than simply trust.

What's next for mem01session

The immediate next steps are publishing the package and submission repository, providing a judge-accessible testing path, and improving installation, documentation, and observability.

After that, I want to:

  • Evaluate additional OpenAI Agents SDK Session backends.
  • Expand lifecycle inspection and memory-management tools.
  • Add more real-world agent evaluations.
  • Improve developer controls for memory budgets and provenance.
  • Explore hosted memory and an embedded long-term SQLite option.
  • Investigate additional model providers after each integration is properly tested.

Version 0.1 remains intentionally focused on the OpenAI Agents SDK, OpenAI models, and Postgres with pgvector.

Prior-work disclosure

mem01 is my pre-existing open-source belief-memory engine.

During the OpenAI Build Week submission period, I used Codex and GPT-5.6 to create the Mem01Session developer product: its OpenAI Agents SDK integration, embedded packaging, default short-term Session composition, GPT-5.6 configuration, deterministic demo, testing experience, and project presentation.

The pre-existing engine and the Build Week extension are documented separately so the scope of the hackathon work remains clear.

Built With

Share this project:

Updates