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

• Smithery

• Tools

• Security

• Build from Source

• CLI

• Hosted endpoint

• 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

Smithery

mnemo-mcp is packaged for Smithery -- install or run it straight from the registry. It starts over stdio via uvx mnemo-mcp with no configuration required to launch; credentials are configured at runtime through the server's own config flow (see Documentation). The published start command lives in smithery.yaml.

Tools

15 MCP tools, 17 memory actions. The memory surface is exposed both as 11 specialized single-purpose tools and a deprecated 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

CLI

The mnemo-mcp console script both starts the server and exposes a few one-shot operator subcommands. A bare invocation (or any ---prefixed flag) starts the server; a leading subcommand runs an action and exits.

mnemo-mcp                       # start the stdio server (default transport)
mnemo-mcp --http                # start the Streamable HTTP server
                                # (also via MCP_TRANSPORT=http or TRANSPORT_MODE=http)

mnemo-mcp auth google           # authorize Google Drive sync via OAuth
mnemo-mcp auth google --client-id <ID> --client-secret <SECRET>   # bring-your-own OAuth client
mnemo-mcp logout                # clear the local Google Drive sync token
mnemo-mcp warmup                # pre-download the bundled local embedding + rerank model

mnemo-mcp config status         # report whether stored config exists
mnemo-mcp config delete --yes   # delete the stored (encrypted) config
mnemo-mcp relay status          # show the active browser-setup relay session
mnemo-mcp relay open            # open the relay setup form in a browser
mnemo-mcp relay reset           # clear relay session state
mnemo-mcp doctor                # environment diagnostics (Python, backend, store, mode)

Hosted endpoint

A ready-to-use shared instance is hosted at https://mnemo.n24q02m.com/mcp -- Streamable HTTP transport, OAuth-gated. Point any MCP client that supports remote HTTP + OAuth at that URL and authenticate on first connect; each authenticated user gets an isolated per-user credential store (see Trust Model). To run your own instance instead, see Deploy to Cloudflare.

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.