Atamaia + Windsurf

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

This guide connects Windsurf (Codeium) to Atamaia via MCP, giving Cascade 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)
• Windsurf installed

---

Step 1: Configure the MCP Server

Create .windsurf/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 ~/.windsurf/mcp.json.

Restart Windsurf after adding the config.

Verify Connection

Open Windsurf settings and navigate to the MCP section. Confirm atamaia shows as connected with available tools listed.

---

Step 2: Create a Rules File

Windsurf uses .windsurfrules for agent behavior configuration. Add hydration instructions:

.windsurfrules

# 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.

## During the Session
- When you learn something important, save it with `memory_create`
- When you learn a specific fact (preference, config value), 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, what you were working on, and any open threads.

---

Step 3: Use Atamaia Tools

Once connected, Cascade has access to the full Atamaia tool surface:

Core Workflow

# 1. Hydrate at session start
hydrate()
→ Returns: identity, memories, facts, projects, hints, session handoff

# 2. Work with full context
# Cascade now knows who it is, what it was working on, and what matters

# 3. Save learnings during the session
memory_create({
  title: "API rate limit is 1000 req/min",
  content: "Discovered during load testing that the API enforces...",
  memoryType: "Technical",
  importance: 7,
  tags: ["api", "performance"]
})

# 4. Save structured facts
fact_upsert({
  key: "deployment_region",
  value: "ap-southeast-2",
  category: "infrastructure"
})

# 5. Search past knowledge
memory_search({ query: "deployment configuration" })

# 6. Save handoff before session ends
session_save_handoff({
  summary: "Set up CI/CD pipeline with GitHub Actions",
  workingOn: "Docker build optimization",
  openThreads: ["Layer caching needs work", "Test stage too slow"]
})

All Available Tools

Domain	Tools
Hydration	hydrate
Memory	memory_create, memory_search, memory_recent, memory_pinned, memory_get, memory_update, memory_archive, memory_add_tags, memory_link, memory_recall
Facts	fact_upsert, fact_get_by_key, fact_list, fact_search, fact_delete
Identity	identity_get, identity_update, identity_update_presence
Hints	identity_hint_list, identity_hint_create, identity_hint_dismiss, identity_hint_complete
Sessions	session_save_handoff, session_get_latest, session_list
Messaging	message_send, message_inbox

---

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 Windsurf 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
.windsurfrules ignored	File must be in project root
Cascade doesn't hydrate	Add explicit instruction in .windsurfrules to call hydrate first