Connect with MCP

Agent Memory exposes memory operations as Model Context Protocol (MCP) tools. MCP clients such as Claude Code, Claude Desktop, VS Code, Cursor, Cline, and Codex use these tools to read and write memory.

There are two transports:

HTTP MCP addressesCopy Anchor Link

AuthenticationCopy Anchor Link

With an API key (works in every client)Copy Anchor Link

Add the address and header to the client's MCP configuration:

{
  "mcpServers": {
    "agent-memory": {
      "url": "https://memory.empecta.com/v1/mcp",
      "headers": { "Authorization": "Bearer amk_..." }
    }
  }
}

The console's Install page generates a ready-made configuration for the client you choose; when a key is created, a copyable mcpServers snippet is also shown.

Claude Code pluginCopy Anchor Link

The Claude Code plugin is published in the public repository erkansezgin/agentmemory-claude-plugin. Install it with:

/plugin marketplace add erkansezgin/agentmemory-claude-plugin
/plugin install agentmemory@agentmemory

The plugin registers the HTTP MCP server using two environment variables:

stdio serverCopy Anchor Link

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

In the stdio server, identity comes from configuration: the tools have no agentId, facet, or runId parameters, and no server instructions (instructions) are sent. local mode is a trusted developer process that performs no permission checks; in shared environments use remote mode or the HTTP transport.

ToolsCopy Anchor Link

The HTTP server offers 20 tools. Tools that take an ID accept, in addition to the full GUID, the short ID from search output (a prefix of at least 8 characters that is unique within the workspace).

Tools return results as plain text. Errors arrive not as MCP protocol errors but as text starting with Error: …; your agent only needs to read this text.

Example add_memory response:

Operation 72afb4fb6c63427082a26b74390445ff. Memory stored: ad9a5c41-f032-4274-b2f6-df98d34ef542

If the same content already exists, the response is Memory merged into existing entry <id> ….

When does the agent use memory?Copy Anchor Link

The model calls MCP tools and decides when to call them. The HTTP server passes the following loop to the connected client as server instructions:

1. At task start, search_memory — recall earlier decisions, corrections, and approved patterns.
2. During the task, add_memory — when something lasting happens, write it with the right type, and use the same runId throughout the task.
3. At task end, consolidate(runId).
4. Once the outcome is known, report_outcome(runId, receiptId).

Some clients apply server instructions weakly. For the most reliable results, add the same rule to the client's project instructions as well (for example AGENTS.md, .cursorrules, .clinerules, .github/copilot-instructions.md, Claude project instructions):

This project has a persistent memory MCP server connected. Use it as a loop:
- Call search_memory at the start of every task; recall earlier decisions, corrections,
  violations and approved patterns, and follow them.
- When you make a decision, when the user corrects you, when a rule is broken, or when a
  solution is approved, save it with add_memory using the right type. Use the same runId
  throughout the task.
- When the task is done, call consolidate(runId); once the outcome is known, send report_outcome.

LimitsCopy Anchor Link

• In MCP, search_memory does not offer reading as of a past point in time (as-of) or topN; use REST POST /v1/memory/retrieve for these.
• The consolidate tool does not take custom extraction instructions; consolidation with instructions is available in REST.
• Valid values for sourceKind: agent, user, document, import.
• Every tool call counts toward the monthly operation quota.

Related pagesCopy Anchor Link

• Project memory for a coding agent
• Identity and access
• Search and context compilation