Memory für KI-Coding-Agenten: Speichern ist die leichte Hälfte

Der Harness-Post von letzter Woche zeigte ein echtes Session-Briefing, und eine Zeile darin hat mehr geleistet als alle anderen:

- **MCP Server** [PITFALL] (claude-code/vincent, 1 day ago): every new ID argument
  name must be added to idArgumentResolvers in authz.go, or the cross-org check
  silently skips it.

Ein Agent, der das liest, spart sich den Nachmittag, den der vorherige Agent verloren hat. Gut. Jetzt lass die Zeile sechs Monate altern. Derselbe Satz, im selben selbstsicheren Ton, ausgeliefert an einen Agenten, der an einer Datei arbeitet, die zwei Leute in der Zwischenzeit neu geschrieben haben. An der Zeile sieht nichts anders aus. Der Agent hat keine Möglichkeit, das zu erkennen, und du auch nicht.

Das ist das eigentliche Problem mit Memory für Coding-Agenten, und es ist nicht der Teil, den die meisten Tools bauen. Dinge aufzuschreiben ist die leichte Hälfte.

Warum ein Haufen Notizen die Frage nicht beantworten kann

Die üblichen Formen von Agent-Memory sind heute eine Markdown-Datei, an die der Agent anhängt, und ein Vector Store, in den er schreibt. Beide speichern gut. Beide holen brauchbar zurück. Keins von beiden kann dir sagen, dass sich der Boden unter einer Notiz bewegt hat, denn keins von beiden weiß in irgendeinem strukturellen Sinn, worum es in der Notiz geht. Ein Vector Store weiß, dass eine Notiz nahe an den Wörtern "Gateway" und "Headers" liegt. Er weiß nicht, dass ApiGateway ein Container in deinem System ist, dass er einen Source-Pfad hat, und dass der Code an diesem Pfad seit drei Wochen nicht mehr zum dokumentierten Modell passt.

Ein Architekturmodell weiß alle drei Dinge. Das ist das ganze Argument dafür, Memory neben eins zu stellen, und es ist der einzige Teil dieses Posts, den ein anderes Produkt nicht in einem Sprint nachbauen könnte.

Memory ist jetzt in Archyl, in jedem Plan. Das hier macht es.

Eine Memory hängt an einem Element, nicht an einer Konversation

Eine Memory ist ein Fakt, typisiert als note, convention oder pitfall, angehängt an ein C4-Element oder an das Projekt als Ganzes. Agenten schreiben sie über MCP; Menschen schreiben sie im Agent Hub oder im Detail-Panel jedes Elements auf dem Diagramm.

▶ remember(projectId: …, element: "ApiGateway", kind: "pitfall",
    content: "The gateway strips custom headers longer than 8KB — payloads must go in the body.")

Es gibt eine vierte Art, session_outcome, automatisch geschrieben, wenn eine Work Session endet. Eine Session, die acht Leases gehalten hat, erzeugt eine Memory, angehängt an acht Elemente, nicht acht Kopien desselben Absatzes. Diese Form ist wichtig für die Retrieval-Seite: Ein Agent, der nach einem dieser Elemente fragt, bekommt das Ergebnis einmal, statt dieselbe Zusammenfassung acht Mal zurückzulesen, nur weil die Session zufällig acht Dinge angefasst hat.

Memory-Inhalt und -Titel sind at rest verschlüsselt, wie jede andere sensible Content-Spalte im Produkt.

Recall rankt nach Bedeutung, nicht nach gemeinsamen Substrings

recall mischt semantische Ähnlichkeit mit Term-Überlappung, gewichtet 0.55 zu 0.45. Ein Agent, der nach "Rate Limiting" fragt, bekommt die Notiz zurück, die jemand anderes über "Throttling" geschrieben hat — genau der Fall, den eine wortbasierte Suche verpasst und ein Kollege nie verpassen würde.

Die Vektoren sind bewusst Best Effort. Ohne konfigurierten AI-Provider (OpenAI-kompatibel oder Ollama) gibt es keine Vektoren, und das Scoring bleibt rein lexikalisch, so wie es sich vorher verhalten hat. Es degradiert, statt zu brechen, und das zählt, wenn du ohne Provider selbst hostest. Und Memories, die geschrieben wurden, als es keinen Provider gab, bleiben nicht für immer zweitklassig: Ein Background-Worker füllt ihre Vektoren nach, sobald einer konfiguriert ist.

Denselben Fakt zweimal zu schreiben bestätigt ihn

Etwas noch einmal zu sagen, was das Projekt schon weiß, erzeugt keine zweite Kopie. Oberhalb einer Cosine-Similarity von 0.94 bestätigt der Write stattdessen die bestehende Memory, und die Response sagt deduplicated: true. Ein Agent, der noch einmal bekräftigt, was er gelernt hat, ist Evidenz, kein Rauschen.

Zwischen 0.82 und 0.94 liegt das interessante Band: nah dran, aber nicht derselbe Fakt. Die werden gespeichert, und die Beinahe-Treffer kommen in similarTo zurück, damit die schreibende Person absichtlich remember(supersedes: "Old title") aufrufen kann, statt still einer Memory zu widersprechen, die noch lebt und noch ausgeliefert wird.

Memory lernt aus der Nutzung

Jedes Recall protokolliert, welche Memories es an welche Session ausgeliefert hat. Wenn die Session endet, nennt usedMemories die, auf die sie sich tatsächlich gestützt hat.

Diese beiden Signale sind bewusst nicht gleich gewichtet. Eine Memory ausgeliefert zu bekommen ist Indizienlage. Zu sagen, dass du sie genutzt hast, ist eine Aussage. Also heben nur Zitationen den Rang einer Memory, log-skaliert und bei 1.8x gedeckelt, damit eine beliebte Memory nicht die neuere begraben kann, die sie korrigiert. Eine Memory, die an fünf Sessions ausgeliefert wurde, ohne ein einziges Mal zitiert zu werden, bekommt einen Multiplikator von 0.75 und wird als Rauschen behandelt.

Behandelt als, nicht gelöscht. Nichts in Memory wird jemals von einer Heuristik entfernt. Ignorierte Memories landen mit ihrer Impression-Zahl in einer Review-Queue, und ein Mensch entscheidet. Dasselbe Prinzip zieht sich durch das ganze Feature: korrigiert, nie gelöscht.

Eine Memory hat einen Lebenszyklus

Frische zerfällt mit einer Halbwertszeit von 45 Tagen ab dem Moment, an dem eine Memory zuletzt als wahr bekannt war — also ihrer Erstellung oder ihrer jüngsten Bestätigung. confirm_memory setzt diese Uhr zurück und erhöht den Confirmation-Count. remember(supersedes: …) ersetzt einen Fakt, der sich geändert hat: Die alte Version verlässt das Retrieval, bleibt aber in der Historie und im Graph, damit du noch sehen kannst, was das Projekt letztes Jahr geglaubt hat.

Darüber liegen Gewichte nach Art, und die haben eine Meinung: ein Pitfall zählt 3.0, eine Convention 2.0, eine schlichte Note 1.5, ein Session Outcome 1.0. Für einen Agenten, der gleich Code ändert, schlägt "das wird dich beißen" das "so ist es damals gelaufen".

Was eine Memory wirklich ungültig macht, ist Drift

Alles oben ist ordentliche Buchführung. Dieser Abschnitt ist der Grund, warum Memory in ein Architektur-Tool gehört.

Zeit ist ein schwacher Stellvertreter für Wahrheit. Eine Convention, die vor zwei Jahren darüber geschrieben wurde, wie deine Service-Grenzen funktionieren, stimmt wahrscheinlich immer noch. Eine Notiz, die letzten Monat über eine Datei geschrieben wurde, die seitdem neu geschrieben wurde, ist wahrscheinlich falsch. Der Zerfall behandelt beide gleich, weil eine Uhr alles ist, was er hat.

Was eine Memory wirklich verdächtig macht, ist, dass sich der Code hinter ihrem Element ändert. Archyl berechnet das bereits, deterministisch: Der Drift Score vergleicht das dokumentierte Modell mit dem Repository und nennt die Elemente, die nicht mehr passen. Lass ihn aus der UI laufen, aus der API, oder bei jedem Push mit der drift-score GitHub Action. Memory ist jetzt daran angeschlossen.

Wenn Drift ein Element findet, das aus dem Tritt ist, wird jede an dieses Element gehängte Memory mit dem Moment gestempelt, an dem das passiert ist. Eine Memory, die zuletzt vor diesem Stempel bestätigt wurde, beschreibt etwas, das sich seitdem unter ihr wegbewegt hat. Daraus folgen drei Dinge:

• Sie wird im Ranking herabgestuft, um einen Multiplikator von 0.6. Herabgestuft, nicht versteckt: Sie ist vielleicht das Einzige, was je jemand über dieses Element geschrieben hat, und sie zu verstecken wäre schlimmer, als sie mit einer Warnung auszuliefern.
• Sie taucht in der Review-Queue für einen Menschen auf.
• Der Agent liest eine Warnung, im Briefing, in Worten statt in Metadaten:

- **ApiGateway** [PITFALL] [VERIFY — the element drifted since this was written]
  (claude-code/sarah, 96 days ago): the gateway strips custom headers longer than 8KB.

Die Memory erneut zu bestätigen löscht das Flag, weil eine Bestätigung die Drift-Frage direkt beantwortet: Jemand hat nachgesehen, und es gilt weiterhin.

Beide Hälften dieses Mechanismus leben im selben Produkt. Das Wissen ist hier, und der Modell-gegen-Code-Vergleich, der es untergraben kann, auch. Eine Memory-Schicht, die an einen Chat-Client geschraubt ist, hat die erste Hälfte und keine Möglichkeit, an die zweite zu kommen.

Memories verlinken sich untereinander

Gib einer Memory einen Titel, und sie wird adressierbar. Jede andere Memory kann sie dann mit [[Title]] in ihrem Inhalt referenzieren, Obsidian-Stil. Dieselbe Syntax löst sich auf C4-Elemente per Name auf ([[ApiGateway]]) und auf Entscheidungen ([[ADR-17]]), und ein Link auf einen Titel, den es noch nicht gibt, bleibt pending und hängt sich von selbst an, sobald jemand diese Memory schreibt.

Die Links sind nicht nur zum Lesen da. recall folgt ihnen: Die Top-Treffer ziehen ihre verlinkten Nachbarn mit, markiert mit via, damit du siehst, was sie hergebracht hat. Ein Pitfall über das Gateway, der auf das ADR verlinkt, das erklärt, warum die Grenze existiert, kommt mit der Begründung im Gepäck.

Die Knowledge Map, und der Graph, den wir weggeworfen haben

Die erste Version des Memory-Panels war ein Node-Link-Graph. Er hat gerendert, er hat geclustert, er sah aus wie das, wovon man einen Screenshot macht. Er beantwortete "welche Memory verlinkt auf welche Memory", und das ist keine Frage, die irgendwer gestellt hat.

Was Leute wissen müssen, ist, welche Teile ihrer Architektur das Projekt versteht und über welche Teile niemand ein Wort geschrieben hat. Also haben wir ihn ersetzt. Das Panel zeigt jetzt eine Zelle pro C4-Element: was darüber bekannt ist, wie frisch dieses Wissen ist, wie viele Pitfalls dort liegen, und, für die Elemente ohne irgendetwas, eine sichtbare Lücke. Es produziert eine Schlagzeile, die dir kein Dashboard vorher gegeben hat:

3 of 19 elements documented

Dieser Satz ist auf nützliche Weise unangenehm. Der Graph war es nicht.

Was es nicht tut

Semantisches Recall braucht einen AI-Provider. Kein OpenAI-kompatibler Endpoint und kein Ollama heißt keine Vektoren, und das Ranking fällt auf Term-Überlappung zurück. Alles andere auf dieser Seite funktioniert trotzdem.

Element-Matching ist immer noch lexikalisch. Memory rankt jetzt nach Bedeutung. Der Schritt davor — find_relevant_context, das auswählt, um welche Elemente es in deiner Aufgabe geht — scort weiterhin über Wortüberlappung auf Namen, Beschreibungen, Tags und Pfaden. Eine Aufgabe über "Checkout" wird immer noch keine Component namens OrderProcessor hochspülen. Wir haben das in viele Agenten, eine Architektur als Grenze markiert, und es stimmt weiterhin.

Das Nützlichkeitssignal existiert nur, wenn Agenten zitieren, was sie genutzt haben. Der archyl-harness-Skill bringt dem Agenten bei, seine sessionId an recall zu übergeben und beim Abschluss usedMemories zu benennen. Nichts erzwingt das. Ein Agent, der ohne den Skill verbunden ist, produziert Impressions und keine Zitationen, und das liest sich identisch zu einer Memory, die niemand nützlich fand.

Memory ist projekt-scoped. Eine organisationsweite Convention muss in jedes Projekt geschrieben werden, das sie braucht. Das ist das Nächste, was wir reparieren.

Und die ehrliche Gesamteinschränkung: Memory ist gerade erst ausgeliefert. Wir haben keine Adoption-Zahlen, keinen Benchmark, und keinen Kunden, der dir erzählt, dass es ihm etwas gespart hat. Was oben steht, ist, was der Code tut, und du kannst jedes einzelne Stück davon an deinem eigenen Projekt nachprüfen.

Wo anfangen

Wenn du das Harness schon laufen hast, ist Memory bereits an. remember, recall und confirm_memory sind drei der sechzehn Tools im Coding-Profil. Claude-Code-Plugin-Version 0.8.0 ist das Stück, das einem Agenten die zwei Gewohnheiten beibringt, von denen das Ranking abhängt: Übergib deine sessionId an recall, und benenne, was du genutzt hast, wenn du fertig bist.

Das Erste, was sich lohnt, ist nicht, Memories zu schreiben. Es ist, die Knowledge Map zu öffnen und die Coverage-Zeile zu lesen. Welchen Anteil sie auch zeigt, das ist der Anteil deiner Architektur, der überlebt, wenn die Person, die sie versteht, in den Urlaub fährt. Rate die Zahl, bevor du hinsiehst, dann sieh hin.

Nimm dann das eine Element mit dem meisten Verkehr und dem wenigsten Geschriebenen, und schreib den Pitfall auf, den du einem neuen Kollegen an seinem ersten Tag erzählen würdest. Das ist die Memory, die der nächste Agent braucht, und bis das jemand tippt, wird kein noch so gutes Retrieval sie finden.

Memory ist Teil des Archyl Harness: Work Sessions, das Preflight Gate, der Guard-Hook und die Fleet console. Das Plugin, die Skills und der Guard-Hook sowie die GitHub Actions sind Open Source, und die vollständige Referenz steht im Harness-Guide. Weiterlesen: Work Sessions, viele Agenten, eine Architektur, und warum deine Agenten eine Rules-Datei haben und kein Modell.