mnemon-mcp

Persistent layered memory for AI agents.

Local-first. Zero-cloud. Single SQLite file.

Landing Page · npm · GitHub

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

It gives any MCP-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. Just `npm install` and your agent remembers.

Why Layered Memory?

Flat key-value stores treat "what happened yesterday" the same as "never commit without tests." That's wrong — different kinds of knowledge have different lifetimes and access patterns.

Mnemon organizes memories into four layers:

A journal entry from last Tuesday and a coding rule that never changes live in different layers — because they should.

Retrieval Quality

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):

Hybrid beats both legs individually, which is the whole argument for

fusing them: lexical search has the better raw recall, vector search the

better ranking, and RRF keeps both instead of averaging them away.

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 does *not* cover. Numbers you

can't audit are marketing; read how these are produced.

Architecture

flowchart LR
    C["MCP clientClaude Code · Cursor · …"] -- "stdio / HTTP" --> T["10 tools · 4 resources · 3 prompts"]
    T --> R["retrieval pipelineFTS5 · vector · RRF fusion"]
    T --> M["memories + supersede chains"]
    I["KB import pipelinemarkdown → 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 under Search.

The full picture — module boundaries, write/read paths, invariants, and known

limitations — is in docs/ARCHITECTURE.md. Design

decisions are recorded as ADRs: SQLite+FTS5 core,

hybrid RRF retrieval,

synchronous driver,

layered memory model.

Quick Start

Install

npm install -g mnemon-mcp

Or from source:

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

Configure Your MCP Client

OpenClaw

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

Or add to `~/.openclaw/mcp_config.json`:

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

Claude Code

Add to `~/.claude/mcp.json`:

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

Cursor / Windsurf / Other MCP clients

Add to your client's MCP config:

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

Running from source?

Use the full path to the compiled entry point:

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

Verify

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.

What It Can Do

10 MCP Tools

MCP Resources & Prompts

Resources — live data your agent can read:

Prompts — pre-built workflows:

Search

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 via Reciprocal Rank Fusion. Detects quoted entities in queries (e.g., `'Essentialism'`) and runs weighted sub-queries for cross-reference retrieval.

Vector mode — pure cosine similarity search over embeddings.

Exact mode — `LIKE` substring match for precise phrase lookups.

Scores: `bm25 × (0.3 + 0.7 × importance) × decay(layer) × recency`

Recency boost: `1 / (1 + daysSince / 365)` — gently rewards recently created memories without penalizing old ones.

Stemming

Snowball stemmer applied at both index time and query time for English and Russian. This means `"running"` matches `"runs"`, and `"книги"` matches `"книга"`. Stop words are filtered from queries to improve precision.

Fact Versioning

Knowledge evolves. Mnemon doesn't delete old facts — it chains them:

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

Search returns only the latest version. `memory_inspect` with `include_history: true` reveals the full chain. `memory_delete` re-activates the predecessor — nothing is lost.

Vector Search (Optional, BYOK)

Enable semantic similarity search by providing your own embedding API:

# OpenAI
MNEMON_EMBEDDING_PROVIDER=openai MNEMON_EMBEDDING_API_KEY=sk-... mnemon-mcp

# Ollama (local, free)
MNEMON_EMBEDDING_PROVIDER=ollama mnemon-mcp

This unlocks two additional search modes:

• `mode: "vector"` — pure cosine similarity search
• `mode: "hybrid"` — FTS5 + vector combined via Reciprocal Rank Fusion

Requires `sqlite-vec` (installed as optional dependency). New memories are embedded on add; existing ones can be backfilled.

Embedding configuration

Importing a Knowledge Base

Got a folder of Markdown files? Import them in bulk:

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)

The config maps glob patterns to memory layers:

{
  "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"
    }
  ]
}

Config Fields

HTTP Transport

For remote or multi-client setups:

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

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

Configuration Reference

Tool Reference

memory_add — full parameter list

memory_search — full parameter list

memory_update — full parameter list

memory_delete

memory_inspect

memory_export

memory_health

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

memory_session_start

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

memory_session_end

Returns: `id`, `ended_at`, `duration_minutes`, `memories_count`.

memory_session_list

Returns: array of sessions with `id`, `client`, `project`, `started_at`, `ended_at`, `summary`, `memories_count`.

How It Compares

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

Development

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

CI runs build + lint + tests on Node 20 and 22, then smoke-tests the compiled

server over real JSON-RPC (`tools/list` must match the exact tool set).

Stack: TypeScript 5.9 (strict mode), better-sqlite3, @modelcontextprotocol/sdk, Snowball stemmer, Zod, vitest.

See CONTRIBUTING.md for code guidelines.

Design Principles

• 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.

License

MIT