Mnemo MCP Server

mcp-name: io.github.n24q02m/mnemo-mcp

Persistent AI memory with hybrid search and embedded sync. Open, free, unlimited.

Table of contents

• Features

• Status

• Documentation

• Tools

• Security

• Build from Source

• Deploy to Cloudflare

• Trust Model

• License

Related MCP server: Better Notion MCP

Roadmap (current = Phase 3 / v2.x)

Features

• Hybrid retrieval -- FTS5 + sqlite-vec, fused via Reciprocal Rank Fusion (k=60), then re-ranked by a configurable rerank chain (RERANK_MODELS, order = litellm fallback; empty -> local qwen3-reranker) with temporal decay and importance boost

• Typed capture -- memory(action="capture") with 6 context_types (conversation/fact/preference/skill/task/decision), embedding-based dedup, and a configurable LLM chain (LLM_MODELS, order = litellm fallback)

• Knowledge graph -- Automatic entity extraction and relation tracking; top results boosted by graph proximity

• Importance scoring + archive policy -- LLM-scored 0.0-1.0 importance; soft-archive when recency_factor * (1 - importance) > 1.0; restore action available

• Auto-archive trigger -- Background sweep every Nth capture (default 100) -- no cron required

• STM-to-LTM consolidation -- LLM summarization of related memories in a category

• Duplicate detection -- Warns before adding semantically similar memories

• Zero config -- Built-in local Qwen3 ONNX embedding + reranking, no API keys needed. Optional cloud providers (Jina AI, Gemini, OpenAI, Cohere)

• Multi-machine sync -- JSONL-based merge sync via Google Drive (bundled Desktop OAuth public client)

• Plugin trinity -- Ships /recall-context + /memory-commit skills and SessionStart + opt-in PostToolUse hooks (see docs/ARCHITECTURE.md)

• Proactive memory -- Tool descriptions and skills guide AI to save preferences, decisions, facts at the right moment

• LLM compression -- Per-turn compression via the multi-provider dispatcher targets ~3x token reduction at >=0.9 fact retention; graceful skip when no provider configured (see docs/compression.md)

• Encrypted passport sync -- AES-256-GCM bundles + Argon2id KDF, S3 (R2 / B2 / MinIO) and Google Drive backends, delta-sync with last-write-wins per row (see docs/passport.md). Bootstrap via the passport-bootstrap skill.

• Temporal knowledge graph -- Bitemporal columns (valid_from / valid_to / superseded_by) on every memory + entity-resolution dedup (embedding KNN at default 0.85 cosine threshold) + audit trail (memory_audit table with prev/new state hashes) + new actions (entity_search / entity_graph / history) + opt-in KG_AUTO_ENABLED auto-extract on capture. BREAKING for clients that called memory.get expecting historical-inclusive results: pass as_of for time-travel; default now filters to current-state (valid_to IS NULL).

Comparison vs. peers

Status

2026-05-02 -- Architecture stabilization update

Past months saw significant churn around credential handling and the daemon-bridge auto-spawn pattern. This caused multi-process races, browser tab spam, and inconsistent setup UX across plugins. The architecture is now stable: 2 clean modes (stdio + HTTP), no daemon-bridge layer, no auto-spawn from stdio.

Apologies for the instability period. If you encountered issues with prior versions, please update to the latest release and follow the current setup docs -- most prior workarounds are no longer needed.

Related plugins from the same author:

• wet-mcp -- Web search + content extraction

• imagine-mcp -- Image/video understanding + generation

• better-notion-mcp -- Notion API

• better-email-mcp -- Email management

• better-telegram-mcp -- Telegram

• better-godot-mcp -- Godot Engine

• better-code-review-graph -- Code review knowledge graph

All plugins share the same architecture -- install once, learn pattern transfers.

Documentation

Full docs at mcp.n24q02m.com/servers/mnemo-mcp/setup/:

• Setup -- install methods for Claude Code, Codex, Gemini CLI, Cursor, Windsurf, mcp.json

• Modes overview -- stdio / local-relay / remote-relay / remote-oauth

• Multi-user setup -- per-JWT-sub credential model

Install with AI agent -- paste this to your AI coding agent:

Install MCP server mnemo-mcp following the steps at https://raw.githubusercontent.com/n24q02m/claude-plugins/main/plugins/mnemo-mcp/setup-with-agent.md

Tools

15 MCP tools, 17 memory actions. The memory surface is exposed both as 11 specialized single-purpose tools and a legacy memory dispatcher (same actions), plus config, help, and config__open_relay:

Plugin trinity (Claude Code marketplace install):

MCP Resources

MCP Prompts

Security

• Graceful fallbacks -- Cloud → Local embedding, no cross-mode fallback

• Sync token security -- OAuth tokens stored at ~/.mnemo-mcp/tokens/ with 600 permissions

• Input validation -- Sync provider, folder, remote validated against allowlists

• Error sanitization -- No credentials in error messages

Build from Source

git clone https://github.com/n24q02m/mnemo-mcp.git
cd mnemo-mcp
uv sync
uv run mnemo-mcp

Deploy to Cloudflare

Run your own mnemo instance serverless on Cloudflare (Containers + D1 + Vectorize + KV).

Prerequisites: a Cloudflare account on the Workers Paid plan — required for Containers, D1, and Vectorize (the Cloudflare free tier does not include them) — and the wrangler CLI.

1. git clone https://github.com/n24q02m/mnemo-mcp && cd mnemo-mcp

2. wrangler login

3. Provision the storage bindings mnemo uses -- the memories database, the embedding index, and the encrypted credential store:

   wrangler d1 create mnemo-memories
   wrangler vectorize create mnemo-memory-vectors --dimensions 768 --metric cosine
   wrangler kv namespace create mnemo-kv

   Paste the returned D1 database ID and KV namespace ID into wrangler.jsonc (the Vectorize index binds by name, so no ID is needed). The memories schema (tables + FTS5 full-text) is created by the container on first boot -- there is no separate migration step.

4. Push the container image to your Cloudflare managed registry (CF Containers cannot pull from external registries directly), then set <YOUR_ACCOUNT_ID> in wrangler.jsonc:

   docker pull ghcr.io/n24q02m/mnemo-mcp:beta
   docker tag ghcr.io/n24q02m/mnemo-mcp:beta mnemo-mcp:beta
   wrangler containers push mnemo-mcp:beta   # prints registry.cloudflare.com/<ACCOUNT_ID>/mnemo-mcp:beta

5. Set <YOUR_PUBLIC_URL> (e.g. https://mnemo.example.com) and <YOUR_WORKER_DOMAIN> (e.g. mnemo.example.com) in wrangler.jsonc, then set the secrets:

   wrangler secret put CREDENTIAL_SECRET              # per-user vault key (encrypts the cf-kv credential store)
   wrangler secret put MCP_RELAY_PASSWORD             # shared password gating the browser setup form
   wrangler secret put MCP_DCR_SERVER_SECRET          # required once PUBLIC_URL is set (multi-user, per-JWT-sub)
   wrangler secret put JINA_AI_API_KEY                # EMBEDDING_MODELS + RERANK_MODELS (cloud embed / rerank)
   wrangler secret put GOOGLE_VERTEX_EXPRESS_API_KEY  # LLM_MODELS (graph extraction, importance, consolidation)

6. wrangler deploy and complete setup in the browser relay form at your Worker domain.

Storage maps to Cloudflare via MCP_STORAGE_BACKEND=cf-kv (credentials / tokens, encrypted), DOCS_DB_BACKEND=cf-d1 (the memories database + FTS5 full-text), and Vectorize (embeddings, cosine). Embedding and reranking are forced cloud through the EMBEDDING_MODELS / RERANK_MODELS chains (jina_ai/...) so the container never downloads the local Qwen3 ONNX models, and graph / LLM features run through the LLM_MODELS chain (vertex_express/...).

Trust Model

This plugin implements TC-Local (machine-bound, single trust principal). The mode/storage/encryption breakdown below is the full classification.

License

MIT -- See LICENSE.