Datenformate und Konventionen

Klare Formate ermöglichen verlässliche Annahmen. Agents wissen, was sie vorfinden — ohne raten zu müssen.

Kernprinzip: Datenlokalität

Benutzerdaten existieren nur an zwei Orten:

Keine Benutzerdaten werden anderswo gespeichert. Das Entfernen dieser Verzeichnisse löscht alle Benutzerspuren.

Verzeichnisstruktur

Systemverzeichnis

~/.outheis/                      # System directory
├── agents/                      # Agent implementations
├── transport/                   # Transport daemon
├── dispatcher/                  # Dispatcher
├── web/                         # Web UI (localhost-only)
└── human/                       # ALL user-specific data
    ├── config.json              # User configuration
    ├── insights.jsonl           # Pattern agent output
    ├── rules/                   # Agenda agent rules
    │   └── priorities.md
    ├── messages.jsonl           # Message queue (append-only)
    ├── archive/                 # Cold storage for old conversations
    │   ├── messages-2025-01.jsonl
    │   └── ...
    ├── index.jsonl              # Search index (across all vaults)
    ├── tag-weights.jsonl        # Learned tag importance
    ├── cache/                   # Cached data
    │   └── agenda/              # Previous versions for diff
    │       ├── Daily.md.prev
    │       ├── Inbox.md.prev
    │       └── Exchange.md.prev
    ├── imports/                 # Imported external data
    │   ├── calendar/
    │   │   └── 2025-03-27.jsonl
    │   ├── email/
    │   │   └── inbox.jsonl
    │   ├── tasks/
    │   └── contacts/
    └── vault/                   # Minimal starter vault

Vault (Extern, vom Benutzer verwaltet)

Vaults können sich überall im Dateisystem befinden. Mehrere Vaults werden unterstützt.

~/Documents/MyVault/             # Example: user's primary vault
├── Agenda/                      # Special directory (required in primary vault)
│   ├── Daily.md
│   ├── Inbox.md
│   └── Exchange.md
├── notes/
│   └── project-alpha.md
├── projects/
│   └── project-alpha/
│       ├── README.md
│       └── assets/
│           └── diagram.png
└── archive/
    └── 2024/

~/Documents/Obsidian/            # Example: second vault
├── ...

Konfiguration

{
  "vault": [
    "~/Documents/MyVault",
    "~/Documents/Obsidian"
  ]
}

Der erste Vault in der Liste ist der primäre Vault — enthält Agenda/.

Vault-Struktur

Konventionen

Philosophie

Gemäß dem Prinzip der prospektiven Informationsarchitektur:

• Selbstbeschreibung: Dateien tragen ihre Bedeutung über Tags — nicht über Position

• Position als Hinweis: Verzeichnisstruktur liefert Kontext, nicht Identität

• Mehrere Zugriffspfade: Tags ermöglichen Abruf aus beliebiger Perspektive

• Struktur zur Abfragezeit: Hierarchien werden berechnet, nicht gespeichert

Dateitypen

Primär: Markdown (.md)

Das primäre Wissensformat. Menschenlesbar, maschinell verarbeitbar, selbstbeschreibend.

Häufige Assets

Dateien, die häufig neben Markdown auftauchen oder darin verlinkt sind:

Beziehungsmuster

Markdown-Format

Frontmatter

Optionales YAML-Frontmatter für explizite Metadaten:

---
title: Project Alpha Notes
created: 2025-01-15
modified: 2025-03-27
tags: [project/alpha, important]
---

# Project Alpha Notes

Content here...

Wenn kein Frontmatter vorhanden ist, leiten agents Metadaten ab aus:

• Titel: Erste # Überschrift oder Dateiname

• Erstellt/Geändert: Dateisystem-Zeitstempel

• Tags: Inline-Tags im Inhalt

Tags

Tags kommen aus zwei Quellen — beide funktionieren, werden automatisch zusammengeführt:

1. YAML-Frontmatter (optional):

---
tags: [project/alpha, important]
---

1. Inline-#Tags im Fließtext (bevorzugt):

This is an #important note about #project/alpha.

Meeting scheduled for tomorrow #deadline #priority-high.

outheis extrahiert Tags aus beiden Quellen und dedupliziert sie.

Tag-Formate

Das Format des Benutzers wird beibehalten. outheis erlernt, ob - oder / als Trennzeichen verwendet wird.

Tag-Normalisierung

Zur Indizierung und Suche werden Tags normalisiert:

#Important     → important
#Priority-High → priority-high
#Project/Alpha → project/alpha

Regeln:

• Kleinbuchstaben für die Suche
• Bindestriche und Schrägstriche beibehalten
• Führendes # entfernen

Tag-Analyse

outheis verfolgt die Tag-Nutzung und kann berichten:

• Top-Tags — am häufigsten verwendet
• Tag-Hierarchien — Präfixe wie status-*, project/*
• Einzelne Tags — nur einmal verwendet (Bereinigungskandidaten)

Im Chat fragen: "welche tags habe ich?" oder "tag-analyse"

Tag-Philosophie

outheis erfindet keine Tags. Es verwendet deine Tags, erlernt dein Format und kann:

• Bereinigung für einzelne Tags vorschlagen
• Auf inkonsistente Formate hinweisen
• Ähnliche vorhandene Tags vorschlagen, wenn neue erstellt werden

Du bestimmst das Vokabular.

Links

Wiki-Style-Links für interne Referenzen:

See [[meeting-notes]] for details.
Related: [[projects/alpha/README]]

Standard-Markdown-Links für externe Referenzen:

Based on [this paper](https://example.com/paper.pdf).

Importierte Daten

Externe Daten (Kalender, E-Mail usw.) importiert der Action-Agent in ~/.outheis/human/imports/. Diese Daten sind kanonisch — strukturierte Repräsentationen externer Quellen.

Verzeichnisstruktur

~/.outheis/human/imports/
├── calendar/
│   ├── 2025-03-27.jsonl
│   └── recurring.jsonl
├── email/
│   ├── inbox.jsonl
│   └── sent.jsonl
├── tasks/
│   └── tasks.jsonl
└── contacts/
    └── contacts.jsonl

Kalendereinträge

{
  "id": "evt_abc123",
  "source": "google_calendar",
  "title": "Team Meeting",
  "start": "2025-03-27T10:00:00Z",
  "end": "2025-03-27T11:00:00Z",
  "location": "Room 3B",
  "description": "Weekly sync",
  "attendees": ["alice@example.com", "bob@example.com"],
  "recurring": false,
  "imported_at": "2025-03-27T08:00:00Z"
}

E-Mail

{
  "id": "msg_xyz789",
  "source": "gmail",
  "from": {"name": "Alice", "email": "alice@example.com"},
  "to": [{"name": "User", "email": "user@example.com"}],
  "cc": [],
  "subject": "Project Update",
  "body_text": "Plain text body...",
  "date": "2025-03-27T09:15:00Z",
  "thread_id": "thread_123",
  "labels": ["inbox", "important"],
  "attachments": [
    {"filename": "report.pdf", "mime_type": "application/pdf", "size": 102400}
  ],
  "imported_at": "2025-03-27T10:00:00Z"
}

Aufgaben

{
  "id": "task_456",
  "source": "todoist",
  "title": "Review proposal",
  "description": "Review and comment on Q2 proposal",
  "due": "2025-03-28T17:00:00Z",
  "priority": 2,
  "status": "pending",
  "project": "Work",
  "labels": ["review", "q2"],
  "imported_at": "2025-03-27T08:00:00Z"
}

Kontakte

{
  "id": "contact_789",
  "source": "google_contacts",
  "name": "Alice Smith",
  "email": ["alice@example.com", "alice.smith@work.com"],
  "phone": ["+1-555-123-4567"],
  "organization": "Acme Corp",
  "notes": "Met at conference 2024",
  "imported_at": "2025-03-27T08:00:00Z"
}

Index

Der Data-Agent pflegt einen Suchindex unter ~/.outheis/human/index.jsonl:

{
  "vault": "~/Documents/MyVault",
  "path": "notes/project-alpha.md",
  "type": "markdown",
  "title": "Project Alpha Notes",
  "tags": ["project/alpha", "important"],
  "links_to": ["meeting-notes.md", "assets/diagram.png"],
  "linked_from": ["README.md"],
  "modified": "2025-03-27T10:00:00Z",
  "accessed_at": "2025-03-27T14:00:00Z",
  "access_count": 12,
  "checksum": "sha256:abc123...",
  "indexed_at": "2025-03-27T10:05:00Z"
}

Der Index umfasst alle konfigurierten Vaults. Jeder Eintrag enthält das vault-Feld.

Human-Verzeichnis

Struktur

~/.outheis/human/
├── config.json                  # User configuration
├── insights.jsonl               # Pattern agent output
├── rules/                       # Agenda agent rules
│   └── priorities.md
└── vault/                       # Minimal starter vault

Schreibzugriff

config.json

{
  "name": "Markus",
  "language": "en",
  "timezone": "Europe/Berlin",
  "vault": [
    "~/Documents/MyVault",
    "~/Documents/Obsidian"
  ]
}

insights.jsonl

Der Pattern-Agent schreibt Beobachtungen:

{
  "v": 1,
  "id": "ins_20251115_001",
  "type": "strategy",
  "domain": "communication",
  "insight": "When formatting for Signal, use emoji headers instead of markdown",
  "confidence": 0.8,
  "evidence_count": 5,
  "source_sessions": ["sess_001", "sess_003", "sess_007"],
  "created_at": "2025-11-15T04:12:00Z"
}

session_notes.jsonl

Temporäre Lernnotizen, die der Pattern-Agent bei geplanten Läufen prüft:

{
  "v": 1,
  "id": "note_20251115_001",
  "session_id": "sess_007",
  "agent": "relay",
  "problem": "User asked for table formatting in Signal",
  "solution": "Replace markdown tables with emoji-separated rows",
  "context": {
    "channel": "signal",
    "user_feedback": "positive"
  },
  "created_at": "2025-11-15T10:30:00Z",
  "reviewed": false
}

Sitzungsnotizen werden:

• Von jedem agent geschrieben, wenn der Benutzer bei der Problemlösung hilft
• Vom Pattern-Agent beim nächtlichen Lauf gelesen

• Nach der Verarbeitung als reviewed: true markiert

• Regelmäßig bereinigt (geprüfte Notizen älter als 30 Tage)

Der Pattern-Agent entscheidet: auf Insight verallgemeinern oder als spezifische Instanz im Archiv belassen.

Agenda-Regeln

Markdown-Dateien in human/rules/ definieren Benutzerpräferenzen:

# Priorities

## Work vs Personal
- Work appointments take priority over personal, except:
  - Family events always take priority
  - Health appointments always take priority

## Time Blocks
- Monday mornings: no meetings before 10:00

- Friday afternoons: no meetings after 15:00

## Notifications
- Deadline < 3 days: always remind

- Emails from boss: always show immediately

Textextraktion

Für Nicht-Markdown-Dateien extrahieren agents Text wo möglich:

Extrahierter Text wird im Index gespeichert, nicht als separate Dateien.

Binärdateien

Binärdateien (Bilder, PDFs, Office-Dokumente) werden:

1. Indiziert nach Metadaten (Größe, Typ, Änderungsdatum)
2. Textextrahiert wo möglich
3. Verlinkt über Referenzen in Markdown
4. Nicht verändert von outheis (aus Agentenperspektive nur Lesen)

Git-Repositories

Wenn ein Verzeichnis .git/ enthält:

1. Erkannt als Git-Repository
2. Indiziert nach Metadaten (Remotes, Branches, aktuelle Commits)
3. Nicht verändert von outheis-Agenten
4. Action-Agent kann Git-Befehle ausführen, wenn angewiesen

Zeitstempel

Alle Zeitstempel verwenden ISO 8601-Format in UTC:

2025-03-27T10:00:00Z

Agents konvertieren zur Anzeige in die lokale Zeitzone basierend auf der Zeitzoneneinstellung in human/config.json.

Dateinamen

Konventionen

Verbotene Zeichen

Dateinamen dürfen nicht enthalten:

• / \ : * ? " < > |

• Führende/abschließende Leerzeichen

• Führenden . in Benutzerdateien (für System reserviert)

Kodierung

Alle Textdateien verwenden UTF-8-Kodierung ohne BOM.

Zusammenfassung

Schema-Versionierung

Das Problem

Datenstrukturen entwickeln sich weiter. Ohne Versionierung:

• Alte Daten werden nach Upgrades unlesbar
• Gemischte Versionen in derselben Datei verursachen Parsing-Fehler
• Kein Migrationspfad für vorhandene Daten

Versionsfeld

Jeder Datensatz in outheis-verwalteten JSONL-Dateien trägt eine Version:

{"v": 1, "id": "msg_001", "from": {"agent": "zeno"}, ...}
{"v": 1, "id": "msg_002", "from": {"agent": "cato"}, ...}
{"v": 2, "id": "msg_003", "from": {"agent": "zeno"}, "priority": "high", ...}

Kurzer Feldname (v statt version) — JSONL sollte kompakt sein.

Versionsautorität

Die Schema-Version ist in core/schema.py definiert:

# core/schema.py — single source of truth

MESSAGES_VERSION = 2
INSIGHTS_VERSION = 1
CONFIG_VERSION = 1

def write_message(msg):
    msg["v"] = MESSAGES_VERSION
    return json.dumps(msg)

Alle agents importieren dieses Modul. Kein agent schreibt JSON direkt.

Lesen mit Versionsüberprüfung

def read_message(line):
    msg = json.loads(line)
    version = msg.get("v", 0)  # v0 = pre-versioning

    if version == MESSAGES_VERSION:
        return msg  # Hot path, no overhead

    if version > MESSAGES_VERSION:
        raise UnsupportedVersion(
            f"Message v{version} requires newer outheis"
        )

    # Only old messages go through migration
    return migrate_message(msg, from_version=version)

Performance: 99 % der Nachrichten entsprechen der aktuellen Version → einzelner Integer-Vergleich, kein Overhead.

Migrationslogik

Migration erfolgt schrittweise (v0 → v1 → v2), in core/schema.py:

def migrate_message(msg, from_version):
    """Stepwise migration: v0 → v1 → v2 → ..."""

    if from_version < 1:
        # v0 → v1: "from" was string, now object
        if isinstance(msg.get("from"), str):
            msg["from"] = {"agent": msg["from"]}
        msg["v"] = 1
        from_version = 1

    if from_version < 2:
        # v1 → v2: New field "priority" with default
        msg.setdefault("priority", "normal")
        msg["v"] = 2
        from_version = 2

    return msg

Migrations-CLI

# Scan for outdated records
outheis migrate --scan

> Found 47 messages at v1 (current: v2)
> Found 12 insights at v0 (current: v1)
>
> Run 'outheis migrate --apply' to convert

# Apply migration
outheis migrate --apply

> Migrating messages.jsonl: 47 entries v1 → v2
> Migrating archive/messages-2025-01.jsonl: 128 entries v1 → v2
> Migrating insights.jsonl: 12 entries v0 → v1
> Done. Backup in human/.migrate-backup/2025-11-15T10:00:00/

# Quiet mode for automation
outheis migrate --apply --quiet

Automatische Migration

Optional: Migration im nächtlichen Batch mit Pattern-Agent ausführen.

{
  "system": {
    "auto_migrate": true,
    "migrate_schedule": "04:00"
  }
}

Versionshistorie

Wird mit jeder Schema-Änderung aktualisiert.

Theoretischer Hintergrund

Die vault-Architektur implementiert Prinzipien der prospektiven Informationsarchitektur:

• Selbstbeschreibende Objekte: Dateien tragen Bedeutung über Tags — nicht über Position

• Multiple Relationierung: Tags und Links ermöglichen mehrere Zugriffspfade

• Struktur zur Abfragezeit: Hierarchien werden berechnet, nicht gespeichert

• Klartext als Fundament: Universelle Lesbarkeit, langfristige Stabilität

Siehe: Temporalization of Order für theoretische Grundlagen.

Randfälle

Symlinks

Symlinks außerhalb des vault könnten Daten leaken oder die Zugangskontrolle umgehen.

Versteckte Dateien

Dateien und Verzeichnisse, die mit . beginnen, werden ignoriert, außer:

Das umfasst .obsidian/, .DS_Store, .gitignore usw.

Große Dateien

Schwellenwerte sind konfigurierbar.

Kodierungsprobleme

Wenn eine Datei kein gültiges UTF-8 ist:

1. Erkennung versuchen (ISO-8859-1, Windows-1252 usw.)
2. Wenn Konvertierung erfolgreich: konvertierten Text indexieren
3. Wenn Konvertierung fehlschlägt: nur Metadaten indexieren, Benutzer benachrichtigen

Benachrichtigungspfad: Data-Agent → Dispatcher → Agenda-Agent (Persönlicher Modus) oder Relay (Domain-Expert-Modus) → Benutzer

Domain-Expert-Modus: Administratorrolle

Im Domain-Expert-Modus dient das human/-Verzeichnis einem anderen Zweck:

Die Administratorrolle im Domain-Expert-Modus:

• konfiguriert agents, Modelle, Routing
• definiert domänenspezifische Regeln
• überwacht Systemzustand
• empfängt kein persönliches Filtern (kein Agenda)

Mehrere Endbenutzer interagieren über Transport, aber nur der Administrator konfiguriert human/.

Agenda-Verzeichnis

Der primäre vault enthält ein spezielles Agenda/-Verzeichnis — strukturierte Schnittstelle zwischen Benutzer und System.

Struktur

vault/Agenda/
├── Daily.md
├── Inbox.md
└── Exchange.md

Drei Dateien, keine Unterverzeichnisse.

Zweck

Daily.md

Der aktuelle Tag. Agenda-Agent pflegt die Struktur, Benutzer fügt Inhalte hinzu.

# 2025-03-27

## Appointments
- 09:00 Standup

- 14:00 Workshop

## Focus
- [ ] Finish report #deadline
- [ ] Review proposal

## Notes

Inbox.md

Schnellerfassung. Benutzer schreibt, System verarbeitet.

meeting with X next week, important

remember to call Y about the contract

#idea redesign the onboarding flow

Der Agenda-Agent liest, klassifiziert und leitet an passende agents weiter.

Exchange.md

Asynchroner Dialog. System fragt, Benutzer antwortet wenn es passt. Kein Druck.

# Open

## Scheduling conflict
> Friday 28.03 you have:
> - 10:00 Team meeting
> - 10:00 Dentist
>
> Which takes priority?

Your answer:


---

# Resolved

## Tag meaning
> You use #wip and #in-progress. Synonyms?

Your answer: Yes, merge to #wip

Learned: #in-progress → #wip

Besondere Behandlung

Das ermöglicht dem Agenda-Agenten zu verstehen, was sich geändert hat — nicht nur dass sich etwas geändert hat.

Cache-Ort

~/.outheis/human/cache/agenda/
├── Daily.md.prev
├── Inbox.md.prev
└── Exchange.md.prev

Vorherige Versionen werden im Systemverzeichnis gecacht, um Diffs zu berechnen.

Zugriffsstrategien

Ohne Datenbank erfordert schneller Zugriff clevere Strategien auf Basis von Klartext.

Index als primärer Nachschlageort

Der Index (~/.outheis/human/index.jsonl) ist der erste Zugangspunkt. Dateiinhalte werden nur bei Bedarf geladen.

Query
  │
  ▼
Index (fast, in-memory)
  │
  ├── Filter by tags, type, date
  ├── Rank candidates
  │
  ▼
Top-N file access (lazy load)

Ranking-Heuristiken

Kandidaten aus dem Index werden nach mehreren Signalen gerankt:

Tag-Lernen

Der Pattern-Agent analysiert Tag-Nutzung und erlernt Gewichte:

{
  "tag": "project/alpha",
  "weight": 0.85,
  "access_count": 47,
  "co_occurs_with": ["deadline", "important"],
  "last_accessed": "2025-03-27T10:00:00Z"
}

Gespeichert in ~/.outheis/human/tag-weights.jsonl.

Gewichte werden aktualisiert basierend auf:

• Zugriffshäufigkeit (Tag erscheint in aufgerufenen Dateien)
• Gemeinsames Auftreten mit erfolgreichen Suchen
• Implizitem Feedback (wurde Ergebnis verwendet?)

Volltextsuche

Für Inhalte, die nicht im Index erfasst sind:

Implementierungswahl hängt von vault-Größe und Hardware ab.

Index-Aktualisierungen

Dateiwatcher verwendet inotify (Linux) oder kqueue (macOS/BSD) — ereignisgesteuert, kein Polling.

Kaltspeicherzugriff

Für archivierte Gespräche (~/.outheis/human/archive/messages-*.jsonl):

Query about old conversation
  │
  ▼
Data agent identifies relevant archive
  │
  ▼
Load archive file (slower)
  │
  ▼
Search within archive
  │
  ▼
Return results, unload archive

Kein dauerhafter Speichereinfluss. Bei Bedarf laden, nach Verwendung freigeben.

Open source under AGPL-3.0 · Code on GitHub