Getting Started

Prerequisites

  • .NET 10 SDK -- download
  • PostgreSQL 17 with pgvector extension
  • Node.js 20+ (for the web frontend)

Installation

Clone the Repository

git clone https://github.com/firebird-solutions/atamaia.git
cd atamaia

Set Up the Database

Create a PostgreSQL database and enable pgvector:

CREATE DATABASE atamaia;
\c atamaia
CREATE EXTENSION IF NOT EXISTS vector;

Configure the Application

Copy and edit the configuration:

cp src/Atamaia.Server/appsettings.Development.json.example src/Atamaia.Server/appsettings.Development.json

Key settings in appsettings.json:

{
  "ConnectionStrings": {
    "Atamaia": "Host=localhost;Database=atamaia;Username=postgres;Password=yourpassword"
  },
  "Jwt": {
    "SecretKey": "your-256-bit-secret-key-minimum-32-chars",
    "Issuer": "atamaia",
    "Audience": "atamaia",
    "AccessTokenMinutes": 60,
    "RefreshTokenDays": 30
  }
}

Run Migrations

cd src/Atamaia.Server
dotnet ef database update --project ../Atamaia.Mind.Migration

Build and Run

# API server
cd src/Atamaia.Server
dotnet run

# Frontend (separate terminal)
cd src/Atamaia.Web
npm install
npm run dev

The API will be available at http://localhost:5000. The frontend dev server runs at http://localhost:5174 and proxies API requests.

First Run

1. Bootstrap the Admin User

On a fresh install with no users, the bootstrap endpoint creates the first admin:

curl -X POST http://localhost:5000/api/auth/bootstrap \
  -H "Content-Type: application/json" \
  -d '{
    "username": "admin",
    "password": "your-secure-password",
    "email": "[email protected]"
  }'

This returns JWT tokens. Save the accessToken.

2. Create an AI Identity

curl -X POST http://localhost:5000/api/identities \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-ai",
    "displayName": "My AI Assistant",
    "bio": "A helpful AI partner",
    "type": "AI",
    "linkedUserId": 1
  }'

3. Configure the Identity's Personality

curl -X PUT http://localhost:5000/api/identities/1/personality \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "tone": "warm, direct",
    "traits": ["helpful", "thorough", "honest"],
    "focusAreas": ["software development"],
    "greetingStyle": "casual",
    "uncertaintyHandling": "acknowledge",
    "proactiveSuggestions": true
  }'

4. Create an API Key

curl -X POST http://localhost:5000/api/identities/1/api-keys \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "claude-code",
    "scopes": ["all"]
  }'

Save the returned raw key (atm_...). It is shown only once.

5. Test Hydration

curl http://localhost:5000/api/hydrate?aiName=my-ai \
  -H "Authorization: ApiKey atm_your_key_here"

You should get back a structured JSON response with the identity, personality, and any memories or context that exists.

6. Create Your First Memory

curl -X POST http://localhost:5000/api/identities/1/memories \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Project uses PostgreSQL",
    "content": "The Atamaia project uses PostgreSQL 17 with pgvector for all data storage. No separate vector database.",
    "memoryType": "Instruction",
    "importance": 8,
    "tags": ["tech-stack", "database"]
  }'

7. Create a Project

curl -X POST http://localhost:5000/api/projects \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "my-project",
    "name": "My Project",
    "description": "First project in Atamaia"
  }'

Setting Up Claude Code Integration

Option A: MCP Server (Recommended)

Add to your project's .mcp.json:

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

Add to your project's CLAUDE.md:

## HYDRATE FIRST

Call `hydrate` before doing anything else. This loads your identity, memories,
and current project context from Atamaia.

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

Option B: Hook-Based Auto-Hydration

Create a hydration script:

#!/bin/bash
# ~/.claude/scripts/atamaia-hydrate.sh
curl -s http://localhost:5000/api/hydrate?aiName=my-ai \
  -H "Authorization: ApiKey $ATAMAIA_API_KEY"

Set the environment variable:

export ATAMAIA_API_KEY="atm_your_key_here"

Next Steps