diff --git a/knowledge-curator.md b/knowledge-curator.md new file mode 100644 index 0000000..2e75e4d --- /dev/null +++ b/knowledge-curator.md @@ -0,0 +1,52 @@ +# knowledge-curator + +Orchestrator-Worker-Setup zum Auditieren und Restrukturieren des MCP-Memory-Hubs (Knowledge Graph). **Read-only per Default** — Mutationen laufen ausschließlich über einen separaten, explizit aufgerufenen Apply-Schritt mit Backup und Bestätigung. + +## Architektur + +``` +/kg-curate ──► skill: knowledge-curator (Main-Thread, orchestriert) + │ dispatcht parallel via Task-Tool: + ├─► kg-graph-auditor (Struktur-Integrität) read-only / sonnet + ├─► kg-entity-deduplicator (Überschneidungen/Merges) read-only / opus + ├─► kg-relation-miner (fehlende Verknüpfungen) read-only / opus + └─► kg-taxonomy-architect (Kategorien/Ontologie) read-only / opus + │ + ├─► Deutscher Audit-Report + └─► kg-changeset.json (Vorschlag, KEINE Mutation) + +/kg-apply ───► liest kg-changeset.json, Backup → Diff → Bestätigung → schreibt +``` + +Der Orchestrator ist ein **Skill**, weil Subagents vom Main-Thread per Task gestartet werden und nicht weiter verschachteln. Jeder Worker arbeitet in eigenem Kontextfenster, zieht den `read_graph`-Dump dorthin und gibt nur kompaktes JSON zurück — der Hauptkontext bleibt schlank. + +## Die vier Subagents (read-only) + +| Agent | Aufgabe | Modell | +|---|---|---| +| `kg-graph-auditor` | Orphans, Dangling Relations, leere Entities, Naming-Inkonsistenzen, Typ-Wildwuchs | sonnet | +| `kg-entity-deduplicator` | Merge-Cluster gleicher realer Dinge, mit Confidence | opus | +| `kg-relation-miner` | semantisch verwandte, aber unverbundene Entities → neue Relations mit Evidenz | opus | +| `kg-taxonomy-architect` | saubere Typ-Hierarchie + Naming-Regeln + Migrations-Map | opus | + +Alle vier haben in ihrer `tools:`-Whitelist **nur** `read_graph`, `search_nodes`, `open_nodes` — keine Write-Tools. Sie können den Graph technisch nicht verändern. + +## Commands + +- **`/kg-curate`** — startet das read-only Audit: dispatcht die vier Worker parallel, synthetisiert einen deutschen Audit-Report (Zusammenfassung, Statistik, Strukturbefunde, Dubletten, vorgeschlagene Verknüpfungen, Taxonomie-Vorschlag, empfohlenes Vorgehen) und schreibt den Vorschlag nach `./kg-changeset.json`. **Keine Mutation** — endet in der Plan-Phase zur Review. +- **`/kg-apply`** — der **einzige Writer**. Liest ein freigegebenes `kg-changeset.json` und wendet es an. + +## Change-Set-Format + +`/kg-curate` schreibt `kg-changeset.json` mit den Gruppen `merges`, `new_relations`, `deletions`, `type_migrations`, `rename_suggestions` (jeweils mit Confidence bzw. Begründung). + +## Sicherheitsmodell + +- Audit ist strikt read-only (Whitelist ohne Write-Tools). +- `/kg-apply` macht zuerst ein **Voll-Backup** (`kg-backup-.json`), zeigt dann einen nach Operationstyp gruppierten **Diff** und verlangt **Bestätigung pro destruktiver Gruppe** (Merges/Deletes sind unwiderruflich). +- **Apply-Reihenfolge:** additiv (neue Entities/Relations) → Observations → Merges (Relations auf Canonical umhängen, Observations kopieren, redundante Member löschen) → Typ-Migrationen/Renames → Standalone-Deletes zuletzt. Nach jeder Gruppe Re-Read zur Verifikation. +- **Backup-Hook als zweite Verteidigungslinie:** `hooks/hooks.json` matcht `mcp__memory__(create|add|delete)_.*` und feuert `backup-memory.sh` vor jedem Memory-Write — debounced (ein Apply-Lauf = ein Backup), gepruned auf `KG_BACKUP_KEEP`, **blockiert nie** (Exit 0). Greift auch bei manuellen Writes außerhalb von `/kg-apply`. Konfiguration siehe [Installation](Installation). + +## Kosten + +Vier parallele Opus-Subagents ≈ ~7× Tokens vs. Single-Thread. Für Routine-Re-Audits die drei semantischen Worker auf `model: sonnet` setzen — der Auditor läuft bereits auf `sonnet`.