Mnemon — Persistent Layered Memory for AI Agents

Persistent layered memory for AI agents.Local-first. Zero-cloud. Single SQLite file.

Your AI agent forgets everything after each session. Mnemon fixes that.

It gives anyMCP-compatible client —OpenClaw, Claude Code, Cursor, Windsurf, or your own — a structured long-term memory backed by a single SQLite database on your machine. No API keys, no cloud, no telemetry. Justnpm installand your agent remembers.

Retrieval is measured against a 50-case golden set on a real 797-memory bilingual (RU/EN) corpus, through the actual MCP server — not a reimplementation. Current numbers (methodology & history):

The eval doc tracks the failures too — score drift under corpus growth, the BM25 field-weight bug the eval caught, the two cases where fusion still loses to pure lexical search, and what the golden set doesnotcover. Numbers you can't audit are marketing;read how these are produced.

flowchart LR C["MCP client<br/>Claude Code · Cursor · …"] -- "stdio / HTTP" --> T["10 tools · 4 resources · 3 prompts"] T --> R["retrieval pipeline<br/>FTS5 · vector · RRF fusion"] T --> M["memories + supersede chains"] I["KB import pipeline<br/>markdown → memories"] --> M M -- triggers --> F["FTS5 index (stemmed EN+RU)"] R --> F R --> V["sqlite-vec (optional, BYOK)"]

One SQLite file holds memories, the FTS5 index, and the optional vector index. Writes go through transactions that keep the supersede-chain invariant; reads run the staged retrieval pipeline described underSearch.

The full picture — module boundaries, write/read paths, invariants, and known limitations — is indocs/ARCHITECTURE.md. Design decisions are recorded as ADRs:SQLite+FTS5 core,hybrid RRF retrieval,synchronous driver,layered memory model.

git clone https://github.com/nikitacometa/mnemon-memory-mcp.git cd mnemon-memory-mcp && npm install && npm run build

openclaw mcp register mnemon-mcp --command="mnemon-mcp"

{ "mnemon-mcp": { "command": "mnemon-mcp" } }

{ "mcpServers": { "mnemon-mcp": { "command": "mnemon-mcp" } } }

{ "mcpServers": { "mnemon-mcp": { "command": "mnemon-mcp" } } }

{ "mnemon-mcp": { "command": "node", "args": ["/absolute/path/to/mnemon-mcp/dist/index.js"] } }

echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | mnemon-mcp

You should see 10 tools in the response. The database (~/.mnemon-mcp/memory.db) is created automatically on first run.

That's it. Your agent now has persistent memory.

Resources— live data your agent can read:

Four modes, all supporting layer / entity / scope / date / confidence filters:

FTS mode(default without embeddings) — tokenized full-text search with BM25 ranking. Multi-word queries use AND; if too few results, OR supplements with a score penalty. Progressive AND relaxation tries top-3 most specific terms before falling back to full OR.

Hybrid mode(default when embeddings configured) — combines FTS5 + vector search viaReciprocal Rank Fusion. Detects quoted entities in queries (e.g.,'Essentialism') and runs weighted sub-queries for cross-reference retrieval.

v1: "Team uses React 17" → superseded_by: v2 v2: "Team uses React 19" → supersedes: v1 (active)

# OpenAI MNEMON_EMBEDDING_PROVIDER=openai MNEMON_EMBEDDING_API_KEY=sk-... mnemon-mcp # Ollama (local, free) MNEMON_EMBEDDING_PROVIDER=ollama mnemon-mcp

- mode: "vector"— pure cosine similarity search
- mode: "hybrid"— FTS5 + vector combined viaReciprocal Rank Fusion

cp config.example.json ~/.mnemon-mcp/config.json # edit this first npm run import:kb -- --kb-path /path/to/your/kb # incremental (skips unchanged files)

{ "owner_name": "your-name", "extra_stop_words": [], "mappings": [ { "glob": "journal/.md", "layer": "episodic", "entity_type": "user", "entity_name": "$owner", "importance": 0.6, "split": "h2" }, { "glob": "people/.md", "layer": "semantic", "entity_type": "person", "entity_name": "from-heading", "importance": 0.8, "split": "h3" } ] }

MNEMON_AUTH_TOKEN=your-secret MNEMON_HOST=0.0.0.0 MNEMON_PORT=3000 npm run start:http

Binds to127.0.0.1by default. Binding to any other host requiresMNEMON_AUTH_TOKEN— the server refuses to expose the memory store to the network unauthenticated (override withMNEMON_ALLOW_INSECURE_HTTP=1on a trusted network). Rate limiting (100 req/min/IP by default), opt-in CORS, 1MB body limit, timing-safe auth, graceful shutdown on SIGTERM.

Returns: status (healthy/warning/degraded), per-layer stats, expired entries, orphaned chains, stale/low-confidence counts, cleaned count whencleanup=true.

Returns:id(session UUID),started_at(ISO 8601).

Returns:id,ended_at,duration_minutes,memories_count.

Returns: array of sessions withid,client,project,started_at,ended_at,summary,memories_count.

Extended competitive analysis with sources:docs/COMPETITORS.md.

npm run dev # run via tsx (no build step) npm run build # TypeScript → dist/ npm run lint # eslint (flat config) npm test # vitest — unit + integration + MCP dispatch + HTTP transport + hybrid RRF npm run bench # performance benchmarks npm run db:backup # backup database

SeeCONTRIBUTING.mdfor code guidelines.

- Air-gapped by default— zero telemetry, ever. Out of the box nothing leaves the machine; the only component that talks to the network is the optional embedder, and only to the provider you configure (including a local Ollama).
- Single file— one SQLite database, zero ops, instant backup via file copy.
- Deterministic search— FTS5, not embeddings, is the default. Interpretable, reproducible, no GPU needed.
- Structured over flat— layers encode access patterns; superseding chains encode time.
- Minimal— 4 production dependencies. Works everywhere Node runs.
- Measured, not asserted— retrieval changes are judged against a golden set,regressions included.

[VEKTOR Memory] (https://vektormemory.com) - Local-first persistent memory for AI agents. SQLite-vec, 4-layer associative graph, 8ms recall, 34 tools. No cloud.

An intelligent memory management server with 14 optimized tools. It provides AI-powered summaries, a clean interface, and supports an optional PostgreSQL database with pgvector.

A memory system for the Cursor code editor, providing persistent context awareness for Claude via a Turso database.

A TypeScript and SQLite-based server enabling AI to remember personal data for personalized communication.

MCP-native memory layer for Claude Code, Cursor, Cline, Continue, and 16 other AI tools. Hybrid search (BM25 + pgvector + graph), self-hosted on Supabase + Vercel, 100% MIT, no paywall.

Engram is a hosted MCP server that provides reliable memory for AI agents:

Persistent memory, teams, and projects for AI agents. 76 MCP tools for storing, recalling, and sharing knowledge across sessions.

Provides persistent memory for AI systems to enable continuity of consciousness, using an external PostgreSQL database.

Agent Memory as a Service with x402 USDC micropayments on Base blockchain — provides memory_store, memory_recall, memory_forget, and memory_stats tools.

Provides AI assistants with persistent memory using ChromaDB vector storage.