MCP

Agent Memory speaks the Model Context Protocol. There are two ways to connect:

Both expose the same 20 tools.

Remote endpointCopy Anchor Link

URLsCopy Anchor Link

With an API key, the key's own workspace and application decide the scope: create the key for an application in the console to get application-scoped memory. See Scoping.

The endpoint is stateless Streamable HTTP: every POST is self-contained, with no session handshake.

AuthenticationCopy Anchor Link

• API key — send Authorization: Bearer amk_…. Works on every deployment, with no identity provider required.
• OAuth — when the deployment runs its built-in OAuth 2.1 server, an unauthenticated request gets a 401 whose WWW-Authenticate header points at the protected-resource metadata (/.well-known/oauth-protected-resource). Clients such as Claude Desktop, Claude Code and VS Code then run the sign-in flow automatically (with dynamic client registration), and you sign in with your Agent Memory account. See Authentication.

Connect a clientCopy Anchor Link

Replace https://memory.example.com with your deployment's URL.

claude mcp add --transport http agent-memory https://memory.example.com/v1/mcp \
  --header "Authorization: Bearer amk_..."

claude mcp add --transport http agent-memory https://memory.example.com/v1/mcp

The console's API Keys page shows a ready-made mcpServers block for each new key.

How the agent knows when to use memoryCopy Anchor Link

MCP tools are model-driven: the client shows the tools to the model, and the model decides when to call them. Agent Memory steers that in two ways:

1. Server instructions. The initialize response carries a usage protocol that compliant clients inject into the model's context: search at the start of a task, add a memory the moment something durable happens (with the right type and one stable runId), consolidate at the end, and report the outcome when the result is known.
2. Directive tool descriptions. search_memory says to call it at the start of a task, add_memory during it, consolidate at the end.

Some clients ignore server instructions. For the most reliable behaviour, add a short rule to the client's own instructions file (for example AGENTS.md for Codex, .cursorrules for Cursor, .clinerules for Cline, .github/copilot-instructions.md for VS Code Copilot, or a project instruction in Claude):

A persistent memory MCP server is connected. Use it as a loop:
- At the START of every task, call search_memory and follow prior decisions,
  corrections, violations and approved patterns.
- When you make a decision, the user corrects you, a rule is broken or a solution
  is approved, call add_memory with the matching type. Use one runId per task.
- When the task is done, call consolidate with that runId.
Prefer recalling memory over asking the user to repeat themselves.

ToolsCopy Anchor Link

Notes:

• runId defaults to mcp-session on the remote endpoint. Pass one stable runId per task so entries group into one episode.
• Tools that take a memory ID accept the full GUID or the short form (8+ characters) that search and explain print.
• agentId is optional everywhere and only needed when a key is bound to several agents; an agent the key isn't bound to returns Error: this credential is not bound to agent '…'. Naming a userId needs a key with act for users.
• Failures come back as tool results starting with Error: (for example a missing capability or an exhausted monthly quota), not as protocol errors.

Local stdio serverCopy Anchor Link

AgentMemory.Mcp is a .NET 10 console app that serves the same tools over stdio. It runs in one of two modes, chosen with MCP_MODE:

• remote — the process holds no database credentials and calls the HTTP API with a bearer token. Use this on developer machines.
• local (default) — the process runs the memory engine in-process against PostgreSQL and Redis. It is a trusted mode for operators on the database host; identity comes from configuration, not from a token.

ConfigureCopy Anchor Link

In local mode, connection strings and provider settings come from the usual configuration keys (environment variables such as ConnectionStrings__SharedDb, ConnectionStrings__ControlPlaneDb, ConnectionStrings__PlatformDb and ConnectionStrings__Redis).

Register it with a clientCopy Anchor Link

{
  "mcpServers": {
    "agent-memory": {
      "command": "dotnet",
      "args": ["run", "--project", "/path/to/agent-memory/AgentMemory.Mcp"],
      "env": {
        "MCP_MODE": "remote",
        "MCP_API_URL": "https://memory.example.com",
        "MCP_API_TOKEN": "amk_...",
        "MCP_WORKSPACE_ID": "<workspace-guid>"
      }
    }
  }
}

One stdio process is one session: every add_memory and search_memory call uses the process's run ID, so consolidating that run sweeps the whole session. Those two tools therefore take no runId, agentId or facet arguments; consolidate, report_outcome and record_retrieval_feedback still take an explicit runId.