Mnemo

Mnemo MCP Server

Renamed (2026-09-13): repo is now mnemo — CLI-first (mnemo command). PyPI package stays mnemo-mcp; MCP server remains a secondary surface.

mcp-name: io.github.n24q02m/mnemo

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

[Mode] [CI] [codecov] [PyPI] [License: Apache-2.0] [SafeSkill 91/100]

[Python] [SQLite] [MCP] [semantic-release] [Renovate]

Table of contents

• Features
• Quick install
• Status
• Documentation
• Smithery
• Tools
• Security
• Build from Source
• CLI
• Self-hosting (local HTTP instance)
• Remote (HTTP mode)
• Deploy to Cloudflare
• Trust Model
• License

Roadmap (current = Phase 3 / v2.x)

Features

• Hybrid retrieval -- FTS5 + vector search (sqlite-vec locally, Vectorize on Cloudflare), fused via Reciprocal Rank Fusion (k=60), then re-ranked by a configurable rerank chain (RERANK_MODELS, order = litellm fallback; empty -> Fastretrieval's 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 -- Fastretrieval's built-in local registry resolves 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).

Quick install

# Method 1 (default): plugin install via Claude Code/plugin marketplace add n24q02m/claude-plugins/plugin install mnemo-mcp@n24q02m-plugins
# Method 2 (CLI): direct uvx invocationclaude mcp add mnemo -- uvx mnemo-mcp
# Method 3 (remote): point a client at an HTTP deploymentclaude mcp add --transport http mnemo https://<your-host>/mcp

Install matrix (stdio unless noted; see the Setup page for full steps):

Example stdio config (zero-config local defaults):

{  "mcpServers": {    "mnemo": {      "command": "uvx",      "args": ["mnemo-mcp"]    }  }}

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/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.gitcd mnemouv syncuv run mnemo-mcp

CLI

The package ships two distinct console scripts:

• mnemo -- CLI-first memory surface (primary for scripts/agents; it never starts a server): capture, recall, reflect, fetch, and the standing-* family operate directly on a SQLite memory DB. mnemo-pilot is a legacy alias of the same entry point.
• mnemo-mcp -- the MCP server plus one-shot operator subcommands. A bare invocation (or any ---prefixed flag) starts the server; a leading subcommand runs an action and exits.

CLI-first memory surface (mnemo; every subcommand takes --db <path>, prints a JSON envelope, and exits with a taxonomy-mapped code):

uvx --from mnemo-mcp mnemo recall --db ./mem.db "package naming" --k 3   # try without a persistent install
mnemo capture --db ./mem.db "keep PyPI name mnemo-mcp; repo is mnemo" --tags decision --category decisionmnemo recall --db ./mem.db "release ladder" --k 5        # search a subject's memoriesmnemo reflect --db ./mem.db "why keep the alias?" --k 5  # bounded cited reflect over retrievalmnemo fetch --db ./mem.db <memory_id>                    # fetch one memory by idmnemo standing-refresh --db ./mem.db onboarding "how do releases cut?" --k 5   # materialize a standing pagemnemo standing-read --db ./mem.db onboarding             # cheap read with staleness info

Server operator CLI (mnemo-mcp):

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 OAuthmnemo-mcp auth google --client-id <ID> --client-secret <SECRET>   # bring-your-own OAuth clientmnemo-mcp logout                # clear the local Google Drive sync tokenmnemo-mcp warmup                # pre-download Fastretrieval-managed local embedding + rerank models
mnemo-mcp config status         # report whether stored config existsmnemo-mcp config delete --yes   # delete the stored (encrypted) configmnemo-mcp relay status          # show the active browser-setup relay sessionmnemo-mcp relay open            # open the relay setup form in a browsermnemo-mcp relay reset           # clear relay session statemnemo-mcp doctor                # environment diagnostics (Python, backend, store, mode)

Self-hosting (local HTTP instance)

Two ways to run the server for MCP clients on your machine.

Dev: start with uv (no-auth, loopback only)

uv run mnemo-mcp --http        # binds 127.0.0.1:8000, auth = "no-auth" by default

no-auth refuses non-loopback binds, so this is localhost-only by construction — fine for trying the server locally. The MCP endpoint is http://127.0.0.1:8000/mcp. For a real config, bootstrap one and edit it:

uv run mnemo-mcp config-init   # writes ~/.mnemo/config.toml from the template

Always-on: docker compose (token auth, loopback-published port)

docker-compose.http.yml is self-contained (builds the image, persists state in the mnemo-data volume) and publishes only on loopback:

cp mnemo-config/config.example.toml mnemo-config/config.toml   # then edit:#   auth = "token"; set token_hash per the comments at the top of the exampledocker compose -f docker-compose.http.yml up --build -d# MCP endpoint: http://127.0.0.1:8771/mcp   (override the host port: MNEMO_PORT=9000 ...)

Token setup (also documented in the example config):

python -c "import secrets; print(secrets.token_urlsafe(32))"     # 1. mint tokenMNEMO_AUTH_TOKEN=<token> uv run mnemo-mcp token-hash              # 2. print scrypt$ hash# 3. paste the hash into token_hash in mnemo-config/config.toml; give clients the token

For auth = "multi" (per-user namespaces) also mount users.toml — see the commented line in docker-compose.http.yml.

CLI consumer (no server needed)

The mnemo surface talks straight to the memory DB — handy for scripts and agents:

mnemo capture --db ./mem.db "keep PyPI name mnemo-mcp; repo is mnemo" --tags decision --category decisionmnemo recall  --db ./mem.db "release ladder" --k 5mnemo fetch   --db ./mem.db <memory_id>

Every subcommand prints a JSON envelope and takes --db <path>. See CLI for the full surface (reflect, standing-*, doctor, …).

Pointing an MCP client at the instance

Register the HTTP endpoint (Streamable HTTP transport):

• Claude Code: claude mcp add --transport http mnemo http://127.0.0.1:8771/mcp
• Any OpenAI-spec MCP client: server URL http://127.0.0.1:8771/mcp; with auth = "token" send the shared token as the Bearer credential.

Config: local vs cloud, per task

Each task cell in mnemo-config/config.toml ([models.embed], rerank, chat, jev_score) is independent: base_url + api_key + model, OpenAI-spec HTTP. Mix freely — e.g. cloud OpenRouter for chat while embed/rerank point at a local OpenAI-spec server, or all cloud. Keys are host-only (end users never see them) and may alternatively come from the HULL_<TASK>_API_KEY env vars.

Remote (HTTP mode)

Deployed over HTTP, mnemo speaks Streamable HTTP transport and is OAuth-gated. Point any MCP client that supports remote HTTP + OAuth at https://<your-host>/mcp and authenticate on first connect; each authenticated user gets an isolated per-user credential store (see Trust Model). To stand up an instance, see Deploy to Cloudflare.

Public OCI image publication is discontinued. Existing historical registry tags remain untouched; new container deployments build from source or use the Cloudflare-managed registry.

Deploy to Cloudflare

[Deploy to Cloudflare]

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

Paused 2026-09-13 (maintained instance only): the CF deploy token was removed from the account as off-manifest (process violation), so the CD deploy-cf job no-ops behind the CF_DEPLOY_ENABLED repo variable. The maintained instance freezes at its last deployed release until a token is re-established via the documented process and the variable is set to true. Self-hosting on your own account (below) is unaffected.

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 && cd mnemo
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-memorieswrangler vectorize create mnemo-memory-vectors-1536 --dimensions 1536 --metric cosinewrangler 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), then create the memories schema (tables, indexes, and the FTS5 full-text index) in the database you just made:
   wrangler d1 migrations apply mnemo-memories --remote

   The SQL lives in migrations/0001_init.sql, and the D1 binding in wrangler.jsonc points at that folder via migrations_dir: "migrations". Full-text search uses FTS5, which D1 ships; vector similarity is served by Vectorize rather than by an in-database extension, because D1 cannot load one.
4. Build the HTTP container from this checkout and push it to your Cloudflare managed registry (CF Containers cannot pull from external registries directly), then set <YOUR_ACCOUNT_ID> in wrangler.jsonc:
   docker build --target http -t mnemo-mcp:local .wrangler containers push mnemo-mcp:local# set image to registry.cloudflare.com/<YOUR_ACCOUNT_ID>/mnemo-mcp:local

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 formwrangler secret put MCP_DCR_SERVER_SECRET          # required once PUBLIC_URL is set (multi-user, per-JWT-sub)

6. wrangler deploy and complete setup in the browser relay form at your Worker domain. Save each subject's models, endpoints and provider keys there, not in Worker environment variables. The managed route uses Minimax-free completion and paid Cohere embedding/reranking through Cloudflare AI Gateway -- obtain the required budget authorization before exercising the paid tiers (Provider Spend Gate); see the per-task configuration. Storage maps to Cloudflare via MCP_STORAGE_BACKEND=cf-kv (credentials / tokens, encrypted), MEMORY_DB_BACKEND=cf-d1 (the memories database + FTS5 full-text; unset or sqlite keeps the local SQLite file at DB_PATH), and Vectorize (embeddings, cosine). Cloud embedding, reranking and completion resolve per authenticated subject. Remote startup does not probe shared provider credentials or download local Fastretrieval models. Missing subject configuration never selects a process-wide provider/model fallback.

Authority & Sync Boundary

On Cloudflare deployments, Cloudflare D1 + Vectorize + KV is the sole production authority:

• D1 (MEMORY_DB_BACKEND=cf-d1): Authoritative storage for memory rows, metadata, bitemporal valid ranges, and FTS5 search.
• Vectorize (MCP_VECTORIZE_IDX): Dense vector index for semantic similarity search.
• KV (MCP_STORAGE_BACKEND=cf-kv): Encrypted per-user credential and session store.
• Sync boundary: MEMORY_DB_BACKEND=cf-d1 disables Google Drive OAuth and all external sync paths even if SYNC_ENABLED is toggled on or stale S3/Google settings remain. SYNC_ENABLED=false independently disables sync on non-CF deployments.
• Local & self-host bootstrap: Local stdio (~/.mnemo/memories.db) and self-hosted instances retain optional passport sync (Google Drive Device Code OAuth or S3/R2/B2) for workstation migration.

Deployment (maintained instance)

Every tagged release deploys automatically: the CD deploy-cf job checks out the released tag, builds the http-slim image, pushes it to the Cloudflare-managed registry as immutable :<release-tag>, deploys the Worker, and gates on a canary health check -- a release is live at exactly its own version. A beta dispatch redeploys the beta; a stable dispatch is maintainer-gated. Manual wrangler deploy against the maintained instance is not permitted: it would break the release-tag ↔ live-image correspondence. Self-hosting on your own Cloudflare account (the button above) is unaffected.

Trust Model

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

Workspace username (HTTP setup form)

The browser setup form has an optional workspace username field. Entering the same username always lands you in the same per-sub bucket, so your credentials and memories stay reachable across a re-authorization and across devices, instead of being tied to the one-off subject minted for each /authorize round-trip. Leaving it blank keeps the previous per-authorize behaviour.

Trust boundary: when the form is gated by a shared MCP_RELAY_PASSWORD, the username is a partition key, not a secret -- anyone who knows that password can type any username and reach that bucket. That is fine for a trusted group; an untrusted multi-tenant deployment needs a per-user secret or delegated OAuth instead.

One-time migration: existing users must re-enter their credentials once after this change. Nothing is deleted; credentials stored under the old random subject are simply no longer addressed.

License

Apache-2.0 -- See LICENSE.