71 lines
3.4 KiB
Markdown
71 lines
3.4 KiB
Markdown
# 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.
|