Skip to main content
Glama

mnemo

Long-term memory for AI agents: it remembers facts across sessions, replaces outdated ones and keeps their history, and gives the model only what's relevant. Runs on local SQLite and plugs into Claude through MCP.

ci python license

In mnemo's own benchmark, over 12 simulated users and 6 sessions each, the model got 18.8x fewer context tokens than when you paste the whole history (112 vs 2,104 per question) with the same 100% answer accuracy, including every question about a fact that had changed. At 24 sessions the gap is 58x (132 vs 7,719). A naive "last 800 tokens" window answers just 25%. (details · how it's graded)


Why

Agents forget everything between sessions, and the two usual fixes both break:

  • Paste the whole history. The cost grows with every turn, and the model has to work out on its own that "I moved to Berlin" (session 5) cancels "I live in Madrid" (session 1).

  • Plain vector RAG over old chat. It finds text that looks like the question, but it has no idea that one fact replaced another. Ask "where do I live?" and you get back both cities.

mnemo treats memory like a small database instead of a pile of text:

memory type

what it holds

example

episodic

raw conversation turns, with timestamps and a session id

user: I just moved to Berlin last week!

semantic

facts as subject-predicate-object triples, with a version and a source

user | lives_in | Berlin (v2, supersedes Madrid, from episode #9)

procedural

standing rules and preferences

Always answer in bullet points (topic: format)

Each new turn is checked against what's already stored. If it repeats a fact, that fact's importance goes up. If it contradicts a single-valued fact, the old one is superseded: kept with an end date and linked to the new version. If the user withdraws something ("I don't like jazz anymore"), the fact is retracted. Retrieval ranks memories by relevance × recency × importance. Old episodes get consolidated into summaries, and anything can be given a TTL or forgotten for good. Each namespace (for example, one per user) is kept separate.

Related MCP server: memory-mcp

Quickstart

git clone https://github.com/lijo123ferdinand/mnemo && cd mnemo
python3 -m venv .venv && source .venv/bin/activate
pip install -e '.[dev]'          # the only runtime dependency is numpy
pytest -q                        # 85 passed, 1 skipped (the skip needs the optional anthropic SDK)
python examples/quickstart.py

You don't need an API key. By default, mnemo uses a deterministic offline MockProvider (it extracts facts with patterns rather than an LLM).

Library

from mnemo import Mnemo

mem = Mnemo("~/.mnemo/mnemo.db", namespace="priya")
mem.remember("Hi! My name is Priya and I live in Madrid.", session="s1")
mem.remember("Big news: I just moved to Berlin last week!", session="s2")

mem.recall("Where does the user live?", k=3)       # -> scored memories
prompt_block = mem.context("plan a dinner for me")  # -> ready to paste into a system prompt

Real output of python examples/quickstart.py, where a simulated clock moves 30 days forward between the two sessions:

== session 1 ==
  added      user is named Priya
  added      user lives in Madrid
  added      user works at Acme Robotics
  added      user works as data engineer
  added      user is allergic to peanuts
  added      Always answer in bullet points

== session 2 (30 days later) ==
  superseded user lives in Berlin   (was: user lives in Madrid)
  reinforced user lives in Berlin

== recall: 'Where does the user live?' ==
  score=0.660 rel=0.78 rec=1.00 imp=0.85  [fact] user | lives_in | Berlin
  score=0.299 rel=0.67 rec=1.00 imp=0.45  [episode] user: I live in Berlin now, still at Acme Robotics.
  score=0.061 rel=0.68 rec=0.20 imp=0.45  [episode] user: Hi! My name is Priya and I live in Madrid.

== version history of lives_in ==
  v1 Madrid   status=superseded  from episode #1
  v2 Berlin   status=active  from episode #11

== prompt context for 'plan a dinner for me' ==
## Current facts (most recent, authoritative)
- user | allergic_to | peanuts [v1, since 2026-01-01]

Look at the third recall hit: the old "Madrid" turn is still relevant (rel 0.68), but it's 30 days old, so its recency has fallen to the 0.2 floor and it ranks well below the current fact.

CLI

Real session (by default the database is $MNEMO_DB or ~/.mnemo/mnemo.db):

$ mnemo remember "My name is Priya and I live in Madrid."
stored     #1     episode   My name is Priya and I live in Madrid.
added      #2     fact      user is named Priya
added      #3     fact      user lives in Madrid

$ mnemo remember "I am allergic to peanuts and shellfish."
stored     #4     episode   I am allergic to peanuts and shellfish.
added      #5     fact      user is allergic to peanuts
added      #6     fact      user is allergic to shellfish

$ mnemo remember "Please always answer in bullet points."
stored     #7     episode   Please always answer in bullet points.
added      #8     procedure Always answer in bullet points

$ mnemo remember "I just moved to Berlin last week!"
stored     #9     episode   I just moved to Berlin last week!
superseded #10    fact      user lives in Berlin  (was: user lives in Madrid)

$ mnemo facts --history
#5     v1  user | allergic_to | peanuts <- episode #4
#6     v1  user | allergic_to | shellfish <- episode #4
#3     v1  user | lives_in | Madrid  [superseded 2026-11-07 15:43] <- episode #1
#10    v2  user | lives_in | Berlin <- episode #9
#2     v1  user | name | Priya <- episode #1
#8     rule  Always answer in bullet points  (topic: format)

$ mnemo recall "where does the user live?" -k 3
0.621  rel=0.78 rec=1.00 imp=0.80  #10    fact      user | lives_in | Berlin
0.330  rel=0.73 rec=1.00 imp=0.45  #1     episode   user: My name is Priya and I live in Madrid.

$ mnemo recall "any food allergies?" --context
## Current facts (most recent, authoritative)
- user | allergic_to | peanuts [v1, since 2026-11-07]
- user | allergic_to | shellfish [v1, since 2026-11-07]

Other commands: forget <id> | --query Q | --all-in-namespace, consolidate --older-than-days N, gc [--purge-archived] [--purge-history-days N], stats, serve, eval [--sweep]. Use -n/--namespace to pick a namespace and --provider mock|anthropic|openai|ollama to pick a provider.

MCP server (Claude Desktop / Claude Code)

mnemo serve speaks JSON-RPC 2.0 over stdio (initialize, ping, tools/list, tools/call) and exposes three tools: remember, recall and forget.

Claude Code:

claude mcp add mnemo -- mnemo --db ~/.mnemo/mnemo.db --namespace me serve

Claude Desktop (claude_desktop_config.json, also in examples/):

{
  "mcpServers": {
    "mnemo": {
      "command": "mnemo",
      "args": ["--db", "~/.mnemo/mnemo.db", "--namespace", "me", "serve"],
      "env": { "MNEMO_PROVIDER": "mock" }
    }
  }
}

Set MNEMO_PROVIDER=anthropic (plus ANTHROPIC_API_KEY) to have an LLM extract facts. Real output of examples/mcp_client_demo.py, which starts the server as a subprocess and talks to it the way an MCP host does:

server: {'name': 'mnemo', 'version': '0.1.0'} protocol 2025-06-18
tools: ['remember', 'recall', 'forget']
remember -> [('added', 'user lives in Lisbon'), ('added', 'user follows a diet: vegetarian')]
remember -> [('superseded', 'user lives in Oslo')]
recall ->
## Relevant past conversation
- [2026-11-07] user: I live in Lisbon and I'm vegetarian.
## Current facts (most recent, authoritative)
- user | diet | vegetarian [v1, since 2026-11-07]
- user | lives_in | Oslo [v2, since 2026-11-07]
forget -> {"deleted": [{"id": 5, "text": "user lives in Oslo"}]}

LLM providers

provider

how to use it

notes

MockProvider (default)

nothing to set up

deterministic pattern extraction, extractive summaries and answers; used by the tests and the eval

AnthropicProvider

pip install -e '.[anthropic]', ANTHROPIC_API_KEY

default model claude-sonnet-5-5 (override with MNEMO_MODEL)

OpenAICompatibleProvider

--provider openai or --provider ollama

plain urllib POST to /chat/completions; MNEMO_BASE_URL, OPENAI_API_KEY (optional for local servers)

A provider has to implement only extract, summarize and answer. ChatProvider builds all three on top of a single complete(system, user) method. If an LLM returns output that won't parse, mnemo logs it and skips extraction for that turn; the turn itself is still stored. Pass strict=True to make it raise instead.

Architecture

                       remember(text)                                    recall(query) / context(query)
                            │                                                       │
             ┌──────────────┴──────────────┐                    ┌───────────────────┴───────────────────┐
             ▼                             ▼                    ▼                                       ▼
   episode row (always)          provider.extract()       FTS5 bm25 over stemmed           cosine(q, M) over the namespace's
   = ground truth + provenance   (outside the write lock)  terms + predicate glosses        float32 vectors (numpy)
                                           │                    └──────────────┬────────────────────────┘
                                           ▼                                   ▼
                              reconcile per candidate             relevance = α·cos + (1-α)·bm25_norm
                              ├ same key+value  → reinforce        score = rel^w1 · recency^w2 · importance^w3
                              ├ exclusive, new  → supersede (v+1)             │
                              ├ negated         → retract                     ▼
                              └ otherwise       → add               top-k → touch(last_accessed) → render
                                           │
                                           ▼
     ┌──────────────────────── SQLite (one file, WAL) ───────────────────────────┐
     │ memories(id, namespace, kind, status, text, subject, predicate, object,    │
     │          version, supersedes, superseded_by, valid_to, expires_at,         │
     │          source_id → episode, importance, created_at, last_accessed, ...,  │
     │          embedding BLOB)                                                   │
     │ memories_fts  (FTS5, external content, kept in sync by triggers)           │
     └────────────────────────────────────────────────────────────────────────────┘
      consolidate(): old episodes → one summary per session, originals archived
      gc():          TTL expiry, purge archived episodes / old fact versions

module

what it does

memory.py

the Mnemo class: write path, reconciliation, recall, context, forgetting, consolidation

store.py

schema, FTS5 triggers, transactions (BEGIN IMMEDIATE)

scoring.py

the ranking formula (documented below)

extraction.py

the deterministic pattern extractor, plus a validator for LLM JSON

predicates.py

predicate registry: whether each one holds one value or many, how it's phrased, extra search keywords

embedding.py

HashingEmbedder: hashed features of stemmed words and character trigrams

mcp.py

the stdio JSON-RPC 2.0 MCP server

bench/

dialogue generator and eval harness

Scoring formula

score      = relevance^w_rel · recency^w_rec · importance^w_imp          (defaults: all weights 1.0)
relevance  = α · max(0, cos(q, m)) + (1 − α) · bm25(q, m) / max bm25      (α = 0.5)
recency    = floor + (1 − floor) · 0.5^(age / half_life[kind])            (floor = 0.2)
age        = now − max(created_at, last_accessed)
half_life  = episode 3d · summary 30d · fact 180d · procedure 365d
importance ∈ (0, 1]  set when the memory is extracted, +0.05 each time it's repeated
memories with relevance < 0.08 are never returned

All of these settings live in ScoringConfig. Setting a weight to 0 switches that factor off.

Design decisions and trade-offs

  • Weights are exponents in a product, not terms in a sum. In an additive blend (as in the Generative Agents paper), a very recent but irrelevant memory can outrank a relevant one. Multiplying means a memory has to be relevant to score at all, and an exponent works just like a weight: 0 turns it off, 2 makes it count more. The recency floor keeps old but still-true facts from decaying to zero. Your name doesn't stop being your name after six months.

  • The predicate registry decides whether a new value conflicts. Contradiction handling depends on whether a predicate holds one value or many. lives_in holds one, so a new city replaces the old one. likes holds many, so a new like doesn't replace anything. The registry fixes this for known predicates. For predicates it doesn't know, the LLM's exclusive flag decides, because one model call is a noisier judge than a fixed schema.

  • Old facts are superseded, not overwritten. A replaced fact stays in the table with valid_to, superseded_by and its source_id episode. You can still answer "where did I live before?" and audit why the agent believes something. forget() deletes the whole version chain, because "forget where I live" shouldn't leave the previous address behind.

  • Every turn is stored as an episode, even when extraction fails. If extraction misses something or the LLM returns junk, no information is lost, and the raw turn can still be found by search.

  • The mock extractor would rather miss a fact than invent one. A wrongly extracted fact can supersede a true one, which does more damage than a fact that was never extracted. "My sister lives in Paris" and "I used to live in Rome" are deliberately ignored, and there are tests to keep it that way.

  • Search combines keyword (FTS5) and vector matching. Keyword search catches exact names like "Acme" that a hashing embedder blurs together. Vectors with character trigrams catch inflections and small typos. Both sides go through the same stemmer, because a mismatch there is a classic way for search to silently miss things. User text is always quoted before it reaches FTS5, so it can't inject query syntax.

  • Facts go at the end of the context. Raw past conversation comes first, then rules, then the reconciled current facts, under the heading authoritative. Models pay more attention to the end of the context, so the reconciled facts should win.

  • The LLM call happens outside the write transaction. Extraction can take seconds, and SQLite allows only one writer at a time. The transaction (BEGIN IMMEDIATE) covers only the dedup check and the insert.

  • No vector database. One SQLite file holds everything, so backups, inspection with the sqlite3 CLI and running entirely offline are trivial. The cost is the linear scan described under limitations.

  • MCP without the SDK. The wire format is small and stable. Implementing it directly keeps the install to numpy, and the stdio test checks that nothing except protocol messages reaches stdout.

Benchmark

mnemo eval --sweep (about 20 s on a laptop) writes benchmarks/results.json. The dataset is a seeded, scripted set of multi-session dialogues (src/mnemo/bench/dataset.py):

  • 12 personas, 6 sessions each, 3 days apart. That's 1,264 turns and about 2,100 tokens of history per persona.

  • Facts come up in sessions 1–2. A city, employer, favourite food, diet or car changes in a later session, which accounts for 35 of the 124 questions.

  • Every session is padded with off-topic requests and distractors that look like facts but aren't the user's ("My sister lives in Lyon", "I used to live in Rome", "My friend works at Initech").

  • After the last session, there's one question per fact, worded one of two ways. The second wording shares fewer words with the stored fact ("Who is the user's current employer?").

Grading: an answer is correct only if it contains the latest value and does not contain the old one. All four systems are answered by the same reader.

Results (MockProvider, real numbers from benchmarks/results.json):

system

accuracy

stable facts

updated facts

mean context tokens / question

context build p50

full_history

100.0%

100.0%

100.0%

2104.2

2.5 ms

window_800 (last 800 tokens)

25.0%

0.0%

88.6%

784.4

0.9 ms

mnemo, k=8

100.0%

100.0%

100.0%

112.2

1.05 ms

mnemo, k=8, after consolidation

100.0%

100.0%

100.0%

311.6

0.77 ms

As conversations get longer, mnemo's context stays roughly flat while the full history keeps growing:

sessions

history tokens

full_history acc / tokens

window_800 acc / tokens

mnemo k=8 acc / tokens

6

2102.9

100.0% / 2104.2

25.0% / 784.4

100.0% / 112.2

12

3936.0

100.0% / 3937.2

23.4% / 780.4

100.0% / 117.0

24

7719.8

100.0% / 7719.1

20.8% / 783.1

100.0% / 132.3

How many memories mnemo needs to return (a test of the ranking itself):

mnemo k

accuracy

updated-fact accuracy

mean context tokens

1

98.4%

100.0%

26.5

2

100.0%

100.0%

42.2

4

100.0%

100.0%

71.1

8

100.0%

100.0%

112.2

At k=1 there are two misses, both on "What is the name of the user's pet?". The word name pulls in user | name | Priya, which outranks the pet fact. Once k is 2 or more, the right fact is always returned.

Write path: remember() takes 0.19 ms at p50 and 0.61 ms at p95 with the mock extractor. Consolidation cut active episodes from 1,264 to 358. The summaries then get retrieved alongside facts, which is why context grows to 312 tokens. It's a trade-off: you keep less raw text, but each recall returns more.

What the numbers do and don't show

  • The mock reader is a perfect extractive reader. It replays every assertion it can parse, and later ones win. So full_history is an upper bound, and the table isolates what each strategy puts in the context and at what token cost, not how well an LLM reads it. With a real LLM, a long history also runs into "lost in the middle" and stale-fact confusion, which this eval doesn't measure. I didn't run it against a live model for this release (no API key in the build environment). The harness supports it: mnemo eval --provider anthropic.

  • mnemo moves token spend from reading to writing. If an LLM did the extraction, the harness estimates that would cost about 92k tokens for the 632 user turns, roughly 146 per turn, paid once. In this run that's well below what it saves on reads, (2104 − 112) × 124 ≈ 247k tokens for a single pass of questions. The savings grow with every additional question and every additional session.

  • The dialogues come from templates, and the mock extractor was written against the same kinds of phrasing. A test checks that every template can be extracted, so the eval measures memory rather than parsing luck. Even so, real conversations are messier. That's what the LLM extractor is for.

  • The token counter is approximate (approx_tokens: one token per word or punctuation mark). It's applied identically to every system, so the ratios are meaningful even though the absolute counts are approximate.

Limitations

  • Vector search is a linear scan. Recall loads the namespace's vectors and runs a numpy matrix product. That's fine up to tens of thousands of memories per namespace. Past that you'd want an ANN index (sqlite-vec or FAISS).

  • The default embedder isn't semantic. HashingEmbedder won't link "spouse" to "wife". mnemo makes up for it with keyword lists attached to each known predicate. For open-domain recall, plug in a real embedding model (anything with embed() and dim; the DB records which embedder built it and refuses to mix them).

  • The mock extractor only understands first-person English in common phrasings. Use an LLM provider for anything beyond that.

  • Only one namespace owner is treated as "user". Facts about other people do work (add_fact("Ana", "works_at", ...)), but the mock extractor doesn't produce them.

  • Conflicts are detected per key, not by meaning. "I live in Berlin" vs "I'm based in Germany" isn't flagged as a conflict.

  • There's no authentication on the MCP server. It relies on stdio, so whoever launches the process has access.

Roadmap

  • Optional sqlite-vec backend for ANN search

  • OpenAI-compatible embeddings provider (Ollama nomic-embed-text, etc.)

  • Run the eval against a real LLM, as both reader and extractor, and publish the numbers

  • Temporal queries ("where did I live in March?") using valid_to

  • Use the LLM to resolve conflicts between different predicates

  • MCP resources (browse facts) and a memory:// URI scheme

  • Streamable HTTP transport for the MCP server

Development

pip install -e '.[dev]'
pytest -q
python examples/quickstart.py
python examples/mcp_client_demo.py
mnemo eval --sweep --out benchmarks/results.json

CI runs the test suite on Python 3.11, 3.12 and 3.13.

License

MIT © 2026 Lijo Ferdinand

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to store and semantically retrieve durable memories across sessions via MCP or REST, with tools for remembering, recalling, asking, updating, and forgetting memories.
      17 npm
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Enables Claude Code and other MCP-capable agents to turn conversations into structured long-term memories, deciding whether each extracted fact is new, an update, or already known while preserving superseded history. It also lets agents recall the right facts through hybrid keyword and entity-graph search, list what is stored, and permanently forget entries.
      5
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables MCP clients such as Claude Code and Claude Desktop to keep long-term memory: store facts with remember, retrieve them with recall, and submit feedback so rankings adapt to which memories actually helped across tasks. It also infers outcomes when feedback is skipped, retiring replaced facts and demoting useless look-alikes while staying within a token budget.
      1
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables any MCP-compatible client to persist long-term memories for AI agents, with LLM-based fact extraction, semantic vector search, update/delete/list operations, and queue status checks across sessions.
      Apache 2.0