# Architektur

> Agent NAS hat vier Schichten und eine optionale Synchronisierungsschicht: Interface projiziert Fähigkeiten in vorhandene Schnittstellen, Trust ist die einzige Autorisierungsstelle, Memory macht aus Notizen durchsuchbares Wissen, und Store hält einen Tree mit Verlauf. Die Memory-Schicht lässt sich als Ganzes löschen und neu aufbauen, und Store nutzt schlicht bewährten Speicher.

## Vier Schichten und optionale Synchronisierung

- **Interface**: Projiziert Fähigkeiten in Schnittstellen, die Agenten, Menschen und Werkzeuge bereits nutzen. Gateways sind zustandslos und entscheiden nie, wer was darf. (Mount (FUSE, NFS, SMB), Git, S3-kompatibel, WebDAV, MCP, HTTP-API, CLI, A2A (optional))
- **Trust (Vertrauen)**: Die einzige Autorisierungsstelle. Eine deterministische Richtlinien-Engine ohne Modell in der Entscheidung; erst protokollieren, dann handeln. (Principals und Ausführungen, Capability Lease, Richtlinien-Engine, Human Gate, Trust Labels, Credential Broker, Flight Recorder)
- **Memory (Gedächtnis)**: Macht aus Notizen durchsuchbares, budgetiert lesbares Wissen. Alles lässt sich aus der Schicht darunter neu aufbauen. (Notizkonventionen, Indizes (Volltext, Vektor, Graph), Budgeted Reads, Wartungsjobs, Lineage, Cascade Forget)
- **Store (Speicher)**: Ein Tree mit Verlauf, auf bewährten Dateisystem-Snapshots, Git oder versioniertem Objektspeicher. Er versteht weder Gedächtnis noch Labels. (Tree, Commit, Agent Branch, Dateisystem-Snapshots, Git, Objektspeicher)
- **Sync (Synchronisierung, optional)**: Replikation und Teilen zwischen Knoten. Absichtlich zuletzt: Bringen Sie zuerst einen einzelnen Knoten in Ordnung. (Git-Remotes, Snapshot-Transfer, Lease-Links, Übergabepakete)

- **Die Memory-Schicht ist wiederaufbaubar.** Löschen Sie alle Indizes und bauen Sie neu auf: Die Notizen im Store bleiben vollständig lesbar.
- **Gateways sind zustandslos.** Aller persistente Zustand liegt im Store und in den Protokollen von Trust; ein Gateway darf jederzeit neu starten und lässt sich horizontal skalieren.
- **Trust ist die einzige Autorisierungsstelle.** Dazu zählen auch die Hintergrundjobs des NAS (Indexierung, Wartung): Auch sie laufen als `svc:*`-Principals mit Leases.
- **Store versteht weder Gedächtnis noch die Semantik von Labels.** Er hält nur einen Tree mit Metadaten.
- **Erst protokollieren, dann handeln.** Eine folgenreiche Operation muss zuerst einen Absichtseintrag schreiben.

## Die schmale Taille: sechs Kernbegriffe

Der gesamte Entwurf hängt an sechs Kernbegriffen; Labels, Gates, Gedächtnis und Lesemanifeste sind Konventionen, die darauf aufbauen.

| Begriff | Bedeutung | Zentrale Invariante |
| --- | --- | --- |
| Tree | Ein Verzeichnisbaum mit Verlauf. | Jeder Commit lässt sich reproduzieren; es gibt einen Inhalts-Hash oder eine gleichwertige Änderungserkennung. |
| Commit | Eine unveränderliche Änderung. | Trägt Provenienz-Metadaten: `principal`, `on_behalf_of`, `run`, `lease`. |
| Principal | Eine Entität, die authentifiziert und zur Verantwortung gezogen werden kann. | Typ ist `human`, `agent`, `service` oder `node`; ein `agent` gehört zu einer Rolle, nicht zu einer einzelnen Ausführung. |
| Run | Eine Ausführung mit Anfang, Ende, Zweck und einem Verantwortlichen. | Hält genau eine Wurzel-Lease; besitzt genau einen Branch. |
| Lease | Die Autorisierung einer Ausführung. | Hat ein Ablaufdatum; kann nur enger werden; widerrufbar; trägt Budgets. |
| Record | Ein Append-only-Eintrag. | Per Hash verkettet; erst protokollieren, dann handeln. |

## Die Store-Schicht: Vertrag und mögliche Engines

Der Store-Vertrag wird von einer Engine bereitgestellt oder vom Gateway nachgebildet. Eine Implementierung darf Engines kombinieren, zum Beispiel Git für Text und Snapshots für große Dateien; der Vertrag schreibt weder die Engine noch die Hash-Funktion noch das On-Disk-Format vor.

1. Atomare Commits.
2. Günstige Forks: idealerweise nahe an O(1); schlimmstenfalls als Kopie, dann sind Kontingente und eine TTL Pflicht.
3. Unveränderliche Snapshots.
4. Änderungserkennung: ein Inhalts-Hash oder Gleichwertiges.
5. Die Differenz zwischen zwei Commits.
6. Vollständiger Export in einem Standardformat: ein Verzeichnis, Git-Verlauf und die Klartext-Metadaten in `.nas/`.

| Engine | Geeignet für | Fork-Kosten | Hinweis |
| --- | --- | --- | --- |
| Git (mit Worktrees) | Text, Gedächtnis, Skills, kleine Codebasen | Gering | Große Dateien brauchen LFS oder externen Speicher; Binär-Merges sind schlecht. |
| Dateisystem-Snapshots und -Clones (ZFS, btrfs, APFS) | Große Verzeichnisse, gemischte Dateien | Etwa O(1) | Hängt vom Dateisystem ab; Kopieren zwischen Maschinen braucht send/receive. |
| Versionierter Objektspeicher (Tigris-Forks, lakeFS, S3 plus Manifest) | Datensätze, große Dateien | Etwa O(1) | Das Gateway muss eine Dateiansicht bereitstellen. |
| Einfaches Verzeichnis plus Kopie | Einstieg mit Lite | O(n) | Nur für kleine Datenmengen; Kontingente und eine TTL sind Pflicht. |

> **Der Wiederherstellungspfad liegt außerhalb des Schadensradius.** Snapshots und Backups gehören dem Eigentümer-Principal, und keine Lease darf „einen Snapshot löschen“ oder „ein Backup löschen“ enthalten. Das ist die direkteste Lehre aus dem Vorfall vom April 2026: Der Wiederherstellungspfad muss außerhalb des Schadensradius dessen liegen, was er schützt.

- Verschlüsselung im Ruhezustand kommt von der darunterliegenden Schicht; die Aufbewahrungsklasse `sensitive` hat eine eigene Schlüsseldomäne und lässt sich daher durch Zerstören des Schlüssels vernichten.
- Deduplizierung und Vernichtung stehen im Konflikt: Die Klasse `sensitive` wird nicht über Schlüsseldomänen hinweg dedupliziert.

## Die Reise einer Ausführung

1. **Anfordern.** Der Orchestrator (oder der Eigentümer) fordert für eine Ausführung eine Lease an: Pfade, Aktionen, Ablauf, Zweck. Innerhalb des **Richtlinienrahmens** wird sie automatisch ausgestellt; außerhalb geht sie an ein Human Gate.
2. **Starten.** Das NAS legt den `run` und den Branch `<role>/<run_id>` an und übergibt die Lease an die Ausführung; die Sandbox bindet den Branch ein (oder führt ein `git clone` aus).
3. **Arbeiten.** Der Agent liest und schreibt mit gewöhnlichen Dateiwerkzeugen. Lesezugriffe sammeln sich im **Lesemanifest**, und die Sitzungskontamination wird entsprechend aktualisiert; Zugriffe außerhalb der Grenzen werden abgelehnt und protokolliert.
4. **Committen.** Änderungen werden automatisch (entprellt) oder ausdrücklich committet, und jeder Commit trägt Provenienz-Metadaten.
5. **Vorschlagen.** `propose` erzeugt einen **Agent PR**: den Diff, die Absicht, eine Zusammenfassung des Lesemanifests, Prüfergebnisse und eine Zusammenfassung der Labels.
6. **Entscheiden.** Die Richtlinien-Engine entscheidet: Bestehen die Prüfungen und ist das Risiko gering, wird automatisch gemergt; geht es um geschützte Daten, eine nach außen gerichtete Aktion oder einen Verstoß gegen die Zweierregel, geht es an ein Human Gate; ist etwas eindeutig verboten, wird abgelehnt.
7. **Mergen und protokollieren.** Der Merge erzeugt einen Commit mit Provenienz und schreibt einen Record.
8. **Abschließen.** Die Lease läuft ab; der Branch wird nach seiner TTL in den Papierkorb verschoben; Lesemanifeste und Records werden nach der Aufbewahrungsrichtlinie vorgehalten.

**Der Lesepfad:** Anfrage, Lease-Prüfung, Label-Prüfung (erlaubt die aktuelle Sitzungskontamination dieses Lesen?), Budgetzählung, Lesen aus dem Store, Eintrag im Lesemanifest, Inhalt und Belegzeiger zurückgeben.

> **Erst protokollieren, dann handeln.** Eine folgenreiche Operation (Merge, Löschen, Teilen, Egress, Lease-Änderung) muss zuerst einen Absichtseintrag schreiben; lässt er sich nicht schreiben, schlägt die Operation fehl (fail closed). Lesezugriffe gehen in das Lesemanifest, das stapelweise geschrieben wird und nicht pro Lesezugriff synchron sein muss.

## Einsatzformen

| Form | Beschreibung | Geeignet für |
| --- | --- | --- |
| Lite | Einzelner Rechner, einzelner Nutzer: ein Gateway-Prozess plus lokaler Speicher (Git oder Dateisystem-Snapshots); L0 bis L1. | Privatpersonen und Entwickler beim Ausprobieren. |
| Overlay | Lässt das vorhandene NAS oder den Objektspeicher unangetastet: Ein Gateway sitzt davor und verwaltet nur ein einziges Verzeichnis oder einen Bucket; Mounts und die S3-Ansicht laufen über das Gateway. | **Der realistischste Einstieg:** Wer schon eine Box hat. |
| Team | Mehrere Nutzer und Agenten, ein Server oder ein kleiner Cluster; L0 bis L3; Gate-Benachrichtigungen und ein Leitstand. | Kleine Teams. |
| Cloud | Ein gehosteter mandantenfähiger Dienst mit starker Isolation; L0 bis L3. | Wer keine eigene Hardware hat. |

Das Prinzip: Spezielle Hardware ist nicht nötig, jeder dauerhaft laufende Rechner genügt; Beschleuniger sind optional, denn für Embeddings und Zusammenfassungen reichen kleine Modelle, und externe Dienste lassen sich ebenfalls aufrufen.

## Ein v0 aus vorhandenen Bausteinen bauen

| Fähigkeit | Bausteine, die es heute schon gibt |
| --- | --- |
| Store und Branches | Git und Worktrees; btrfs- oder ZFS-Snapshots; oder Tigris und lakeFS (Objektspeicher). |
| Geschützte Hauptlinie | Branch-Schutz in Forgejo, Gitea oder GitHub; oder geschützte Branches in lakeFS. |
| Leases | Ein OAuth-Autorisierungsserver (zum Beispiel Keycloak) mit Token Exchange und ein Resource Server, der Pfadpräfix und Aktion prüft; oder ein Signaturdienst von ein paar hundert Zeilen. |
| Records | Eine Append-only-SQLite-Tabelle plus ein täglicher Hash; Git-Trailer in Commits; OpenTelemetry-Export. |
| Gates | PR-Review plus eine Push-Benachrichtigung; die CLI `nas gate approve`. |
| Gedächtnis | Markdown unter `memory/` plus SQLite FTS5; einen Vektorspeicher können Sie später ergänzen. |
| Labels | Das Importverzeichnis als `external` markieren; die Sitzungskontamination pro Ausführung im Gateway halten. |
| Schnittstellen | NFS-, SMB- oder FUSE-Mount; Git über SSH oder HTTPS; ein S3-Gateway; ein kleiner MCP-Server. |

Was diese Tabelle sagt: **L0 und L1 brauchen keine neue Erfindung.** Neu ist der Vertrag, der sie verbindet, und die Tests, die ihn überprüfen; siehe die [Spezifikation](https://agentnas.com/de/spec/).

## Betrieb

- **Backups:** 3-2-1; Snapshots und Backups gehören dem Eigentümer-Principal, und keine Lease darf sie berühren; üben Sie jedes Quartal eine Wiederherstellung und halten Sie sie im Protokoll fest.
- **Upgrades:** Gateways sind zustandslos und lassen sich schrittweise aktualisieren; jede Änderung des Store-Formats muss mit einem Migrations- und Rollback-Plan kommen; die Memory-Schicht lässt sich als Ganzes neu aufbauen.
- **Überwachung:** Raten der Lease-Ausstellung und -Ablehnung; Länge der Gate-Warteschlange und Freigabequote (bleibt die Freigabequote über 95 %, sind Gates zu häufig und sollten zusammengelegt oder die Richtlinie verschärft werden); Anzahl und Alter der Branches; Aktualität der Indizes; Prüfung der Record-Kette; Kontingente.
- **Kapazität:** Branches haben eine TTL und Kontingente; der Papierkorb hat eine Aufbewahrungsfrist; abgeleitete Daten haben ein Budget.

## Der Leitstand

Die Oberfläche für Menschen kann eine Webseite, eine CLI oder ein Chatbot sein. Sie ist nicht zwingend: L0 bis L1 können vollständig mit einer CLI und einer vorhandenen Git-Plattform laufen.

- **Aktivitätsverlauf:** nach Ausführung aggregiert: wer was getan hat und was gelesen wurde.
- **Gate-Posteingang:** Aktionen, die auf Freigabe warten, als Gate Cards dargestellt.
- **Rollenverzeichnis:** Home, Leases, Budgets und letzte Ausführungen jeder Rolle.
- **Gedächtnis-Browser:** Notizen und Quellen, die Quarantäne ungeprüfter Notizen, Wartungsvorschläge.
- **Branches und PRs:** nicht gemergte Branches und der Papierkorb.
- **Vergessen-Konsole:** Anfragen, eine Lineage-Vorschau und Berichte.

Menschen können auch direkt über SMB oder WebDAV nachsehen: `/humans/<user>/Agent Activity/` ist eine schreibgeschützte Aktivitätsansicht aus gewöhnlichen Dateien.

---

Kanonische URL: https://agentnas.com/de/architecture/
Aktualisiert am: 2026-11-11 · Spezifikationsentwurf v0.2 · CC BY 4.0