Architektur

Wie die Teile zusammenpassen.

Überblick

┌─────────────────────────────────────────┐
│              Dispatcher                  │
│            (Microkernel)                 │
│  ┌─────────┐ ┌─────────┐ ┌───────────┐  │
│  │ Watcher │ │  Lock   │ │ Scheduler │  │
│  │         │ │ Manager │ │           │  │
│  └─────────┘ └─────────┘ └───────────┘  │
└─────────────────┬───────────────────────┘
                  │
    ┌─────────────┼─────────────┬─────────────┐
    ▼             ▼             ▼             ▼
┌───────┐    ┌───────┐    ┌───────┐    ┌───────┐
│  ou   │    │ zeno  │    │ cato  │    │ rumi  │
│ relay │    │ data  │    │agenda │    │pattern│
└───┬───┘    └───┬───┘    └───┬───┘    └───┬───┘
    │            │             │             │
    ▼            ▼             ▼             ▼
┌─────────┐  ┌───────┐   ┌────────┐   ┌────────┐
│   LLM   │  │ Vault │   │ Agenda │   │ Memory │
│ (Haiku) │  │       │   │  dir   │   │        │
└─────────┘  └───────┘   └────────┘   └────────┘

Dispatcher

Der dispatcher ist der Microkernel. Er:

• überwacht die Nachrichtenwarteschlange auf Änderungen
• verwaltet Sperren für gemeinsam genutzte Ressourcen
• plant periodische Aufgaben (Pattern-Analyse, Index-Neuerstellung)
• stellt wieder her ausstehende Operationen beim Start

Der dispatcher enthält keine LLM-Aufrufe. Er ist deterministisch, testbar, schnell.

Agenten

Sechs agents, jeder mit einem Namen und einer Rolle:

Routing

Relay (ou) behandelt alle Benutzernachrichten. Er verwendet Haiku mit Tools:

• search_vault → delegiert an Data-Agent (zeno)
• check_agenda → delegiert an Agenda-Agent (cato)
• refresh_agenda → löst manuelle Agenda-Aktualisierung aus

Kein separater Klassifizierungsschritt. Relay entscheidet intelligent basierend auf der Frage und Memory.

Explizite Erwähnungen (@zeno, @cato) funktionieren weiterhin für direkte Delegation.

Data-Agent (zeno)

Der Data-Agent behandelt vault-Abfragen. Bei einfachen Fragen antwortet er direkt — ohne LLM-Aufrufe:

Komplexe Abfragen verwenden weiterhin LLM für intelligente Suche und Synthese.

Agenda-Agent (cato)

cato verwaltet drei Dateien in vault/Agenda/:

Befehle:

• "aktualisiere daily" / "update agenda" → löst manuelle Aktualisierung aus
• Verarbeitet Inbox-Einträge, prüft Exchange-Antworten, aktualisiert Daily

Stündliche Überprüfung (bedingt):

• Läuft um xx:55 (konfigurierbar)

• Prüft Datei-Hashes vor der Verarbeitung — keine Änderungen = kein LLM-Aufruf

• Unbedingt am Start (04:55) und Ende (23:55) des Tages

• Läuft nur innerhalb konfigurierter Stunden (Standard 04:55-23:55)

Pattern-Agent (rumi)

rumi läuft nächtlich und: 1. Extrahiert Memory aus aktuellen Gesprächen 2. Konsolidiert Duplikate, löst Widersprüche auf 3. Fördert stabile Muster zu User Rules 4. Validiert eigene Extraktionsstrategien (lernt zu lernen)

Memory-Migration wird über Chat-Befehle ("memory migrate") durch Relay behandelt, nicht vom Pattern-Agenten. Siehe Migration.

Action-Agent (hiro)

hiro führt Aufgaben und Hintergrundjobs aus. Derzeit in der Entwicklung:

Action ist standardmäßig deaktiviert (enabled: false). Wenn aktiviert:

• Empfängt Aufgaben von anderen agents oder geplanten Jobs
• Führt Aktionen mit expliziter Bestätigung für destruktive Operationen aus
• Meldet Ergebnisse über Nachrichtenwarteschlange zurück

Sicherheitsmodell: hiro hat eine Whitelist erlaubter Operationen. Unbekannte Befehle erfordern explizite Benutzergenehmigung in Exchange.md.

Code-Agent (alan)

alan bietet entwicklungszeitliche Intelligenz. Siehe Code-Agent (alan) für vollständige Dokumentation.

Zusammenfassung:

• Introspektion: Fragen zur outheis-Implementierung beantworten

• Vorschläge: Verbesserungen über vault/Codebase/Exchange.md vorschlagen

• Suche: Muster und Implementierungen im Quellcode finden

• Isolation: Schreibzugriff auf vault/Codebase/ beschränkt

alan ist nur für Entwicklung. Standardmäßig deaktiviert, wird nie in Produktion geladen.

Wissensspeicher

Memory

Meta-Wissen über den Benutzer:

Gespeichert in ~/.outheis/human/memory/. Siehe Memory für Details.

Rules

Externe Anweisungen an agents — was zu beachten ist:

• Benutzerdefiniert: "Auf Deutsch antworten"

• Durch Pattern gefördert: "Benutzer bevorzugt kurze Antworten"

Gespeichert in ~/.outheis/human/rules/. Siehe Memory für Details.

Skills

Interne Fähigkeiten — wie agents handeln:

• System-Skills: Basisfähigkeiten (im Paket)

• Gelernte Skills: Durch Nutzung und Korrektur verfeinert

Gespeichert in src/outheis/agents/skills/ (System) und ~/.outheis/human/skills/ (gelernt). Siehe Skills für Details.

Vault

Der vault ist ein Verzeichnis mit Markdown-Dateien und YAML-Frontmatter:

vault/
├── Agenda/
│   ├── Daily.md      # Today's schedule
│   ├── Inbox.md      # Unprocessed items
│   └── Exchange.md   # Async communication
├── projects/
│   └── *.md
└── notes/
    └── *.md

Der Data-Agent pflegt einen Suchindex in ~/.outheis/human/cache/index/.

Nachrichtenwarteschlange

Die gesamte Kommunikation fließt durch messages.jsonl:

{"v":1,"id":"msg_abc","conversation_id":"conv_xyz","to":"dispatcher",...}
{"v":1,"id":"msg_def","conversation_id":"conv_xyz","to":"transport",...}

Append-only. Versioniert. Wiederherstellbar.

Datei-Layout

~/.outheis/
├── .dispatcher.pid       # PID file
├── .dispatcher.sock      # Lock manager socket
└── human/
    ├── config.json       # Configuration (includes schedule)
    ├── messages.jsonl    # Message queue
    ├── memory/           # Persistent memory
    │   ├── user.json
    │   ├── feedback.json
    │   ├── context.json
    │   └── pattern/      # Pattern agent's learning
    │       └── strategies.md
    ├── cache/            # Regenerable working data
    │   ├── index/        # Search indices
    │   │   └── Vault.jsonl
    │   ├── agenda/       # Agenda file state
    │   │   ├── hashes.json       # Quick change detection
    │   │   ├── Daily.md.prev     # For diff
    │   │   ├── Inbox.md.prev
    │   │   └── Exchange.md.prev
    │   └── sessions/     # Session replay logs
    ├── rules/            # User-defined rules (external)
    │   ├── common.md
    │   ├── relay.md
    │   ├── agenda.md
    │   └── data.md
    ├── skills/           # Learned skills (internal)
    │   ├── common.md
    │   ├── relay.md
    │   ├── agenda.md
    │   └── data.md
    ├── vault/            # Primary vault (default)
    │   └── Migration/    # Temporary migration dir (user creates)
    │       ├── data.md           # Files to import
    │       └── Migration.md      # outheis creates
    └── archive/          # Archived messages

Cache vs. Memory vs. Vault vs. Rules vs. Skills

Das Cache-Verzeichnis ist explizit neu erstellbar. Jederzeit löschen — outheis baut nach Bedarf neu auf.

Geplante Aufgaben

Der dispatcher führt periodische Aufgaben über den integrierten Scheduler aus. Alle Zeiten in config.json konfigurierbar:

Ressourceneffizienz: Agenda-Überprüfung prüft Datei-Hashes vor der Verarbeitung. Wenn nichts geändert wurde, wird kein LLM-Aufruf gemacht. Morgen- (04:55) und Abendläufe (23:55) sind unbedingt, um Tagesgrenzen korrekt zu behandeln.

Zeitplan-Konfiguration

In config.json:

{
  "schedule": {
    "pattern_nightly": {"enabled": true, "times": ["04:00"]},
    "index_rebuild":   {"enabled": true, "times": ["04:30"]},
    "archive_rotation":{"enabled": true, "times": ["05:00"]},
    "shadow_scan":     {"enabled": true, "times": ["03:30"]},
    "agenda_review": {
      "enabled": true,
      "times": ["04:55","05:55","06:55","07:55","08:55","09:55",
                "10:55","11:55","12:55","13:55","14:55","15:55",
                "16:55","17:55","18:55","19:55","20:55","21:55",
                "22:55","23:55"]
    }
  }
}

Jede Aufgabe kann unabhängig deaktiviert werden. Aufgaben laufen in Daemon-Threads — eine laufende Aufgabe blockiert einen zweiten Start derselben Aufgabe, aber nicht andere.

Das Skalierungsproblem

Wenn ein vault wächst, können agents nicht alles im Kontext halten. Das wird durch Abstraktion adressiert — nicht durch mehr Lese-Tools.

Falsch: Mehr Tools

read_file_1(), read_file_2(), ... read_file_n()

Richtig: Bessere Abstraktionen — ein Index, den der agent abfragen kann, mit Details auf Abruf.

Vier Strategien in Nutzung oder geplant:

1. Index mit Aktualitätsgewichtung — Der Data-Agent pflegt einen Suchindex. Agents sehen einen kompakten Index, nicht rohe Dateien. Der Index enthält Zugriffshäufigkeit und Aktualitätssignale.

2. Shadow.md als chronologischer Vorfilter — Der Data-Agent führt einen nächtlichen vault-Scan durch und schreibt alle zeitrelevanten Einträge in eine einzelne strukturierte Datei (Agenda/Shadow.md). cato lädt diese statt bei jeder stündlichen Überprüfung den gesamten vault zu scannen.

3. Progressives Laden — Überblick zuerst, Details auf Anfrage. Der load_skill(topic)-Mechanismus funktioniert wie kontrolliertes Demand Paging: Der agent hat eine Zusammenfassung im Kontext und fordert Details nur bei Bedarf an.

4. Skill-basierte Kompression — Skills ersetzen ausführliche Anweisungen. "ISO-Datumsformat verwenden" statt zehn Beispiele. Bessere Skills bedeuten kleinere Prompts und mehr Platz für Benutzerinhalte.

Weiterführende Lektüre

• Memory — Wie dauerhaftes Memory funktioniert
• Agenda — Zeitmanagement mit Daily, Inbox, Exchange
• Migration — Memory aus externen Quellen einpflegen
• Code-Agent (alan) — Code-Intelligenz zur Entwicklungszeit
• Web UI — Browser-basierte Verwaltungsoberfläche
• Grundlagen — Warum diese Architektur

Open source under AGPL-3.0 · Code on GitHub