Integration Guide

Claude Code Integration Guide

Give Claude Code persistent memory across sessions. Store decisions, search your knowledge base, and share context with your team — all powered by AgentRecall's graph-backed MCP server.

Overview

AgentRecall provides Claude Code with a persistent memory layer backed by a knowledge graph. Instead of losing context when you close a session, AgentRecall lets you:

  • Store — architectural decisions, debugging notes, code conventions
  • Search — semantic search across all stored memories
  • Relate — automatically build entity relationships via the knowledge graph
  • Share — team-wide memory through project-scoped configuration

The MCP (Model Context Protocol) server runs as a local stdio process. Claude Code communicates with it automatically — no API calls to write yourself.

Prerequisites

  • Python 3.10 or newer
  • Claude Code installed (any recent version with MCP support)
  • An AgentRecall account — sign up free at dashboard.agentrecall.cloud
  • An API key (starts with ark_) and an Agent ID

Installation

Install the AgentRecall MCP server package from PyPI:

# Install globally or in your project's virtual environment pip install agentrecall-mcp
Tip: We recommend installing in a dedicated virtual environment to avoid dependency conflicts:python -m venv ~/.venvs/agentrecall && source ~/.venvs/agentrecall/bin/activate

Setup

There are three ways to register the MCP server with Claude Code. Pick whichever fits your workflow.

A. CLI — User Scope

Registers the server globally for your user. Available in every Claude Code session automatically.

# One-time setup — run anywhere claude mcp add \ --transport stdio \ --scope user \ --env AGENTRECALL_API_KEY=ark_YOUR_KEY \ agentrecall \ -- agentrecall-mcp

B. CLI — Project Scope

Creates a .mcp.json file in the current directory. Other team members can pick it up from version control.

# From your project root claude mcp add \ --transport stdio \ --scope project \ --env AGENTRECALL_API_KEY=ark_YOUR_KEY \ agentrecall \ -- agentrecall-mcp
⚠️ Note: Do not commit your real API key to version control. Use environment variable substitution or a secrets manager.

C. Manual — Edit ~/.claude.json

Open ~/.claude.json (or create it) and add the server entry directly:

{ "mcpServers": { "agentrecall": { "command": "agentrecall-mcp", "args": [], "env": { "AGENTRECALL_API_KEY": "ark_YOUR_KEY", "AGENTRECALL_API_URL": "https://api.agentrecall.cloud/mcp", } } }

Configuration Reference

All configuration is done through environment variables passed to the MCP server process.

VariableRequiredDefaultDescription
AGENTRECALL_API_KEYYes—Your API key from the AgentRecall dashboard (starts with ark_).
AGENTRECALL_API_URLNohttps://api.agentrecall.cloud/mcpOverride if you're self-hosting or using a regional endpoint.
API keyNohermesUnique agent identifier. Each ID gets its own memory namespace. The agent is auto-created on first use if it doesn't exist.

Verify Installation

After setup, confirm the server is registered and reachable.

List registered MCP servers

claude mcp list

You should see agentrecall in the output with status ready.

Check MCP status inside a session

# Inside an active Claude Code session /mcp

This prints all connected MCP servers and their available tools. You should see tools like store_memory, search_memories, and traverse_graph.

Use Cases

1. Store Architectural Decisions

After a design discussion, tell Claude Code to save the decision for future sessions:

# In your Claude Code session, just ask: # "Store this architectural decision: we chose PostgreSQL # over MongoDB for the user service because of our need # for complex joins and ACID transactions." # Claude Code will call the MCP tool automatically: mcp("agentrecall", tool: "store_memory", args: { content: "Architectural decision: PostgreSQL chosen over MongoDB for user service...", category: "factual", importance: "high", metadata: { project: "user-service", type: "architecture" } } }) # Next session, Claude Code remembers this automatically.

2. Search Codebase Knowledge

Ask Claude Code to find relevant memories when you start working on a new area:

# "Search my memory for everything related to the auth module" mcp("agentrecall", tool: "search_memories", args: { query: "authentication module design and edge cases", limit: 5 } }) # Results ranked by semantic relevance — not just keywords.

3. Cross-Session Debugging

When you find a tricky bug, save the solution so you never re-encounter it:

# "Save this debugging insight: the race condition in the # payment queue was caused by missing await on # Stripe.confirmCardPayment in processOrder.ts line 142." # Later, when debugging a similar issue: # "Search for past debugging notes about race conditions" # Claude Code finds your stored insight and applies it.

4. Team Memory Sharing via .mcp.json

Use project-scoped setup so your whole team shares a memory namespace. Commit the .mcp.json file (with environment variables, not secrets):

{ "mcpServers": { "agentrecall": { "command": "agentrecall-mcp", "args": [], "env": { "AGENTRECALL_API_KEY": "${AGENTRECALL_API_KEY}", } } } }

Every team member sets their own AGENTRECALL_API_KEY in their shell profile, and the MCP server connects them all to the same agent namespace.

Troubleshooting

⚠ "Binary not found" or "command not found"

The agentrecall-mcp binary isn't on your PATH. Fix:

  • If using a virtualenv, make sure it's activated before running claude mcp add
  • Verify the binary exists: which agentrecall-mcp
  • If installed with pipx, ensure ~/.local/bin is on your PATH

⚠ Python / venv mismatch

Claude Code may use a different Python than the one you installed the package with. To fix, specify the full path in your MCP config:

// In ~/.claude.json or .mcp.json "command": "/Users/you/.venvs/agentrecall/bin/python", "args": ["-m", "agentrecall_mcp"]

⚠ Agent auto-creation

If you specify an API key that doesn't exist yet, AgentRecall automatically creates it on the first store or search call. No extra setup needed.

Multi-Project Setup

Use different API key values per project to keep memories isolated:

# Project A — frontend claude mcp add --scope project \ --env AGENTRECALL_API_KEY=ark_KEY \ agentrecall -- agentrecall-mcp # Project B — backend API claude mcp add --scope project \ --env AGENTRECALL_API_KEY=ark_KEY \ agentrecall -- agentrecall-mcp

Each project gets its own memory namespace. Memories stored in the frontend project won't pollute the backend project's context — unless you deliberately search across namespaces using the API directly.

Removing the Server

To unregister the AgentRecall MCP server from Claude Code:

# Remove from user scope claude mcp remove --scope user agentrecall # Or remove from project scope claude mcp remove --scope project agentrecall # If you set it up manually, remove the 'agentrecall' entry # from your ~/.claude.json # To uninstall the Python package entirely: pip uninstall agentrecall-mcp
Note: Removing the MCP server does not delete your stored memories. Your data remains in AgentRecall and is available when you reconnect.

Next Steps