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.

[PyPI] [Downloads] [GitHub stars] [License: Apache 2.0]

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

[Session 1 in Claude Code runs /memtomem:handoff save, writing one checkpoint record into the project's .memtomem/memories.local Markdown files. Session 2 in Codex CLI runs $memtomem-brief to list handoff IDs and updates, then $memtomem-handoff resume to load the checkpoint. After work and commits, back in Claude Code, /memtomem:update writes decisions, fixes, and preferences back into the same files.]

Illustrative output — agent wording and results vary.

# End of a session, in Claude Code> /memtomem:handoff save codex-clihandoff_id: 3f2a9c1e-7b4d-4e8a-9c2f-1d5e6a7b8c9dscope: project_local · namespace: shared:retry-policy · 1 file written, 2 chunks indexed
# Next session, in Codex CLI> $memtomem-briefRecent 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-1d5e6a7b8c9dgit_head matches the live HEAD · worktree clean · in sync with `origin` `refs/heads/main`
# After a few commits, back in Claude Code> /memtomem:updatemode: incremental · 4 of the latest 10 commits not yet reviewedsaved 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 statusmm add "Deployment checklist uses blue-green rollout" --tags opsmm 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:8080mm web -b             # run in the background; logs go to ~/.memtomem/logs/web.logmm 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.

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

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

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

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 CHANGELOG — without that guarantee.

These are experimental — their behaviour, output, or format can still change or go away without a window, because a decision that shapes them is still open or an LLM writes what they produce:

• Multi-agent memory — mem_agent_register, mem_agent_search, mem_agent_share, and per-agent session scopes (mem_session_start with agent_id). Open decisions: #1477, #1478.
• Memory export and import bundles — mem_export / mem_import and the Web export/import. How a backup made before 0.7.0 (bundle v1–v3) that holds project memories should be restored is still open.
• LLM-written output — anything memtomem's configured LLM (MEMTOMEM_LLM__ENABLED=true) writes: LLM auto-tagging and entity extraction, strategy="llm" query expansion, LLM consolidation and policy summaries, session auto-summaries, source summaries (indexing.auto_summarize), and contextual chunk enrichment (indexing.enrich_chunk_context). The rule-based modes beside them are supported.
• Claude projects scan in the Context Gateway (MEMTOMEM_CONTEXT_GATEWAY__EXPERIMENTAL_CLAUDE_PROJECTS_SCAN).
• Antigravity CLI plugin (packages/memtomem-antigravity-plugin/).
• Cursor plugin (packages/memtomem-cursor-plugin/).

Works with

Documentation

Hosted at memtomem.com and available as Markdown in this repo.

Contributing

See CONTRIBUTING.md for setup instructions and the contributor guide. New here? Start with an issue labelled good first issue.

License

Apache License 2.0. Contributions are accepted under the terms of the Contributor License Agreement.