# 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. Install managed skills, configure MCP URL, and leverage automatic X-Session-Id header propagation for isolated memory operations per session.

- Repository: [Fabio Akita/ai-memory](https://github.com/akitaonrails/ai-memory)
- Tags: how-to-guide
- Published: 2026-08-20

---

**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:

```bash
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`](https://github.com/akitaonrails/ai-memory/blob/main/.agents/skills/ai-memory-retrieval/SKILL.md)
- [`.agents/skills/ai-memory-handoff/SKILL.md`](https://github.com/akitaonrails/ai-memory/blob/main/.agents/skills/ai-memory-handoff/SKILL.md)
- [`.agents/skills/ai-memory-durable-pages/SKILL.md`](https://github.com/akitaonrails/ai-memory/blob/main/.agents/skills/ai-memory-durable-pages/SKILL.md)
- [`.agents/skills/ai-memory-learning-maintenance/SKILL.md`](https://github.com/akitaonrails/ai-memory/blob/main/.agents/skills/ai-memory-learning-maintenance/SKILL.md)
- [`.agents/skills/ai-memory-routing-install/SKILL.md`](https://github.com/akitaonrails/ai-memory/blob/main/.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`](https://github.com/akitaonrails/ai-memory/blob/main/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:

```bash
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`](https://github.com/akitaonrails/ai-memory/blob/main/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`](https://github.com/akitaonrails/ai-memory/blob/main/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`](https://github.com/akitaonrails/ai-memory/blob/main/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`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-core/src/routing_skills.rs), the `EXPECTED_TOOL_CLUSTERS` constant defines these associations:

```rust
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:

```bash
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:

```bash
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:

```bash
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):

```bash
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:

```bash
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`](https://github.com/akitaonrails/ai-memory/blob/main/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`](https://github.com/akitaonrails/ai-memory/blob/main/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`](https://github.com/akitaonrails/ai-memory/blob/main/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`](https://github.com/akitaonrails/ai-memory/blob/main/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`](https://github.com/akitaonrails/ai-memory/blob/main/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`](https://github.com/akitaonrails/ai-memory/blob/main/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`](https://github.com/akitaonrails/ai-memory/blob/main/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`](https://github.com/akitaonrails/ai-memory/blob/main/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`](https://github.com/akitaonrails/ai-memory/blob/main/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.