Markdown-first long-term memory for AI coding agents — your files stay yours, and core usage is hook-free by default.
🚧 Alpha — APIs, defaults, and on-disk config surfaces may still change between
0.xreleases. 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.
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, Ollama / OpenAI providers, code chunker, and the Web UI. For a BM25-only install without those downloads (~40 MB vs ~250 MB), see the minimal install option in the Getting Started guide.
If
mm --versionshows an older version than the latest release,uvis likely serving cached PyPI metadata — re-run withuv tool install 'memtomem[all]' --refresh, or clear the cache first:uv cache clean memtomem.
mm: command not found?uv tool installdrops the shim into~/.local/bin, which isn't on$PATHin fresh shells on macOS/Linux. Runuv tool update-shell, then open a new shell and re-runmm --version.
mm init # preset picker, then memory_dir + MCPThe interactive picker starts with three presets — Minimal (BM25, no downloads), English (Recommended) (ONNX bge-small-en-v1.5 + English reranker + auto-discover providers), Korean-optimized (ONNX bge-m3 + kiwipiepy tokenizer + multilingual 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 wizardSee Embeddings for the full model/provider matrix.
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/notesmm status --json (or --format json) provides the same status as machine-readable output for scripts and CI.
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 Namespaces, Sessions, Working Memory, and Health Report.
Other install options
uv tool install memtomem # no extras — dense search, web UI, Korean tokenizer unavailable until you add themOpt in later per-feature: uv tool install --reinstall 'memtomem[onnx,web]' (see the extras table).
Project-scoped (per-project isolation):
uv add 'memtomem[all]' && uv run mm init # all commands need `uv run` prefixNo install (uvx on demand):
claude mcp add memtomem -s user -- uvx --isolated --from "memtomem[all]==0.5.0" memtomem-serverSee MCP Client Setup for OpenCode / Codex / Cursor / Windsurf / Claude Desktop / Gemini CLI / Kimi Code.
- 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 --devfor 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_dometa-tool routes all non-core actions incoremode 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 —
--jsonoutput onmm statusand write commands (mm add/mm reset/mm purge);mm warmuppre-loads local models so the first query skips the cold-start cost - Scheduled jobs —
mm schedule add/list/run-now/delete(ormem_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
mm pinned compose - LangGraph Store — optional
MemtomemBaseStoreimplements LangGraph's tuple-namespace long-term-memory contract
| Package | Description |
|---|---|
| memtomem | Core — MCP server, CLI, Web UI, hybrid search, storage |
| opencode-memtomem | OpenCode — exact-pinned MCP, commands, read skills, safe permissions |
| memtomem-stm | STM proxy — proactive memory surfacing via tool interception |
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:
See CONTRIBUTING.md for setup instructions and the contributor guide.
Apache License 2.0. Contributions are accepted under the terms of the Contributor License Agreement.