Memtomem

memtomem

Long-term memory for AI coding agents, kept as Markdown you own. Core usage is hook-free by default: memory changes happen only when you or your agent call memtomem.

🧪 Beta — the nine core MCP tools, the mm CLI, and the format of your memory and config files change only with an Upgrading note in the CHANGELOG. Features marked experimental can change without one; see Stability. Feedback is welcome: Issues · Discussions.

The session loop

Three plugin workflows carry a project's memory from one session to the next, and from one coding agent to another.

Illustrative output — agent wording and results vary.

# End of a session, in Claude Code

/memtomem:handoff save codex-cli

handoff_id: 3f2a9c1e-7b4d-4e8a-9c2f-1d5e6a7b8c9d scope: project_local · namespace: shared:retry-policy · 1 file written, 2 chunks indexed

Next session, in Codex CLI

$memtomem-brief

Recent updates and active handoff IDs

• 3f2a9c1e-7b4d-4e8a-9c2f-1d5e6a7b8c9d from claude-code → codex-cli load it with: $memtomem-handoff resume 3f2a9c1e-7b4d-4e8a-9c2f-1d5e6a7b8c9d

$memtomem-handoff resume 3f2a9c1e-7b4d-4e8a-9c2f-1d5e6a7b8c9d

git_head matches the live HEAD · worktree clean · in sync with origin refs/heads/main

After a few commits, back in Claude Code

/memtomem:update

mode: incremental · 4 of the latest 10 commits not yet reviewed saved 2 items · commit-derived: 1 · session-derived: 1

handoff save writes one Markdown record into the project's own .memtomem/memories.local; brief only reads; update saves decisions, bug fixes, and preferences as separate items. All three run only when you invoke them, and nothing runs in the background. The Project workflows guide has each one's modes, checks, and host-specific names.

Why memtomem?

• Your files stay yours. Memories are plain .md files you can read, edit, and version. The search index is rebuilt from them, day-file namespaces included; tag edits and working state live only in the database (what a rebuild restores).
• Explicit by default. Memory operations run on your CLI or MCP calls (mm add, mem_add, mem_index). Optional client hooks are separate, removable integrations, not a hidden runtime default.
• One store, many tools. Claude Code, Codex CLI, OpenCode, Kimi Code, and Antigravity share one local store, and any MCP client can search it. memtomem-stm is a separate, optional proxy that surfaces memories proactively.

Quick Start

1. Install

uv tool install 'memtomem[all]'       # or: pipx install 'memtomem[all]'

mm --version # verify install

[all] bundles ONNX dense embeddings, the Korean tokenizer, the code chunker, and the Web UI (about 340 MB installed, before any model download). The Ollama and OpenAI embedding providers need no extra. A smaller install is under Other install options below.

2. Setup

mm init                               # preset picker, then memory_dir + MCP

The interactive picker starts with three presets — Minimal (BM25, no downloads), English (Recommended) (ONNX multilingual-e5-small + auto-discover providers), Korean-optimized (ONNX multilingual-e5-small + kiwipiepy tokenizer); no preset turns on a reranker — plus an Advanced entry that opens the full 10-step wizard. Preset paths only ask about the memory directory and MCP registration; everything else is set from the preset.

Choose Minimal for the fastest no-download first proof and rerun mm init later to add semantic search. For automation, mm init --non-interactive picks the minimal preset without prompts. See Embeddings for the model and provider matrix. The presets keep embedding on your machine; choosing OpenAI embeddings, a cloud LLM, or the Cohere reranker sends note text to that service (What leaves your machine).

3. Verify a complete memory round trip

mm status

mm add "Deployment checklist uses blue-green rollout" --tags ops mm search "blue-green"

The last command should return the sentence you just added. mm add writes to your user memory directory and indexes the entry immediately, so this works without an existing notes directory or a connected editor. To bring existing notes into the same index, run mm index /path/to/your/notes.

4. Connect your coding agent

Install the plugin for your tool — Claude Code, Codex CLI, OpenCode, Kimi Code, Antigravity, or Cursor — then, in the project you work on, register the memory tier the session loop writes to:

cd <your-project> && mm mem init --scope project_local

Start a new session and run the brief workflow: /memtomem:brief in Claude Code, and the name each other host uses is in the Project workflows guide. The Claude Code & Codex CLI plugin quickstart (한국어) walks through plugin installation and a first memory save-and-search round trip in 10–15 minutes. For Windsurf, Claude Desktop, Gemini CLI, other MCP clients, and registering Cursor by hand instead of through the plugin, see MCP Client Setup; from any client, asking it to call the mem_status tool confirms the connection.

5. Open the Web UI (optional)

mm web                # dashboard on http://127.0.0.1:8080

mm web -b # run in the background; logs go to ~/.memtomem/logs/web.log mm web stop # stop the tracked Web UI process

mm web shows the polished page set. mm web --dev (or MEMTOMEM_WEB__MODE=dev) adds maintainer pages such as Sessions, Working Memory, and Health Report.

Other install options

Minimal (no bundled model, about 50 MB):

uv tool install memtomem             # no extras — no local ONNX model, Web UI or Korean tokenizer until you add them; Ollama/OpenAI embeddings still work

Opt in later per feature: uv tool install --reinstall 'memtomem[onnx,web]' (see the extras table). List every extra you want to keep, because --reinstall replaces the whole set. A plain mm upgrade keeps the extras it detects from the current install, but an explicit mm upgrade --extras list must name the complete set too.

Project-scoped (per-project isolation):

uv add 'memtomem[all]' && uv run mm init    # all commands need `uv run` prefix

No install (uvx on demand):

claude mcp add memtomem -s user -e MEMTOMEM_EXTRA_TOOLS=mem_update_coverage -- uvx --isolated --from "memtomem[all]==0.7.5" memtomem-server

Troubleshooting the install

• `mm --version` shows an older version than the [latest release](https://github.com/memtomem/memtomem/releases) right after installing: uv is likely serving cached PyPI metadata. Re-run with uv tool install 'memtomem[all]' --refresh, or clear the cache first with uv cache clean memtomem. To upgrade an existing uv tool install, use mm upgrade rather than re-running uv tool install; see the CLI reference for what it preserves and stops.
• `mm: command not found`: uv tool install drops the shim into ~/.local/bin, which is not on $PATH in fresh shells on macOS/Linux. Run uv tool update-shell, then open a new shell and re-run mm --version.
• Duplicate tools after upgrading the Claude plugin: re-check /mcp after reloading. The plugin launches memtomem[onnx]==0.7.5. A manual registration whose launch differs — base-only memtomem, or the ONNX launch pinned to an earlier release — no longer matches for deduplication. Confirm the manual entry's name and scope, then align its launch command with the plugin or remove the redundant registration.
• Indexing vs. discovery (Claude Code): provider memory folders that setup auto-discovers (such as ~/.claude/projects/*/memory/) are added to the search *index*. That is separate from the Web UI's opt-in Context Gateway scan of ~/.claude/projects/, which discovers project *roots* for Skills, Commands, and Subagents; see Configuration → Context Gateway.

What else is inside

Stability

memtomem is beta (0.x). The nine core MCP tools, the mm CLI, and the format of your memory files and config files change only with an Upgrading note in the CHANGELOG, and behind a deprecation window where one is possible. Other features are supported — maintained, with their changes recorded in the CHA