CLI Reference

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

This page targets memtomem v0.6.8. Commands are grouped by function, but it’s a single reference — scan top to bottom.

Complete Command Index

The current top-level surface is preserved here in full. Detailed task flows follow below; use mm <command> --help for the option types accepted by the installed 0.6.8 binary.

Group	Commands
Setup / data	init, config, add, index, ingest, mem, memory
Retrieval / UI	search, recall, tags, pinned, shell, web, serve
Runtime context	context, wiki, sync-doctor
Collaboration	session, activity, agent, review
Evaluation / operations	status, doctor, quality, warmup, watchdog, schedule
Lifecycle	gc, embedding-reset, purge, reset, upgrade, uninstall, version

All command-group subcommands are mirrored below.

Group	Subcommands
activity	log
agent	debug-resolve, list, migrate, register, search, share
config	set, show, unset
context	adopt, copy, detect, diff, export, generate, import, init, install, memory-migrate, migrate, move, projects, pull, rescan, seed-validation, settings-copy, settings-doctor, settings-migrate, status, sync, update, version
context projects	add, list, pause, remove, resume
context version	create, delete-label, enable, list, promote
gc	orphan-projects, orphan-sources
ingest	claude-memory, codex-memory, gemini-memory
mem	init, rescan, rescan-files
memory	doctor
pinned	compose, delete, get, list, set
quality	cases, compare, experiment, export, gate, import, promote, replay, show, status
review	approve, evidence, list, recover, reject, scan, show
schedule	add, delete, list, run-now
session	end, events, list, start, wrap
tags	delete, list, merge, rename
watchdog	history, run, status
web	status, stop
wiki	agent, command, init, list, pull, push, remote, skill
wiki agent/command/skill	commit, diff, lint, new, override, promote

Bare mm web launches the UI; status and stop manage it.

Additional diagnostics and review

mm doctor --json
mm agent debug-resolve --agent-id alice
mm review evidence CANDIDATE_ID --top-k 5
mm context seed-validation --help
mm context version --help
mm context settings-doctor --json

doctor diagnoses runtime configuration; agent debug-resolve explains search scope. review evidence compares a candidate with indexed memories but never approves it. BM25-only or unindexed dense stores may report evidence unavailable. seed-validation writes validation context assets; inspect its help before choosing to run it. settings-doctor --json reports the highest-ranking status of duplicates, malformed, incomplete, advisory, clean. advisory means the only findings are hook commands that may not run on another machine; clean means every axis is empty. duplicates and malformed exit 1; the others exit 0, so a script that passes only on clean should accept advisory too or read the findings. A settings file in a directory memtomem cannot search is skipped and listed as unreadable; with no duplicates or malformed matchers the status is then incomplete.

Setup

In v0.6.8, -y is accepted but ignored. Scripts must pass --non-interactive explicitly. Embedding reset deletes vectors but retains file hashes, so recovery requires mm index --force <path>.

mm init

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

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

mm init                              # interactive setup with preset picker
mm init --non-interactive            # auto-accept; behaves as `--preset minimal --non-interactive`
mm init --preset korean --non-interactive   # apply Korean preset non-interactively
mm init --preset english --non-interactive   # English preset, no prompts
mm init --advanced                   # skip picker, run full 10-step wizard
mm init --fresh                      # bulk-clean accumulated config, then re-run 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 --non-interactive, it prints a recovery hint pointing at mm embedding-reset --mode apply-current. The chunks table itself is preserved, so re-running mm index --force <path> afterwards restores the working set.

--fresh resets wizard-untouched canonical settings to built-in defaults. It preserves custom keys, credentials, endpoints and user-curated lists; a backup is written only when keys are actually dropped.

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 (core / standard / full) in the client’s MCP config. The default is core (8 core tools + the mem_do router, 9 total); full exposes 100 current tools without deprecated aliases. 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 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.

Search & Recall

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 tags list / rename / delete / merge

Curate the tags on your chunks — the CLI equivalent of the Web UI Tags tab. Every mutating subcommand is a dry-run by default; pass --apply to actually write.

mm tags list                                 # tags in use and how often
mm tags rename ops infra                      # dry-run preview
mm tags rename ops infra --apply              # perform the rename
mm tags delete deprecated --apply             # drop a tag (chunks stay indexed)
mm tags merge py python --into python --apply # fold several tags into one

Without --apply, each command first shows the affected chunk count and samples. delete only strips the tag — the chunks themselves stay in the index.

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 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. Simple mode shows Home, Search, Sources, Gateway, Index, and Settings. Gateway contains Overview, Projects, Skills, Commands, Subagents, MCP Servers, Hooks, and Wiki; rows use Push and preview-first Pull actions. Settings contains Config, Namespaces, and Reset Database.

The header’s Advanced toggle reveals Tags and Timeline plus Dedup, Age-out, and Export/Import settings. Pass --dev (or set MEMTOMEM_WEB__MODE=dev) to add maintainer pages: Sessions, Search Runs, Quality Lab, Working Memory, Procedures, Health Report, Redaction.

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

Adding & Indexing

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 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 watched by the long-running memtomem-server process, but the watcher is reactive only. It reindexes modify/create/move events after startup; pre-existing files are not scanned automatically. Seed once with mm index <dir> (or mem_index(path="<dir>")), then let the MCP server watcher handle later edits. MEMTOMEM_INDEXING__STARTUP_BACKFILL=true is an opt-in one-shot backfill for the Web UI startup path.

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 Antigravity CLI GEMINI.md
mm ingest codex-memory --source ~/.codex/memories/      # import Codex CLI memories

mm mem init / rescan / rescan-files

Manage the explicit project-memory trust gate and audit already-stored material without writing new memory.

mm mem init --scope project_local
mm mem init --scope project_shared --confirm-project-shared
mm mem rescan --scope user [--source PATH] [--json] [--quiet]
mm mem rescan-files --json

init requires a real project marker and registers the chosen memory tier atomically. rescan is read-only and exits 1 on a privacy finding; the scope is always explicit. rescan-files audits historical imported, fetched, and session files.

Context Gateway

The Context Gateway keeps canonical agents, skills, and commands in a Store. sync Pushes Store copies out to runtimes; pull previews and brings a selected runtime copy back into the Store. Cross-project / cross-tier transfer and fleet-wide operations use the same model.

Tiers are addressed by friendly labels: User (--scope user, personal, visible in every project), Project (shared) (--scope project_shared, git-tracked), and Project (local) (--scope project_local, local drafts).

mm context sync

Sync your stored canonical files out to the detected runtime files.

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

Project (shared) is git-tracked, so it requires explicit confirmation and should not contain secrets. Syncing to the User tier (--scope user) places the canonical files under ~/.memtomem/ so they show up in every project — because that writes outside the project (your home directory), the gateway shows exactly which file paths it will touch and asks for confirmation. In non-interactive contexts, --yes skips the prompt.

MCP server definitions move through the same flow. mm context sync --include=mcp-servers syncs canonical MCP server definitions into a project’s .mcp.json (with secret-safety checks) — an opt-in path that only runs when you ask for it.

mm context pull

Pull one named runtime artifact into the Store. Preview is the default; --diff shows the would-land change, --from selects a runtime when candidates diverge, and --overwrite snapshots the current Store payload before replacement.

mm context pull skills reviewer
mm context pull skills reviewer --from claude --diff
mm context pull skills reviewer --from claude --scope project_shared --overwrite --apply

Reuse a skill from another project (mm context move / copy)

Use this when you want to bring a skill, agent, or command you already built in another project into this one, or shift it between tiers. copy leaves the original in place (rename it with --as if needed); move cleans up the source.

# copy another project's skill into the current one (preview first)
mm context copy skills my-skill --to-project ~/work/other-app
mm context copy skills my-skill --to-project ~/work/other-app --apply

# copy to your user tier under a new name
mm context copy agents reviewer --to user --as reviewer-strict --apply

# tier move: promote a local draft to the shared tier
mm context move commands deploy --to project_shared --confirm-project-shared --apply

# copy an MCP server definition to another project
mm context copy mcp-servers github --to-project ~/work/other-app --apply

Both default to a dry-run preview; pass --apply to execute. A destination collision always refuses (no --force valve). A landing in Project (shared) runs a privacy scan and additionally requires --confirm-project-shared. After a transfer the command prints the follow-up that pushes the artifact out to your AI tools at the destination (e.g. mm context sync) so you can run it next.

Operate across many projects (mm context projects)

Register the projects you work across, then push shared artifacts out to all of them in one call (sync --all-projects) or ask read-only which projects have drifted (status --all-projects).

mm context projects add ~/work/app-a          # register in the registry
mm context projects list                      # registered projects + health/enrollment
mm context projects pause ~/work/app-a        # exclude from batch operations
mm context projects resume ~/work/app-a       # include again

mm context sync --all-projects                # bulk-sync every eligible project
mm context status --all-projects              # read-only: which projects drifted

The bulk sync targets the Project (shared) tier only, and one project’s failure does not abort the batch. A paused project is skipped by every --all-projects operation.

Seeding from existing runtime files

mm context init seeds canonical files from the runtime-specific files already on this machine. Give it the artifact kinds and the 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, Antigravity CLI, or another runtime and want memtomem to manage them going forward. For reuse across projects see move/copy above; to install from a host-global library see mm wiki.

Carrying an artifact to another machine

mm context export packs one canonical artifact into a portable bundle — a single JSON file with no absolute paths and no hostnames — and mm context import lands a bundle in a canonical store (ADR-0037). Use this pair to hand an artifact to a colleague; use context init above when the files are already on this machine.

mm context export skills deploy-check --out deploy-check.json
mm context import deploy-check.json --to user            # preview (the default)
mm context import deploy-check.json --to user --apply    # write

A bundle is foreign by definition, so every entry is scanned on the way in no matter which tier it lands in, and --to is required: a foreign file must not choose where it lands. Export refuses on a secret from every source tier and has no force flag, because a file you have handed over is as unretractable as a pushed commit. On import, --force-unsafe-import accepts a secret-shaped value into user or project_local after review; a project_shared landing refuses a secret-shaped value in every case, with or without that flag.

Wiki — a canonical artifact library

Collect canonical versions of your skills, agents, and commands in a host-global wiki (~/.memtomem-wiki/) and install them into projects on demand. The wiki is a normal git repo, so changes are recorded as isolated commits and backed up / synced across machines via remote/push/pull — no separate sync tooling needed.

mm wiki init                          # create ~/.memtomem-wiki/ (skills/ agents/ commands/)
mm wiki init --from git@host:me/wiki  # clone an existing wiki from a git URL
mm wiki list                          # list the skills / agents / commands you hold
mm wiki list --type skills

mm wiki remote git@host:me/wiki       # configure the backup remote (origin)
mm wiki push                          # back up to the remote
mm wiki pull                          # restore on another machine

Each artifact kind (skill / agent / command) has a subgroup to seed per-runtime overrides and to diff, lint, and commit them. The Commit button in the dev-mode browser does the same, so no raw git is required.

mm wiki skill override my-skill --vendor claude --editor   # seed an override from canonical content
mm wiki skill diff my-skill --vendor claude                # diff against the canonical render
mm wiki skill lint my-skill                                # validate it is installable (usable as a CI gate)
mm wiki skill commit my-skill --vendor claude              # record as an isolated commit

Install an artifact you’ve collected with mm context install <type> <name>.

Sessions & Multi-Agent

mm pinned

Manage durable Pinned Context blocks that compose ahead of retrieved memory. The complete group is list, get, set, delete, and compose.

mm pinned list
mm pinned get <key>
mm pinned set <key> --content "Keep reviews evidence-first"
mm pinned delete <key>
mm pinned compose

See Pinned Context for exact scope, shadowing, idempotency, and composition rules.

mm review

Generate and adjudicate review-first memory candidates. Nothing becomes durable until approval.

mm review scan <session-id>
mm review list --status pending
mm review show <candidate-id>
mm review approve <candidate-id> --reviewer alice
mm review reject <candidate-id> --reviewer alice --reason "not durable"
mm review recover --stale-after-minutes 15 --actor alice

mm session

Manage agent sessions — start, end, list, events, and wrap. 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 --auto --json                     # summarize from events, print a JSON ack

mm session end --json prints {"ok": true, "session_id": ..., "summary": ..., "event_count": N} on success, and {"ok": false, "reason": ...} with exit code 1 when there is no active session or storage fails. mm session events --json with no session prints {"error": "no_session"} and also exits 1.

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; a failure returns {"ok": false, "reason": ...}. No active session (no_active_session) is a no-op and exits 0; malformed --meta (invalid_meta) or a failed write (write_failed) exits 1. Without --json, a missing session or a failed write prints nothing on stdout and exits 0.

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._-] — IDs outside the allowed pattern 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.

Diagnostics

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)
mm status --json                     # machine-readable, for scripts / `jq` pipelines

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

When search.tokenizer is kiwipiepy but the kiwipiepy package cannot be found, or the process has already fallen back to unicode61, both mm status and mem_status list a tokenizer_fallback warning. Rows indexed during the fallback are tokenized differently, so Korean keyword search can miss them. Install the korean extra wherever memtomem runs, restart its servers, then rebuild the keyword index.

mm sync-doctor

Run six read-only checks against the current private memory-sync repository. Failures exit non-zero; warnings do not.

mm sync-doctor

mm warmup

Preload the local embedder / reranker models so the first query doesn’t pay the one-time model load. Optional — without it the models load lazily on first use.

mm warmup                            # load models now (one-shot)

To warm up automatically when the MCP server starts, set MEMTOMEM_WARMUP__ENABLED=true. Remote providers (Ollama / OpenAI / Cohere) are skipped — there’s nothing local to preload.

mm memory doctor

Inspect memory-store consistency read-only — it reports 3-way drift between the notes folder on disk, the index file, and the searchable DB (e.g. files added while the server was off and never indexed, or dead index links). The default report is read-only and changes nothing.

mm memory doctor                     # inspect every memory_dir (read-only)
mm memory doctor ~/notes             # scope to one configured memory_dir
mm memory doctor --fix               # preview removal of broken index links (dry-run)
mm memory doctor --fix --apply       # actually remove broken links

--fix only removes index pointer lines whose target is missing on disk, and it is a dry-run unless --apply is also passed. It exits 1 when any error-severity finding exists, so it works as a CI check. A held missing source is reported as held_source, a warning, so it exits 0 when held sources are the only finding.

dangling_wikilink is informational: it may be a deliberate forward reference or a stale name. It never fails the run and --fix never removes it.

mm quality

Manage deterministic retrieval evaluation cases, replay them, compare reports, and enforce a quality gate. Search runs and labels are also available in the dev-mode Web UI’s Search Runs and Quality Lab pages.

mm quality cases list
mm quality replay --output report.json
mm quality compare baseline.json candidate.json
mm quality gate baseline.json candidate.json

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 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. The dispatcher rides the health-watchdog loop, so registered jobs only fire when both scheduler.enabled and health_watchdog.enabled are on.

Maintenance & Lifecycle

mm gc orphan-sources

Find indexed source records whose files no longer exist. Preview is the default; pass --apply to remove the orphaned source records and their chunks permanently.

The watcher, scheduled compaction and health maintenance never delete a missing source on their own: they hold it. A held source is hidden from search while its chunks are kept for recovery. To delete those chunks, review with mm gc orphan-sources, then run it with --apply. Over MCP, cleanup_orphans purges only when both dry_run=false and confirm_purge=true are passed. One case still deletes on its own: a path that now holds a directory or another non-regular file loses its chunks on the next event for it.

mm gc orphan-sources
mm gc orphan-sources --apply

mm gc orphan-projects handles a separate case: chunks whose recorded project_root no longer exists. It previews by default; use --apply for per-root confirmation or --apply --yes for an explicitly non-interactive deletion. Review removable or temporarily unmounted roots before confirming.

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 --force <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 upgrade

Stop a running memtomem-server, then reinstall via uv tool. uv tool install --reinstall memtomem alone only swaps the on-disk bytes — a server already imported by an MCP client keeps running the previous version — so this adds the process-cleanup step around it.

mm upgrade                           # reinstall to the latest version (extras auto-detected)
mm upgrade --version 0.6.8           # pin a specific version
mm upgrade --extras all              # name the extras to install (default: auto-detect)
mm upgrade --dry-run                 # print the plan, change nothing

Extras are auto-detected from the current uv-tool install by default, so a memtomem[all] user keeps [all]. If uv’s install receipt is missing or unreadable, none are detected; check the Extras: line of --dry-run and pass --extras when it says none were found.

Since 0.6.5 the database uses schema version 3. The first newer process to open it migrates it; an earlier binary then stops with This database has schema version 3, but this memtomem binary only supports up to 2 and exit code 1, without touching the data. Any client that launches its own server pinned to an earlier memtomem== version, such as an MCP entry, has to move too.

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          # limited POSIX heuristics only; stop live writers first

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. --force cannot bypass live instance-registry evidence, the lifecycle barrier, untrusted registry state, or an open SQLite database on Windows. 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.

See Quick Start for the full getting-started walkthrough.

Complete option index by command

Public long options from the pinned source. Short aliases and the common --help flag are omitted. Use each command’s --help for arguments, defaults, and constraints.

Command	Options
mm	--version
mm activity	—
mm activity log	--content, --json, --meta, --type
mm add	--allow-namespace-mix, --confirm-project-shared, --file, --force-unsafe, --json, --namespace, --scope, --tags, --title, --yes
mm agent	—
mm agent debug-resolve	--agent-id, --current-agent-id, --current-namespace, --include-shared, --no-include-shared
mm agent list	--json
mm agent migrate	--dry-run, --yes
mm agent register	--color, --description
mm agent search	--agent-id, --format, --include-shared, --no-include-shared, --shared-namespace, --top-k
mm agent share	--force-unsafe, --target
mm config	—
mm config set	—
mm config show	--format, --json
mm config unset	—
mm context	—
mm context adopt	—
mm context copy	--apply, --as, --confirm-project-shared, --from, --to, --to-project, --yes
mm context detect	--include
mm context diff	--include, --scope
mm context export	--from, --no-versions, --out
mm context generate	--agent, --include, --label, --on-drop, --scope, --strict, --yes
mm context import	--apply, --as, --confirm-project-shared, --force-unsafe-import, --to, --to-project, --yes
mm context init	--confirm-project-shared, --force-unsafe-import, --include, --only, --overwrite, --scope
mm context install	--all, --force, --yes
mm context memory-migrate	--apply, --confirm-project-shared, --from, --to, --yes
mm context migrate	--apply, --confirm-project-shared, --force, --from, --to, --yes
mm context move	--apply, --confirm-project-shared, --from, --to, --to-project, --yes
mm context projects	—
mm context projects add	--label
mm context projects list	--json
mm context projects pause	—
mm context projects remove	—
mm context projects resume	—
mm context pull	--apply, --confirm-project-shared, --diff, --force-unsafe-import, --from, --json, --overwrite, --scope, --yes
mm context rescan	--json, --quiet, --scope
mm context seed-validation	--force, --json
mm context settings-copy	--apply, --confirm-project-shared, --event, --hook-command, --json, --matcher, --to, --to-project, --yes
mm context settings-doctor	--json, --scope
mm context settings-migrate	--apply, --confirm-project-shared, --from, --json, --to, --yes
mm context status	--all-projects, --scope
mm context sync	--all-projects, --force-unsafe, --include, --label, --on-drop, --runtime, --scope, --strict, --yes
mm context update	--all, --dry-run, --force, --force-head, --yes
mm context version	—
mm context version create	--note, --scope
mm context version delete-label	--scope
mm context version enable	--scope
mm context version list	--scope
mm context version promote	--scope, --to, --version
mm doctor	--claude-mcp, --json
mm embedding-reset	--mode, --yes
mm gc	—
mm gc orphan-projects	--apply, --yes
mm gc orphan-sources	--apply, --yes
mm index	--debounce-window, --flush, --force, --force-unsafe, --json, --namespace, --no-recursive, --reassign-namespaces, --recursive, --status
mm ingest	—
mm ingest claude-memory	--dry-run, --source
mm ingest codex-memory	--dry-run, --source
mm ingest gemini-memory	--dry-run, --source
mm init	--advanced, --api-key, --auto-ns, --db-path, --decay, --fresh, --include-provider, --mcp, --memory-dir, --model, --namespace, --non-interactive, --preset, --provider, --tokenizer, --top-k
mm mem	—
mm mem init	--confirm-project-shared, --scope
mm mem rescan	--json, --quiet, --scope, --source
mm mem rescan-files	--json
mm memory	—
mm memory doctor	--apply, --fix, --json
mm pinned	—
mm pinned compose	--agent, --agent-id, --max-chars, --no-rerank, --top-k
mm pinned delete	--agent, --agent-id, --confirm-project-shared, --scope
mm pinned get	--agent, --agent-id, --scope
mm pinned list	--agent, --agent-id, --json
mm pinned set	--agent, --agent-id, --confirm-project-shared, --content, --description, --file, --force-unsafe, --priority, --scope
mm purge	--apply, --json, --matching-excluded, --sample
mm quality	—
mm quality cases	--format, --status
mm quality compare	--fail-on-regression, --format, --out
mm quality experiment	--as-of, --baseline, --case, --format, --out, --policy, --profile
mm quality export	--case, --out
mm quality gate	--comparison-out, --format, --out, --policy
mm quality import	--replace
mm quality promote	--allow-unreplayable-filters, --name
mm quality replay	--as-of, --case, --format, --out
mm quality show	—
mm quality status	—
mm recall	--format, --limit, --namespace, --scope, --since, --source-filter, --tag-filter, --until
mm reset	--backup, --force, --json, --yes
mm review	—
mm review approve	--reason, --reviewer
mm review evidence	--top-k
mm review list	--limit, --status
mm review recover	--actor, --limit, --stale-after-minutes
mm review reject	--reason, --reviewer
mm review scan	—
mm review show	—
mm schedule	—
mm schedule add	--cron, --job, --params
mm schedule delete	—
mm schedule list	--json
mm schedule run-now	—
mm search	--as-of, --format, --namespace, --no-rerank, --scope, --source-filter, --tag-filter, --top-k
mm serve	—
mm session	—
mm session end	--auto, --json, --summary
mm session events	--json
mm session list	--agent-id, --json, --limit, --since
mm session start	--agent-id, --auto-end-stale, --idempotent, --json, --namespace, --title
mm session wrap	--agent-id, --title
mm shell	—
mm status	--format, --json
mm sync-doctor	—
mm tags	—
mm tags delete	--apply, --yes
mm tags list	—
mm tags merge	--apply, --into, --yes
mm tags rename	--apply, --yes
mm uninstall	--force, --keep-config, --keep-data, --yes
mm upgrade	--dry-run, --extras, --grace, --json, --version, --yes
mm version	—
mm warmup	—
mm watchdog	—
mm watchdog history	--hours
mm watchdog run	--json
mm watchdog status	--json
mm web	--allow-remote-ui, --background, --dev, --host, --log-file, --mode, --open, --port, --timeout, --trusted-host, --trusted-origin
mm web status	—
mm web stop	—
mm wiki	—
mm wiki agent	—
mm wiki agent commit	--canonical, --message, --vendor
mm wiki agent diff	--vendor
mm wiki agent lint	--vendor
mm wiki agent new	--editor
mm wiki agent override	--editor, --force, --vendor
mm wiki agent promote	--message, --project
mm wiki command	—
mm wiki command commit	--canonical, --message, --vendor
mm wiki command diff	--vendor
mm wiki command lint	--vendor
mm wiki command new	--editor
mm wiki command override	--editor, --force, --vendor
mm wiki command promote	--message, --project
mm wiki init	--from
mm wiki list	--type
mm wiki pull	—
mm wiki push	—
mm wiki remote	—
mm wiki skill	—
mm wiki skill commit	--canonical, --message, --vendor
mm wiki skill diff	--vendor
mm wiki skill lint	--vendor
mm wiki skill new	--editor
mm wiki skill override	--editor, --force, --vendor
mm wiki skill promote	--message, --project