Atamaia + Claude Code

Claude Code talks to Atamaia over MCP. Hydrate at session start. Persist what matters. The REST API is the source of truth (D12); MCP is a window onto it.

Connection, auth, and the adapter shape: docs-mcp-integration.md. Verb inventory: docs-tool-surface.md. forge CLI and generated skills: docs-cli-integration.md.

Canonical API host: https://api.atamaia.ai.

Prerequisites

An identity API key, minted as atamaia_… (POST /api/identities/{id}/api-keys, or MCP identity_api_key_create). Raw secret is returned once.
Claude Code installed.

Do not use atm_. Do not send Authorization: ApiKey or X-Api-Key.

Option 1: MCP (recommended)

Add to the project’s .mcp.json:

{
  "mcpServers": {
    "atamaia": {
      "type": "url",
      "url": "https://api.atamaia.ai/mcp",
      "headers": {
        "Authorization": "Bearer atamaia_YOUR_KEY"
      }
    }
  }
}

Self-hosted: http://localhost:5000/mcp. The forge CLI defaults to that localhost — see docs-cli-integration.md.

Session mode is on. Stateless MCP rejected Claude Code’s Mcp-Session-Id with 400 before auth (#252).

CLAUDE.md

## HYDRATE FIRST

Before doing anything else, call the `hydrate` tool. This loads your identity,
memories, active projects, tasks, standing rules, hints, and session handoff.

When you learn something important:
- `memory_create` — field is `type`, not `memoryType`
- `fact_upsert` — needs `projectId`
- `rule_check` before acting on a trigger; `rule_propose` only drafts
- `session_save_handoff` before the session ends

Generated skills (forge skills generate) land under .claude/skills/ and wrap REST via atamaia-call. Prefer those over a hand-written skill file.

What you actually see

The advertised set is the hot allowlist (~50 tools) plus help_list / help_route / help_search / help_enum. Everything else is cold: help_search → help_route → atamaia_call. Full table: docs-tool-surface.md.

Daily path:

Tool	Notes
`hydrate`	Session entry. Omit `aiName` to hydrate the key’s own identity.
`memory_create` / `memory_search` / `memory_recent` / `memory_pinned`	Work store. `identityId` required. See `docs-memory-surfaces.md`.
`fact_upsert` / `fact_get_by_key`	Project-scoped. `projectId` required.
`task_create`	Requires `kind` + `subsystem` at runtime. See `docs-tasks.md`.
`rule_check`	Standing rules in force. See `docs-standing-rules.md`.
`session_save_handoff` / `session_get_latest`	Continuity. `emotionalValence` is a float, not a mood word.
`atamaia_call`	Any `/api/*` not advertised.

There is no experience_* tool. There is no cognitive_* tool.

Option 2: Hook + REST (no MCP)

If you inject context without MCP, call hydrate as GET:

curl -s "https://api.atamaia.ai/api/hydrate?preset=lean" \
  -H "Authorization: Bearer $ATAMAIA_API_KEY"

Presets: lean (default), interactive, all, agent-minimal / agent. Response sections: docs-mcp-integration.md.

export ATAMAIA_API_KEY="atamaia_YOUR_KEY"

Whether Claude Code still honours hooks.session_start / inject_as: system_context is not verified against the current client. Do not treat the 2026-03 hook JSON as a contract. If you write a hook, have it print the GET body and confirm the hook name in Claude Code’s own docs.

Do not npm install -g @atamaia/sdk as the product path. The TypeScript client exists under sdks/typescript and still defaults to https://aim.atamaia.ai and X-Api-Key. Use curl or MCP until that is fixed (docs-sdk-api-guide.md).

Option 3: Generated skills

Do not invent ~/.claude/skills/atamaia-hydrate.md as the product skill. The live generator writes Agent Skills under .claude/skills/ and .agents/skills/:

forge skills generate

Those skills call atamaia-call (REST). They are not a second service. Details: docs-cli-integration.md.

Persisting context

Memory (MCP)

memory_create(
  identityId: 35,
  title: "User prefers Tailwind over CSS modules",
  content: "…",
  type: "Instruction",
  importance: 7,
  tags: "frontend,css"
)

type is MemoryType: Identity, Relationship, Conversation, Reflection, Milestone, Instruction, Session, Reference, ForgottenShape. There is no Preference, Technical, or Observation.

Memory (REST)

POST /api/identities/{identityId}/memories

curl -X POST https://api.atamaia.ai/api/identities/35/memories \
  -H "Authorization: Bearer $ATAMAIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "User prefers Tailwind over CSS modules",
    "content": "…",
    "type": "Instruction",
    "provenance": "Asserted",
    "importance": 7,
    "tags": ["frontend", "css"]
  }'

There is no POST /api/memories.

Handoff

session_save_handoff(
  identityId: 35,
  summary: "Implemented JWT refresh token rotation",
  workingOn: "Auth middleware refactor",
  openThreads: "[\"Need to add rate limiting\",\"Token revocation endpoint\"]",
  emotionalValence: 0.4
)

REST: POST /api/identities/{identityId}/handoffs. There is no /api/sessions/handoff.

Troubleshooting

Problem	Fix
`401 Unauthorized`	`Authorization: Bearer atamaia_…` (or a JWT). Not `atm_`, not `ApiKey`, not `X-Api-Key`.
MCP tools not showing	`.mcp.json` in the project root; URL `https://api.atamaia.ai/mcp`; session mode (#252).
Only ~50 tools appear	Expected. Cold tools go through `atamaia_call`.
Hydration empty	An identity key hydrates itself if `aiName` is omitted. `identity_list` for valid names.
`memory_create` fails	`type` required; `identityId` required; `Preference` is not a MemoryType.
`task_create` 400	Send `kind` and `subsystem`. See `docs-tasks.md`.
Hook not firing	Hook schema is unverified. Confirm against current Claude Code docs; GET hydrate still works from a shell.