# knowledge-curator (plugin internals)

Orchestrator-Worker-Setup für das Auditieren und Restrukturieren des
MCP-Memory-Hubs.

## 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
```

**Warum der Orchestrator ein Skill ist:** Subagents werden vom Main-Thread per
Task gestartet und verschachteln nicht weiter. Der dispatchende Teil muss im
Hauptkontext laufen → Skill (bzw. `/kg-curate`). Jeder Worker arbeitet in
eigenem Kontextfenster, zieht den `read_graph`-Dump in seinen Kontext und gibt
nur kompaktes JSON zurück — der Hauptkontext bleibt sauber.

## Sicherheit

- Audit ist **strikt read-only**: die vier Worker haben im `tools:`-Whitelist
  keine Write-Tools, können den Graph also nicht verändern.
- Mutationen ausschließlich in `/kg-apply`: erst Voll-Backup
  (`kg-backup-<timestamp>.json`), dann Diff, dann Bestätigung pro destruktiver
  Gruppe (Merges/Deletes sind unwiderruflich).
- Apply-Reihenfolge: additiv (neue Entities/Relations/Observations) → Merges →
  Migrationen/Renames → Standalone-Deletes zuletzt.
- **Backup-Hook (zweite Verteidigungslinie):** `hooks/hooks.json` feuert vor
  jedem Memory-Write-Tool (`create*`/`add*`/`delete*`) und sichert die
  Graph-Datei per `backup-memory.sh`. Debounced (ein Apply-Lauf = ein Backup),
  pruned auf `KG_BACKUP_KEEP`, blockiert nie (Exit 0). Greift auch bei manuellen
  Writes außerhalb von `/kg-apply`. Pfad zur Graph-Datei via `KG_MEMORY_FILE`
  (oder `MEMORY_FILE_PATH`) setzen.

## Komponenten

| Datei | Rolle |
|-------|-------|
| `skills/knowledge-curator/SKILL.md` | Orchestrator, Report-Synthese, Change-Set |
| `agents/kg-graph-auditor.md` | Orphans, Dangling Relations, leere Entities, Naming |
| `agents/kg-entity-deduplicator.md` | Merge-Cluster mit Confidence (≥ 0.6) |
| `agents/kg-relation-miner.md` | neue Relations mit Evidenz (≥ 0.5) |
| `agents/kg-taxonomy-architect.md` | Typ-Hierarchie + Naming-Regeln + Migrations-Map |
| `commands/kg-curate.md` | startet das read-only Audit |
| `commands/kg-apply.md` | wendet ein freigegebenes Change-Set an (einziger Writer) |
| `hooks/hooks.json` | PreToolUse-Hook auf Memory-Write-Tools |
| `hooks/backup-memory.sh` | dateibasiertes Graph-Backup, debounced + pruned |

## 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`.

## Konfiguration

- MCP-Servername / Tool-Namen in den `agents/*.md` und im SKILL.md an deine
  Instanz anpassen (Default: Server `memory`, Tools `read_graph` /
  `search_nodes` / `open_nodes`).
- Confidence-Schwellen in den Agent-Bodies justierbar.
- Report-Sprache im SKILL.md (Phase 3); Worker-Output bleibt englisch/JSON.