munin/AGENTEN-GUIDE.md

Agenten anbinden

Wie man KI-Werkzeuge so einrichtet und anspricht, dass sie den Munin tatsächlich benutzen.

Dieselben Inhalte stehen für Nutzer auch in der Weboberfläche unter /hilfe/mit-agenten-arbeiten (Quelle: internal/hilfe/seiten/). Wer hier etwas ändert, sollte dort nachziehen.

---

1. Verbinden

Key erzeugen unter /p/<projekt>/keys. Der Klartext wird genau einmal angezeigt.

Die fertigen Konfigurationsblöcke für Claude Code, Cline und OpenCode stehen im README — dort auch, worin sich die drei Dateien unterscheiden. Kurzfassung:

Client	Datei	Schlüssel	type
Claude Code	.mcp.json	mcpServers	http
Cline	cline_mcp_settings.json	mcpServers	streamableHttp
OpenCode	opencode.json	mcp	remote

Ein Server je Projekt. Der Key bestimmt das Projekt — kein weiterer Parameter nötig.

Ein Key je Person und je Agent. Der Key-Name landet als Autor an jedem Eintrag und im Protokoll.

---

2. Werkzeuge

Werkzeug	Parameter	Rolle
recall	query, tags?, limit?	read
get	slug	read
list	tag?, curated?, limit?	read
remember	title, content, slug?, tags?, expected_version?	write
forget	slug	write

---

3. Das eigentliche Problem

Der Server schickt jedem Client eine Anleitung mit (instructions). Viele Clients gewichten sie schwach oder ignorieren sie. Ohne eigene Anweisung im Projekt- oder Systemprompt greift ein Agent selten von selbst zum Werkzeug — er antwortet lieber aus seinem eigenen Wissen.

Deshalb der folgende Block.

---

4. Projektprompt

In CLAUDE.md, .clinerules, „Custom Instructions" oder den Systemprompt der eigenen Anwendung:

## Munin

Für dieses Projekt gibt es einen Munin über MCP (Werkzeuge: recall,
get, list, remember, forget). Er ist das gemeinsame Gedächtnis des Teams.

LESEN — vor jeder Antwort zu projektspezifischen Fragen:
- Zuerst `recall` mit der Frage aufrufen, nicht mit Stichworten.
- Passenden Treffer mit `get` vollständig laden.
- Erst wenn nichts Passendes da ist, aus eigenem Wissen antworten — und das
  kenntlich machen.
- Nie raten, wenn es um Prozesse, Zugänge oder Entscheidungen dieses Teams geht.

SCHREIBEN — sobald etwas festgehalten werden sollte:
- IMMER zuerst `recall`, ob es zum Thema schon einen Eintrag gibt.
- Gibt es einen: mit DESSEN slug `remember` aufrufen. Das aktualisiert ihn.
- Nur wenn wirklich nichts passt, einen neuen slug wählen.
- Vor dem Aktualisieren `get` aufrufen und die gelieferte `version` als
  `expected_version` mitgeben.

WAS festgehalten wird:
- Entscheidungen mit Begründung
- Abläufe, die sich wiederholen
- Lösungen für Probleme, die länger gedauert haben
- Nicht: Zwischenstände, Diskussionsverlauf, was im Code steht

WIE festgehalten wird:
- Destilliert, nicht als Protokoll. Ein Eintrag beantwortet eine Frage.
- Verwandtes mit [[bezeichner]] verknüpfen.
- Schlagworte sparsam: 1–3 aus dem bestehenden Bestand (`list` zeigt sie).

---

5. Bezeichner (slug)

Der slug ist der Schlüssel gegen Dubletten: gleicher slug = Aktualisierung.

gut	schlecht	warum
deployment-prozess	notiz-2026-01-15	Datum ist kein Thema
fehler-zugriff-verweigert	problem-3	nicht wiederfindbar
entscheidung-sqlite	sqlite-entscheidung-final-v2	Fassungen zählt das System

Regeln: a-z, 0-9, -, _. Kurz, sprechend, dauerhaft. Ohne Angabe wird er aus dem Titel abgeleitet.

---

6. Muster für einzelne Aufgaben

Nachschlagen

Wie läuft bei uns das Deployment? Schau zuerst im Munin nach.

Festhalten nach getaner Arbeit

Halte fest, was wir über den abgelaufenen Token herausgefunden haben.
Prüfe vorher mit recall, ob es dazu schon einen Eintrag gibt — dann
ergänze diesen, statt einen neuen anzulegen.

Bestand aufräumen

Rufe list auf und nenne mir Einträge, die dasselbe Thema doppelt behandeln.
Nichts ändern, nur auflisten.

Einarbeiten

Verschaffe dir mit list und recall einen Überblick über den Munin
und fasse zusammen, was dieses Team über Betrieb und Deployment festgehalten hat.

Vorhandenes fortschreiben

Lies deployment-prozess mit get, ergänze den Schritt mit dem Rollback und
schreibe zurück — mit expected_version aus dem get.

---

7. Was Dubletten erzeugt

Ursache	Gegenmittel
Agent schreibt ohne vorher zu suchen	„IMMER zuerst recall" im Projektprompt
Neuer slug für vorhandenes Thema	slug-Regeln oben; recall liefert den vorhandenen
Zeitstempel im slug	verbieten — Fassungen zählt das System
Jede Erkenntnis als eigener Eintrag	„Ein Eintrag beantwortet eine Frage"

---

8. Prüfen, ob es wirkt

Protokoll: /p/<projekt>/audit — jeder Schreibvorgang mit Zugang und Zeit.

Faustregel: Nach ein paar Wochen sollte das Verhältnis von Aktualisierungen zu Neuanlagen steigen. Viele Neuanlagen bei ähnlichen Themen heißt: Der Projektprompt greift nicht.

In der Oberfläche: Einträge mit Herkunft „Agent" und ohne Marke „kuratiert" sind ungeprüfte Beobachtungen. Wer sie durchsieht und bestätigt, setzt den Haken „Kuratiert" — Agenten sehen das Feld über recall und get.

---

9. Rollen

Rolle	darf	wofür
read	recall, get, list	Agenten, die nur auskunftsfähig sein sollen
write	zusätzlich remember, forget	der Normalfall
admin	zusätzlich Zugänge verwalten	Menschen

Ein Agent, der ohne Aufsicht läuft, bekommt read. Schreibrecht dort, wo jemand die Einträge auch durchsieht.

---

10. Grenzen

• Suche ist wortbasiert. „wie deployen wir" findet „Release-Prozess" nicht. Im Zweifel list für den Überblick.
• forget legt in den Papierkorb. Der Eintrag ist für Agenten sofort unsichtbar, ein Mensch kann ihn 30 Tage lang in der Weboberfläche zurückholen. Agenten können weder wiederherstellen noch den Papierkorb leeren. Änderungen mit remember sind trotzdem der bessere Weg: Die vorherige Fassung bleibt im Verlauf (Weboberfläche → Verlauf ansehen), und der Eintrag bleibt auffindbar.
• remember auf einen Bezeichner im Papierkorb holt den Eintrag zurück und überschreibt ihn; der gelöschte Stand wandert in den Verlauf. Die Antwort sagt das ausdrücklich.
• Was drinsteht, landet im Kontext aller. Wer schreiben darf, schreibt indirekt in die Prompts der anderen — Herkunft und Autor stehen deshalb an jedem Eintrag.