Architektur & Orchestrierung

Kern-Orchestrierungsarchitektur

OpenCognit nutzt eine Planner → Executor → Critic → Self-Heal-Pipeline:

Das Zero-Human Company Modell

OpenCognit implementiert eine hierarchische Multi-Agenten-Architektur, die sich an realen Unternehmensstrukturen orientiert. Anstatt einen einzelnen All-in-One-Agenten zu verwenden, arbeiten spezialisierte KI-Experten in Rollen zusammen — koordiniert von einem CEO-Agenten.

graph TB
    Board["👤 Board (Mensch)"]
    CEO["🤖 CEO-Agent\nOrchestrator"]
    Dev["🔧 Dev-Experte\nFrontend/Backend"]
    Research["🔍 Research-Experte\nMarkt & Daten"]
    DevOps["⚙️ DevOps-Experte\nInfrastruktur"]
    DB[(SQLite\nDatenbank)]

    Board -->|Strategisches Ziel| CEO
    CEO -->|Aufgabe delegieren| Dev
    CEO -->|Aufgabe delegieren| Research
    CEO -->|Aufgabe delegieren| DevOps
    Dev -->|Ergebnis + Kommentar| CEO
    Research -->|Ergebnis + Kommentar| CEO
    DevOps -->|Ergebnis + Kommentar| CEO
    CEO -->|Status-Report| Board
    CEO <--> DB
    Dev <--> DB
    Research <--> DB
    DevOps <--> DB

Rollenhierarchie

CEO-Agent (Zentraler Orchestrator)

Der CEO ist ein spezieller Agent mit dem Adapter-Typ ceo. Er:

• Empfängt übergeordnete Ziele vom Board (Menschen)
• Zerlegt Ziele in konkrete Aufgaben (Sub-Tasks)
• Delegiert Aufgaben an den passenden Experten anhand von Skills
• Überprüft abgeschlossene Aufgaben auf Qualität
• Eskaliert blockierte Aufgaben an Manager oder Board
• Empfiehlt neue Einstellungen, wenn die Kapazität fehlt

Experten (Spezialisierte Agenten)

Jeder Experte hat:

• Rolle & Titel — z.B. Senior Frontend Developer
• Skills — Tags wie react, typescript, css
• Verbindungstyp — Welcher LLM-Provider wird genutzt?
• Manager — Optional: Wem wird berichtet (reportsTo)
• Budget — Monatliches Token-Kostenbudget

Experten arbeiten autonom: Sobald eine Aufgabe zugewiesen wird, nimmt der Heartbeat-Motor sie auf.

Der Heartbeat-Motor

Der Heartbeat ist das Herz der Autonomie in OpenCognit. Er ermöglicht es Agenten, ohne menschliche Prompts kontinuierlich zu arbeiten.

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 Datenbank

    S->>W: Wer braucht einen Wakeup?
    W->>DB: Ausstehende Wakeup-Requests abrufen
    DB-->>W: [Agent A: Task #12, Agent B: Timer]
    W->>H: triggerZyklus(Agent A)
    H->>DB: Arbeitszyklen-Eintrag erstellen
    H->>DB: Inbox des Agenten abrufen (offene Tasks)
    DB-->>H: [Task #12: "Login-Seite implementieren"]
    H->>DB: Execution Lock setzen (30min Timeout)
    H->>A: Task ausführen (Prompt + Kontext)
    A-->>H: Ergebnis + Token-Verbrauch
    H->>DB: Kommentar auf Task posten
    H->>DB: Task-Status aktualisieren (done/blocked)
    H->>DB: Kosten buchen
    H->>DB: Lock freigeben

Wakeup-Quellen

Agenten werden durch verschiedene Ereignisse geweckt:

Execution Lock

Jede Aufgabe kann gleichzeitig nur von einem Agenten bearbeitet werden. Der Lock enthält:

• executionRunId — ID des aktiven Heartbeat-Runs
• executionAgentNameKey — Normalisierter Agenten-Name
• executionLockedAt — Zeitstempel des Locks
• Timeout: 30 Minuten — danach wird der Lock automatisch freigegeben

CLI Lock Safety

Der Claude-Code-Adapter nutzt zwei separate Mutexe mit 5-Minuten-Timeout:

Die Trennung der Locks stellt sicher, dass eine lang laufende Chat-Session den Heartbeat nicht aushungert — und umgekehrt. Der 5-Minuten-Timeout verhindert Deadlocks bei Abstürzen.

Adapter-System

OpenCognit nutzt ein Adapter-Pattern für polymorphe Ausführung. Jeder Experte kann mit einem anderen LLM-Provider verbunden werden:

graph LR
    HB[Heartbeat Service]
    REG[Adapter Registry]
    CL[Claude Adapter]
    CC[Claude Code CLI]
    OR[OpenRouter]
    OL[Ollama]
    BA[Bash Adapter]
    HT[HTTP Adapter]
    CEO[CEO Adapter]

    HB --> REG
    REG --> CL
    REG --> CC
    REG --> OR
    REG --> OL
    REG --> BA
    REG --> HT
    REG --> CEO

Datenbank-Schema

OpenCognit nutzt SQLite mit Drizzle ORM (16 Tabellen):

SOUL.md — Dateibasierte Agenten-Identität

SOUL.md ist eine optionale, git-trackbare Markdown-Datei, die den in der Datenbank gespeicherten System-Prompt ersetzt.

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

Du arbeitest bei {{company.name}}.
{{company.goal}}

## Deine Prinzipien
- Sei präzise und zielgerichtet
- Schließe Aufgaben vollständig ab

Verfügbare Template-Variablen:

• {{agent.name}} — Name des Agenten
• {{agent.role}} — Rollenbeschreibung
• {{company.name}} — Unternehmensname
• {{company.goal}} — Unternehmensziel

Funktionsweise: Die Datei wird vor jeder Task-Ausführung geladen. Das Caching basiert auf der Datei-mtime — neu eingelesen wird nur bei Änderungen. Export über Experten-Einstellungen → SOUL.md exportieren.

Semantisches Gedächtnis

Jeder Agent hat ein 5-schichtiges Gedächtnissystem:

BM25+ Abruf: Beim Task-Start wird das Agenten-Gedächtnis mit BM25+-Scoring durchsucht (Robertson–Zaragoza-Variante). Dokumente werden nach Term-Häufigkeit × inversem Dokument-Frequenz rangiert, mit Dokumentlängen-Normalisierung. Deutsche und englische Stopwords werden gefiltert.

Agenten können mit [REMEMBER:room]-Tags in ihrem Output ins Gedächtnis schreiben:

Fertig! Der API-Endpunkt ist /api/v2/benutzer.
[REMEMBER:api_endpunkte] /api/v2/benutzer — GET, gibt paginierte Benutzerliste zurück

Wartung: Cleanup & Backup

OpenCognit verwaltet seine eigene Wartung automatisch:

Cleanup-Service (alle 6 Stunden)

Backup-Service (täglich)

• Hot-Backup über SQLites sqlite.backup() API — sicher bei gleichzeitigen Schreibvorgängen
• Gespeichert in data/backups/opencognit_JJJJ-MM-TT.db
• 7-Tage-Aufbewahrung (ältere Backups werden automatisch gelöscht)

Tech Stack