mnemo
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
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.
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 |
|
semantic | facts as subject-predicate-object triples, with a version and a source |
|
procedural | standing rules and preferences |
|
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.pyYou 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 promptReal 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 serveClaude 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 |
| nothing to set up | deterministic pattern extraction, extractive summaries and answers; used by the tests and the eval |
|
| default model |
|
| plain |
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 versionsmodule | what it does |
| the |
| schema, FTS5 triggers, transactions ( |
| the ranking formula (documented below) |
| the deterministic pattern extractor, plus a validator for LLM JSON |
| predicate registry: whether each one holds one value or many, how it's phrased, extra search keywords |
|
|
| the stdio JSON-RPC 2.0 MCP server |
| 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 returnedAll 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_inholds one, so a new city replaces the old one.likesholds many, so a new like doesn't replace anything. The registry fixes this for known predicates. For predicates it doesn't know, the LLM'sexclusiveflag 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_byand itssource_idepisode. 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
sqlite3CLI 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_historyis 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.
HashingEmbedderwon'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 withembed()anddim; 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-vecbackend for ANN searchOpenAI-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_toUse the LLM to resolve conflicts between different predicates
MCP
resources(browse facts) and amemory://URI schemeStreamable 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.jsonCI 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…
This server cannot be deployed
Maintenance
Related MCP Connectors
Hosted agent memory: store, search, and recall facts across sessions from any MCP client.
Persistent memory for AI agents across Claude, ChatGPT and any MCP client.
Persistent memory for AI assistants. Save once; recall from Claude, ChatGPT, or any MCP client.
Persistent AI memory shared across Claude, ChatGPT, coding agents, and compatible MCP clients.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceEnables 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 npmMIT
- AlicenseAqualityCmaintenanceEnables 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.5MIT
- AlicenseNot gradedqualityBmaintenanceEnables 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.1MIT
- AlicenseNot gradedqualityBmaintenanceEnables 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