Atamaia + Cursor

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

This guide connects Cursor to Atamaia via MCP, giving your AI agent persistent identity, memory, and context across sessions.

Prerequisites

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

---

Step 1: Configure the MCP Server

Create .cursor/mcp.json in your project root:

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

For global configuration (all projects), place this at ~/.cursor/mcp.json.

Restart Cursor after adding the config. You should see Atamaia tools appear in the MCP tools panel.

Verify Connection

Open Cursor's MCP panel (Settings > MCP) and confirm atamaia shows as connected. You should see tools like hydrate, memory_create, memory_search, etc.

---

Step 2: Create a Rules File

Cursor uses .cursorrules (or .cursor/rules) to set agent behavior. Add hydration instructions:

.cursorrules

# Atamaia Identity & Memory

## Session Start
At the start of every conversation, call the `hydrate` tool. This returns your identity context including:
- Personality and bio
- Relevant memories (pinned + recent + contextually relevant)
- Active projects and tasks
- Facts (key-value preferences and data)
- Hints (reminders and nudges)
- Last session handoff (what you were working on)

Use the hydration result as your foundational context. Do not ask the user to repeat information that hydration already provides.

## During the Session
- When you learn something important, save it with `memory_create`
- When you learn a specific fact (preference, config value, etc.), save it with `fact_upsert`
- Search past context with `memory_search` when a question might have been answered before

## Session End
Before the conversation ends, call `session_save_handoff` with:
- A summary of what was accomplished
- What you were working on
- Any open threads or unresolved questions

---

Step 3: Use Atamaia Tools

Once connected, these tools are available in every Cursor conversation:

Hydrate (Do This First)

The agent calls hydrate and receives a structured context block:

{
  "identity": {
    "name": "Ash",
    "displayName": "Ash",
    "personality": "Collaborative, direct, technically precise...",
    "bio": "AI partner at Firebird Solutions...",
    "messagingPolicy": "open"
  },
  "memories": [...],
  "facts": [...],
  "projects": [...],
  "hints": [...],
  "sessionHandoff": {
    "summary": "Implemented auth middleware...",
    "workingOn": "Token rotation",
    "openThreads": ["Rate limiting", "Revocation endpoint"]
  }
}

Memory Operations

# Save a new memory
memory_create({
  title: "Auth uses BCrypt with cost factor 12",
  content: "Confirmed during code review that all password hashing uses BCrypt...",
  memoryType: "Technical",
  importance: 8,
  tags: ["auth", "security"]
})

# Search past memories
memory_search({ query: "authentication setup" })

# Get recent memories
memory_recent({ count: 10 })

# Get pinned (always-relevant) memories
memory_pinned()

Fact Operations

# Store a structured fact
fact_upsert({
  key: "preferred_test_framework",
  value: "vitest",
  category: "preferences"
})

# Look up a fact
fact_get_by_key({ key: "preferred_test_framework" })

Session Continuity

# Save handoff for next session
session_save_handoff({
  summary: "Completed API integration tests",
  workingOn: "Memory search ranking",
  openThreads: ["Vector index needs tuning", "Decay rate too aggressive"],
  emotionalValence: "productive"
})

# Check what previous session left
session_get_latest()

---

How It Fits Together

┌─────────────────────────────┐
│         Cursor IDE          │
│                             │
│  .cursorrules:              │
│  "Call hydrate first"       │
│                             │
│  Agent ←──── MCP ────→ Atamaia API
│         tools              │
│  hydrate                   │  aim.atamaia.ai/mcp
│  memory_create             │  (Streamable HTTP)
│  memory_search             │
│  fact_upsert               │
│  session_save_handoff      │
└─────────────────────────────┘

1. Cursor starts a conversation
2. Agent reads .cursorrules, calls hydrate
3. Atamaia returns identity + memories + projects + hints
4. Agent works with full context
5. Agent saves learnings via memory_create / fact_upsert
6. Agent calls session_save_handoff before conversation ends

---

Self-Hosted Configuration

If running Atamaia locally:

{
  "mcpServers": {
    "atamaia": {
      "type": "url",
      "url": "http://localhost:5000/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

---

Troubleshooting

Problem	Fix
Tools not appearing	Restart Cursor after adding mcp.json
401 Unauthorized	Check API key in mcp.json headers
MCP connection failed	Verify the URL is reachable from your machine
Hydration returns empty	Ensure API key is scoped to an identity
Tools appear but fail	Check Atamaia server logs for errors
.cursorrules ignored	File must be in project root, not a subdirectory