mnemon-mcp
Persistent layered memory for AI agents. Local-first. Zero-cloud. Single SQLite file.
Potencia tu agente
El comando propio del publicador. No es un endpoint de PlugMCP.
Host a copy with our keys and logs.
npx -y [email protected]Claude Code no tiene enlace de instalación para un comando local. Copia el comando de abajo y ejecútalo en una terminal.
MNEMON_DB_PATH=<value> MNEMON_EMBEDDING_PROVIDER=<value> MNEMON_EMBEDDING_API_KEY=<secret> claude mcp add io.github.nikitacometa-mnemon-mcp -- npx -y mnemon-mcp@1.0.1Ejecútalo en una terminal.
{ "mcpServers": { "io.github.nikitacometa-mnemon-mcp": { "command": "npx", "args": [ "-y", "[email protected]" ], "env": { "MNEMON_DB_PATH": "<value>", "MNEMON_EMBEDDING_PROVIDER": "<value>", "MNEMON_EMBEDDING_API_KEY": "<secret>" } } }}claude_desktop_config.json
¿URL remota o un comando en tu máquina? En qué se diferencian las dos instalaciones
Ejecutar en PlugMCP
A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.
AbrirLanding Page · npm · GitHub
Your AI agent forgets everything after each session. Mnemon fixes that.
npm install and your agent remembers.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 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.
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 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.
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
openclaw mcp register mnemon-mcp --command="mnemon-mcp"
Or add to ~/.openclaw/mcp_config.json:
{
"mnemon-mcp": {
"command": "mnemon-mcp"
}
}
Add to ~/.claude/mcp.json:
{
"mcpServers": {
"mnemon-mcp": {
"command": "mnemon-mcp"
}
}
}
Add to your client's MCP config:
{
"mcpServers": {
"mnemon-mcp": {
"command": "mnemon-mcp"
}
}
}
Use the full path to the compiled entry point:
{
"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:
Prompts — pre-built workflows:
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.
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.
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.
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 searchmode: "hybrid" — FTS5 + vector combined via Reciprocal Rank FusionRequires sqlite-vec (installed as optional dependency). New memories are embedded on add; existing ones can be backfilled.
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"
}
]
}
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.
Returns: status (healthy / warning / degraded), per-layer stats, expired entries, orphaned chains, stale/low-confidence counts, cleaned count when cleanup=true.
Returns: id (session UUID), started_at (ISO 8601).
Returns: id, ended_at, duration_minutes, memories_count.
Returns: array of sessions with id, 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
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.
Persistent layered memory for AI agents. SQLite FTS5, fact versioning, zero-cloud.
{ "mcpServers": { "io.github.nikitacometa-mnemon-mcp": { "command": "npx", "args": [ "-y", "[email protected]" ], "env": { "MNEMON_DB_PATH": "<value>", "MNEMON_EMBEDDING_PROVIDER": "<value>", "MNEMON_EMBEDDING_API_KEY": "<secret>" } } }}Herramientas
Aún no hay lista de herramientas. Los servidores remotos la reciben tras la primera comprobación de estado.
Preguntas frecuentes
Copia en esta página la configuración stdio para Cursor, Claude Desktop, Claude Code o VS Code. Usa la instalación del publicador, no un proxy de PlugMCP.
El publicador indica estas variables de entorno: MNEMON_DB_PATH, MNEMON_EMBEDDING_PROVIDER, MNEMON_EMBEDDING_API_KEY.
Mnemon se ejecuta localmente por stdio.
Última comprobación: 2026-11-10. Persistent layered memory for AI agents. SQLite FTS5, fact versioning, zero-cloud.