io.github.memtomem/memtomem

memtomem

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.x releases. 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?

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

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 -- uvx --isolated --from "memtomem[all]==0.6.12" 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 --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 mm pinned compose
• LangGraph Store — optional MemtomemBaseStore implements LangGraph's tuple-namespace long-term-memory contract
• Hybrid LangGraph Store — MemtomemHybridStore adds dedicated SQLite persistence, BM25/dense/RRF retrieval, TTL, and diagnostics

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:

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.