Cognition Documentation

Complete reference for the zero-knowledge encrypted AI platform. Cognition combines AES-256-GCM client-side encryption with a beautiful chat interface, multi-provider AI support, and agent workflows.

01 Quick Start

Get Cognition running in under a minute. Choose your preferred method:

# Clone and run
docker pull cognitionai/cognition
docker compose up -d

# Open http://localhost:3000
# Create your vault with a strong password
# Add AI providers in SettingsCopy

# Clone and install
npm install cognition-ai
cd cognition-ai

# Development mode
npm run dev
# Open http://localhost:5173

# Production build
npm run build
node buildCopy

# No install needed — use the live instance
https://app.cognitionai.tech

# 1. Create a vault (set a strong password)
# 2. Go to Settings → Add Provider
# 3. Enter your OpenAI/Anthropic API key
# 4. Start chatting — everything encryptedCopy

02 Docker Setup

Cognition ships as a single Docker container with zero external dependencies. SQLite stores all data in a persistent volume.

# docker-compose.yml
services:
  cognition:
    build: .
    ports:
      - "3000:3000"
    volumes:
      - cognition-data:/app/data
    extra_hosts:
      - "host.docker.internal:host-gateway"
    environment:
      - PORT=3000
      - NODE_ENV=production
      - DATABASE_PATH=/app/data/cognition.db

volumes:
  cognition-data:Copy

The extra_hosts mapping enables Ollama access from inside the container — if you run Ollama locally, Cognition auto-detects it at host.docker.internal:11434.

Environment Variables

03 Architecture

Cognition follows a strict client-side encryption model. The server is architecturally a "dumb data store" — it stores and retrieves ciphertext blobs. It never has access to encryption keys, plaintext conversations, or decrypted API keys.

Data Flow

1. User types a message in the browser
2. Browser encrypts the message with AES-256-GCM using the in-memory master key
3. Ciphertext is sent to the server via API and stored in SQLite
4. For AI chat: browser sends decrypted API key + plaintext message to server
5. Server proxies the request to the AI provider via SSE, streams response back
6. Browser receives AI response, encrypts it, stores ciphertext on server
7. API key exists in server memory only during the request, then is garbage collected

04 Encryption

Cognition uses AES-256-GCM (Galois/Counter Mode) — the same authenticated encryption used in TLS 1.3, military communications, and hardware security modules. Combined with PBKDF2 key derivation, it provides both confidentiality and integrity.

Key Derivation

Encryption Process

// Simplified encryption flow
1. Generate random 12-byte IV (crypto.getRandomValues)
2. Encrypt: AES-256-GCM(masterKey, IV, plaintext) → ciphertext
3. Encode: base64(IV) + ":" + base64(ciphertext)
4. Store encoded string on server

// Decryption (reverse)
1. Split on ":" → base64(IV), base64(ciphertext)
2. Decode both from base64
3. Decrypt: AES-256-GCM(masterKey, IV, ciphertext) → plaintext

05 Key Management

Key Lifecycle

1. Derivation: User enters password → PBKDF2(password, salt, 600000, SHA-256) → 256-bit CryptoKey
2. Storage: CryptoKey held in Svelte store (JavaScript memory only). Never in localStorage, cookies, or IndexedDB
3. Usage: Used for encrypt/decrypt operations via Web Crypto API
4. Lock: CryptoKey reference set to null → garbage collected. All decrypted data cleared from memory
5. Auto-lock: Configurable timeout (default 15 minutes). Every encrypt/decrypt operation resets the timer

Verification

On vault creation, the string "cognition-vault-test" is encrypted and stored. On subsequent unlocks, Cognition tries to decrypt this test string. Success = correct password. Failure = wrong password. The server never validates the password — the client does by attempting decryption.

06 AI Providers

Cognition supports multiple AI backends. Add as many as you need — each provider's API key is encrypted with your vault key before storage.

Adding a Provider

1. Open Settings (gear icon in sidebar)
2. Click "Add Provider" and select the type
3. Enter your API key (for cloud providers)
4. The key is encrypted with your vault key before being sent to the server
5. Available models will load automatically

API Key Flow (Zero-Knowledge)

// How API keys are handled
1. User enters API key in Settings
2. Client: encrypt(vaultKey, apiKey) → ciphertext
3. Server stores ciphertext in providers table
4. On vault unlock: client fetches providers → decrypts API keys → holds in memory
5. For model listing/chat: client sends decrypted key per-request
6. Server uses key transiently, never persists plaintext

07 Agents

Create custom AI agents with specialized behaviors, system prompts, and model selection. Agent configurations are encrypted like everything else.

Built-in Templates

Custom Agent Configuration

// Agent config (stored encrypted)
{
  name: "Legal Advisor",
  role: "Legal Research",
  systemPrompt: "You are a legal research assistant...",
  modelId: "gpt-4o",
  providerId: "provider-uuid",
  color: "#7c5cfc",
  icon: "⚖️"
}

08 Workflows

Chain multiple agents into sequential pipelines. The output of each agent becomes the input to the next, enabling complex multi-step AI processes.

How Workflows Execute

1. User provides initial input text
2. First agent processes the input with its system prompt + step instruction
3. Output streams in real-time to the UI
4. Completed output becomes input to the next agent
5. Process repeats for each step in the pipeline
6. All intermediate and final outputs are encrypted before storage

Example: Research Pipeline

// Research → Analysis → Summary workflow
Step 1: Researcher agent → "Research this topic thoroughly"
Step 2: Analyst agent → "Extract key findings and data points"
Step 3: Writer agent → "Synthesize into a concise executive summary"

Input: "Impact of quantum computing on current encryption standards"
→ Researcher produces detailed research
→ Analyst identifies key findings
→ Writer creates executive summary

09 API Reference

Cognition exposes a RESTful API for all operations. All conversation content is stored as ciphertext — the API neither encrypts nor decrypts.

SSE Stream Format

// POST /api/chat response (text/event-stream)
data: {"token":"Hello"}
data: {"token":" world"}
data: {"token":"!"}
data: [DONE]

// On error:
data: {"error":"Provider returned 401 Unauthorized"}

10 Deployment

Docker (Recommended)

# Production deployment
docker pull cognitionai/cognition
docker compose up -d

# Custom port
PORT=8080 docker compose up -d

# View logs
docker compose logs -f cognitionCopy

Railway

Cognition auto-deploys from the main branch on Railway. The live instance runs at cognition-production.up.railway.app. Data persists on a Railway volume mounted at /app/data.

Manual Build

# Build for production
npm install
npm run build

# Run production server
NODE_ENV=production PORT=3000 node build

# Or use the Dockerfile directly
docker build -t cognition .
docker run -p 3000:3000 -v cognition-data:/app/data cognitionCopy

Reverse Proxy (nginx)

# nginx config for custom domain
server {
    listen 443 ssl http2;
    server_name your-domain.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_buffering off;  # Required for SSE
    }
}Copy

11 Security Model

What's Encrypted

• Conversation titles
• All message content (user + assistant + system)
• AI provider API keys and configuration
• Agent configurations (system prompts, model choices)
• Workflow configurations

What's NOT Encrypted

• User ID and registration metadata
• Conversation timestamps and IDs
• Message roles (user/assistant/system) and timestamps
• Provider type (ollama/openai/anthropic) and display name
• Provider base URLs (for non-secret endpoints like Ollama)

Threat Model

Guarantees

For maximum privacy, use Cognition with Ollama (local models). This ensures your prompts never leave your network — combined with client-side encryption, you get true end-to-end privacy with zero data exposure.