Quick Start

This path gets one thing working first: install the LTM server, run setup, save one memory, and find it again from the CLI. That proof needs neither an existing notes directory nor a connected editor. Connect an MCP client and index existing files only after the basic memory loop works. STM is optional.

1. Install

uv tool install 'memtomem[all]'       # or: pipx install 'memtomem[all]'
mm --version

[all] includes the Web UI, local ONNX embeddings, code chunking, Korean tokenizer support, Ollama / OpenAI clients, Langfuse, and LangGraph adapters. For a smaller BM25-only install, see Installation.

If mm --version prints an older version right after install, upgrade with refreshed package metadata:

uv tool install 'memtomem[all]' --refresh

If the shell can’t find mm at all (command not found), run uv tool update-shell and reopen the terminal — see Troubleshooting.

2. Run Setup

mm init

The mm init wizard starts with a preset picker:

Preset	Best for	What it does
Minimal	First smoke test, smallest install	BM25 keyword search only
English	Most English projects	Local ONNX embeddings + English reranker
Korean	Korean or multilingual notes	Multilingual embeddings, reranker, Korean tokenizer

Choose Minimal for the fastest no-model-download first proof. You can rerun mm init later to add semantic search.

For scripts or CI:

mm init --non-interactive                   # minimal preset, no prompts
mm init --preset english --non-interactive  # English preset, no prompts
mm init --preset korean --non-interactive   # Korean preset, no prompts
mm init --advanced                          # full wizard

During setup you can also register existing AI-agent memory folders for watching, such as Claude Code memories, Claude plans, or Codex CLI memories. Registration only sets them up for future watching; seed existing files once with mm index.

At the end, the mm init wizard offers to auto-register memtomem with your MCP client (e.g. Claude Code). Accept it and Step 4 is already done — you’ll only need the manual steps below if you skip this prompt.

3. Verify a Memory Round Trip

First confirm the CLI can open the config and database:

mm status

Zero chunks is normal. Now create and find one controlled memory without depending on an existing folder or agent:

mm add "Deployment checklist uses blue-green rollout" --tags ops
mm search "blue-green"

The search should return the sentence you just added. mm add writes to the configured user memory directory and indexes the entry immediately.

4. Connect Your MCP Client

If you picked “auto-register with Claude Code” in the mm init wizard, LTM (memtomem-server) is already registered — no extra LTM command needed.

For a manual registration (skipped the wizard prompt, or moved to a new machine):

claude mcp add memtomem -s user -- memtomem-server

Add the server to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "memtomem": {
      "command": "uvx",
      "args": ["--from", "memtomem", "memtomem-server"]
    }
  }
}

The command must be memtomem-server — plain memtomem is the CLI and will not start the MCP server.

Add the server to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "memtomem": {
      "command": "uvx",
      "args": ["--from", "memtomem", "memtomem-server"]
    }
  }
}

The command must be memtomem-server — plain memtomem is the CLI and will not start the MCP server.

Add the server to your config file (macOS ~/Library/Application Support/Claude/claude_desktop_config.json, Windows %APPDATA%\Claude\claude_desktop_config.json), then restart Claude Desktop:

{
  "mcpServers": {
    "memtomem": {
      "command": "uvx",
      "args": ["--from", "memtomem", "memtomem-server"]
    }
  }
}

For other clients and the full option matrix, see MCP Client Setup.

Ask your agent to “call mem_status” after registration. That verifies the MCP client is launching the same server your terminal sees. If the agent reports no memtomem tools, see Troubleshooting.

5. Index Existing Notes

Once the controlled round trip works, index a directory that actually exists:

mm index ~/notes
mm index ~/projects/my-app/docs

Replace these examples with your real paths, then search for a phrase you already know appears in those files.

After that, use natural language in your MCP client:

Tell your agent	Tool usually called	Result
”Check memtomem status”	`mem_status`	Connection and index summary
”Remember this decision…”	`mem_add`	New memory stored in markdown
”Index this docs folder”	`mem_index`	Existing files become searchable
”Search for the deploy checklist”	`mem_search`	Ranked snippets from your memory

6. Open the Web UI

mm web --open

The default Web UI is the user-facing surface for search, sources, tags, timeline, settings, and Context Gateway. mm web --dev adds maintainer-oriented pages that most users do not need.

Optional: Add STM Later

memtomem-stm is a separate proxy for proactive memory surfacing and response compression. Add it after the LTM flow above works:

uv tool install memtomem-stm
mms init --mcp claude   # prompts for one upstream server, then registers STM with Claude Code

mms init walks you through adding one upstream MCP server (name, prefix, command) and then offers a 3-way client registration (Claude Code / write .mcp.json / skip). After it finishes, confirm the setup with three read commands:

mms list      # the upstreams you've registered (and their SURFACING column)
mms status    # config summary — is the proxy enabled and pointed at the right file?
mms health    # probe upstream connectivity and LTM surfacing readiness

For a non–Claude-Code client, register STM manually with a one-line command block:

{
  "mcpServers": {
    "mms": { "command": "mms" }
  }
}

STM’s proxied tools surface as <prefix>__<tool>. If a proxied tool goes missing after registration, it’s almost always the composed mcp__<server>__<prefix>__<tool> name exceeding MCP’s 64-char limit — see Troubleshooting for the fix (a shorter prefix, or registering STM under a short client name).

Moving a server behind the proxy is reversible — if STM isn’t a fit, mms eject restores each server to the host config it came from.

See STM Overview when you want tool-response compression or automatic memory injection.

Memory Persistence — save in one session, recall in another
Hybrid Search — BM25 + vector + RRF fusion
MCP Tools — core, standard, and full tool modes
Context Gateway — sync agents, skills, and commands across runtimes, move or copy them between projects, and sync many projects at once
Troubleshooting — fixes for command not found, missing tools, and surfacing that isn’t firing