mem01
Get started
Self-hosted · Belief memory · Open source

mem01 · memory for AI agents

Memory that
stays correct

Open-source, self-hosted memory for AI agents that updates when the truth changes — so they don't keep acting on yesterday's facts. Built for long-term agent memory that stays correct.

Engine · self-hosted

mem01

Belief lifecycle, multi-signal recall, and Postgres / pgvector. Run the engine with Docker or call it from Python when you own the agent loop.

Engine on GitHubQuick start

$ docker compose up -d --build

Package · OpenAI Agents SDK

Mem01Session

One Session object for the Agents SDK: keep each chat separate, recall durable user beliefs across conversations. pip install mem01session

Get startedPackage repo

from mem01session import memSession

demo · location_updatelive

bag of facts

  • ×User lives in New York City
  • ×User moved NYC → San Francisco

Both active. Agent invents a cover story.

mem01 · recall (now)

  • —User lives in New York Cityout of prompt
  • ●User lives in San Franciscoactive

Default: one truth for the agent.

mem01 · history / include_history

“Where did we live before SF?”

  • ● [active] User lives in San Francisco
  • ○ [superseded] User lives in New York City

Previous facts stay in the DB and can be recalled on purpose — labeled so the agent never confuses past with present.

The problem

Append-only
becomes wrong

Users change their minds. Agents that remember everything end up remembering the past louder than the present.

01

Facts only grow

Most memory layers ADD. Preferences flip, jobs change, cities move — the old fact still sits in the prompt.

02

Agents reconcile

When NY and SF both retrieve, the LLM covers the mess. Looks fine in a demo. Fails in production.

03

Quality decays

Token budgets fill with contradictions. Cost climbs. Correctness slides the other way.

Benchmarks

LoCoMo
v0.2 → v0.3

Self-run on LoCoMo-10 (1,540 questions). Same open eval style as mem0's public harness. Extract, answer, and judge: gpt-4o-mini.

v0.2 · prior

77.9%

1200/1540 correct

v0.3 · current

80.5%

1240/1540 correct · +2.6 pts

Multi-hop

cat 1
v0.2
83.3%
v0.3
86.9%

Temporal

cat 2
v0.2
74.5%
v0.3
77.9%

Open-domain

cat 3
v0.2
74.0%
v0.3
75.0%

Single-hop

cat 4
v0.2
77.9%
v0.3
80.0%

v0.3: multi-signal retrieval (vector + lexical, RRF + MMR), Postgres store, mean packed ~1.3k tokens under a 6.5k cap. Full method, models, and caveats on Research.

Research details

Compare

Why mem01

mem0 wins on cloud polish. Zep wins on graph depth. mem01 wins when you need correct beliefs under evolution, self-hosted, lean recall.

Capabilitymem01mem0Zep
Belief lifecycle (supersede / invalidate)
Stale facts retired on conflict
Recall without LLM by default
Multi-signal retrieval (vector + lexical / RRF + MMR)
History / timeline without polluting default recall
Token-budgeted context packing
Self-hosted first (your Postgres)
Light model — no full knowledge graph required
Open-source MIT core

● yes · — partial · × no · from public docs / positioning

vs mem0

The append problem

They do well: Best-in-class ease and fact extraction.

Gap: After NYC → SF, search often returns both. Store stays dirty; agent covers it.

Why mem01: SUPERSEDE retires NYC. One active belief. Product suite: mem01 5/5 vs mem0 2/5 on conflict cases.

vs zep

Graph power, heavier path

They do well: Temporal graphs, enterprise packaging, multi-hop context.

Gap: Graph materialization trades simplicity and cost. Overkill for “two cities in the prompt.”

Why mem01: Belief ops + budgeted packing. Evolution correctness without a full temporal graph.

vs diy

Vectors alone

They do well: You control embeddings and filters.

Gap: No extraction policy, no conflict model, no packer. Every agent reinvents hygiene.

Why mem01: remember / recall / correct / forget over Postgres. Lifecycle is the product.

Use cases

Where we have
leverage

Not every product needs belief memory. These are the jobs where staleness, scopes, and self-host actually change the outcome.

01

Coding agents that share project memory

Why here · Stack, monorepo tools, and “we use light mode now” change over a repo’s life. Append-only memory keeps old toolchains in the prompt.

How mem01 · Scope by user + project. SUPERSEDE when the project switches package manager, model, or conventions. Cursor / Claude / custom agents hit the same HTTP API.

Skip if · One-shot scripts with no shared state — skip a memory layer.

02

Long-running agents when user state flips

Why here · Location, job, plan tier, and preferences are single-slot truths. Stacked facts force the model to guess which one is current.

How mem01 · Default recall is active-only. Opt into history when the question is temporal (“before SF?”) without poisoning every turn.

Skip if · Pure multi-hop “who works with whom across orgs” — a temporal graph fits better.

03

Self-hosted / data-boundary teams

Why here · Agent memory often includes code context, internal names, and PII. SaaS memory is a non-starter for many shops.

How mem01 · docker compose · Postgres + pgvector on your network. Same remember / recall shape as a managed API, under your keys.

Skip if · Zero-ops hobby demos that only need a cloud key and never leave the laptop.

04

Multi-tool agents without memory cross-talk

Why here · One user, several agents: a coder, a support bot, a research runner. Shared user prefs should travel; agent scratch should not.

How mem01 · user / project / agent / session scopes. Share what’s meant to be shared; isolate the rest.

Skip if · A single chat window with no second agent or project boundary.

System

Three calls.
One truth.

Plus history, correct, and forget when you need audit, human fix, or hard delete.

01

remember

Send messages. One extraction pass classifies belief ops: ADD, UPDATE, SUPERSEDE, INVALIDATE, MERGE — then embeds and writes to Postgres + pgvector.

02

beliefs evolve

New truths replace old ones. Superseded and invalidated beliefs stay for audit; default recall only packs what is active now.

03

recall

Vector + lexical/entity search, RRF fusion, conflict filter, MMR diversity, then pack to a token budget. Multi-signal by default. Still zero LLM on the hot path.

Product

Infrastructure,
not a chat toy

A1

Belief lifecycle

ADD · UPDATE · SUPERSEDE · INVALIDATE · MERGE — not just store another string.

A2

Multi-signal recall

Vector + lexical/entity search, RRF fusion, MMR diversity. Conflict filter + token packer. Still zero LLM on read.

A3

Token discipline

Budgeted packing keeps memory blocks tight. Eval runs pack far under a 6.5k cap when truth is clean.

B1

History when you need it

Default recall is active-only. include_history or POST /v1/history for labeled timelines — past is not erased.

B2

Postgres + pgvector

Production store in dev and deploy. Neon or any Postgres with vectors. Self-hosted first.

B3

Agent scopes

User, project, agent, session. Share what should be shared; isolate the rest.

API

Endpoints
that ship

HTTP + Python SDK. Core path is remember / recall. Scope with user_id + optional project_id, session, agent.

  • POST /v1/remember — extract & apply belief ops
  • POST /v1/recall — multi-signal pack; include_history for labeled past
  • POST /v1/history — chronological audit timeline
  • POST /v1/correct · /v1/forget — human supersede or invalidate
  • GET /health — liveness

Defaults shown (k=20, 800 tokens) are the product hot path. LoCoMo evals use a larger envelope for fair open-harness comparison — see Research.

shell:8080
# remember — extract beliefs (1 LLM batch)
curl -s http://localhost:8080/v1/remember \
  -H 'Content-Type: application/json' \
  -d '{
    "user_id": "user_1",
    "project_id": "proj_acme",
    "messages": [
      {"role": "user", "content": "I live in San Francisco."}
    ]
  }'

# recall — multi-signal, 0 LLM (active beliefs only)
curl -s http://localhost:8080/v1/recall \
  -H 'Content-Type: application/json' \
  -d '{
    "user_id": "user_1",
    "project_id": "proj_acme",
    "query": "Where does the user live?",
    "max_memory_tokens": 800,
    "k": 20,
    "include_history": false
  }'

# history — full timeline for audit / "before SF?"
curl -s http://localhost:8080/v1/history \
  -H 'Content-Type: application/json' \
  -d '{
    "user_id": "user_1",
    "project_id": "proj_acme",
    "include_invalidated": true,
    "limit": 50
  }'

# correct / forget — human fix or hard invalidate
# POST /v1/correct  { "memory_id": "bel_...", "new_value": "..." }
# POST /v1/forget   { "memory_id": "bel_...", "reason": "optional" }

FAQ

Straight
answers

Same job — long-term agent memory — different model. mem01 is belief-centric: lifecycle ops, conflict filtering, and self-hosted Postgres as the default story.

No. v1 avoids full temporal graphs. You get validity windows and supersede chains without multi-hop search on every request.

Docker Compose: FastAPI + PostgreSQL with pgvector. Point OPENAI_API_KEY (or compatible) at extraction/embeddings. Data stays in your DB.

Yes. Recall is multi-signal (vector + lexical/entity, RRF, MMR), conflict filter, and pack — no LLM on the hot path. Writes may call an LLM once per batch for extraction.

On conflict and staleness — location/job/preference flips — not every public benchmark. Product suite: mem01 5/5 vs mem0 2/5 when old values must not reappear. LoCoMo self-runs use gpt-4o-mini throughout; see Research for numbers and caveats.

No. Default recall is active-only so agents stay correct. For “before SF?” or audit, call recall with include_history=true, or POST /v1/history for a full timeline. Past beliefs stay labeled, not mixed in as active truth.

v0.3 fuses embedding search with a lexical/entity pass (RRF), then applies MMR diversity before packing. Same zero-LLM constraint — better hit rate when names and exact phrases matter.

Get started

Ship agents that
remember right

Clone the repo. Compose up. Call remember and recall.

Start on GitHub