Atamaia + Cursor

Cursor talks to Atamaia over MCP. A rules file tells the agent to hydrate first. Persist as you go.

Connection and auth: docs-mcp-integration.md. Tool list: docs-tool-surface.md. Claude Code’s longer walkthrough of the same tools: docs-integration-claude-code.md.

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

---

Prerequisites

• An identity API key (atamaia_…). See docs-sdk-api-guide.md.
• Cursor installed.

---

1. MCP config

Project:

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

This was previously documented at .cursor/mcp.json (or ~/.cursor/mcp.json for all projects). That path is client-side and changes independently of Atamaia. Claude Code uses project-root .mcp.json with the same object. If Cursor’s MCP panel does not pick the file up, use whatever path the current Cursor docs name — the URL and header above are the contract.

Self-hosted: http://localhost:5000/mcp.

Restart Cursor after adding the file.

---

2. Rules

Cursor historically read .cursorrules in the project root (earlier revisions also mentioned .cursor/rules). Confirm the current path in Cursor; the instruction is what matters:

# Atamaia

## Session start
Call `hydrate` before doing anything else.

## During
- `memory_create` for observations and decisions (`type`, not `memoryType`)
- `fact_upsert` for structured key-value data (needs `projectId`)
- `memory_search` before answering from scratch
- `rule_check` before deploy / schema / claiming done

## Session end
`session_save_handoff` with summary, workingOn, and openThreads (JSON string).
emotionalValence is a float from -1 to 1, not a mood word.

---

3. Tools

You will see the hot set (~50) plus help tools. Not every compiled verb. Cold path: help_search → help_route → atamaia_call. Inventory: docs-tool-surface.md.

hydrate()
memory_search(identityId, query, limit)
memory_create(identityId, title, content, type)
memory_recent(identityId, limit)          # not count
memory_pinned(identityId)
fact_upsert(projectId, key, value)
session_save_handoff(identityId, summary)
session_get_latest(identityId)

There is no hot tool named memory_recall. Record a reflection with memory_create (type Reflection). Four memory surfaces (work / personal / agent / session): docs-memory-surfaces.md.

What hydrate actually returns

Not a flat { identity, memories, facts, projects, hints, sessionHandoff }. Live HydrationContext sections include identity / aiIdentity, identityMemories / pinnedMemories / recentMemories, activeProjects / currentTasks, hints, lastSession, standingRules, systemHealth, optional systemPrompt. Full table: docs-mcp-integration.md.

Do not ask the human to repeat what hydration already provided.

---

Flow

┌─────────────────────────────┐
│         Cursor              │
│  rules: "hydrate first"     │
│                             │
│  Agent ──── MCP ───► Atamaia│
│         tools        /mcp   │
└─────────────────────────────┘

1. Conversation starts.
2. Agent reads the rules file, calls hydrate.
3. Work proceeds with that context.
4. Learnings go to memory_create / fact_upsert.
5. session_save_handoff before the conversation ends.

---

Troubleshooting

Problem	Fix
Tools not appearing	Restart after adding the MCP file; URL must be https://api.atamaia.ai/mcp.
401 Unauthorized	Bearer atamaia_…. Not atm_, not ApiKey, not X-Api-Key.
MCP connection failed	Host reachable? Local uses http://, not https://.
Hydration empty	Key hydrates its own identity if aiName is omitted.
Rules ignored	File must be wherever current Cursor reads rules from — not verified here.
memory_create fails	type is required; Preference / Technical are not MemoryType values.

---