Architecture & Orchestration

Core Orchestration Architecture

OpenCognit uses a Planner → Executor → Critic → Self-Heal pipeline:

The Zero-Human Company Model

OpenCognit implements a hierarchical multi-agent architecture modeled after real company structures. Instead of using a single all-in-one agent, specialized AI experts work together in roles — coordinated by a CEO agent.

graph TB
    Board["👤 Board (Human)"]
    CEO["🤖 CEO Agent\nOrchestrator"]
    Dev["🔧 Dev Expert\nFrontend/Backend"]
    Research["🔍 Research Expert\nMarket & Data"]
    DevOps["⚙️ DevOps Expert\nInfrastructure"]
    DB[(SQLite\nDatabase)]

    Board -->|Strategic goal| CEO
    CEO -->|Delegate task| Dev
    CEO -->|Delegate task| Research
    CEO -->|Delegate task| DevOps
    Dev -->|Result + comment| CEO
    Research -->|Result + comment| CEO
    DevOps -->|Result + comment| CEO
    CEO -->|Status report| Board
    CEO <--> DB
    Dev <--> DB
    Research <--> DB
    DevOps <--> DB

Role Hierarchy

CEO Agent (Central Orchestrator)

The CEO is a special agent with adapter type ceo. It:

• Receives high-level goals from the board (humans)
• Breaks goals into concrete tasks (sub-tasks)
• Delegates tasks to the best-matching expert based on skills
• Reviews completed tasks for quality
• Escalates blocked tasks to managers or board
• Recommends new hires when capacity is missing

Experts (Specialized Agents)

Each expert has:

• Role & Title — e.g. Senior Frontend Developer
• Skills — tags like react, typescript, css
• Connection type — which LLM provider is used
• Manager — optional: who to report to (reportsTo)
• Budget — monthly token cost budget

Experts work autonomously: once a task is assigned, the Heartbeat engine picks it up.

The Heartbeat Engine

The heartbeat is the core of autonomy in OpenCognit. It allows agents to work without human prompts continuously.

sequenceDiagram
    participant S as Scheduler (30s)
    participant W as Wakeup Service
    participant H as Heartbeat Service
    participant A as Adapter (Claude/etc.)
    participant DB as Database

    S->>W: Who needs a wakeup?
    W->>DB: Fetch pending wakeup requests
    DB-->>W: [Agent A: Task #12, Agent B: Timer]
    W->>H: triggerCycle(Agent A)
    H->>DB: Create arbeitszyklen entry
    H->>DB: Fetch agent inbox (open tasks)
    DB-->>H: [Task #12: "Implement login page"]
    H->>DB: Set execution lock (30min timeout)
    H->>A: Execute task (prompt + context)
    A-->>H: Result + token usage
    H->>DB: Post comment on task
    H->>DB: Update task status (done/blocked)
    H->>DB: Record costs
    H->>DB: Release lock

Wakeup Sources

Agents are woken up by various events:

Execution Lock

Each task can only be worked on by one agent at a time. The lock contains:

• executionRunId — ID of the active heartbeat run
• executionAgentNameKey — Normalized agent name
• executionLockedAt — Lock timestamp
• Timeout: 30 minutes — lock is automatically released after that

CLI Lock Safety

The Claude Code adapter uses two separate mutexes with a 5-minute timeout:

Separating the locks ensures a long-running chat session cannot starve the heartbeat — and vice versa. A 5-minute timeout prevents deadlocks if either path crashes mid-execution.

Adapter System

OpenCognit uses an adapter pattern for polymorphic execution. Each expert can connect to a different LLM provider:

SOUL.md — File-Based Agent Identity

SOUL.md is an optional, git-trackable Markdown file that replaces the system prompt stored in the database.

# {{agent.name}} — {{agent.role}}

You work at {{company.name}}.
{{company.goal}}

## Your principles
- Be concise and precise
- Always finish tasks completely

Template variables available:

• {{agent.name}} — Agent's name
• {{agent.role}} — Agent's role description
• {{company.name}} — Company name
• {{company.goal}} — Company goal

How it works: The file is loaded before each task execution. Caching is based on the file's mtime — the file is only re-read when it changes. You can export an agent's current system prompt as a SOUL.md via Expert Settings → Export SOUL.md.

Semantic Memory

Each agent has a 5-layer memory system:

BM25+ Retrieval: When a task starts, the agent's memory is searched using BM25+ scoring (Robertson–Zaragoza variant). Documents are ranked by term frequency × inverse document frequency, with document-length normalization. German and English stopwords are filtered.

Agents can write to their memory using [REMEMBER:room] tags in their output:

Done! The API endpoint is at /api/v2/users.
[REMEMBER:api_endpoints] /api/v2/users — GET, returns paginated user list

Maintenance: Cleanup & Backup

OpenCognit handles its own maintenance automatically:

Cleanup Service (runs every 6 hours)

Backup Service (daily)

• Hot backup via SQLite's sqlite.backup() API — safe during concurrent writes
• Stored in data/backups/opencognit_YYYY-MM-DD.db
• 7-day retention (older backups auto-deleted)

Tech Stack