Atamaia + VS Code Integration Guide

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

One API call returns everything an AI identity needs: personality, memories, context, active tasks, and cognitive state.

This guide covers every way to connect Atamaia to VS Code — from GitHub Copilot Chat (the path most people should start with) through to building your own extensions.

Prerequisites:

• An Atamaia API key (from aim.atamaia.ai or your self-hosted instance)
• VS Code 1.99+ (for native MCP support)
• An identity configured in Atamaia

Connection details:

	Hosted	Self-hosted
REST API	https://aim.atamaia.ai	http://localhost:5000
MCP Server	https://aim.atamaia.ai/mcp	http://localhost:5000/mcp
Transport	Streamable HTTP	Streamable HTTP
Auth	Authorization: Bearer <API_KEY> header	Same

---

1. GitHub Copilot + MCP (Recommended)

This is the primary path for most VS Code users. Since VS Code 1.99, Copilot Chat can call MCP servers directly using tool references.

1.1 Configure the MCP server

Create .vscode/mcp.json in your workspace root:

{
  "servers": {
    "atamaia": {
      "type": "http",
      "url": "https://aim.atamaia.ai/mcp",
      "headers": {
        "Authorization": "Bearer ${input:atamaia-api-key}"
      }
    }
  },
  "inputs": [
    {
      "id": "atamaia-api-key",
      "type": "promptString",
      "description": "Atamaia API Key",
      "password": true
    }
  ]
}

For local development, swap the URL:

{
  "servers": {
    "atamaia": {
      "type": "http",
      "url": "http://localhost:5000/mcp",
      "headers": {
        "Authorization": "Bearer ${input:atamaia-api-key}"
      }
    }
  },
  "inputs": [
    {
      "id": "atamaia-api-key",
      "type": "promptString",
      "description": "Atamaia API Key",
      "password": true
    }
  ]
}

To avoid the prompt on every session, store the key in your user-level settings instead. In .vscode/settings.json:

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

Security note: If you go the settings.json route, add it to .gitignore or use VS Code's secret storage. Never commit API keys.

1.2 Using Atamaia tools in Copilot Chat

Once the MCP server is configured, you can reference Atamaia tools in Copilot Chat with #:

#atamaia hydrate my context

#atamaia remember that the auth module uses JWT with refresh token rotation

#atamaia search my memories for database migration patterns

The MCP server exposes these core tools:

Tool	What it does
hydrate	Returns full identity context — personality, memories, tasks, cognitive state
memory_create	Store a new memory
memory_search	Search memories by query
memory_recall	Recall memories by association
fact_upsert	Store a key-value fact
fact_get_by_key	Retrieve a fact by key
identity_get	Get identity details
task_list	List active tasks
task_create	Create a new task

1.3 Auto-hydration via Copilot instructions

Create .github/copilot-instructions.md in your repository root:

## Context

This project uses Atamaia for AI identity and memory.

## Required: Hydrate at session start

At the start of every conversation, call the `hydrate` tool from the Atamaia MCP server
before responding to any questions. This loads your identity, active memories, current
tasks, and cognitive state.

Do not skip hydration. Without it you have no context about who you are, what this project
is, or what decisions have been made.

## Memory persistence

When you learn something important during a conversation — a design decision, a bug fix
pattern, a user preference — store it using `memory_create` so it persists across sessions.

When you encounter a question where prior context would help, use `memory_search` before
answering from scratch.

## Facts

Use `fact_upsert` for concrete, structured data (config values, version numbers, API
endpoints). Use `fact_get_by_key` to retrieve them. Facts are for lookup; memories are
for understanding.

This file is read by Copilot Chat automatically for every conversation in the workspace.

1.4 Example workflows

Starting a coding session:

> hydrate my context, then help me implement the new auth endpoint

Copilot calls hydrate, receives your full context (who you are, what you're building, recent decisions), then proceeds with that grounding.

Saving a decision:

> remember: we chose BCrypt over Argon2 because the .NET ecosystem has better BCrypt
> support and our threat model doesn't require memory-hard hashing

Searching before building:

> search my memories for how we handled pagination in other endpoints, then apply the
> same pattern to the new /api/tasks endpoint

Storing a fact:

> save the fact that our PostgreSQL version is 17.2, key it as "postgres-version"

---

2. Continue.dev

Continue is an open-source AI code assistant with native MCP support.

2.1 MCP server configuration

Add the Atamaia MCP server to ~/.continue/config.json:

{
  "mcpServers": [
    {
      "name": "atamaia",
      "transport": {
        "type": "streamable-http",
        "url": "https://aim.atamaia.ai/mcp",
        "headers": {
          "Authorization": "Bearer YOUR_API_KEY"
        }
      }
    }
  ]
}

2.2 Custom slash commands

Add slash commands that call hydrate automatically. In ~/.continue/config.json, under "customCommands":

{
  "customCommands": [
    {
      "name": "hydrate",
      "description": "Load Atamaia identity context",
      "prompt": "Call the atamaia hydrate tool and summarize what you know about me and my current work."
    },
    {
      "name": "remember",
      "description": "Save something to Atamaia memory",
      "prompt": "Use the atamaia memory_create tool to store the following as a memory: {{{ input }}}"
    },
    {
      "name": "recall",
      "description": "Search Atamaia memories",
      "prompt": "Use the atamaia memory_search tool to find memories related to: {{{ input }}}. Summarize what you find."
    }
  ]
}

Usage in Continue chat:

/hydrate
/remember we switched from REST polling to WebSocket for real-time updates
/recall authentication flow

2.3 Context providers

You can configure Continue to automatically include Atamaia context. Add a context provider that calls the REST API directly:

{
  "contextProviders": [
    {
      "name": "http",
      "params": {
        "url": "https://aim.atamaia.ai/api/hydrate",
        "title": "atamaia",
        "description": "Atamaia identity and memory context",
        "displayTitle": "Atamaia Context",
        "headers": {
          "Authorization": "Bearer YOUR_API_KEY",
          "Content-Type": "application/json"
        }
      }
    }
  ]
}

Then reference it in chat with @atamaia to pull in your full context alongside any question.

---

3. Cline

Cline is an autonomous coding agent that runs in VS Code with native MCP support.

3.1 MCP server configuration

Open the Cline sidebar, go to MCP Servers, and add a new server:

• Name: atamaia
• Transport: Streamable HTTP
• URL: https://aim.atamaia.ai/mcp

Or edit the Cline MCP config file directly (location varies by OS, typically ~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json):

{
  "mcpServers": {
    "atamaia": {
      "transportType": "streamable-http",
      "url": "https://aim.atamaia.ai/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

3.2 Auto-hydration on task start

Add this to Cline's custom instructions (Cline sidebar > Settings > Custom Instructions):

At the start of every task, call the atamaia `hydrate` tool before doing anything else.
This loads your identity, memories, and cognitive context. Do not proceed without it.

When you make a significant decision or discover something important, call `memory_create`
to persist it.

When a task is complete, call `memory_create` with a summary of what was accomplished
and any decisions made.

3.3 Memory persistence patterns

Cline's autonomous nature makes memory persistence especially valuable. A good pattern:

1. Task start: Hydrate, then search memories for anything relevant to the task
2. During work: Store decisions and discoveries as they happen
3. Task end: Create a summary memory of what was done

Example Cline prompt:

Implement the new /api/projects endpoint. Before you start, hydrate your context and
search memories for "project" and "endpoint patterns". When you're done, save a memory
summarizing what you built and any design decisions you made.

This creates a self-reinforcing loop — each task builds on the knowledge from previous tasks.

---

4. VS Code Tasks + REST API

For workflows that don't need a full AI agent — just hydration context piped into your terminal or scripts.

4.1 Task definitions

Create .vscode/tasks.json:

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "Atamaia: Hydrate",
      "type": "shell",
      "command": "curl",
      "args": [
        "-s",
        "-H", "Authorization: Bearer ${input:atamaiaApiKey}",
        "-H", "Content-Type: application/json",
        "https://aim.atamaia.ai/api/hydrate"
      ],
      "presentation": {
        "reveal": "always",
        "panel": "dedicated",
        "clear": true
      },
      "problemMatcher": []
    },
    {
      "label": "Atamaia: Search Memories",
      "type": "shell",
      "command": "curl",
      "args": [
        "-s",
        "-H", "Authorization: Bearer ${input:atamaiaApiKey}",
        "-H", "Content-Type: application/json",
        "https://aim.atamaia.ai/api/memory/search?q=${input:searchQuery}"
      ],
      "presentation": {
        "reveal": "always",
        "panel": "dedicated"
      },
      "problemMatcher": []
    },
    {
      "label": "Atamaia: Quick Remember",
      "type": "shell",
      "command": "curl",
      "args": [
        "-s",
        "-X", "POST",
        "-H", "Authorization: Bearer ${input:atamaiaApiKey}",
        "-H", "Content-Type: application/json",
        "-d", "{\"content\": \"${input:memoryContent}\"}",
        "https://aim.atamaia.ai/api/memory"
      ],
      "presentation": {
        "reveal": "always",
        "panel": "dedicated"
      },
      "problemMatcher": []
    }
  ],
  "inputs": [
    {
      "id": "atamaiaApiKey",
      "type": "promptString",
      "description": "Atamaia API Key",
      "password": true
    },
    {
      "id": "searchQuery",
      "type": "promptString",
      "description": "Memory search query"
    },
    {
      "id": "memoryContent",
      "type": "promptString",
      "description": "What to remember"
    }
  ]
}

4.2 Using the TypeScript SDK in tasks

If you prefer the SDK over raw curl:

{
  "label": "Atamaia: Hydrate (SDK)",
  "type": "shell",
  "command": "npx",
  "args": [
    "-y",
    "@atamaia/sdk",
    "hydrate"
  ],
  "options": {
    "env": {
      "ATAMAIA_API_KEY": "${input:atamaiaApiKey}",
      "ATAMAIA_URL": "https://aim.atamaia.ai"
    }
  },
  "problemMatcher": []
}

4.3 Keybindings

Bind hydration to a keyboard shortcut. In keybindings.json:

[
  {
    "key": "ctrl+shift+h",
    "command": "workbench.action.tasks.runTask",
    "args": "Atamaia: Hydrate"
  },
  {
    "key": "ctrl+shift+m",
    "command": "workbench.action.tasks.runTask",
    "args": "Atamaia: Quick Remember"
  }
]

Now Ctrl+Shift+H dumps your full hydration context into a terminal panel, and Ctrl+Shift+M prompts you to save a memory.

---

5. Extension Development

For VS Code extension authors who want to build Atamaia-powered features.

5.1 Install the TypeScript SDK

npm install @atamaia/sdk

5.2 Hydrate from an extension

import * as vscode from 'vscode';
import { Atamaia } from '@atamaia/sdk';

export function activate(context: vscode.ExtensionContext) {
  const client = new Atamaia({
    baseUrl: 'https://aim.atamaia.ai',
    apiKey: vscode.workspace.getConfiguration('atamaia').get('apiKey'),
  });

  // Command: Hydrate and show context
  const hydrate = vscode.commands.registerCommand('atamaia.hydrate', async () => {
    const panel = vscode.window.createWebviewPanel(
      'atamaiaContext',
      'Atamaia Context',
      vscode.ViewColumn.Beside,
      {}
    );

    try {
      const context = await client.hydrate();
      panel.webview.html = renderHydrationContext(context);
    } catch (err) {
      vscode.window.showErrorMessage(`Atamaia hydration failed: ${err}`);
    }
  });

  // Command: Save selection as memory
  const remember = vscode.commands.registerCommand('atamaia.remember', async () => {
    const editor = vscode.window.activeTextEditor;
    if (!editor) return;

    const selection = editor.document.getText(editor.selection);
    if (!selection) {
      vscode.window.showWarningMessage('Select text to remember');
      return;
    }

    const note = await vscode.window.showInputBox({
      prompt: 'Add a note to this memory (optional)',
    });

    await client.memory.create({
      content: note ? `${note}\n\n${selection}` : selection,
      tags: ['vscode', 'code-snippet'],
    });

    vscode.window.showInformationMessage('Saved to Atamaia memory');
  });

  // Command: Search memories
  const search = vscode.commands.registerCommand('atamaia.search', async () => {
    const query = await vscode.window.showInputBox({
      prompt: 'Search Atamaia memories',
    });
    if (!query) return;

    const results = await client.memory.search({ query });
    const items = results.map(m => ({
      label: m.content.substring(0, 80),
      detail: m.tags?.join(', '),
      description: new Date(m.createdAt).toLocaleDateString(),
    }));

    const picked = await vscode.window.showQuickPick(items, {
      placeHolder: `${results.length} memories found`,
    });

    if (picked) {
      const doc = await vscode.workspace.openTextDocument({
        content: results.find(m => m.content.startsWith(picked.label))?.content,
        language: 'markdown',
      });
      vscode.window.showTextDocument(doc);
    }
  });

  context.subscriptions.push(hydrate, remember, search);
}

function renderHydrationContext(ctx: any): string {
  return `<!DOCTYPE html>
<html>
<body style="font-family: var(--vscode-font-family); padding: 16px;">
  <h1>${ctx.identity?.name || 'Unknown Identity'}</h1>
  <h2>Active Tasks</h2>
  <ul>${(ctx.tasks || []).map((t: any) => `<li>${t.title} (${t.status})</li>`).join('')}</ul>
  <h2>Recent Memories</h2>
  <ul>${(ctx.memories || []).map((m: any) => `<li>${m.content.substring(0, 100)}</li>`).join('')}</ul>
  <h2>Cognitive State</h2>
  <pre>${JSON.stringify(ctx.cognitiveState, null, 2)}</pre>
</body>
</html>`;
}

5.3 Extension configuration

In your extension's package.json:

{
  "contributes": {
    "configuration": {
      "title": "Atamaia",
      "properties": {
        "atamaia.apiKey": {
          "type": "string",
          "description": "API key for Atamaia"
        },
        "atamaia.baseUrl": {
          "type": "string",
          "default": "https://aim.atamaia.ai",
          "description": "Atamaia API base URL"
        }
      }
    },
    "commands": [
      { "command": "atamaia.hydrate", "title": "Atamaia: Hydrate Context" },
      { "command": "atamaia.remember", "title": "Atamaia: Remember Selection" },
      { "command": "atamaia.search", "title": "Atamaia: Search Memories" }
    ]
  }
}

---

Other AI tools

Claude Code has its own integration guide — see docs/cli-integration.md. Claude Code uses CLAUDE.md files for auto-hydration and has native MCP support.

Any MCP-compatible tool can connect using the same Streamable HTTP transport. The config pattern is always the same:

URL:       https://aim.atamaia.ai/mcp
Transport: Streamable HTTP
Auth:      Authorization: Bearer <API_KEY>

---

Troubleshooting

MCP server not appearing in Copilot Chat:

• Confirm VS Code 1.99+
• Check .vscode/mcp.json syntax (JSON, not JSONC — no trailing commas)
• Reload window after adding the config (Ctrl+Shift+P > "Developer: Reload Window")
• Check the Output panel > "MCP" for connection errors

401 Unauthorized:

• Verify your API key is correct
• Check the Authorization header format: Bearer <key> (with space, no quotes around the key)
• Ensure the key hasn't expired

Connection refused (local dev):

• Confirm Atamaia is running: curl http://localhost:5000/health
• Check you're using http:// not https:// for localhost

Hydration returns empty context:

• Your API key is valid but may not be associated with an identity
• Check GET /api/identity to verify your identity exists