mnemo
README.md
# 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.**
[](https://github.com/lijo123ferdinand/mnemo/actions/workflows/ci.yml)


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](#benchmark) · [how it's graded](#what-the-numbers-do-and-dont-show))
---
## 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.
## Quickstart
```bash
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
```python
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:
```bash
claude mcp add mnemo -- mnemo --db ~/.mnemo/mnemo.db --namespace me serve
```
Claude Desktop (`claude_desktop_config.json`, also in [`examples/`](examples/claude_desktop_config.json)):
```json
{
"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`](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`](benchmarks/results.json). The dataset is a seeded, scripted set of multi-session dialogues ([`src/mnemo/bench/dataset.py`](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
```bash
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
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues