Skip to main content
Pre-release

This release is a pre-release and may not be stable for production use.

Mnemo MCP Server

mcp-name: io.github.n24q02m/mnemo

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

Distribution & CLI: the repo is mnemo; the PyPI distribution is n24q02m-mnemo (install pip install n24q02m-mnemo / uvx n24q02m-mnemo). Two console scripts ship: n24q02m-mnemo (legacy alias mnemo-mcp) starts the HTTP MCP server, and mnemo is the CLI-first memory surface that never serves. See CLI.

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

Python SQLite MCP semantic-release Renovate

Sister projects from n24q02m (click to expand)
Project Tagline Tag
better-semantic-release Drop-in python-semantic-release fork with built-in release-safety guards (orp... Tooling
claude-plugins Claude Code plugin marketplace for the n24q02m MCP servers -- install web sea... Marketplace
crg Knowledge graph for token-efficient code reviews -- semantic search and call-... MCP
email IMAP/SMTP email for AI agents -- read, send, organize folders, and manage att... MCP
fastretrieval Fast multi-model retrieval runtime: ONNX and GGUF embeddings, reranking, and ... Tooling
hull hull is the shared monorepo core for the wet, crg and mnemo self-hosted stack MCP
jules-task-archiver Chrome Extension for bulk operations on Jules tasks via batchexecute API -- a... Tooling
mnemo Persistent AI memory with hybrid search. Open, free, unlimited. MCP
notion Markdown-first Notion for AI agents -- pages, databases, blocks, and comments... MCP
sillstone Pure-Rust multimedia, hashing, and array suite Tooling
skret Secrets without the server. CLI
tacet A self-distilling neuro-symbolic cascade that amortises LLM cost across knowl... Tooling
telegram Telegram for AI agents -- messages, chats, media, and contacts across both bo... MCP
tools-docs Docs portal for the n24q02m open-source tool stack (skret, MCP plugins, hull,... Tooling
wet Open-source MCP server for AI agents: web search, content extraction, and lib... MCP
workspace Google Workspace MCP server (Docs/Drive/Calendar/Gmail/Sheets/Slides/Tasks/Ch... MCP

Table of contents

Mnemo MCP server

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).

Phase Version Status Highlights
Phase 1 v1.x Shipped Typed memory(action="capture") (6 context_types + dedup) -- RRF (k=60) hybrid fusion + cross-encoder rerank + temporal decay -- importance x recency archive policy + restore -- Alembic migrations -- multi-provider LLM dispatch (pre-de-host) -- plugin trinity (recall-context + memory-commit skills, SessionStart + opt-in PostToolUse hooks)
Phase 2 v1.x+1 Shipped, partially removed LLM-driven compression of older memories (kept, now via [models.chat] cell) + Passport sync (encrypted import/export bundle; removed 2026-09)
Phase 3 v2.0.0 Shipped (BREAKING) Temporal knowledge graph -- bitemporal valid_from / valid_to columns -- entity resolution via embedding KNN -- entity_search / entity_graph / history actions -- KG_AUTO_ENABLED opt-in auto-extract on capture

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):

Client Install
Claude Code (plugin) /plugin marketplace add n24q02m/claude-plugins then /plugin install mnemo@n24q02m-plugins (requires a running instance; see Self-hosting)
Claude Code (HTTP) start the server (uvx n24q02m-mnemo or docker compose), then claude mcp add --transport http mnemo http://127.0.0.1:8000/mcp
Codex / Gemini CLI / Cursor / Windsurf start the server, then register the http://<host>:<port>/mcp HTTP endpoint in the client's MCP settings
Any MCP client point it at the /mcp endpoint of a running instance (Streamable HTTP)

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

Feature mnemo Mem0 Letta OpenMemory
Hybrid retrieval (FTS + vec) yes (FTS5 + RRF + sqlite-vec) yes partial yes
Cross-encoder rerank yes (Fastretrieval Qwen3 local + [models.rerank] cell) partial (Cohere only) no no
Temporal decay scoring yes (exp half-life) no no no
Importance boost in rank yes (LLM 0.0-1.0) no no no
Soft-archive + restore policy yes (importance x recency) no no no
Self-hostable (single SQLite file) yes (zero ext deps) partial (cloud-first) yes (Postgres) yes (Postgres + Qdrant)
LLM dispatch yes ([models.chat] cell, any OpenAI-spec endpoint) partial yes partial
Plugin trinity (skills + hooks) yes (recall-context + memory-commit) n/a n/a n/a
Cross-machine migration yes (rclone backup/restore outside the server) yes (cloud) n/a n/a
LLM compression on capture yes ([models.chat] cell, ~3x at >=0.90 retention) no no no
Bitemporal valid_from / valid_to queries yes (as_of time-travel) no partial (events only) no
Entity resolution via embedding KNN yes (cosine threshold tunable) no no no
Audit trail with state hashes yes (memory_audit table) no no no

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:

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

Documentation

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

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

Install MCP server n24q02m-mnemo 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:

Tool Actions Description
add_memory, search_memory, list_memories, update_memory, delete_memory, export_memories, import_memories, memory_stats, restore_memory, archived_memories, consolidate_memories (one action each) Specialized single-purpose memory tools -- the recommended surface
memory (legacy dispatcher, DEPRECATED -- use the granular tools above instead; will be removed in a future release) add, capture, search, list, as_of, update, delete, export, import, stats, restore, archived, archive_now, consolidate, compress, entity_search, entity_graph, history Core CRUD + typed capture (6 context_types) + hybrid search (RRF + rerank + temporal decay) + import/export + soft-archive + restore + on-demand archive sweep + LLM consolidation + LLM compression + temporal KG (entity search / graph / history / as_of)
config status, set, warmup, backfill_embeddings Server status, update runtime settings, pre-download embedding model, backfill missing embedding vectors

Plugin trinity (Claude Code marketplace install):

Component Trigger Purpose
mnemo:recall-context skill session start, before significant decisions, "what do I know about X?" Pulls cwd / topic-relevant memories with context_type filtering
mnemo:memory-commit skill "remember this" / "save this" / "ghi nho" / "luu lai" Typed manual capture with context_type decision tree
mnemo:knowledge-audit skill periodic / "audit memory" Find duplicates, contradictions, stale entries; consolidate
mnemo:session-handoff skill end of session Capture decisions / preferences / corrections / conventions / open questions
mnemo:temporal-query skill "as of" / "back in" / "history of" / "what did I think then" Point-in-time snapshots via action="as_of" and version-chain tracing via superseded_by
SessionStart hook every session init Non-blocking nudge to invoke recall-context
PostToolUse hook (opt-in) CAPTURE_AUTO_ENABLED=true Hint memory-commit after Write/Edit of CLAUDE.md / AGENTS.md / ARCHITECTURE.md / docs/*.md

MCP Resources

URI Description
mnemo://stats Database statistics and server status

MCP Prompts

Prompt Parameters Description
save_summary summary Generate prompt to save a conversation summary as memory
recall_context topic Generate prompt to recall relevant memories about a topic

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
Subcommand Purpose
config-init [--force] Write the default instance config.toml (server auth + [models.*] provider cells)
warmup Pre-download the Fastretrieval-managed local ONNX embedding model so first use works offline
token-hash Mint a scrypt$ hash for [server] token_hash (shared-token auth)
token-verify Verify a candidate token against a stored scrypt$ 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.

Provider keys: rotation across several credentials

A cell's key is the seed of an ordered credential pool per provider identity (hull_core.credentials, stored under ~/.mnemo/credentials.db, keys sealed at rest). Every provider call leases the highest-priority usable credential, records the outcome, and rotates:

Upstream Action
401 / 403 disable that credential, use the next one
429 cool it down (Retry-After / rate_limit_reset, 1 s–1 h, default 60 s), use the next one
5xx retry once on the same credential, then use the next one
anything else re-raise; the credential is not blamed
pool empty / all blocked one error naming the pool counts and the earliest retry, never a key
  • Add more keys through the library (hull_core.credentials), e.g. CredentialStore(mnemo_config_dir() / "credentials.db").add_credential(...), or the KeyPool/CredentialStore API directly; a task cell with no api_key still works as long as its provider pool holds one.
  • provider = "openrouter" (optional) selects a pool identity other than the one derived from base_url. account = "<account-id>" (optional) selects a named account's own pool — rotation never crosses accounts.
  • A legacy key in config.toml or HULL_<TASK>_API_KEY is copied into the pool on startup while the pool is empty and keeps working untouched; the env var is never deleted and no key is ever logged.
  • The cell always owns the model id: all four task cells may share one provider pool, so an entry contributes its key and endpoint, not a model override.

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.

[server] auth Bind allowed Storage Who can read your data?
no-auth (default) loopback only (non-loopback bind refused) ~/.mnemo/memories.db + config.toml Only your OS user
token any same, one shared default namespace Anyone holding the shared token
multi any per-namespace ~/.mnemo/subs/<ns>/memories.db (via users.toml) Each token holder sees only their own namespace

License

Apache-2.0 -- See LICENSE.

Metadata

Release files for n24q02m-mnemo 2.23.0b4

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for n24q02m-mnemo 2.23.0b4
File Size Uploaded Provenance Actions
n24q02m_mnemo-2.23.0b4.tar.gz 133.7 kB With provenance Details for n24q02m_mnemo-2.23.0b4.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for n24q02m-mnemo 2.23.0b4
File Interpreter ABI Platform Actions
n24q02m_mnemo-2.23.0b4-py3-none-any.whl Python 3 none any Details for n24q02m_mnemo-2.23.0b4-py3-none-any.whl

Total release size: 280.1 kB

Release files / n24q02m_mnemo-2.23.0b4.tar.gz

Download URL n24q02m_mnemo-2.23.0b4.tar.gz
Size 133.7 kB
Tags Source
SHA-256 checksum
How to use checksums
a7cea483676f710755ffd6e8baa359b0c6a507d2c47c5a6f4f723cd034ef0232
BLAKE2b-256 checksum
How to use checksums
0070d80a5a4c0e55ac23ab8e0e96dcbc55bf1b66fdbfa987ca428e8bca002588
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

Release files / n24q02m_mnemo-2.23.0b4-py3-none-any.whl

Download URL n24q02m_mnemo-2.23.0b4-py3-none-any.whl
Size 146.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
6aebfeeed61b8f3dd854b95f419e93ac4cf75e6e1c911ce1242d1d21e7898307
BLAKE2b-256 checksum
How to use checksums
bd10c7af2654d3f02eb649efbdf5d07264420be864391d7f4090e4e05c2b61bc
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

Security for n24q02m-mnemo 2.23.0b4

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for n24q02m_mnemo-2.23.0b4.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page