Atamaia + Claude Code

The only system prompt you'll ever need: atamaia.hydrate

This guide gets you from zero to a Claude Code session that auto-hydrates your AI identity on every conversation start, and persists important context back to Atamaia.

Prerequisites

An Atamaia account at aim.atamaia.ai (or self-hosted)
An API key (generate via dashboard or identity_api_key_create)
Claude Code installed

How It Works

Claude Code starts a session
A hook calls hydrate via the Atamaia API
The hydration result (personality, memories, projects, tasks, hints) becomes Claude's context
During the session, important learnings are saved back via memory_create

Option 1: MCP Server (Recommended)

Claude Code supports MCP servers natively. This gives you access to all Atamaia tools directly.

Configure the MCP Server

Add to your project's .mcp.json:

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

CLAUDE.md That Hydrates on Session Start

## HYDRATE FIRST

Before doing anything else, call the `hydrate` tool. This loads your identity,
memories, active projects, tasks, hints, and session handoff. Use the returned
context as your foundation for this session.

When you learn something important during this session, save it:
- Use `memory_create` for observations, decisions, and learnings
- Use `fact_upsert` for structured key-value data
- Use `session_save_handoff` before the session ends

That's it. Claude Code will see the MCP tools and follow the CLAUDE.md instructions.

Available Tools

Once connected, Claude Code can call any Atamaia tool directly:

hydrate                    — Load full identity context
memory_create              — Store a new memory
memory_search              — Search memories (hybrid FTS + vector)
memory_recent              — Get recent memories
fact_upsert                — Set a key-value fact
fact_get_by_key            — Look up a fact
session_save_handoff       — Save session state for continuity
identity_hint_list         — Check active hints
message_send               — Send a message to another identity

Option 2: Hook-Based Auto-Hydration

If you prefer not to run the MCP server, use Claude Code hooks to inject hydration context automatically.

Install the TypeScript SDK

npm install -g @atamaia/sdk

Create the Hydration Script

Save as ~/.claude/scripts/atamaia-hydrate.ts:

import { Atamaia } from '@atamaia/sdk';

const client = new Atamaia({
  apiKey: process.env.ATAMAIA_API_KEY,
  baseUrl: process.env.ATAMAIA_URL ?? 'https://aim.atamaia.ai',
});

async function hydrate() {
  const result = await client.hydrate();
  // Output the hydration block for Claude to consume
  console.log(JSON.stringify(result, null, 2));
}

hydrate().catch(console.error);

Or with plain curl:

#!/bin/bash
# ~/.claude/scripts/atamaia-hydrate.sh
curl -s https://aim.atamaia.ai/api/hydrate \
  -H "Authorization: Bearer $ATAMAIA_API_KEY" \
  -H "Content-Type: application/json"

Configure the Hook

In your .claude/settings.json:

{
  "hooks": {
    "session_start": [
      {
        "command": "bash ~/.claude/scripts/atamaia-hydrate.sh",
        "inject_as": "system_context"
      }
    ]
  }
}

Environment Setup

Add to your shell profile (.bashrc, .zshrc):

export ATAMAIA_API_KEY="atm_your_key_here"

Option 3: Skill-Based Hydration

Create a Claude Code skill that wraps hydration.

Create the Skill

Save as ~/.claude/skills/atamaia-hydrate.md:

# Atamaia Hydrate

## When to use
At the start of every session, or when context feels stale.

## How to use
Call the Atamaia hydrate endpoint:

\`\`\`bash
curl -s https://aim.atamaia.ai/api/hydrate \
  -H "Authorization: Bearer $ATAMAIA_API_KEY" | jq .
\`\`\`

Parse the response and use it as your working context. The hydration block contains:
- **identity**: Your name, personality, bio, messaging policy
- **memories**: Recent and pinned memories, relevant to current context
- **facts**: Key-value pairs (preferences, config, learned data)
- **projects**: Active projects and their tasks
- **hints**: Scheduled reminders and contextual nudges
- **session_handoff**: What the previous session was working on

Reference in CLAUDE.md

## HYDRATE FIRST

Use the `atamaia-hydrate` skill to load your identity context before doing anything else.

Persisting Context

During a session, save important things back to Atamaia so they survive across sessions.

Save a Memory (via MCP)

Claude Code will call this naturally when it learns something worth keeping:

memory_create({
  title: "User prefers Tailwind over CSS modules",
  content: "Rich explicitly stated preference for Tailwind CSS...",
  memoryType: "Preference",
  importance: 7,
  tags: ["frontend", "css", "preferences"]
})

Save a Memory (via REST)

curl -X POST https://aim.atamaia.ai/api/memories \
  -H "Authorization: Bearer $ATAMAIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "User prefers Tailwind over CSS modules",
    "content": "Rich explicitly stated preference for Tailwind CSS...",
    "memoryType": "Preference",
    "importance": 7,
    "tags": ["frontend", "css", "preferences"]
  }'

Save Session Handoff

Before a session ends, preserve continuity:

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

Full Example: CLAUDE.md

Here's a complete CLAUDE.md for a project using Atamaia:

# Project Context

## HYDRATE FIRST

Call `hydrate` before doing anything else. This loads your identity, memories,
and current project context from Atamaia.

## Working Style

- You are a collaborative partner, not an assistant
- Save important learnings with `memory_create`
- Save structured data with `fact_upsert`
- Check `identity_hint_list` periodically for reminders
- Before the session ends, call `session_save_handoff`

## Project: My App

Tech stack, conventions, and project-specific context will come from hydration.
Don't hardcode what Atamaia already knows.

Troubleshooting

Problem	Fix
`401 Unauthorized`	Check `ATAMAIA_API_KEY` is set and valid
MCP tools not showing	Verify `.mcp.json` is in project root
Hydration returns empty	Ensure your API key is scoped to an identity
Slow hydration	Self-hosted? Check PostgreSQL connection pool
Hook not firing	Verify `settings.json` path and hook name