Mnemo MCP Server

Distribution & CLI: the repo and CLI are mnemo. The PyPI distribution is n24q02m-mnemo (install pip install n24q02m-mnemo / uvx n24q02m-mnemo). The MCP server remains available: run mnemo (or legacy mnemo-mcp).

mcp-name: io.github.n24q02m/mnemo

Persistent AI memory with hybrid search. Open, free, unlimited.

Table of contents

• Features

• Quick install

• Status

• Documentation

• Smithery

• Tools

• Security

• Build from Source

• CLI

• Self-hosting (local HTTP instance)

• Remote (HTTP mode)

• Trust Model

• License

Related MCP server: Better Notion MCP

Roadmap (current = Phase 3 / v2.x)

Phase rows below describe the pre-de-host design history (v1.x / early v2): multi-provider LLM dispatch, GDrive/S3 passport sync, and Cloudflare deployment were removed in the 2026-09 de-host. Current architecture: one local SQLite store (WAL), per-task [models.*] provider cells (OpenRouter pre-wired default), no embedded sync (backup = rclone).

Features

• Hybrid retrieval -- FTS5 + vector search (sqlite-vec), fused via Reciprocal Rank Fusion (k=60), then re-ranked via the [models.rerank] provider cell (OpenRouter pre-wired default) with the local Fastretrieval Qwen3 cross-encoder as fallback, plus temporal decay and importance boost

• Typed capture -- memory(action="capture") with 6 context_types (conversation/fact/preference/skill/task/decision), embedding-based dedup, and optional [models.chat]-cell compression + importance scoring

• 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 calls go through per-task [models.<task>] provider cells (OpenAI-spec; OpenRouter pre-wired default)

• Local-first storage -- one SQLite file (WAL) under ~/.mnemo/; backup and cross-machine migration = rclone outside the server (no embedded sync)

• 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 through the [models.chat] provider cell targets ~3x token reduction at >=0.9 fact retention; graceful skip when the cell is unconfigured (see docs/compression.md)

• 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 / as_of) + 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: Claude Code plugin (skills + hooks; connects to a running
# mnemo HTTP instance -- start one per "Self-hosting" below)
/plugin marketplace add n24q02m/claude-plugins
/plugin install mnemo@n24q02m-plugins

# Method 2: run the HTTP server yourself and register the endpoint
uvx n24q02m-mnemo                      # serves http://127.0.0.1:8000/mcp by default
claude mcp add --transport http mnemo http://127.0.0.1:8000/mcp

# Method 3 (remote): point a client at an existing HTTP deployment
claude mcp add --transport http mnemo https://<your-host>/mcp

Install matrix (the server speaks Streamable HTTP only — there is no stdio transport post-de-host; see the Setup page for full steps):

With auth = "token" or "multi" configured in mnemo-config/config.toml, send the token as a Bearer credential (--header "Authorization: Bearer <token>" or the client's equivalent).

Comparison vs. peers

Status

2026-09 -- De-host update

The Cloudflare D1/Vectorize/KV deployment mode, embedded GDrive/S3 passport sync, multi-provider key dispatch (per-provider API-key env vars + model chains), and the stdio transport were removed. mnemo now runs one HTTP MCP endpoint on a local SQLite (WAL) store, and all cloud calls go through per-task [models.*] provider cells (OpenRouter pre-wired default). Backup across machines = rclone outside the server.

If you encountered issues with prior versions, update to the latest release and follow the current setup docs.

MCP registry note (2026-10): registry version 2.20.0 was published with a stdio PyPI package claim (uvx mnemo-mcp) that no longer reflects the product: post-de-host, mnemo speaks Streamable HTTP only — self-hosted, no public URL. Registry versions are immutable, so the stale stdio claim cannot be edited in place; the registry entry stays wrong until the owner de-lists it or republishes as 2.20.1. server.json in this repo now declares the package's true transport (streamable-http, default local endpoint), so the next publish carries correct metadata.

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 docs.n24q02m.com/servers/mnemo/setup/:

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

• Modes overview -- http

• 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/setup-with-agent.md

Smithery

mnemo was previously packaged for Smithery via a local stdio start command. Post-de-host the server is HTTP-only, so the local smithery.yaml was removed; publish a running instance's https://<host>/mcp endpoint to Smithery as a remote server instead.

Tools

13 MCP tools, 18 memory actions. The memory surface is exposed as 11 specialized single-purpose tools, the deprecated legacy memory dispatcher (same actions), and config:

Plugin trinity (Claude Code marketplace install):

MCP Resources

MCP Prompts

Security

• Graceful fallbacks -- cloud provider cells degrade to local ONNX; an unconfigured cell never silently selects a paid provider

• Host-only credentials -- provider keys live in the host-owned config.toml or HULL_<TASK>_API_KEY env vars; end users never see them

• Auth-gated HTTP -- auth = "no-auth" refuses non-loopback binds; token / multi require credential checks

• Error sanitization -- No credentials in error messages

Build from Source

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

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.

• n24q02m-mnemo (legacy alias mnemo-mcp) -- the MCP server plus one-shot operator subcommands. A bare invocation starts the HTTP server; a leading subcommand (config-init, warmup, token-hash, token-verify) 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 n24q02m-mnemo mnemo recall --db ./mem.db "package naming" --k 3   # try without a persistent install

mnemo capture --db ./mem.db "keep PyPI name n24q02m-mnemo; repo is mnemo" --tags decision --category decision
mnemo recall --db ./mem.db "release ladder" --k 5        # search a subject's memories
mnemo reflect --db ./mem.db "why keep the alias?" --k 5  # bounded cited reflect over retrieval
mnemo fetch --db ./mem.db <memory_id>                    # fetch one memory by id
mnemo standing-refresh --db ./mem.db onboarding "how do releases cut?" --k 5   # materialize a standing page
mnemo standing-read --db ./mem.db onboarding             # cheap read with staleness info

Server operator CLI (n24q02m-mnemo; a bare invocation starts the HTTP server):

n24q02m-mnemo                       # start the Streamable HTTP MCP server
                                # (bind host/port from config.toml or MNEMO_HOST/MNEMO_PORT)

n24q02m-mnemo config-init [--force] # write ~/.mnemo/config.toml from the template
n24q02m-mnemo warmup                # pre-download local embedding model / probe cells
n24q02m-mnemo token-hash            # print a scrypt$ hash for [server] token_hash
                                # (reads MNEMO_AUTH_TOKEN or prompts)
n24q02m-mnemo token-verify <token> <scrypt$...>   # verify a token against a hash

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 n24q02m-mnemo               # 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 n24q02m-mnemo 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 example
docker 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 token
MNEMO_AUTH_TOKEN=<token> uv run n24q02m-mnemo 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 n24q02m-mnemo; repo is mnemo" --tags decision --category decision
mnemo recall  --db ./mem.db "release ladder" --k 5
mnemo fetch   --db ./mem.db <memory_id>

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

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)

mnemo speaks Streamable HTTP on a single /mcp endpoint — remote access is a self-hosted instance on a reachable host, fronted by whatever TLS proxy you choose (the server itself binds plain HTTP). Auth is configured in mnemo-config/config.toml under [server]: auth = "token" (one shared Bearer token) or auth = "multi" (per-user tokens + namespaces via users.toml). auth = "no-auth" refuses non-loopback binds.

Public OCI image publication is discontinued. Existing historical registry tags remain untouched; new container deployments build from source (docker build --target http) or use docker-compose.http.yml.

Trust Model

mnemo is TC-Local (machine-bound): every storage artifact lives under ~/.mnemo/ owned by your OS user, and provider keys are host-only config (config.toml / HULL_<TASK>_API_KEY), never visible to MCP clients.

License

Apache-2.0 -- See LICENSE.