memtomem
Markdown-first long-term memory for AI coding agents — your files stay yours, and core usage is hook-free by default.
🧪 Beta — 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. Features marked experimental can change or go away without either — see Stability. Feedback and issue reports are especially welcome: Issues · Discussions.
memtomem turns your markdown notes, documents, and code into a searchable knowledge base that any AI coding agent can use. Write notes as plain .md files — memtomem indexes them and makes them searchable by both keywords and meaning.
flowchart LR
A["Your files\n.md .json .py"] -->|Index| B["memtomem"]
B -->|Search| C["AI agent\n(Claude Code, Cursor, etc.)"]
First time here? Follow the Getting Started guide — you'll have a working setup in under 5 minutes. Claude Code or Codex CLI user? See the Korean vibe-coding quickstart.
Why memtomem?
| Problem | How memtomem solves it |
|---|
| AI forgets everything between sessions | Index your notes once, search them in every session |
| Keyword search misses related content | Hybrid search: exact keywords + meaning-based similarity |
| Notes scattered across tools | One searchable index for markdown, JSON, YAML, TOML, Python, JS/TS |
| Vendor lock-in | Your .md files are the source of truth. The DB is a rebuildable cache |
| Hidden automation is hard to reason about | Core memory operations run only when you call them; optional client hooks are explicit, removable integrations |
Quick Start
1. Install
uv tool install 'memtomem[all]' # or: pipx install 'memtomem[all]'
mm --version # verify install
[all] bundles the features the sections below describe — ONNX dense embeddings, Korean tokenizer, code chunker, and the Web UI. The Ollama and OpenAI embedding providers need no extra; they work on any install. For a smaller install without those downloads (about 50 MB installed instead of about 340 MB, before any model download), see the minimal install option in the Getting Started guide.
If mm --version shows an older version than the latest release right after installing, uv is likely serving cached PyPI metadata — re-run with uv tool install 'memtomem[all]' --refresh, or clear the cache first: 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 isn't on $PATH in fresh shells on macOS/Linux. Run uv tool update-shell, then open a new shell and re-run mm --version.
2. Setup
After upgrading the Claude plugin: re-check /mcp after reloading.
The plugin launches memtomem[onnx]==0.7.0. A manual registration whose launch
differs — base-only memtomem, or the ONNX launch pinned to an earlier
release — no longer matches for deduplication and may expose
duplicate tools. Confirm the manual entry's name and scope, then align its
launch command with the plugin or remove that redundant registration.
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 + English reranker + auto-discover providers), Korean-optimized (ONNX multilingual-e5-small + kiwipiepy tokenizer, no 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; rerun mm init
later when you are ready to add semantic search.
Indexing vs. discovery (Claude Code): provider memory folders that setup auto-discovers (e.g. ~/.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, Custom Commands, and Subagents — see Configuration → Context Gateway for the distinction and the lossy-slug caveats.
For automation / CI:
mm init --non-interactive # minimal preset, no prompts
mm init --preset korean --non-interactive # Korean-optimized bundle, no prompts
mm init --advanced # force the full 10-step wizard
See Embeddings for the full model/provider matrix.
3. Verify a complete memory round trip
The first success path does not require an existing notes directory or a connected editor:
mm status
mm add "Deployment checklist uses blue-green rollout" --tags ops
mm search "blue-green"
mm add writes to your configured user memory directory and indexes the entry immediately. The final command should return the sentence you just added.
Then verify the editor connection:
"Call the mem_status tool"
To bring existing notes into the same index, point mm index at a directory that already exists:
mm index /path/to/your/notes
mm status --json (or --format json) provides the same status as machine-readable output for scripts and CI.
4. Open the Web UI (optional)
mm web # polished dashboard on http://127.0.0.1:8080
mm web -b # run in the background; logs go to ~/.memtomem/logs/web.log
mm web status # show pid/port/start time
mm web stop # stop the tracked Web UI process
mm web --dev # maintainer surface (adds opt-in pages)
mm web shows the polished page set by default. Pass --dev (or set
MEMTOMEM_WEB__MODE=dev in your shell profile) to expose maintainer pages
like Sessions, Working Memory, and Health Report.
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 -- uvx --isolated --from "memtomem[all]==0.7.0" memtomem-server
See MCP Client Setup for OpenCode / Codex / Cursor / Antigravity / Windsurf / Claude Desktop / Gemini CLI / Kimi Code.
Key Features
- Hybrid search — BM25 keyword + dense vector + RRF fusion in one query
- Semantic chunking — heading-aware Markdown, AST-based Python, tree-sitter JS/TS, structure-aware JSON/YAML/TOML
- Incremental indexing — chunk-level SHA-256 diff; only changed chunks get re-embedded
- Namespaces — organize memories into scoped groups with auto-derivation from folder names; review and label them (colour, description) from Settings → Namespaces in the Web UI
- Maintenance — near-duplicate detection, time-based decay, TTL expiration, auto-tagging
- Web UI — visual dashboard for search, sources, tags, timeline, dedup, and more (
mm web --dev for the full maintainer surface)
- Context Gateway — keep canonical Skills, Commands, and Subagents in a project or user Store, optionally install reusable assets from a separate Wiki, then push them to supported AI runtimes. See Context Gateway.
- MCP tools —
mem_do meta-tool routes all non-core actions in core mode for minimal context usage
- Predictable core — memory operations run on explicit CLI/MCP calls (
mm add, mem_add, mem_index, etc.). Optional client hooks are installed and removed separately rather than being a hidden runtime default.
- Scriptable CLI — JSON output for scripts:
--json on mm status, the write commands (mm add / mm reset / mm purge), mm session start / end / list / events, mm schedule list, mm watchdog status / run and mm doctor, and --json (or --format json) on mm search and mm recall; mm warmup pre-loads local models so the first query skips the cold-start cost
- Scheduled jobs —
mm schedule add/list/run-now/delete (or mem_do(action="schedule_*")) for cron-driven compaction, importance decay, dead-link cleanup, and dedup scans
- Pinned Context — keep small user/project/agent Markdown blocks ahead of retrieved results with
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 not listed below 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 —
keyword auto-tagging, regex entity extraction, tags/headings expansion,
heuristic consolidation summaries — are supported.
- Claude projects scan in the Context Gateway
(
MEMTOMEM_CONTEXT_GATEWAY__EXPERIMENTAL_CLAUDE_PROJECTS_SCAN).
- Antigravity CLI plugin (
packages/memtomem-antigravity-plugin/).
Ecosystem
Documentation
Hosted at memtomem.com — also available as Markdown in this repo. New to memtomem? The guides have a suggested reading order. The table below follows it, with the two runnable examples placed after the first-run guides:
| Guide | Description |
|---|
| Getting Started | Install, configure, save and find your first memory |
| 한국어 바이브코딩 빠른 시작 | Claude Code·Codex CLI에서 10~15분 안에 기억 저장·검색 |
| MCP Client Setup | Editor-specific configuration |
| Cross-runtime handoff | Claude Code·Codex CLI·Kimi Code 순차 공동 개발 |
| Use cases | Nine runnable scenarios for multi-tool developers, personal knowledge bases, and teams |
| 프로젝트 업무별 체험 | 개발 작업 인계·제품 의사결정·온보딩: 모델 없는 체험, 기록 양식, 2주 파일럿 |
| Example notebooks and coding-agent sample | Notebooks: start with 00 to recover decisions, code, and settings across 150 synthetic files without a model (Korean); 01–04 teach APIs, 05–06 teach LangGraph. Sample: recover a decision and its ADR source across sessions, with an isolated CLI proof and copyable prompts |
| Core memory tools | Index existing notes, search, and manage memories |
| Data, config & CLI |
Contributing
See CONTRIBUTING.md for setup instructions and the contributor guide.
License
Apache License 2.0. Contributions are accepted under the terms of the Contributor License Agreement.
