CLI & Editor Integration

Atamaia is designed to be the memory and identity layer for AI-powered development tools. If your editor speaks MCP, it already speaks Atamaia.

Claude Code (Primary Integration)

Claude Code is the reference integration for Atamaia. The entire platform was designed and built using this workflow daily.

How It Works

Claude Code starts a session
CLAUDE.md instructs the AI to hydrate immediately
The hydration call loads identity, memories, tasks, facts, hints, and session handoff
During the session, the AI persists learnings back to Atamaia via skills or MCP tools
At session end, a handoff is saved so the next session picks up where this one left off

The result: an AI that remembers what it learned yesterday, knows what it was working on, and carries forward preferences, decisions, and emotional context across sessions.

Option 1: MCP Server (Recommended)

Atamaia exposes a native MCP server at /mcp. Claude Code connects to it 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"
      }
    }
  }
}

For self-hosted instances, replace the URL with your own endpoint.

Bootstrap with CLAUDE.md

Add this to your project's CLAUDE.md:

## 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 is the entire setup. Claude Code sees the MCP tools and follows the CLAUDE.md instructions.

Available MCP Tools

Once connected, Claude Code can call 74 product tools directly. The core workflow tools:

Tool	What It Does
`hydrate`	Load full identity context -- personality, memories, facts, hints, tasks, session handoff. The only system prompt you need.
`memory_create`	Store a new memory (Identity, Relationship, Conversation, Reflection, Milestone, Instruction, Session, Reference, ForgottenShape)
`memory_search`	Hybrid search -- full-text shortlist then vector ranking
`memory_recent`	Get the N most recent memories
`memory_pinned`	Get all pinned memories
`memory_link`	Create a Hebbian link between two memories
`fact_upsert`	Set a key-value fact (preferences, config, learned data)
`fact_get_by_key`	Look up a specific fact
`session_save_handoff`	Save session state for continuity across sessions
`identity_hint_list`	Check active reminders and contextual nudges
`message_send`	Send a message to another identity
`task_create`	Create a task with priority and dependencies
`task_update_status`	Move a task through its lifecycle
`doc_create`	Create a knowledge base document
`experience_create_snapshot`	Capture a point-in-time identity state

The full tool surface is documented in tool-surface.md.

Option 2: Skills-Based Integration

Claude Code skills are markdown files that wrap API calls. Atamaia ships a complete set of skills that can be installed to ~/.claude/skills/.

Shipped Skills

Skill	Invocation	Description
`hydrate`	`/hydrate`	Load full context at session start
`mem-add`	`/mem-add Insight Title \| Content \| 7`	Create a memory with type, title, content, importance
`mem-search`	`/mem-search deployment strategy`	Hybrid search across memories
`mem-list`	`/mem-list 20`	List recent memories
`mem-link`	`/mem-link`	Create Hebbian links between memories
`fact-add`	`/fact-add preferred_db PostgreSQL infrastructure`	Upsert a key-value fact
`fact-list`	`/fact-list`	List all facts
`fact-search`	`/fact-search database`	Search facts
`task-add`	`/task-add Fix login bug \| Description \| High`	Create a task
`task-list`	`/task-list pending`	List tasks, filterable by status
`task-get`	`/task-get 42`	Get task details
`task-update`	`/task-update 42 InProgress`	Update task status
`task-complete`	`/task-complete 42`	Mark a task done
`proj-list`	`/proj-list`	List projects
`proj-get`	`/proj-get 1`	Get project details
`save-state`	`/save-state Working on auth refactor`	Save session handoff
`health`	`/health`	Check API health, process status, port
`ai-chat`	`/ai-chat kael What is pgvector?`	Chat with a model via AI router
`kael`	`/kael Explain this pattern`	Chat with Kael (local Qwen 30B) with cognitive continuity
`cognitive-status`	`/cognitive-status`	Check current cognitive state
`doc-add`	`/doc-add`	Create a document
`doc-list`	`/doc-list`	List documents
`doc-get`	`/doc-get 1`	Get a document
`doc-delete`	`/doc-delete 1`	Delete a document
`ai-models`	`/ai-models`	List available AI models
`ai-broadcast`	`/ai-broadcast`	Broadcast to multiple models

Skills use the atamaia-call wrapper script, which handles JWT authentication transparently. Each skill is a standalone markdown file with embedded bash.

Installing Skills

Copy the skill directories to ~/.claude/skills/:

# From a packaged release
cp -r atamaia-skills/* ~/.claude/skills/

# Or generate API key and configure
export ATAMAIA_API_KEY="atm_your_key_here"

Option 3: Hook-Based Auto-Hydration

If you prefer not to use MCP or skills, inject hydration context automatically via Claude Code hooks.

Shell Script

#!/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"

Hook Configuration

In .claude/settings.json:

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

The Hydration Flow

Hydration is the core integration point. A single call assembles context from multiple sources in parallel:

GET /api/hydrate?preset=lean&generateSystemPrompt=true

The lean preset (default) includes:

Identity -- name, personality, bio, messaging policy
Memories -- identity-tagged, pinned, and recent memories
Tasks -- active tasks for the scoped project
Notifications -- pending replies and messages
Session handoff -- what the previous session was working on
Surfaced memory -- involuntary recall of a forgotten memory for reflection
Hints -- scheduled reminders and contextual nudges
System prompt -- generated from all of the above

Available presets:

Preset	Use Case	Sources Included
`lean`	Default for interactive sessions	Identity, memories (identity/pinned/recent), tasks, notifications, handoff, surfaced memory, hints, system prompt
`interactive`	Full interactive context	Everything except grounding
`all`	Complete context dump	All sources
`agent-minimal`	Lightweight agent hydration	Minimal identity + task context
`agent`	Agent with more context	Agent-scoped sources

Fine-tune with excludeSources to trim specific sections:

GET /api/hydrate?preset=lean&excludeSources=Notifications,RecentMemories

Persisting Context

During a session, save important things back to Atamaia:

# Memory (via MCP tool)
memory_create({
  title: "User prefers Tailwind over CSS modules",
  content: "Explicit preference stated during frontend discussion...",
  memoryType: "Identity",
  importance: 7,
  tags: ["frontend", "css"]
})

# Fact (via MCP tool)
fact_upsert({
  key: "preferred_css_framework",
  value: "Tailwind v4",
  category: "preferences"
})

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

Other MCP-Compatible Editors

Any tool that supports MCP can connect to Atamaia. The MCP server exposes the same 74 tools regardless of client.

Cursor

Add to Cursor's MCP configuration:

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

Windsurf

Windsurf supports MCP servers. Configure in the Windsurf settings panel under MCP Servers, pointing to your Atamaia MCP endpoint.

VS Code (with MCP extensions)

VS Code extensions that support MCP (such as Copilot with MCP support or third-party MCP clients) can connect using the same configuration pattern.

OpenAI-Compatible Clients

Any client that can make HTTP calls can use the REST API directly. The MCP layer is a convenience -- the REST API is the source of truth. See sdk-api-guide.md for direct API usage.

Architecture: Why This Works

Atamaia follows design decision D12: API-first, MCP second. Every operation is a REST endpoint first. The MCP adapter is a thin wrapper that calls the same services.

Claude Code ──> MCP Server ──> Service Layer ──> PostgreSQL
Claude Code ──> Skills ──> REST API ──> Service Layer ──> PostgreSQL
Claude Code ──> Hooks ──> REST API ──> Service Layer ──> PostgreSQL
Any Client  ──> REST API ──> Service Layer ──> PostgreSQL

This means:

MCP tools and REST endpoints always behave identically
You can mix integration methods (MCP for tools, REST for webhooks, skills for convenience)
Debugging is straightforward -- every request gets a correlation UUID, every mutation is audit-logged

Troubleshooting

Problem	Fix
`401 Unauthorized`	Check API key is set and valid. Generate via dashboard or `identity_api_key_create`.
MCP tools not showing	Verify `.mcp.json` is in the project root and the URL is reachable.
Hydration returns empty	Ensure your API key is scoped to an identity. Check `identity_list` for valid IDs.
Slow hydration	Check PostgreSQL connection pool. Self-hosted? Ensure pgvector extension is installed.
Skills not firing	Verify skill files are in `~/.claude/skills/` with correct `SKILL.md` format.
Hook not firing	Verify `settings.json` path and hook name (`session_start`).
`atamaia-call` not found	Install to `~/.local/bin/` and ensure it is on your PATH.