# Claude Agent SDK

> Claude Agent SDK and Messages API integration example.

Canonical page: https://xmemory.ai/claude-agent-sdk/

This guide shows how to give Claude persistent memory by connecting it to the xmemory MCP server. Two approaches are covered:

- **Agent SDK** — the [Claude Agent SDK](https://code.claude.com/docs/en/agent-sdk) connects to the xmemory MCP server; the agent gets `write` and `read` (and more) as ready-made tools.
- **Messages API connector** — the [Claude Messages API](https://platform.claude.com/docs/en/agents-and-tools/mcp-connector) connects to the MCP server directly, with no SDK.

---

## Prerequisites

```bash
pip install claude-agent-sdk anthropic xmemory-ai pyyaml
```

Set `XMEM_API_KEY` (your xmemory key — create one in the [console](https://console.xmemory.ai)) in your environment; every example below reads it. Both approaches call Claude, so set `ANTHROPIC_API_KEY` too. (For TypeScript, the Agent SDK package is `@anthropic-ai/claude-agent-sdk`.)

---

## Part 1 — Create an instance

xmemory stores data in typed *instances*. Describe what you want to remember in plain language and xmemory designs the schema for you — natural-language generation is the primary path (you can also hand it an existing schema, e.g. a Pydantic model's JSON schema).

The contract is [XMD](https://xmemory.ai/xmd/). Agents may author it directly for exact control or use the
natural-language generator to save time, then review or improve extraction quality with the guide.

This is a one-time setup script. Save the returned instance ID (e.g. in an environment variable) and reuse it in your agent.

> **Fastest path:** the [CLI](https://xmemory.ai/cli/) creates an instance in three commands
> (`xmemcli xmd generate → validate → instance create`). The Python script below is the equivalent
> if you'd rather stay in code.

```python
import os
import yaml
from xmemory import XmemoryClient, SchemaType

API_KEY = os.environ["XMEM_API_KEY"]

# Connect and pick a cluster
client = XmemoryClient(api_key=API_KEY)
cluster_id = client.admin.list_clusters()[0].id

# Describe what to remember in plain language — xmemory designs the schema
schema = client.admin.generate_schema(
    cluster_id,
    "Track contacts with name, email, company, and notes.",
)

# Create the instance from that schema
inst = client.admin.create_instance(
    cluster_id=cluster_id,
    name="contacts",
    schema_text=yaml.dump(schema.data_schema, allow_unicode=True),
    schema_type=SchemaType.YML,
)
print(f"Created instance: {inst.id}")
# → store this in XMEM_INSTANCE_ID and reuse it on subsequent runs
```

The instance ID is a UUID string. Keep it — you'll use it to get an instance handle on subsequent runs.

---

## Part 2 — Claude Agent SDK with MCP

### Authentication

This headless flow sends your account **API key** directly as the Bearer token on the `/instance/<instance_id>` shortcut path — no OAuth exchange needed. The instance is bound by the **URL path**. See the [MCP guide](https://xmemory.ai/mcp/#authentication) for the other connection options.

Register the xmemory MCP server under `mcp_servers` (keyed by server name) with `type: "http"`. MCP tools must be allow-listed via `allowed_tools` using the `mcp__<server>__<tool>` pattern, or Claude can see them but not call them.

```python
import asyncio
import os
from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage

API_KEY = os.environ["XMEM_API_KEY"]
INSTANCE_ID = os.environ["XMEM_INSTANCE_ID"]  # from Part 1

async def main():
    options = ClaudeAgentOptions(
        mcp_servers={
            "xmemory": {
                "type": "http",
                "url": f"https://mcp.xmemory.ai/instance/{INSTANCE_ID}",
                "headers": {"Authorization": f"Bearer {API_KEY}"},
            }
        },
        allowed_tools=["mcp__xmemory__write_async", "mcp__xmemory__read"],
    )

    async for message in query(
        prompt="Remember that Alice Johnson works at Acme Corp, her email is alice@acme.com.",
        options=options,
    ):
        if isinstance(message, ResultMessage) and message.subtype == "success":
            print(message.result)

if __name__ == "__main__":
    asyncio.run(main())
```

The TypeScript SDK takes the same shape under `mcpServers` / `allowedTools`:

```typescript

const INSTANCE_ID = process.env.XMEM_INSTANCE_ID!;
const API_KEY = process.env.XMEM_API_KEY!;

for await (const message of query({
  prompt: "Remember that Alice Johnson works at Acme Corp, her email is alice@acme.com.",
  options: {
    mcpServers: {
      xmemory: {
        type: "http",
        url: `https://mcp.xmemory.ai/instance/${INSTANCE_ID}`,
        headers: { Authorization: `Bearer ${API_KEY}` },
      },
    },
    allowedTools: ["mcp__xmemory__write_async", "mcp__xmemory__read"],
  },
})) {
  if (message.type === "result" && message.subtype === "success") {
    console.log(message.result);
  }
}
```

> `write_async` returns immediately — recall it in a **later** turn (a subsequent `query` reflects it). Avoid `read` in the same turn as an async write.

---

## Part 3 — Messages API MCP connector

The Messages API can connect to a remote MCP server itself — Claude calls the tools server-side. Pass the server under `mcp_servers` with `type: "url"`, set `authorization_token` to your **raw** xmemory API key (the connector adds the `Bearer ` prefix), and reference the server from `tools` with an `mcp_toolset` entry. The connector is in beta — pass the `mcp-client-2025-11-20` beta flag.

```python
import os
import anthropic

API_KEY = os.environ["XMEM_API_KEY"]
INSTANCE_ID = os.environ["XMEM_INSTANCE_ID"]  # from Part 1

client = anthropic.Anthropic()  # reads ANTHROPIC_API_KEY

response = client.beta.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    betas=["mcp-client-2025-11-20"],
    mcp_servers=[
        {
            "type": "url",
            "url": f"https://mcp.xmemory.ai/instance/{INSTANCE_ID}",
            "name": "xmemory",
            "authorization_token": API_KEY,
        }
    ],
    tools=[{"type": "mcp_toolset", "mcp_server_name": "xmemory"}],
    messages=[{"role": "user", "content": "What do you know about Alice?"}],
)
print(response)
```

---

## Available MCP tools (instance connection type)

The instance connection exposes 10 default tools — 7 bound (`get_instance_id`, `get_instance_schema`, `get_setup_instructions`, `write`, `write_async`, `write_status`, `read`) and the 3-tool schema-evolution suggestion engine (`review_suggestions`, `decide_suggestions`, `apply_pending_decisions`) — plus an opt-in **Schema management** group (5 more). See the [MCP — Tools](https://xmemory.ai/mcp/#tools) reference for full parameter and return-shape details.
