API_KEYS — Provider API keys (format: PROVIDER_API_KEY:key,...). Select models per task with EMBEDDING_MODELS / RERANK_MODELS / LLM_MODELS (CSV provider/model, order = litellm fallback); provider is inferred from the model prefix. Empty embedding/rerank chains select Fastretrieval local ONNX/GGUF models; configured cloud chains never silently fall back to local.
Claude Code ไม่มีลิงก์ติดตั้งสำหรับคำสั่งแบบโลคัล ให้คัดลอกคำสั่งด้านล่างแล้วรันในเทอร์มินัล
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).
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
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-mcp@n24q02m-plugins
# Method 2: run the HTTP server yourself and register the endpoint
uvx --from mnemo-mcp mnemo-mcp # 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-mcp@n24q02m-plugins (requires a running instance; see Self-hosting)
Claude Code (HTTP)
start the server (uvx --from mnemo-mcp mnemo-mcp 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.
mnemo-mcp 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:
Error sanitization -- No credentials in error messages
Build from Source
git clone https://github.com/n24q02m/mnemo.git
cd mnemo
uv sync
uv 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 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 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 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 (mnemo-mcp; a bare invocation starts the HTTP server):
mnemo-mcp # start the Streamable HTTP MCP server
# (bind host/port from config.toml or MNEMO_HOST/MNEMO_PORT)
mnemo-mcp config-init [--force] # write ~/.mnemo/config.toml from the template
mnemo-mcp warmup # pre-download local embedding model / probe cells
mnemo-mcp token-hash # print a scrypt$ hash for [server] token_hash
# (reads MNEMO_AUTH_TOKEN or prompts)
mnemo-mcp token-verify <token> <scrypt$...> # verify a token against a hash
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 mnemo-mcp # 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
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 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:
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.