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.

<p align="center"> <img src="demo/mnemon-demo.gif" alt="mnemon-mcp demo — memory_add, memory_search, memory_inspect, memory_update" width="800"> </p>

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.

Quick Start

Install

npm install -g mnemon-mcp

Or from source:

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

Configure Your MCP Client

<details open> <summary><strong>OpenClaw</strong></summary>

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

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

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

</details>

<details> <summary><strong>Claude Code</strong></summary>

Add to ~/.claude/mcp.json:

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

</details>

<details> <summary><strong>Cursor / Windsurf / Other MCP clients</strong></summary>

Add to your client's MCP config:

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

</details>

<details> <summary><strong>Running from source?</strong></summary>

Use the full path to the compiled entry point:

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

</details>

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.

<details> <summary>Embedding configuration</summary>

</details>

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_PORT=3000 npm run start:http

Rate limiting (100 req/min/IP by default), CORS headers, 1MB body limit, timing-safe auth, graceful shutdown on SIGTERM.

Configuration Reference

Tool Reference

<details> <summary><code>memory_add</code> — full parameter list</summary>

</details>

<details> <summary><code>memory_search</code> — full parameter list</summary>

</details>

<details> <summary><code>memory_update</code> — full parameter list</summary>

</details>

<details> <summary><code>memory_delete</code></summary>

</details>

<details> <summary><code>memory_inspect</code></summary>

</details>

<details> <summary><code>memory_export</code></summary>

</details>

<details> <summary><code>memory_health</code></summary>

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

</details>

<details> <summary><code>memory_session_start</code></summary>

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

</details>

<details> <summary><code>memory_session_end</code></summary>

Returns: id, ended_at, duration_minutes, memories_count.

</details>

<details> <summary><code>memory_session_list</code></summary>

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

</details>

How It Compares

Development

npm run dev        # run via tsx (no build step)
npm run build      # TypeScript → dist/
npm test           # vitest (229 tests)
npm run bench      # performance benchmarks
npm run db:backup  # backup database

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

See CONTRIBUTING.md for code guidelines.

Design Principles

• Air-gapped — zero network calls, zero telemetry. Your memories stay on your machine.
• 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.

License

MIT