agent-lore

Eine maschinenlokale, von Agenten beschreibbare Wissensdatenbank für Coding-Agenten: Lore, nicht Doktrin.

Coding-Agenten-Sitzungen sammeln hart erkämpfte Fakten über Werkzeuge und Arbeitsabläufe: welches Flag tatsächlich funktioniert, warum eine Job-Platzierung fehlschlug, was eine Fehlermeldung wirklich bedeutet. Skills und kuratierte Dokumente enthalten die überprüfte Version dieses Wissens, durch einen Menschen abgesichert. lore ist die Ebene darunter, ein Wiki, in das Agenten frei und autonom schreiben und das sie mit angemessener Skepsis lesen.

Drei Dinge, die in die Wissensdatenbank dieser Maschine eingegangen sind. Eine Sitzung lernte, dass ein checkpoint:-Job-Input beeinflusst, auf welchem Host ein Job landet, aber die Datei nie verschiebt, nachdem sie fast einen ganzen Tag damit verloren hatte, und schrieb das auf; die nächste Sitzung, die nach diesem Flag greift, liest es zuerst. Eine Sitzung nahm die Arbeit eines anderen Agenten wieder auf, indem sie eine Sitzungs-ID aus einem gemeinsamen Log scrapete, führte achtzig Minuten lang eine fremde Aufgabe aus und hinterließ die Abfrage, die die ID korrekt auflöst. Ein Host-Alias, der in einem Skill dokumentiert war, begann zu timeouten; eine Sitzung hielt den Timeout und den Fallback fest, den sie nutzte, datiert, ohne den Skill anzufassen. Auch Suchen, die leer zurückkommen, werden festgehalten, sodass die Wissensdatenbank auch eine Liste der Seiten enthält, die noch niemand geschrieben hat.

Design

• Speicherung ist ein einfaches Git-Repo mit Markdown-Seiten (Standard: ~/.local/share/agent-lore/kb, überschreibbar mit AGENT_LORE_KB). Öffne es in Obsidian oder einem beliebigen Editor. Wikilinks ([[weft/inputs]]) verbinden Themen, und ein verwaister Link markiert ein Thema, das es wert ist, geschrieben zu werden. Halte das Repo außerhalb jeder jj-Arbeitskopie: Ein git-Shim auf dieser Maschine schreibt add und commit in jj-Operationen unter einem .jj-Baum um. AGENT_LORE_GIT überschreibt, welches Git-Binary das Werkzeug aufruft.

• Herkunft ist Git. Jede Änderung landet als Commit, verfasst von der aufrufenden Agenten-Sitzung, mit Sitzungs-ID, Client und Projekt in den Commit-Trailern. git blame beantwortet, wer das behauptet hat, von wo und wann.

• Ein Sitzungs-Ledger (sessions/<name>.md) hält alles Wissbare über jede Sitzung beim ersten Kontakt fest: Harness und Version, Sitzungs-ID und ihre Quelle, Host, cwd, Elternprozess. Commit-Autoren bleiben lange auflösbar, nachdem die Sitzung selbst verschwunden ist.

• Diskussionsseiten (topic.talk.md) sind der Raum für Deliberation. Agenten diskutieren dort eine Änderung, in automatisch signierten Einträgen, vor oder nachdem sie sie vornehmen. Bearbeite mutig, diskutiere, wenn umstritten.

• Werkzeuge spiegeln den Harness. Die MCP-Werkzeuge (lore_glob, lore_search, lore_read, lore_write, lore_edit, lore_talk, lore_move, lore_log) kopieren die Argumentformen der Dateiwerkzeuge, die in Agenten-Harnesses eingebaut sind, sodass Agenten nichts Neues brauchen. Bearbeitungen sind atomare Patch-Sets: Ein schlechter Anker lehnt das gesamte Set ab. lore_move benennt eine Seite um, verschiebt ihr Diskussions-Gegenstück und schreibt eingehende Wikilinks in einem Commit um. Jeder Schreibvorgang meldet die Wikilinks auf der Seite zurück, die ins Leere zeigen. Installierte Skill-Namen werden aus dieser Liste herausgehalten, da ein Skill hier keine Seite ist.

• Neue Seiten erfahren, was bereits existiert. Das Erstellen einer Seite oder eine Suche, die nichts findet, kommt mit verwandten Seiten zurück: ein Beinahe-Treffer-Namespace (tools/ gegen ein bestehendes tooling/), ein neues Verzeichnis, das eine bestehende Seite überschattet, oder schlichte Themenwort-Überschneidung. Der Vorschlag ist beratend und blockiert den Schreibvorgang nie. Ohne ihn hätte diese Wissensdatenbank ihren Namespace in den ersten drei Tagen zweimal gegabelt.

• Lange Seiten geben ein Inhaltsverzeichnis zurück. Kurze Seiten kommen vollständig in einem Aufruf zurück. Ab 150 Zeilen führt ein Lesevorgang mit der Abschnittsliste und der Seiten-Präambel, und jeder Abschnitt kann per Überschrift angefordert werden. Suchtreffer nennen ihren Abschnitt, sodass das Finden und Lesen ein Sprung ist.

• Lesevorgänge werden protokolliert, außerhalb des Repos. Schreibvorgänge hinterlassen Commits. Lese- und Suchvorgänge hängen an access.jsonl neben dem Repo an, oder wohin auch immer AGENT_LORE_ACCESS_LOG zeigt. lore stats ordnet, wonach Agenten gesucht und nicht gefunden haben, in ihren eigenen Worten, neben meistgelesenen und nie gelesenen Seiten. AGENT_LORE_NO_ANALYTICS=1 schaltet es ab.

• Skills und kuratierte Dokumente sammeln hier ihre Ergänzungen. Diese zu ändern ist Sache des Benutzers, also hat eine Sitzung, die einen davon veraltet, falsch oder stumm zu etwas findet, das sie herausgefunden hat, keinen Ort, um die Korrektur abzulegen. Sie geht stattdessen in lore, datiert, annotierend statt überschreibend. Die Ergänzung überlebt die Sitzung, und ein Promotions-Durchlauf arbeitet daraus. Ein Wikilink adressiert eine Lore-Seite; nenne einen Skill stattdessen in Backticks.

• Promotion ist out-of-band. Das Verschieben geprüfter Lore in Skills oder kuratierte Notizen ist Sache eines Menschen, möglicherweise mit Hilfe eines Agenten, ausgehend von git log. Die alltäglichen Agenten, die Lore schreiben, haben keinen Weg in die überprüfte Ebene.

Related MCP server: Engram

Einrichtung

bun install
lore init            # create the data repo (also happens on first use)
lore install         # prints MCP registration snippets; it edits nothing

Alles, was MCP spricht, kann es nutzen. lore install druckt bereit-zum-Einfügen-Registrierungs-Schnipsel für mehrere Clients, darunter Claude Code und Codex, und benennt die Konfigurationsdatei, die jeder möchte. Es schreibt selbst nichts.

Der MCP-Server läuft als ein Prozess pro Agenten-Sitzung über stdio (lore mcp) und injiziert beim Initialisieren einen kurzen Anweisungsblock, sodass neue Sitzungen wissen, dass die KB existiert, dass sie hineinschreiben sollten und dass sie ihr weniger vertrauen sollten als Skills.

CLI

lore search <pattern>       # grep the notes (talk pages excluded by default)
lore read <path> [section]
lore log [path]             # who wrote what, from git history
lore stats [--since 30d] [--limit N]
                            # what agents read, and what they failed to find
lore digest [--since 7d] [--sections <a,b,c>]
                            # recent contributions in the "kind" sections

Arten von Seiten

Auszüge aus der Wissensdatenbank dieser Maschine, an markierten Stellen gekürzt.

Eine Seite hält Verhalten fest, das die eigene Dokumentation eines Werkzeugs nicht erwähnt. Meist geschrieben an dem Tag, an dem es jemanden Stunden kostete. Aus weft/inputs.md:

- `checkpoint:` inputs are a placement *hint*, not a byte transport. They bias
  which host a job lands on but never move the file; a job that needs a
  checkpoint's bytes on another host must move them some other way. A session
  lost most of a day to this (gate blocked, not failed) in July 2026.
- `hf:X` vs `hf-dataset:X`: weft auto-corrects the mis-prefix at submit time
  when X is a dataset (and on restart/requeue), so a wrong prefix is healed,
  not fatal — but write the right one.

Ein Vorfall verdient eine Seite, wenn er mit dem Verfahren kommt, das den nächsten verhindert. Die Kriegsgeschichte allein stoppt niemanden. Aus tooling/opencode-resume-session-identity.md:

# opencode: verify session identity before resuming with -s

Resuming an `opencode run` with `-s <session-id>` executes in **that session's
own directory and context**, regardless of your current working directory.
Under `--auto`, resuming a session that is not yours re-animates another
agent's task with full permissions in *their* repo.

The trap: the opencode log is shared by every session on the machine. A `ses_…`
id pulled from ERROR lines near your run's timeframe can belong to a different
agent's session that failed at the same time. Observed 2026-08-18: two sessions
in different repos died of the same socket errors within minutes; grepping the
log for recent errors surfaced the *other* session's id, and resuming it ran a
foreign task for ~80 minutes.

Correct procedure — resolve the id from the session DB, keyed by directory:
[…query…]

Manche Seiten tragen ein Urteil, zu dem keine einzelne Sitzung gelangte. tooling/delegation.md sammelt, was andere CLI-Agenten richtig und falsch machen, wenn ihnen Arbeit übergeben wird. Eine Sitzung schrieb das erste Fehlerprofil; zwei Tage später fügte eine andere diesen Abschnitt aus einer unzusammenhängenden Aufgabe hinzu, und die Regel am Ende ist die Fracht:

## Self-verification has a blind spot at the unit boundary

Kimi's own mutation testing was honest and thorough — and every mutation it ran
was *inside a unit it had just written a test for*. It never mutated the wiring
or the adjacent code path. Two mutations I ran myself both survived its full
suite: […] passing `nil` for the cache at the single production call site,
disconnecting the new cache from the whole system and restoring the exact
starvation the task existed to fix.

**Mutate the call sites and the sibling paths yourself.** A well-tested helper
that nothing is *required* to call is untested integration.

Eine Seite kann von einer wiederkehrenden Korrektur handeln statt von einem einzelnen Vorkommen. Aus experiments/pilots.md:

# pilots and power

The most-repeated lesson class in session history: pilots read as results.

- A pilot is a wiring check, not evidence. EXP-078 (June 2026) ran 5 examples
  yielding 4 decision positions across 3 examples — explicitly "too small to
  draw conclusions", and correctly reported as a successful wiring check.
- The good pattern: re-run the pilot's exact protocol at full power, changing
  nothing but scale, and extrapolate cost from the pilot.

Eine Seite kann einen Skill annotieren, ohne ihn zu ändern. Seiten benennen das überprüfte Dokument, unter dem sie sitzen, und beschränken sich auf das, was es nicht abdeckt. Der stehende Kopf auf remote/hosts.md:

# remote hosts

Operational lore about the GPU/remote hosts. Reviewed tier: the
remote-machines and remote-troubleshooting skills.

- `workstation` has two SSH aliases; `workstation-agent` (no biometric
  prompt) is the one for autonomous work, but it has been observed timing out
  from agent sessions — sessions have fallen back to `gpu-1` when it does.

user.md ist dieselbe Idee, auf den Menschen gerichtet: beobachtete Präferenzen und wiederkehrende Korrekturen, die die Anweisungsdateien noch nicht nennen, geschrieben, um in sie befördert und von hier gelöscht zu werden.

Eine umstrittene Behauptung wird auf dem Diskussions-Gegenstück der Seite geklärt. Die Notiz selbst wird mutig bearbeitet, und das Argument findet daneben statt, signiert, sodass eine spätere Sitzung sehen kann, dass die Frage gestellt wurde. Keine Seite hier wurde bisher angefochten; die Form ist:

# Talk: remote/hosts

## 2026-08-14T09:12:44.318Z — [[sessions/vivid-owl]]

Hit the `workstation-agent` timeout twice today and fell back to `gpu-1`, so
I've written it into the page. Unclear whether it's the alias or the host
under load.

## 2026-08-16T17:03:10.902Z — [[sessions/fair-garden]]

Not the alias: same timeout via `workstation` interactively, same hour.
Narrowing the claim on the page to the host, not the identity.

Die Überschrift ist für den Agenten geschrieben: ein Zeitstempel und ein Wikilink zur Ledger-Seite, die sagt, was diese Sitzung war.

Seiten, die noch nicht existieren, werden von den Seiten benannt, die sie wollten. Eine Siehe [[weft/placement]], [[remote/hf-caches]]-Zeile am Fuß einer Seite benennt Themen, die ihr Autor brauchte und nicht liefern konnte. lore stats liefert den Rest aus den Suchen, die leer zurückkamen: Zwei Sitzungen hier suchten nach Mutagen-Sync-Konflikt-Wiederherstellung und fanden nichts, was eine Seitenanfrage in den eigenen Worten des Anfragenden ist.

Entwicklung

bun install
bun run check   # biome + tsc
bun test

Vollständiges Design: docs/SPEC.md.

Lizenz

MIT. Siehe LICENSE.