How to Integrate ai-memory with Claude Code's Session-Aware Routing: A Complete MCP Guide

Integrate ai-memory with Claude Code's session-aware routing by installing the managed skill files via ai-memory install-instructions, configuring the AI_MEMORY_MCP_URL environment variable to point to the ai-memory server, and leveraging Claude Code's automatic X-Session-Id header propagation to isolate memory operations per conversation session.

The akitaonrails/ai-memory repository provides a production-ready session-aware routing layer designed specifically for agent clients like Claude Code. When you integrate ai-memory with Claude Code's session-aware routing, the system automatically directs retrieval, handoff, and durable-page requests to the appropriate tool implementations while maintaining strict session isolation through HTTP headers.

Step-by-Step Integration Process

Step 1: Install the Managed Agent-Skill Snippets

Begin by generating the required markdown skill files that contain the routing instructions. Run the installation command from your project root:

ai-memory install-instructions --target AGENTS.md

This command writes five skill bundles into the .agents/skills/ directory:

• .agents/skills/ai-memory-retrieval/SKILL.md
• .agents/skills/ai-memory-handoff/SKILL.md
• .agents/skills/ai-memory-durable-pages/SKILL.md
• .agents/skills/ai-memory-learning-maintenance/SKILL.md
• .agents/skills/ai-memory-routing-install/SKILL.md

Each file contains a unique managed marker (<!-- ai-memory-managed: routing-skill -->) defined in crates/ai-memory-core/src/routing_skills.rs within the MANAGED_SKILLS constant. The server uses this marker to verify that the skill is under ai-memory control.

Step 2: Configure the MCP Endpoint Connection

Point Claude Code at the running ai-memory MCP server by setting the environment variable:

export AI_MEMORY_MCP_URL="http://127.0.0.1:49374"

Alternatively, pass the URL via the --mcp-url flag when starting the server. Claude Code resolves its current agent session through an internal lifecycle hook and automatically adds the X-Session-Id header (containing a UUID) to every request. The session-aware router in crates/ai-memory-mcp/src/server.rs inspects this header along with the X-Agent-Kind: ClaudeCode value to route the request to the correct skill bucket.

Step 3: Enable Session Propagation

Claude Code automatically includes its session identifier in every MCP call—no additional code is required. The ai-memory system stores observations under this session ID, allowing the routing layer to retrieve or hand off sessions to other agents (e.g., Codex). The native session discovery logic resides in crates/ai-memory-workstream/src/transcript.rs, which handles the workspace and project scoping.

How the Router Implements Session-Aware Logic

The routing mechanism in crates/ai-memory-mcp/src/server.rs employs three distinct strategies to determine request handling:

Tool-to-Skill Mapping – Each managed skill contains a registry of tool identifiers (e.g., memory_query, memory_handoff_begin). In crates/ai-memory-core/src/routing_skills.rs, the EXPECTED_TOOL_CLUSTERS constant defines these associations:

const EXPECTED_TOOL_CLUSTERS: &[(&str, &str)] = &[
    ("memory_query", "ai-memory-retrieval"),
    ("memory_handoff_begin", "ai-memory-handoff"),
    // …
];

AgentKind Discrimination – The router matches the X-Agent-Kind: ClaudeCode header against the ai_memory_core::AgentKind enum. This mapping allows Claude-specific policies, such as refusing synthetic meta records, while maintaining compatibility with other agent types.

Session-ID Scoping – The router extracts the X-Session-Id value and constrains all read/write operations to a unique (workspace, project, session_id) triple. This guarantees that Claude Code's observations remain isolated from other concurrent agent sessions.

Practical Implementation Examples

Installing Skill Files

Execute the following to generate the routing instructions:

ai-memory install-instructions --target AGENTS.md

This creates the skill files with the managed marker, ensuring the server can verify skill integrity.

Starting the ai-memory Server

If the server is not already running, start it with:

ai-memory serve --bind 127.0.0.1:49374

Configuring Claude Code

Ensure Claude Code recognizes the MCP endpoint by exporting the URL in your shell environment before launching the editor:

export AI_MEMORY_MCP_URL="http://127.0.0.1:49374"

Testing Session-Aware Requests

The following curl example simulates how Claude Code routes a retrieval request (in production, Claude Code generates the SESSION_ID internally):

SESSION_ID=$(uuidgen)
curl -X POST "$AI_MEMORY_MCP_URL/api/v1/memory_query" \
     -H "Content-Type: application/json" \
     -H "X-Session-Id: $SESSION_ID" \
     -H "X-Agent-Kind: ClaudeCode" \
     -d '{"query":"latest project decisions"}'

The ai-memory MCP routes this to the retrieval skill and uses the session ID to fetch observations scoped to that specific Claude Code session.

Performing Agent Hand-offs

To transfer session context to another agent (e.g., Codex), invoke the handoff endpoint:

curl -X POST "$AI_MEMORY_MCP_URL/api/v1/memory_handoff_begin" \
     -H "Content-Type: application/json" \
     -H "X-Session-Id: $SESSION_ID" \
     -H "X-Agent-Kind: ClaudeCode" \
     -d '{"target_agent":"Codex"}'

The handoff skill records the intent, allowing the target agent to resume the session by providing the same X-Session-Id value.

Key Source Files in akitaonrails/ai-memory

File	Role
crates/ai-memory-core/src/routing_skills.rs	Defines the MANAGED_SKILLS constant, the managed marker pattern, and the EXPECTED_TOOL_CLUSTERS mapping that associates tool names with skill directories.
crates/ai-memory-mcp/src/server.rs	Implements the MCP request handler that extracts X-Agent-Kind and X-Session-Id headers and dispatches to the appropriate skill cluster based on the tool name.
crates/ai-memory-workstream/src/transcript.rs	Handles native session discovery and export logic; manages the (workspace, project, session_id) scoping for Claude Code work-streams.
AGENTS.md	Canonical instruction file located at the project root; contains the "install-self-routing" skill snippet that Claude Code reads to discover available memory tools.

Summary

• Installation requires running ai-memory install-instructions to create managed skill files under .agents/skills/ with verification markers.
• Configuration involves setting AI_MEMORY_MCP_URL to point Claude Code at the ai-memory server endpoint.
• Session Isolation relies on Claude Code's automatic X-Session-Id header and the router's scoping to (workspace, project, session_id) triples.
• Routing Logic maps tools to skills via EXPECTED_TOOL_CLUSTERS and discriminates agents via the AgentKind enum in crates/ai-memory-core/src/routing_skills.rs.
• Interoperability supports hand-offs to other agents (e.g., Codex) while maintaining session continuity through consistent session ID usage.

Frequently Asked Questions

What is the purpose of the managed skill marker in ai-memory?

The managed skill marker (<!-- ai-memory-managed: routing-skill -->) acts as a verification token defined in crates/ai-memory-core/src/routing_skills.rs. The server checks for this marker to confirm that a skill file was generated by the ai-memory install-instructions command and has not been manually modified, ensuring routing integrity and security.

How does Claude Code generate and propagate the session ID?

Claude Code generates a UUID through its internal lifecycle hook when a conversation begins. It automatically attaches this value to every MCP request via the X-Session-Id header. The ai-memory router in crates/ai-memory-mcp/src/server.rs extracts this header to scope all memory operations to that specific session, as tracked in crates/ai-memory-workstream/src/transcript.rs.

Can ai-memory route requests from agents other than Claude Code?

Yes, the routing layer supports multiple agent types through the AgentKind enum. While Claude Code identifies itself via the X-Agent-Kind: ClaudeCode header, other agents (such as Codex) can participate in the same session by providing the same X-Session-Id and using the appropriate AgentKind variant, enabling seamless hand-offs and multi-agent workflows.

Where are session observations physically stored?

Session observations are stored under the unique triple of (workspace, project, session_id) extracted from the request headers. This scoping mechanism, implemented in the work-stream module at crates/ai-memory-workstream/src/transcript.rs, ensures that data retrieved via memory_query or stored via other tools remains isolated to the specific Claude Code session and does not leak across different projects or workspaces.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}