🌳 Mnemotree

Local, source-first memory for LLM agents: SQLite, FTS5 and sqlite-vec.

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. This repository does not yet publish reproducible retrieval-quality benchmarks.

Install

pip install mnemotree

This README describes the 0.5 API. When using it before the 0.5 release, install the development version instead:

pip install "mnemotree @ git+https://github.com/kurcontko/mnemotree.git@main"

Python's sqlite3 must support loadable extensions and FTS5. Tiktoken downloads its vocabulary once; see the guide to run offline.

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.

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.

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.

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

# AML Add/Search service with a bearer key (the serve extra).
export MNEMOTREE_API_KEY='replace-with-your-service-key'
mnemotree-evidence --db service.sqlite serve

mnemotree-evidence also runs add, search, 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.

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 the 0.5 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.