Mnemon Mcp

io.github.nikitacometaPublished by GitHub account nikitacometav1.0.1Updated Oct 24, 2026

Persistent layered memory for AI agents. SQLite FTS5, fact versioning, zero-cloud.

VerifiedSTDIODesktop onlyDatabases Knowledge & Memory

Server details

Identifier: io.github.nikitacometa/mnemon-mcp
Transport: STDIO
Runtime: Desktop only
Trust: Verified
Published: Sep 16, 2026

Security note

MCP servers receive tool arguments from a conversation and may perform external actions. Review what a server can do before you enable it, and give it only the access it needs.

The registry verified the GitHub account nikitacometa for this listing. That does not show the account is the product's maker.

SourceWeft's checks cover whether the listing is complete and the endpoint answered; they do not review the server's code or what its tools do.

Add a badge to your README

Show readers this MCP server is listed on SourceWeft. The badge links to this page.

[![Listed on SourceWeft](https://sourceweft.com/badge/mcp/io.github.nikitacometa%2Fmnemon-mcp.svg)](https://sourceweft.com/mcp/io.github.nikitacometa%2Fmnemon-mcp?utm_source=readme&utm_medium=badge)

Overview

AI-generated overview

Gives an AI assistant persistent long-term memory stored in a local SQLite file, with layered memories, versioned facts, and full-text or hybrid search.

What you can do: Mnemon provides ten MCP tools for storing, searching, updating, deleting, inspecting, exporting, and health-checking memories, plus session tracking and knowledge-base import. Memories are organized into episodic, semantic, procedural, and resource layers, and updated facts are kept as superseding chains rather than deleted. Search runs over SQLite FTS5 by default, with optional vector and hybrid modes when an embedding provider is configured. Resources and prompts expose stats, recent memories, and recall or journal workflows.
When to use it: Use it when an assistant should remember facts, preferences, rules, and past sessions across conversations, and you want that memory to stay on your own machine. It suits local-first setups where a single SQLite file is easier to back up and audit than a cloud memory service.
Requirements: Runs as a local stdio process installed from the npm package mnemon-mcp, so Node.js is needed. The SQLite database is created automatically at MNEMON_DB_PATH (default ~/.mnemon-mcp/memory.db). No account or API key is required for the default full-text search; vector or hybrid search needs MNEMON_EMBEDDING_PROVIDER set to openai or ollama, and MNEMON_EMBEDDING_API_KEY for OpenAI. An optional HTTP transport uses MNEMON_AUTH_TOKEN, MNEMON_HOST, and MNEMON_PORT.

Before you install

The memory store holds whatever the assistant writes, so treat the database file as sensitive and back it up deliberately. Vector search sends memory content to the configured embedding provider; with OpenAI that means data leaves the machine, while Ollama can stay local. The optional HTTP transport refuses non-local binding without MNEMON_AUTH_TOKEN, and MNEMON_ALLOW_INSECURE_HTTP=1 disables that protection. Tools can update, delete, and garbage-collect memories, and memory_delete…

Installation

In SourceWeft

Open Mnemon Mcp in the dashboard and add it to a workspace.
Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

mnemon-mcp

[CI] [npm version] [Node.js] [License: MIT]

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.

[mnemon-mcp demo — memory_add, memory_search, memory_inspect, memory_update]

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:

Layer	What it stores	How it's accessed	Lifetime
Episodic	Events, sessions, journal entries	By date or period	Decays (30-day half-life)
Semantic	Facts, preferences, relationships	By topic or entity	Stable
Procedural	Rules, workflows, conventions	Loaded at startup	Rarely changes
Resource	Reference material, book notes	On demand	Decays slowly (90 days)

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

mermaid

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)"]

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.

Quick Start

Install

Or from source:

bash

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

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

Configure Your MCP Client

OpenClaw

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

Claude Code

Add to ~/.claude/mcp.json:

Cursor / Windsurf / Other MCP clients

Add to your client's MCP config:

Running from source?

Use the full path to the compiled entry point:

json

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

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

Verify

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

Tool	What it does
`memory_add`	Store a memory with layer, entity, confidence, importance, and optional TTL
`memory_search`	Full-text or exact search with filters by layer, entity, date, scope, confidence
`memory_update`	Update in-place or create a versioned replacement (superseding chain)
`memory_delete`	Delete a memory; re-activates its predecessor if any
`memory_inspect`	Get layer statistics or trace a single memory's version history
`memory_export`	Export to JSON, Markdown, or Claude-md format with filters
`memory_health`	Run diagnostics: expired entries, orphaned chains, stale memories; optionally GC
`memory_session_start`	Start an agent session — returns session ID for grouping memories
`memory_session_end`	End a session with optional summary; returns duration and memory count
`memory_session_list`	List sessions with filters by client, project, or active status

MCP Resources & Prompts

Resources — live data your agent can read:

URI	Returns
`memory://stats`	Aggregate stats per layer
`memory://recent`	Memories created/updated in last 24h
`memory://layer/{layer}`	All active memories in a layer
`memory://entity/{name}`	All active memories about an entity

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: v2v2: "Team uses React 19"  →  supersedes: v1 (active)

v1: "Team uses React 17"  →  superseded_by: v2v2: "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:

bash

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

# OpenAIMNEMON_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

Variable	Default	Description
`MNEMON_EMBEDDING_PROVIDER`	—	`openai` or `ollama` (unset = disabled)
`MNEMON_EMBEDDING_API_KEY`	—	API key (required for OpenAI)
`MNEMON_EMBEDDING_MODEL`	`text-embedding-3-small` / `nomic-embed-text`	Model name
`MNEMON_EMBEDDING_DIMENSIONS`	`1024` / `768`	Vector dimensions
`MNEMON_OLLAMA_URL`	`http://localhost:11434`	Ollama endpoint

Importing a Knowledge Base

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

bash

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

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

The config maps glob patterns to memory layers:

json

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

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

Field	Type	Description
`owner_name`	string	Your name — used for `$owner` substitution in `entity_name`
`extra_stop_words`	string[]	Words to filter from FTS queries (e.g., your name forms)
`glob`	string	File pattern to match
`layer`	string	Target memory layer
`entity_type`	string	`user` / `person` / `project` / `concept` / `file` / `rule` / `tool`
`entity_name`	string	Literal name, `"$owner"`, or `"from-heading"` (extract from H2/H3)
`split`	string	`"whole"` (one memory per file), `"h2"`, or `"h3"` (split on headings)
`importance`	number	0.0–1.0, affects search ranking
`confidence`	number	0.0–1.0, filterable in search
`scope`	string	Optional namespace

HTTP Transport

For remote or multi-client setups:

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

Variable	Default	Description
`MNEMON_DB_PATH`	`~/.mnemon-mcp/memory.db`	Database path
`MNEMON_KB_PATH`	`.`	Knowledge base root for import
`MNEMON_CONFIG_PATH`	`~/.mnemon-mcp/config.json`	Import config path
`MNEMON_AUTH_TOKEN`	—	Bearer token for HTTP transport
`MNEMON_HOST`	`127.0.0.1`	HTTP transport bind address
`MNEMON_PORT`	`3000`	HTTP transport port
`MNEMON_CORS_ORIGIN`	—	CORS `Access-Control-Allow-Origin` (no CORS headers unless set)
`MNEMON_RATE_LIMIT`	`100`	Max requests per minute per IP (0 = off)

Tool Reference

memory_add — full parameter list

Parameter	Type	Required	Description
`content`	string	Yes	Memory text (max 100K chars)
`layer`	string	Yes	`episodic` / `semantic` / `procedural` / `resource`
`title`	string	No	Short title (max 500 chars)
`entity_type`	string	No	`user` / `project` / `person` / `concept` / `file` / `rule` / `tool`
`entity_name`	string	No	Entity name for filtering
`confidence`	number	No	0.0–1.0 (default 0.8)
`importance`	number	No	0.0–1.0 (default 0.5)
`scope`	string	No	Namespace (default `global`)
`source_file`	string	No	Source file path — triggers auto-supersede of matching entries
`ttl_days`	number	No	Auto-expire after N days
`valid_from` / `valid_until`	string	No	Temporal fact window (ISO 8601)

memory_search — full parameter list

Parameter	Type	Required	Description
`query`	string	Yes	Search text
`mode`	string	No	`fts` (default), `exact`, `vector`, `hybrid`
`layers`	string[]	No	Filter by layers
`entity_name`	string	No	Filter by entity (supports aliases)
`scope`	string	No	Filter by scope
`date_from` / `date_to`	string	No	Date range (ISO 8601)
`as_of`	string	No	Temporal fact filter — facts valid at this date
`min_confidence`	number	No	Minimum confidence
`min_importance`	number	No	Minimum importance
`limit`	number	No	Max results (default 10, max 100)
`offset`	number	No	Pagination offset

memory_update — full parameter list

Parameter	Type	Required	Description
`id`	string	Yes	Memory ID
`content`	string	No	New content
`title`	string	No	New title
`confidence`	number	No	New confidence
`importance`	number	No	New importance
`supersede`	boolean	No	`true` = versioned replacement; `false` (default) = in-place
`new_content`	string	No	Content for superseding entry

memory_delete

memory_inspect

memory_export

Parameter	Type	Required	Description
`format`	string	Yes	`json` / `markdown` / `claude-md`
`layers`	string[]	No	Filter by layers
`scope`	string	No	Filter by scope
`date_from` / `date_to`	string	No	Date range
`limit`	number	No	Max entries (default all, max 10K)

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

Parameter	Type	Required	Description
`limit`	number	No	Max sessions (default 20, max 100)
`client`	string	No	Filter by client
`project`	string	No	Filter by project
`active_only`	boolean	No	Only return sessions that haven't ended (default false)

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

How It Compares

	mnemon-mcp	mem0	basic-memory	Engram	Anthropic KG
Architecture	SQLite FTS5 + vector	Cloud API + Qdrant	Markdown + vector	SQLite FTS5	JSON file
Memory structure	4 typed layers	Flat	Flat	Flat + sessions	Graph
Search	FTS5 + hybrid RRF	Semantic	Hybrid	FTS5	Exact
Fact versioning	Superseding chains	Partial	No	No	No
Stemming	EN + RU (Snowball)	EN only	EN only	None	None
Embeddings	BYOK (OpenAI / Ollama)	Built-in	FastEmbed	None	None
Dependencies	0 required	Qdrant, Neo4j	Python 3.12	Go binary	None
Cloud required	No	Yes	No	No	No
Cost	Free	$19–249/mo	Free	Free	Free
Setup	`npm install -g`	Docker + API keys	pip + deps	Go install	Built-in
License	MIT	Apache 2.0	AGPL	MIT	MIT

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

Development

bash

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 RRFnpm run bench      # performance benchmarksnpm run db:backup  # backup database

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 RRFnpm run bench      # performance benchmarksnpm 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

Source: README.md at commit 4e1a320

Tools

SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

v1.0.1LatestSep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

Reached in the last 30 days25 pts
Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.
Auth declared10 pts
Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.
Tools listed15 pts
Answer tools/list without a credential, or ship a package that starts in a sandbox without one.
DescriptionRequired15 pts
Logo10 pts
Documentation15 pts
License10 pts

Metric	FTS-only	Vector-only	Hybrid (RRF)
Composite score	88.9	89.2	91.7
Recall@5	0.907	0.898	0.919
MRR	0.817	0.832	0.878
nDCG@5	0.816	0.828	0.869
Negative precision	1.000	1.000	1.000

Prompt	Purpose
`recall`	"Tell me everything you know about X"
`context-load`	Load relevant context before starting a task
`journal`	Create a structured journal entry

Endpoint	Description
`POST /mcp`	MCP JSON-RPC (Bearer auth if token set)
`GET /health`	`{"status":"ok","version":"..."}`