mnemotree
Memory module for LLMs and Agents with MCP
Install / Use
claude mcp add kurcontko -- npx -y github:kurcontko/mnemotreeIf the server publishes to npm under a different name, use that package instead — check the repo README.
MCP Server
Model Context Protocol server
Quality Score
Category
AI & Machine LearningSupported Platforms
Our assessment of mnemotree
mnemotree scores 76/100 on our quality scale, 819th of 950 AI & Machine Learning skills we index.
Its MCP Server is 10 KB long, well organised into 14 sections with 8 code examples: a thorough specification that gives an agent plenty to work with.
It has 10 GitHub stars, so there is little community track record yet; judge it on its content.
Maintenance, license and trust
- The repository was last updated 2 days ago, so mnemotree is actively maintained.
- It is released under the MIT license, a permissive license that allows use, modification and commercial use with attribution.
- Its trust signals score 92/100, with 1 caution from licensing, adoption, age or documentation. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.
mnemotree compared with similar skills
All 4 of these similar skills score higher than mnemotree; compare them before choosing.
| Skill | Score | Stars | Updated | Format |
|---|---|---|---|---|
| mnemotree (this skill)by kurcontko | 76 | 10 | 2d ago | MCP Server |
| claude-memby thedotmack | 100 | 119.0k | today | CLAUDE.md |
| Agent-Reachby Panniantong | 100 | 114.0k | today | CLAUDE.md |
| Understand-Anythingby Egonex-AI | 100 | 93.7k | today | CLAUDE.md |
| hyperframesby heygen-com | 100 | 88.2k | today | CLAUDE.md |
Frequently asked questions
- How do I install mnemotree?
- Run
claude mcp add kurcontko -- npx -y github:kurcontko/mnemotree. The install tabs above show the steps for each supported agent. - Which AI agents does mnemotree work with?
- It is written for Claude Code and Claude Desktop, as a MCP Server file. Other agents that read the same format can often use it too.
- Is mnemotree safe to use?
- It is MIT-licensed and scores 92/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
- Is mnemotree still maintained?
- The repository was last updated 2 days ago, so mnemotree is actively maintained.
Skill content
View source on GitHub🌳 Mnemotree
Local, source-first memory for LLM agents: SQLite, FTS5 and sqlite-vec.
<p align="center"> <img src="assets/mnemotree-logo.png" alt="Mnemotree Logo" width="300"> </p>Mnemotree keeps every message exactly as written and recalls attributed source spans instead of rewritten summaries.
- Durable: sources, chunks, both indexes and an idempotency receipt commit in one transaction.
- Hybrid: FTS5 BM25 and sqlite-vec cosine search, fused with RRF, with optional reranking.
- Bounded: evidence is packed into an exact token budget, with a trace of every candidate, rank and packing loss.
- Isolated: every read and write is scoped to one namespace.
The default install needs only Pydantic, sqlite-vec and tiktoken. See Benchmarks for the Agent Memory Leaderboard result and end-to-end results on LoCoMo and LongMemEval.
Install
pip install mnemotree
Python's sqlite3 must support loadable extensions and FTS5. Tiktoken downloads its
vocabulary once; see the guide to run offline.
| Extra | Adds |
| --- | --- |
| embeddings | OpenAI-compatible HTTP embedder and extractor |
| lite | Local SentenceTransformer embedder |
| serve | HTTP service: AML Add/Search, plus routes to list, read and delete memories |
| all | All of the above |
Quickstart
import asyncio
from mnemotree import Memory
async def main():
with Memory("memory.sqlite", namespace="alice") as memory: # lexical without an embedder
await memory.remember("I grow orchids on my balcony.", role="user")
recall = await memory.recall("orchids")
print(recall.context) # packed, attributed evidence
print([item.id for item in recall.items], recall.trace.packed_tokens)
asyncio.run(main())
Memory binds one namespace and offers remember, remember_many, recall, get
and forget. Pass an embedder for hybrid retrieval.
Benchmarks
<a href="https://agentmemoryleaderboard.ai/results/cycle-2/#academic-textual"> <img src="assets/aml-cycle2-textual-open-source.png" alt="AML Cycle 2: mnemotree second in Textual Memory, open-source methods, score 60.81" width="560"> </a>On the Agent Memory Leaderboard Cycle 2 (2026), mnemotree placed second in Textual Memory with 60.81, 0.41 behind first.
These scores measure end-to-end question answering with the v1.0.0 engine.
Mnemotree packs at most 8,000 tokens of evidence per question. gpt-4o-mini answers
from that evidence and also judges the answer. Embeddings come from DashScope
text-embedding-v4 at 1,024 dimensions. Retrieval fuses BM25 and vector search
with RRF and adds the neighboring messages around each hit. No LLM runs inside
Mnemotree.
| Benchmark | Questions | Mnemotree | Published, gpt-4o-mini answering | | --- | ---: | ---: | --- | | LoCoMo, categories 1 to 4 | 1,540 | 72.1 | Full context (26K tokens) 72.9, Mem0 with graph 68.4, Mem0 66.9, Zep 66.0, LangMem 58.1 (Mem0 paper, Table 2) | | LongMemEval-S | 500 | 60.8 | Zep 63.8, full context (115K tokens) 55.4 (Zep paper, Table 2) |
On LoCoMo-Refined, a cleaned release of LoCoMo with 1,382 questions, Mnemotree scores 78.7 with the official scorer, which judges with Qwen3-14B. That run used Nemotron-3-Embed-8B embeddings.
On BEAM we ran BEAM's own answer and scoring code, with gpt-4.1-nano answering and gpt-4.1-mini judging. We also ran BEAM's RAG baseline in the same harness. Its scores under the paper-era scorer match the paper's Table 1.
| BEAM conversation length | Questions | Mnemotree | BEAM RAG, same harness | | --- | ---: | ---: | ---: | | 100K tokens | 400 | 37.7 | 32.5 | | 500K tokens | 700 | 41.2 | 33.4 | | 1M tokens | 700 | 38.5 | 31.8 | | 10M tokens | 200 | 29.9 | 21.9 |
Mnemotree used Qwen3-Embedding-4B embeddings here. With the RAG baseline's own bge-small embedder it still leads at every length.
Each score is a single run of ours. The published rows are the authors' own runs with their own prompts and judges, and the Zep paper judges LongMemEval with gpt-4o. docs/BENCHMARKS.md has the setup, the method, how to size the evidence budget and the limitations. The evaluation harness is not in this repository yet.
MCP server
mnemotree-mcp gives Claude Code, Claude Desktop, Codex and other MCP clients the
same five tools over stdio, with semantic search on a local embedding model. It
needs no API key or configuration:
claude mcp add mnemotree -- uvx mnemotree-mcp
The first start downloads the English-only
granite-embedding-small-english-r2
model (about 200 MB) to ~/.mnemotree/models; the server answers while it loads.
| Setting | Flag | Default |
| --- | --- | --- |
| MNEMOTREE_DB | --db | ~/.mnemotree/memory.sqlite |
| MNEMOTREE_NAMESPACE | --namespace | default |
| MNEMOTREE_CONFIG | --config | local model |
| MNEMOTREE_LEXICAL=1 | --lexical | off |
uvx mnemotree-mcp --lexical # keyword-only, no model download
uvx mnemotree-mcp --config ~/.mnemotree/config.json # e.g. an HTTP embedder
Sessions pointed at the same database share one memory. With pip install mnemotree,
mnemotree mcp runs the same server, but with no default model: pass --config or
--lexical.
HTTP service
The serve extra runs memory as a small HTTP API. Add and Search follow the
Agent Memory Leaderboard API; four more
routes read and delete what is stored. Without --config it is lexical-only.
pip install 'mnemotree[serve]'
export MNEMOTREE_API_KEY='repl…[redacted]'
mnemotree-evidence --db service.sqlite serve --port 8000
KEY="Authorization: Bearer $MNEMOTREE_API_KEY"
curl -s localhost:8000/v1/memories/add -H "$KEY" -H 'Content-Type: application/json' -d '{
"request_id": "r1", "user_id": "alice", "session_id": "s1",
"messages": [{"role": "user", "content": "I moved to Warsaw last spring"}]}'
# {"success": true, ..., "ids": ["67fd494a..."]}
curl -s localhost:8000/v1/memories/search -H "$KEY" -H 'Content-Type: application/json' \
-d '{"user_id": "alice", "query": "Where did I move?", "top_k": 5}'
# {"data": [{"id": "...", "content": "user: I moved to Warsaw last spring",
# "score": 0.016, "source_ids": ["67fd494a..."]}]}
| Route (all POST) | Body | Returns |
| --- | --- | --- |
| /v1/memories/add | request_id, user_id, session_id, messages | ids of the stored messages |
| /v1/memories/search | user_id, query, top_k | ranked passages with their source_ids |
| /v1/memories/get | user_id, ids (up to 100) | the stored messages, and missing |
| /v1/memories/list | user_id, optional session_id, limit, cursor | a page of messages, oldest first, and next_cursor |
| /v1/memories/stats | user_id | counts of memories, chunks and Add requests |
| /v1/memories/delete | user_id, id | deleted: true or false |
Every route but GET /health needs the key, as Authorization: Bearer,
Authorization: Token or X-Api-Key. Memory IDs are unique within a user, so get
and delete always take the user_id. Blank messages are skipped and get no ID.
The service is built for one trusted caller: run it behind your own backend, which
authenticates your users and holds the key. user_id keeps users' data apart but is
not access control, and anyone with the key can read and delete every user's
memories. The guide has the full contract,
the search defaults and a Docker deployment.
Command line
# Retrieval evaluation on the bundled plumbing example (needs a fresh database).
mnemotree-evidence --db demo.sqlite --config examples/evidence/lexical.json \
evaluate examples/evidence/corpus.jsonl examples/evidence/queries.jsonl \
--output demo-results.json
mnemotree-evidence also runs add, search, serve (the HTTP service above), and
the ablate, ablate-context and ablate-retrieval comparisons.
Documentation
docs/GUIDE.md covers the API contract, MCP configuration, embeddings, storage and retrieval behavior, atomic projections, the AML service, evaluation and limits. docs/BENCHMARKS.md records how the benchmark numbers were produced and what they leave out.
Releases up to 0.4.0 shipped MemoryCore, pluggable vector/graph backends and an
older MCP server. They have been removed, and Memory does not read their databases.
See upgrading from 0.4.0 in the
release notes for API and compatibility changes.
Development
git clone https://github.com/kurcontko/mnemotree.git
cd mnemotree
uv sync --extra dev --extra serve
make lint typecheck test
make build
make precommit-install
See CONTRIBUTING.md.
License
MIT, see LICENSE.
Related Skills
claude-mem
119.0kPersistent Context Across Sessions for Every Agent – Captures everything your agent does during sessions, compresses it with AI, and injects relevant context back into future sessions. Works with Claude Code, OpenClaw, Codex, Gemini, Hermes, Copilot, OpenCode + More
Agent-Reach
114.0kGive your AI agent eyes to see the entire internet. Read & search Twitter, Reddit, YouTube, GitHub, Bilibili, XiaoHongShu — one CLI, zero API fees.
Understand-Anything
93.7kGraphs that teach > graphs that impress. Turn any code into an interactive knowledge graph you can explore, search, and ask questions about. Works with Claude Code, Codex, Cursor, Copilot, Gemini CLI, and more.
hyperframes
88.2kAI video you can actually edit. HyperFrames is a free, open-source AI video editor. Describe any video and get a real project you can change down to the frame.
Languages
Trust signals
From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.
