CLI Reference

The mm command is installed with the memtomem package. It provides setup, search, indexing, session tracking, and cross-runtime context sync. Run mm --help for the full command list or mm --version to print the installed version (the mm version subcommand also works).

Commands

mm init

Run the interactive setup wizard. Configures embedding provider, database path, tokenizer, reranker, and default namespace.

At startup, the wizard offers a preset picker (Minimal / English / Korean) that applies a curated bundle of embedding, reranker, tokenizer, and namespace defaults. Pass --preset <name> to pick one non-interactively, or --advanced to force the full 10-step wizard.

mm init                              # interactive setup with preset picker
mm init -y                           # auto-accept; behaves as `--preset minimal -y`
mm init --preset korean              # apply Korean preset non-interactively
mm init --preset english -y          # English preset, no prompts
mm init --advanced                   # skip picker, run full 10-step wizard

On a reinstall path, mm init compares the embedding provider / model / dimension stored in the existing ~/.memtomem/memtomem.db against the new preset. On mismatch, the interactive wizard offers an in-place rebuild of the vector index (chunks_vec); under -y, it prints a recovery hint pointing at mm embedding-reset --mode apply-current. The chunks table itself is preserved, so re-running mm index <path> afterwards restores the working set.

Running the MCP server

memtomem’s MCP server ships as the memtomem-server console script. You normally don’t launch it by hand — your MCP client (Claude Desktop, Claude Code, Cursor, etc.) starts it automatically from its config file. See Quick Start for the config snippets.

To filter which tools the server advertises, set MEMTOMEM_TOOL_MODE in the client’s MCP config. See the MCP Tools page for modes and tool catalogs.

Since v0.1.25, an MCP handshake alone no longer creates ~/.memtomem/memtomem.db — the DB opens on the first tool call, and the server pid/flock file moved to $XDG_RUNTIME_DIR/memtomem/server.pid (or $TMPDIR/memtomem-$UID/ on platforms without one). A client that connects but never calls a tool leaves the home directory untouched.

mm status

Terminal mirror of the MCP mem_status tool. Use it as a post-install sanity check: confirms the binary runs, the config parses, the DB is reachable, and the embedding config is in sync — without needing to launch an MCP client. Sits between mm config show (config only) and mm watchdog status (periodic snapshots).

mm status                            # indexing stats + config summary (same output as mem_status)

Added in v0.1.25. Good fit for a one-liner “is the DB open and how many entries are in it” check before wiring an MCP client.

mm web

Launch the Web UI dashboard for browser-based search and memory management.

On launch, mm web opens the dashboard at http://127.0.0.1:8080 with these tabs: Home · Search · Sources · Index · Tags · Timeline · More. The More tab holds Settings, Dedup, Age-out, Export/Import, and Reset Database.

Pass --dev (or set MEMTOMEM_WEB__MODE=dev) to unlock maintainer pages: Namespaces, Sessions, Working Memory, Health Report. Most users won’t need these.

mm web                               # default: http://localhost:8080 (prod tier)
mm web --port 9000
mm web --open                        # also open the URL in your default browser
mm web --dev                         # shortcut for --mode dev
mm web --mode dev                    # expose opt-in maintainer pages

mm search <query>

Search the knowledge base from the command line.

mm search "how does the auth middleware work"
mm search "deployment config" --namespace project-x --top-k 5

--top-k / -k caps results (default 10). Other filters: --source-filter / -s, --tag-filter / -t, --namespace / -n, --as-of (point-in-time bound, YYYY-MM-DD / YYYY-QN), and --format (table / json / plain / context / smart).

mm add

Add a memory entry and index it. Without --file, the content is appended to ~/.memtomem/memories/<today-UTC>.md.

mm add "apply tree-sitter AST parser to hallway-door PR"
mm add "API timeout policy" --title "API timeout" --tags "ops,api"
mm add "postmortem summary" --file postmortems/2026-04-auth.md

Tags passed via --tags are merged onto the appended file’s chunk metadata right after indexing — the chunker doesn’t parse tag text from the body, so the merge is explicit. --file only accepts paths relative to ~/.memtomem/memories/ and rejects .. components.

mm recall

Browse recent memory chunks chronologically. Unlike mm search, no query needed — filter by date range, source path, or namespace instead.

mm recall                                    # most recent 20 chunks (default table)
mm recall --since 2026-04 --limit 50
mm recall --source-filter "postmortems/" --format json
mm recall --namespace project-x --format plain

--format picks table (default, human), json (scripting), or plain (text pipe). Date arguments accept YYYY, YYYY-MM, YYYY-MM-DD, and ISO datetimes.

mm index <path>

One-shot command that seeds the index with files already on disk. Re-runs are safe — chunks are content-hashed, so unchanged files are skipped.

mm index .                           # index current directory
mm index ~/docs/architecture         # index a specific directory
mm index README.md                   # index a single file

Paths listed in indexing.memory_dirs are additionally watched by the file watcher that mm server starts — but the watcher is reactive only. It reindexes on modify/create/move events that fire after it starts, so pre-existing files at boot time are not auto-scanned. The normal flow is to seed once with mm index <dir> (or mem_index(path="<dir>")) and then let the watcher handle further edits. This is why the mm init wizard prints mm index {memory_dir} as step 1 of its Next steps.

mm ingest

Consolidate memories from other AI tools into memtomem. The --source path is required; re-runs are incremental via content-hash matching.

mm ingest claude-memory --source ~/.claude/projects/    # import Claude Code memories
mm ingest gemini-memory --source ~/.gemini/GEMINI.md    # import Gemini CLI GEMINI.md
mm ingest codex-memory --source ~/.codex/memories/      # import Codex CLI memories

mm session

Manage agent sessions — start, end, list, and wrap commands. Sessions group activity events and tie them to an agent runtime.

mm session start --agent-id claude-code --title "refactor auth"
mm session list --json                           # scriptable list output
mm session events <session-id> --json            # event timeline as JSON
mm session wrap -- <command...>                  # auto start/end around a command
mm session end

The current session ID is stored in ~/.memtomem/.current_session, so mm activity log and other commands pick it up automatically.

mm activity log

Log an activity event (tool call, decision, error, subagent lifecycle) to the current session. Silent by default so hook callers never fail; --json emits an ack shape for scripting.

mm activity log --type tool_call --content "ran tests"
mm activity log --type decision --content "picked strategy X" --meta '{"k":"v"}' --json

With --json, a successful write returns {"ok": true, ...} on stdout; no active session or a write failure returns {"ok": false, "reason": ...}. Exit code is always 0.

mm context sync

Sync agent definitions, skills, and commands across runtimes via the Context Gateway.

mm context detect
mm context init --scope project_shared --confirm-project-shared
mm context sync --scope project_shared
mm context diff --scope project_shared

Use --scope user for personal cross-project context and --scope project_local for local drafts. project_shared is git-tracked, so it requires explicit confirmation and should not contain secrets.

Seeding from existing runtime files

There is no separate mm context import command. To seed canonical files from runtime-specific files, run mm context init with the artifact kinds and destination tier.

mm context detect --include agents,skills
mm context init --include agents,skills --scope project_shared --confirm-project-shared
mm context diff --include agents,skills --scope project_shared

This is useful when you already authored files directly in Claude Code, Codex CLI, Gemini CLI, or another runtime and want memtomem to manage them going forward.

mm config show / set / unset

mm config show displays the current configuration with API keys masked. --json (or --format json) emits the full config as machine-readable JSON. mm config set <key> <value> writes a user override on top of built-in defaults; mm config unset <keys...> removes those overrides so the field reverts to its built-in default (or whatever a config.d/*.json fragment resolves to).

mm config show                       # human-readable table
mm config show --json                # JSON for scripting
mm config set search.default_top_k 20
mm config set rerank.model bge-reranker-base
mm config unset indexing.memory_dirs
mm config unset rerank.model search.default_top_k

mm config unset is idempotent — removing a key that isn’t there is a silent no-op. Useful for clearing stale cross-machine paths in indexing.memory_dirs, or a single field that’s shadowing a config.d fragment.

mm agent register / list / share

CLI mirrors of the MCP mem_agent_* tools — register agents, inspect the registry, and copy chunks between scopes.

mm agent register planner --description "Planning subagent" --color "#6c5ce7"
mm agent list                        # registered agents + the shared namespace
mm agent list --json
mm agent share <chunk-id>                          # copy into the shared namespace
mm agent share <chunk-id> --target agent-runtime:reviewer

mm agent register creates the agent-runtime:{agent_id} namespace; re-registering with the same id only updates metadata. agent_id must match [A-Za-z0-9._-] — hostile shapes are rejected.

mm agent share is a copy, not a reference link. The new chunk gets a fresh UUID and source updates do not propagate; provenance is recorded only via a shared-from=<source-uuid> tag on the copy.

mm schedule add / list / run-now / delete

Register cron-driven jobs (compaction, importance decay, dead-link cleanup, dedup scans, …) and inspect or run them.

mm schedule add --cron "0 3 * * *" --job dedup_scan
mm schedule add --cron "0 */6 * * *" --job importance_decay --params '{"max_age_days": 90}'
mm schedule list
mm schedule list --json
mm schedule run-now <sched-id>       # fire immediately, out of band
mm schedule delete <sched-id>

--cron is a 5-field expression in UTC. --params is a JSON dict of job-specific parameters. Registered jobs run while the MCP server is up — independent of health_watchdog.enabled.

mm watchdog

Periodic health-check command group. Read back snapshots left by the background scheduler, or run every check once on demand.

mm watchdog status                           # latest results summary
mm watchdog status --json                    # JSON output
mm watchdog run                              # run all checks now
mm watchdog history db_size --hours 48       # 48h trend for a specific check

The scheduler only runs in the background when health_watchdog.enabled is on (the MCP server drives it). Even with the scheduler off, mm watchdog run works any time for a one-shot offline check.

mm shell

Start an interactive REPL — search, add, recall, tag counts, and index stats all from a single prompt. Handy for browsing memory from a terminal without an MCP client, or for a quick post-install feel-check of the DB.

mm shell
mm> search deployment checklist
mm> ask summarize last week's migration rollback decision
mm> add "new fact I just learned"
mm> stats
mm> quit

Bare text (no command) is treated as an implicit search. Exit with Ctrl+D or quit / exit / q.

mm init --fresh

Re-run the setup wizard after dropping every wizard-untouched config key whose value differs from the built-in default. A safe cleanup option when the config has accumulated leftovers from older versions. The previous config.json is backed up to config.json.bak-<unix-ts> before rewriting.

mm init --fresh                      # opt-in bulk cleanup + wizard

mm embedding-reset

Check or resolve mismatches between the embedding model/dimension stored in the DB and the current config (typically after swapping providers or following a reinstall). --mode selects the action.

mm embedding-reset                            # --mode status (default): compare DB vs. config
mm embedding-reset --mode apply-current       # reset DB to current config (destructive — re-index required)
mm embedding-reset --mode revert-to-stored    # switch runtime embedder to DB stored values (non-destructive)

apply-current rebuilds chunks_vec at the current config’s dimension. The chunks table itself is preserved, but all vectors are deleted — run mm index <path> afterwards to re-index. revert-to-stored only flips runtime state; to make it permanent, update the embedding fields in ~/.memtomem/config.json accordingly.

mm purge --matching-excluded

Remove already-indexed chunks whose source paths match the built-in credential denylist or your indexing.exclude_patterns. Runs as a dry-run by default — pass --apply to actually delete.

mm purge --matching-excluded          # dry-run — shows what would be removed
mm purge --matching-excluded --apply  # perform the deletion

mm reset

Delete all data (chunks, sessions, activity log, etc.) from the DB and reinitialize the schema. Embedding configuration is preserved — re-index to repopulate, no re-config needed. A confirmation prompt shows the row count; pass -y to skip.

mm reset                             # confirm, then delete
mm reset -y                          # skip prompt

Where mm embedding-reset --mode apply-current rebuilds vectors only, mm reset drops the whole index. It doesn’t touch the config file — for a full wipe, pair it with mm init --fresh or mm uninstall.

mm uninstall

Clean up ~/.memtomem/ state (config, DB, fragments, backups, uploads) separately from removing the binary. Package-manager commands like uv tool uninstall memtomem only remove the executable, which leaves stale state behind on reinstall — since v0.1.23 this subcommand closes the gap.

mm uninstall                  # interactive, removes everything
mm uninstall -y               # skip the confirmation prompt
mm uninstall --keep-config    # preserve config.json + config.d/* + backups
mm uninstall --keep-data      # preserve the SQLite DB + ~/.memtomem/memories/
mm uninstall --force          # bypass the running-server safety check

Custom storage.sqlite_path values outside the default directory are included in the inventory. The command refuses to run while the MCP server is alive (open WAL handles risk corruption); stop it first or pass --force. External editor MCP entries (~/.claude.json, ~/.codex/config.toml, etc.) are detected and reported, never modified. At the end it prints the exact binary-removal command for your install context (uv tool uninstall memtomem, pip uninstall memtomem, etc.) so you can follow through.

Example Workflow

# 1. Initial setup (preset picker runs interactively)
mm init

# 2. Index your project
mm index ~/projects/my-app

# 3. Import existing AI tool memories
mm ingest claude-memory --source ~/.claude/projects/

# 4. Search from CLI
mm search "database migration patterns"

# 5. Open the Web UI to browse and manage memories
mm web --open

The MCP server runs automatically under your AI client once memtomem is registered in its MCP config.

See Quick Start for the full getting-started walkthrough.