Documentation — repo-memory-mcp

Quickstart

The public package is named repo-memory-mcp-ai. The server executable remains repo-memory-mcp.

pip install repo-memory-mcp-ai
repo-memory doctor
repo-memory-mcp

For a zero-install run, use:

uvx --from repo-memory-mcp-ai repo-memory-mcp

MCP configuration

Add this stdio server to the configuration file used by your MCP host:

{
  "mcpServers": {
    "repo-memory": {
      "command": "uvx",
      "args": ["--from", "repo-memory-mcp-ai", "repo-memory-mcp"]
    }
  }
}

Agent workflow

At session start, call get_startup_context().
When a durable correction is made, call remember_correction(topic, lesson).
When a project convention is established, call remember_rule(rule).
When architecture changes, call remember_decision(decision, rationale).
Search before repeating work with recall_memory(query).
Archive obsolete guidance with forget_memory(memory_id).

Important: MCP hosts decide when tools are called. This server does not automatically intercept every conversation. Give your agent an explicit startup instruction.

Core tools

Tool	Purpose
`get_startup_context`	Return concise, high-value repository guidance.
`remember_correction`	Persist a lesson from a correction or bug fix.
`remember_rule`	Persist a convention, constraint, or project rule.
`remember_decision`	Persist an architecture or implementation decision.
`recall_memory`	Search active memory with deterministic local relevance scoring.
`update_memory`	Correct existing guidance without replacement records.
`forget_memory`	Archive obsolete memory for audit-friendly retention.
`export_memory` / `import_memory`	Move validated memory between safe copies of the same repository.

Privacy and storage

Memory is stored locally at .repo-memory/memory.db in the detected repository. The server does not require API keys, cloud accounts, external embeddings, remote databases, or telemetry. Do not store credentials, tokens, passwords, or private keys.

Troubleshooting

My client cannot start the server

Run uvx --from repo-memory-mcp-ai repo-memory-mcp from a terminal. If it works there, check that your client uses the exact stdio JSON configuration and has access to uvx on its PATH.

Memory is not appearing

Confirm the client called a remember tool and that you are working inside the same repository. Run repo-memory doctor and inspect .repo-memory/.