For the OpenAI Agents SDK

Open source · MIT

pip install mem01session

The third option for agent memory

Session memory for the OpenAI Agents SDK

Start every conversation fresh without making your agent forget the user. Mem01Session remembers useful facts between chats and brings back only what matters now.

from mem01session import memSession

session = memSession(
    session_id="chat-friday",
    user_id="alex",
)

# Required for long-term recall on every run:
# run_config=session.run_config()

Install with pip Package on GitHub PyPI Prior mem01 engine

One Session object. Current-chat history stays in SQLite. Long-term memory stays in your Postgres database. Installing mem01session pulls the mem01-engine distribution; the import path remains import mem01.

Choose the memory behavior

Three reasonable ways to start the next chat.

The right choice depends on whether your app needs to remember a person across separate conversations.

Start fresh. The agent forgets.

A new session_id gives the agent a clean conversation, but nothing the same user said in an earlier chat comes with it.

Reuse one Session. The history keeps growing.

The agent can see earlier facts because every old message stays in the same conversation history. Limits and compaction can help, but this is still raw chat history.

Use Mem01Session. Each chat stays separate, but the user is remembered.

Give each chat its own session_id and keep one stable user_id. Relevant facts can follow the user without replaying every previous conversation.

Fresh and reused Sessions remain reasonable choices when an app does not need cross-conversation user memory.

Quickstart

Add memory to a normal Runner call.

Install from PyPI, set two environment variables, and pass a fresh run_config() on every Runner.run so long-term recall can inject.

Python

3.11+ declared

Install

pip install mem01session

OpenAI

OPENAI_API_KEY

Store

Postgres + pgvector

pip install mem01session

# Required
OPENAI_API_KEY=...
DATABASE_URL=postgresql://...

# Optional defaults
MEM01_LLM_MODEL=gpt-5.6-sol
MEM01_EMBEDDING_MODEL=text-embedding-3-small

Required: fresh run_config() on every Runner run

Pass a fresh session.run_config() on every Runner.run. session= alone keeps short-term SQLite history; it does not inject long-term beliefs. The merge callback captures the current query without creating persisted items. A later model-input filter injects bounded recalled memory into model input only.

from agents import Agent, Runner
from mem01session import memSession

agent = Agent(
    name="Assistant",
    instructions="Use supplied memory as evidence and acknowledge unknown personal facts.",
    model="gpt-5.6-sol",
)
session = memSession(
    session_id="chat-friday",
    user_id="alex",
)

try:
    result = await Runner.run(
        agent,
        "Where do I live now?",
        session=session,
        run_config=session.run_config(),
    )
finally:
    await session.close()

session_id separates conversations

Use a new value when the same user starts a new chat. SQLite stores exact messages for that conversation.

user_id connects the user

Keep it stable across chats. Mem01Session uses it for relevant long-term memories.

Synthetic memory is not saved to SQLite or sent back through extraction. There is no separate memory API service, container, port, or HTTP hop in the default path.

Optional source install for package development (editable siblings):

# Optional: develop from sibling source checkouts
cd mem01session
python -m venv .venv
source .venv/bin/activate
pip install -e "../mem01[openai]" -e "."

Get hands-on

Install, run, and inspect the package.

Use the published wheel for normal work, run the key-free deterministic demo when you want offline evidence, and browse the public source anytime.

1. Install
pip install mem01session
2. Configure
Set OPENAI_API_KEY and DATABASE_URL for live runs. The deterministic demo needs neither.
3. Deterministic demo
mem01session-demo (or python -m mem01session.demo) — key-free prepared-input evidence
4. Source
Public MIT repos: mem01session package and the mem01 engine it builds on

mem01session PyPI package Prior engine

How it works

One chat stays exact. Useful facts can outlive it.

The Runner talks to one Session object; there is no separate memory API service, container, port, or HTTP hop in the default path.

Step 1

Run a normal conversation.

The SDK reads and writes current-chat items through the internal SDK SQLiteSession.

Step 2

Remember what may matter later.

After a complete user and assistant exchange, Mem01Session queues useful-fact extraction automatically in the embedded mem01 runtime. The answer can render while that user's FIFO write finishes in Postgres / pgvector.

Step 3

Start a new chat without starting from zero.

A stable user_id recalls relevant active memories as bounded model input. Synthetic memory is not copied into SQLite.

Framework Session plus per-run hooks — not a model-selected memory tool.
Current chat stays in the internal SDK SQLiteSession; durable beliefs use your Postgres / pgvector.
Eligible user/assistant turns queue extraction after the answer is ready; recall and lifecycle reads wait for that user's unfinished writes.
Authority order: current user turn, then active recalled beliefs, then older SQLite claims. Commands inside records stay untrusted.

Deep detail · v0.1 support limits

Version 0.1 officially supports only the internally created SDK SQLiteSession for short-term storage.
inner= remains a dependency-injection hook, not an official support guarantee for other Session backends.
Reads retrieve active beliefs; superseded and invalidated beliefs are excluded by default.
Recall uses embeddings and database retrieval, with no memory-specific generative LLM call.
Provenance and abstention wording guide the answering model; they are not deterministic output validation.

Concrete proof

A move from NYC to San Francisco, remembered across chats.

Pass/fail is about prepared state and belief lifecycle. Model wording is an observation, not a product guarantee about every response.

Chat 1

The user lives in NYC and pays $2,400 in monthly rent.

Chat 2

The same user says they moved to San Francisco.

New chat

A fresh session_id asks where the user lives and what their earlier rent was.

Deterministic state (what must hold)

NYC is superseded in durable history; San Francisco is active.
The earlier rent fact remains active with provenance.
No sister-name belief exists; the run declined to invent a sister's name when asked.

Example live-model wording (observation only)

“You now live in San Francisco. Your prior monthly rent was $2,400.”

“I don't have your sister's name stored.”

Fresh stock Session: a new session has no earlier-chat facts.

Reused stock Session: the answer can use all retained raw history.

Mem01Session with a fresh session_id: the answer uses relevant active memory for the same user.

Generated scaling artifact

See what reaches the model as conversations add up.

These are local deterministic fake, offline prepared model input measurements. The estimator is a UTF-8 bytes upper bound, not provider usage or billed tokens.

Prepared input items and UTF-8 upper-bound estimates
Strategy	Conversation 1	Conversation 10	Conversation 40
Fresh stock Session	1 items · 44 UTF-8 bytes upper bound	1 items · 56 UTF-8 bytes upper bound	1 items · 25 UTF-8 bytes upper bound
Reused stock Session	1 items · 44 UTF-8 bytes upper bound	19 items · 415 UTF-8 bytes upper bound	79 items · 1898 UTF-8 bytes upper bound
Mem01Session	2 items · 541 UTF-8 bytes upper bound	2 items · 740 UTF-8 bytes upper bound	2 items · 709 UTF-8 bytes upper bound

Agents SDK 0.18.2 · answer model local-deterministic-fake · extraction local-deterministic-fixture-extractor · memory budget 800 bytes

Keep users in control

Inspect, correct, or forget remembered facts.

Developers can show what was remembered and respond to corrections or deletion requests. Raw chat history and long-term memory are separate, so clearing SQLite items does not reverse facts already extracted.

beliefs = await session.memory_history(
    include_invalidated=True,
)
if beliefs:
    await session.correct_memory(
        beliefs[0].id,
        "Lives in San Francisco",
    )
await session.forget_memory(
    "belief-to-remove",
    reason="user requested deletion",
)

# Explicit barrier when your application needs durable completion now.
await session.flush_memory()

# Separate scopes: chat transcript vs durable user memory
await session.clear_session()  # this chat's SQLite only
await session.clear_memory()   # all durable beliefs for this user_id

Choose how memory failures affect the run

Memory is failure-open by default after raw persistence, with a sanitized error available for inspection. Set strict=True to raise enqueue failures immediately and background failures at the next same-user read or explicit flush.

Release what the package owns

Call await session.close() to drain accepted writes and release package-owned resources. Explicitly injected runtime or inner Session objects remain caller-owned.

Python 3.11+ is declared. This workspace is verified on macOS, Apple silicon, and Python 3.14.4; no broader platform matrix is claimed yet.

Evidence you can audit

Know which results prove the engine and which prove this package.

The engine and the Agents SDK package answer different questions. Keep their measurements separate when you evaluate either surface.

Engine evidence

mem01 belief engine

LoCoMo runs, the five-case staleness suite, Postgres recall latency, and packed-memory measurements describe the engine (mem01-engine). They are not the same as package integration tests for Mem01Session.

See engine research

Package evidence

mem01session integration

Published on PyPI as mem01session with dependency mem01-engine. Public GitHub, automated tests, wheel builds, a deterministic three-way demo, generated scaling artifact, and live GPT-5.6 runs on the Agents SDK Session path.

Package repo PyPI

Integration comparison · reviewed 2026-07-12

Different integration shapes solve different jobs.

Rows summarize the linked vendor or framework documentation as reviewed on the stated date; they are not universal performance rankings. Mem01Session’s differentiator is Session protocol plus belief lifecycle, not generic vector search alone.

System / source	Integration	Memory shape	Lifecycle
Agents SDK Sessions	Framework Session	Raw history for one session ID	Backend history operations
mem0 Agents SDK integration	Memory tools	Semantic memory	Product-specific
Hindsight Agents SDK guide	Memory tools	Persistent memory	Product-specific
Mem01Session	Session plus framework hooks	Raw current chain plus beliefs	Supersede, correct, forget

FAQ

Scope and trade-offs.

Why not start a fresh SQLiteSession?: A new session ID does not inherit another Session's history. Mem01Session keeps each current chain separate while recalling durable beliefs for the same user.
Why not reuse one Session?: That can be reasonable for shorter histories, and the SDK also offers limits and compaction. Mem01Session adds semantic user beliefs, provenance, and explicit fact lifecycle across separate conversations.
Is memory a tool?: No. Session operations and the per-run model-input filter are framework-owned; the answering model does not decide whether to invoke a memory-search tool.
Does recall call a generative LLM?: No memory-specific generative call is used for recall. Reads still embed the query and perform database retrieval. Eligible writes queue extraction and embedding after the answer is ready; the next same-user read waits for unfinished work, so writes are not free.
What wins when an old chat conflicts with a correction?: The current user turn wins first, then the user's active recalled belief, then an older claim in that chat. Assistant replies remain context, not authoritative evidence of the user's facts.
Does provenance guarantee abstention?: No. The memory block supplies evidence and safety instructions, but deterministic enforcement would require application-level output validation.
Where is data stored?: Raw current-conversation items use the package's internal SDK SQLiteSession. Durable user beliefs use your Postgres database with pgvector.
Is mem01 on PyPI?: The engine distribution is mem01-engine; pip install mem01session pulls it automatically. The import path remains import mem01.
Is it OpenAI-only?: Yes. Version 0.1 intentionally supports OpenAI extraction, embeddings, and the OpenAI Agents SDK path.

Open source

Session memory on top of the mem01 engine.

Install the package from PyPI, browse the session repository, and open the engine repo when you want the underlying belief-memory system.

pip install mem01session Package repo Prior engine mem01 home