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, 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 --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.5. 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 + 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 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 Namespaces, Sessions, Working Memory, and Health Report.

uv tool install memtomem             # no extras — dense search, web UI, Korean tokenizer unavailable until you add them

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

claude mcp add memtomem -s user -- uvx --isolated --from "memtomem[all]==0.6.5" memtomem-server

Key Features