Local stdio server

The hosted server is the one most people want. This page is for running the engine yourself: a checkout of twin-memory and a store directory on disk.

python -m twin_memory.mcp_server <store> --account NAME [--writes]

It serves one account of the store to an MCP client over stdio, with the hosted server's read tools under the same names, four more, and the same schemas as the HTTP routes.

What it doesCopy Anchor Link

• The account is the command's. No tool takes one, so a model cannot ask for another account's memory. Serving two accounts is two servers. An account nothing was written for is refused at start. default is the store python -m twin_memory.store build makes.
• Twelve read tools. The eight the hosted server lists: memory_search, memory_grep, memory_read, memory_ls, memory_around, memory_history, memory_latest and memory_overview. And four the hosted server does not offer: memory_recall, memory_lessons, memory_how_they_work and memory_next (see Local server only). It does not serve status, lineage or unfiled.
• Writes only with --writes. Started with --writes, it also lists memory_add, which lands what it is given in this store, so the server is then the account's writer. --writes is refused when REDIS_URL is set, since a consumer would be the writer there. Without the flag it serves no writes.
• It spends when a key is present. With OPENROUTER_API_KEY in the environment or in .env, memory_search makes one model call and memory_recall one to seven, as over HTTP. Without it both answer free. TWIN_EMBEDDER picks the dense lane as for python -m twin_memory.api; none loads no model.
• It needs the api extra (make install), since its schemas are the API's request models.
• It speaks MCP protocol versions 2025-11-25, 2025-06-18, 2025-03-26 and 2024-11-05.

Claude CodeCopy Anchor Link

claude mcp add twin-memory -e TWIN_EMBEDDER=none -- \
  uv run --directory /path/to/twin-memory python -m twin_memory.mcp_server /path/to/store --account default

--scope user makes it available in every project; claude mcp list checks it started.

Claude DesktopCopy Anchor Link

{
  "mcpServers": {
    "twin-memory": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/twin-memory",
        "python",
        "-m",
        "mcp_server",
        "/path/to/store",
        "--account",
        "default"
      ],
      "env": { "TWIN_EMBEDDER": "none" }
    }
  }
}

Restart Claude Desktop after editing it. The server logs to stderr, which Claude Desktop keeps in ~/Library/Logs/Claude/mcp-server-twin-memory.log.