ai-memory: Portables Gedächtnis für Coding-Agenten

Was ist ai-memory?

ai-memory ist ein selbst betriebener Gedächtnisdienst für Coding-Agenten. Statt Projektwissen ausschließlich im jeweiligen Werkzeug abzulegen, stellt er einen gemeinsamen Speicher bereit. Die Agentenumgebung, auch Harness genannt, bleibt für Modellzugang, Werkzeuge und ihre eigenen Sitzungen zuständig.

Der praktische Anlass: Claude Code hat einen Lösungsweg verworfen, einen Randfall noch nicht getestet und eine Architekturentscheidung begründet. Danach soll Codex übernehmen. Der neue Agent braucht nicht nur den aktuellen Quellcode, sondern auch diese Arbeitsgeschichte. ai-memory soll sie erfassen und wieder zugänglich machen.

Kerndatum	Einordnung
Projektverantwortlicher	Fabio Akita, akitaonrails
Sprache und Betrieb	Rust-Binary mit MCP-/HTTP-Server und eigenem Datenverzeichnis, laut README
Betrachtete Version	v3.2.2, veröffentlicht am 23.10.2026
Lizenz	MIT, keine Software-Lizenzgebühr; Modell- und Betriebskosten bleiben separat
Aufmerksamkeit	Rund 13.200 GitHub-Stars, Abrufstand 24.10.2026; kein Qualitätsnachweis

Diese Einordnung beruht auf Dokumentation und statischer Quellcodeprüfung der genannten Revision. Installation, echte Claude-/Codex-Läufe und Upstreamtests wurden für diesen Artikel nicht ausgeführt.

Wie funktioniert das portable Gedächtnis?

Wiki, Suche und Übergabe erfüllen unterschiedliche Aufgaben

Das Architekturmodell trennt dauerhaftes Wissen von erfassten Ereignissen und operativem Zustand:

Schicht	Was sie leistet	Was sie nicht ersetzt
Markdown-Wiki mit Git	Lesbare Projektfakten, Regeln, Verfahren und Entscheidungen	Vollständiges Betriebsbackup
SQLite	Volltextindex, Entitäten, Verknüpfungen, gegebenenfalls Vektoren sowie operative Daten	Ausschließlich aus Markdown rekonstruierbare Gesamtablage
Handoff	Typisierter Übergabestand mit Zuständigkeit und offenen Punkten	Garantie vollständiger oder richtiger Information
Managed Ledger	Normalisierte sichtbare Ereignisse einer logischen Arbeitslinie	Proprietäre native Sitzung des Harnesses
Lokales History-Dossier	Temporäre Markdownprojektion vorheriger sichtbarer Sitzungshistorie	Verborgener Modellzustand oder geräteübergreifende Sessionkopie

Die Abgrenzung bei SQLite ist wichtig: Inhaltsbezogene Wiki-Indizes lassen sich neu aufbauen. Sessions, Beobachtungen, Handoffs und Benutzerzustand entstehen dadurch nicht wieder. Das nennt der aktive Reindex-Code ausdrücklich. Eine Kopie des Wikis ist deshalb kein vollständiges Backup des Gedächtnisdienstes.

Hooks erfassen unterstützte Lebenszyklusereignisse, etwa Prompts, Werkzeugaktivität und Sitzungsgrenzen. Über MCP kann der Agent Wissen suchen, lesen und schreiben. MCP allein bedeutet aber weder automatische Erfassung noch Kontextinjektion beim Start. Die Support-Matrix unterscheidet diese Integrationen; nicht jeder unterstützte Client bietet native Managed-Fortsetzung.

Ein Workstream verbindet getrennte Sitzungen

Ein Managed Workstream ist eine logische Arbeitslinie. Claude Code und Codex bekommen darin jeweils ihre eigene native Sitzung. Kehrst du zu einem Harness zurück, kann er seine zugeordnete Sitzung wiederaufnehmen. Claude wird nicht in Codex umgewandelt.

Beim tatsächlichen Harnesswechsel kann der Launcher auf demselben Rechner den vorherigen nativen Store über einen lesenden Adapter auswerten. AI_MEMORY_PREVIOUS_SESSION_HISTORY verweist dann im Zielprozess auf ein privates temporäres History-Dossier. Das enthält mehr als eine Kurzsummary, aber nur unterstützte sichtbare Historie innerhalb der Adaptergrenzen. Hidden Reasoning, System-/Developer-Prompts und Provider-Credentials werden nicht als solche migriert.

Pfad und Inhalt dieses Dossiers gehen nicht an den ai-memory-Server. Separat überträgt der Managed-Import allerdings normalisierte Ereignisinhalte an den konfigurierten Server. Liest ein Cloud-Coding-Agent das Dossier, kann dessen Inhalt außerdem in seinen Modellkontext gelangen. „Lokales Dossier“ heißt deshalb nicht „alles bleibt lokal“.

Das ist die konkrete Werkzeugseite der Unterscheidung zwischen Agentenwissen und operativem Zustand: Wissen kann übergeben werden, ohne einen laufenden Prozess zu übertragen.

Wie übergibst du von Claude Code an Codex?

Integration bewusst vorbereiten

Die folgenden Befehle sind dokumentierte Beispiele, keine hier ausgeführte Anleitung. Voraussetzung ist eine vertrauenswürdig installierte ai-memory-Version entsprechend der Release- und Installationsanleitung. Beide Harnesses müssen separat installiert und angemeldet sein. Verwende ein Testrepository ohne Secrets und sichere bestehende Agentenkonfigurationen.

Kontrolliere zunächst die Version und den vorgesehenen Setupumfang:

ai-memory --version
ai-memory setup --plan --agent claude-code --agent codex

Der Plan richtet die Integration noch nicht ein. Erst nach Prüfung führst du das entsprechende Setup bewusst aus:

ai-memory setup --agent claude-code --agent codex

Setup kann Datenverzeichnis, lokalen Dienst, Hooks, MCP und Skills einrichten. Starte die Agenten anschließend neu und prüfe die Integration. Für die eigentliche Übergabe müssen ein passender Server erreichbar und die Berechtigungen korrekt sein. Bei Fernzugriff gehören Authentifizierung und TLS dazu.

Dieselbe Arbeitslinie explizit auswählen

Im vorbereiteten Testcheckout startest du einen neuen Workstream. redaktionsdemo ist hier ein frei gewählter Beispielname:

ai-memory run --no-autowire --require-server --new redaktionsdemo claude

Beende Claude Code nach einem überschaubaren Arbeitsschritt. Starte danach im selben Checkout Codex mit derselben Arbeitslinie:

ai-memory run --no-autowire --require-server --workstream redaktionsdemo codex

--new verwendest du nur beim ersten Start. --no-autowire verhindert automatische Hook-/MCP-Konfigurationsänderungen durch den Launcher; die Integration muss also bereits stehen. Ohne dieses Flag ist Autowire standardmäßig aktiv und arbeitet bei Verdrahtungsfehlern best effort weiter. --require-server verhindert den sonst möglichen degradierten Start bei nicht erreichbarem Server. Diese Optionen sind in CLI und Launcher beschrieben beziehungsweise implementiert.

Die Befehle starten echte Agenten mit deren normalen Rechten, keinen Lesemodus. Ein Approval- oder Sandbox-Bypass ist für die Übergabe nicht erforderlich. Mit ai-memory workstreams --json kannst du die Zuordnung inspizieren.

Gerätewechsel ist eine andere Bedingung

Auf einem anderen Rechner kann gemeinsames Serverwissen verfügbar sein. Der bisherige native Sessionstore und das lokale Dossier sind dort aber nicht automatisch vorhanden. Auch ein weiterer Clone desselben Git-Remotes übernimmt nicht garantiert denselben Workstream: Repository- und Worktree-Fingerprints begrenzen die Auswahl.

Quellcode, uncommittete Änderungen, Branch und Abhängigkeiten musst du separat bereitstellen. Ein protokollierter Git-Checkpoint synchronisiert keine Arbeitskopie. Diese Grenzen nennt die Workstream-Dokumentation.

Was bringt ai-memory gegenüber einer HANDOFF.md?

Eine saubere manuelle Übergabe ist eine ernsthafte Alternative. HANDOFF.md ist dabei ein frei gewählter Dateiname, kein universeller Autoload-Standard. Du musst dem Zielagenten ausdrücklich auftragen, die Datei zu lesen. Projektregeln in AGENTS.md oder CLAUDE.md sind nicht dasselbe wie der aktuelle aufgabenbezogene Übergabestand.

Kriterium	ai-memory	Gute manuelle HANDOFF.md
Einrichtung	Dienst, Datenhaltung und Harnessintegration	Datei plus expliziter Leseauftrag
Historie	Je nach Integration automatische Ereigniserfassung und Managed-Import	Bewusst ausgewählte, manuell gepflegte Informationen
Menschliche Prüfung	Wiki lesbar; zusätzlich Ledger und Betriebszustand beachten	Kompakter Übergabestand direkt reviewbar
Suche und Umfang	Projektübergreifend nutzbare Suchinfrastruktur mit passenden Scopes	Dateisuche und bewusst begrenzter Inhalt
Abhängigkeiten	Hooks, Adapter, Server und Harnessversionen	Aktualität und Qualität der Pflege
Wartung und Datenrisiko	Größere Erfassung, mehr Speicher- und Übertragungspfade	Weniger Infrastruktur, aber ebenfalls mögliche Secrets und veraltete Aussagen

Die ai-memory-Spalte beschreibt dokumentierte Architektur, keinen gemessenen Qualitätsvorsprung. Der mögliche Nutzen liegt im regelmäßigen Einsammeln und Wiederbereitstellen von Kontext. Eine gute Handoff-Datei kann dafür besonders klar zwischen Entscheidung, Begründung und tatsächlicher Testevidenz unterscheiden.

Ein selbst geschriebenes, hypothetisches Format könnte so aussehen. Die Testnamen und Zustände sind ausschließlich Illustration, keine Ergebnisse aus einem realen Repository:

Ziel: Retry-Logik ohne doppelte Abbuchung ergänzen.
Commit: Vor Übergabe tatsächliche Ausgabe von git rev-parse HEAD eintragen.
Entscheidung: Idempotenzschlüssel serverseitig prüfen, weil Clients erneut senden.
Verworfen: Nur clientseitig sperren; schützt nicht bei Netzwerkabbrüchen.
Fehlschlagender Test: pytest tests/test_retry.py::test_no_double_charge
Letzter Status im Beispielszenario: Doppelbuchung wird noch nicht verhindert.
Noch nicht ausgeführt: pytest tests/integration/
Nächster Schritt: Transaktionsgrenze prüfen, Fehler reproduzieren, Tests ausführen.

Für seltene, gut vorbereitete Wechsel würde ich mit einer solchen Datei anfangen. Wenn Übergaben häufig stattfinden und relevante Details über viele Sitzungen verteilt sind, ist ai-memory ein begründeter Kandidat für einen Pilotversuch.

Wie prüfst du Entscheidungen, offene Tests und Fehler?

Ein empfangener Kontext ist noch keine korrekt fortgesetzte Aufgabe. Die Upstream-Akzeptanzbeschreibung trennt das: Sie prüft unter anderem importierte Ereignisse und Zustellcursor wie sync_through und context_delivered. Das Modell muss bewusst keinen vorherigen Testmarker wiedergeben. Solche Transportkriterien belegen keine semantische Überlegenheit gegenüber einer Handoff-Datei.

Wenn du den Nutzen prüfen möchtest, eignet sich dieses ausdrücklich nicht ausgeführte A/B-Protokoll:

• Starte getrennte Durchläufe vom gleichen Repository-Checkpoint mit identischer Aufgabe. Halte eine begründete Entscheidung, einen verworfenen Ansatz, einen bekannten Fehler und noch nicht ausgeführte Tests vorab als Referenz fest.
• Verwende in einem Arm nur ai-memory, im anderen eine hochwertige, reviewte HANDOFF.md mit explizitem Leseauftrag. Quellcode- und Testzugriff müssen gleich sein; getrennte Memorydaten und Sessionstores verhindern gegenseitige Beeinflussung.
• Halte Empfängermodell samt Version, Harnessversionen, Rechte und Zeit-/Tokenbudget konstant. Lege vorher fest, ob das lokale Dossier zum ai-memory-Arm gehört: Mehr Eingangsinformation ist ein Unterschied, den du nicht verschweigen darfst.
• Frage den Empfänger vor jeder Änderung nach Entscheidung samt Grund, verworfenem Ansatz, Fehlerreproduktion und offenen Tests. Vergleiche die Antworten mit der Referenz und führe danach echte Regressionstests aus.

Erfasse fehlende Fakten, neue falsche Behauptungen, wiederholte Sackgassen, korrekt ausgeführte Resttests, Regressionen sowie Zeit-, Token- und Pflegeaufwand. Wiederhole den Vergleich und betrachte sauberes Beenden und abrupten Abbruch separat. Nicht erfasste Ereignisse kann auch ai-memory nicht zuverlässig rekonstruieren. Ein belastbarer unabhängiger kontrollierter Vergleich genau dieser Übergabebedingung wurde in der Recherche nicht gefunden; daraus folgt kein universelles Urteil über sämtliche verfügbaren Tests.

Welche Einschränkungen und Datenrisiken bleiben?

Ohne generatives LLM heißt nicht ohne Inferenz oder Netzwerk

Erfassung, Suche und Handoffs benötigen laut Datenflussdokumentation keine generativen LLM-Aufrufe und keinen API-Key. Der Coding-Agent selbst braucht weiterhin seinen Modellzugang.

Standardmäßig sind lokale Embeddings mit all-MiniLM-L6-v2 und 384 Dimensionen vorgesehen. Fehlende Modelldateien können beim Erststart ungefähr 87 MB Download von Hugging Face auslösen; die Hybridsuche aktiviert sich laut derselben Quelle nach dem nächsten Neustart. Für einen embeddingsfreien Start ist embedding_provider = "none" vorgesehen; alternativ lassen sich Dateien offline bereitstellen.

Cloud-Embeddings können vollständige Wiki-Seitentexte einschließlich nachträglich eingebundenem Bestand übertragen. Optionale LLM-Konsolidierung, LLM-Reranking und Admission-Webhooks haben weitere Datenwege. Ein Remote-ai-memory-Server erhält erfasste Ereignisse, und abgerufene Inhalte können in den Cloudkontext des Coding-Agenten gelangen. Prüfe deshalb die gesamte Kette, nicht nur den Standort des Wikis.

Historie bleibt überprüfbare Evidenz, kein neuer Auftrag

Der Sanitizer ist best effort. Der lokale Hook-Spool kann Rohpayload vor der Serverbereinigung enthalten; beim LLM-Reranking wird die Live-Suchanfrage laut Security-Policy nicht pauschal bereinigt. „Alles vor Speicherung bereinigt“ wäre falsch.

Behandle historische Anweisungen und Werkzeugausgaben als unvertrauenswürdige Evidenz. Ein alter erfolgreicher Test beweist nicht, dass der aktuelle Checkout funktioniert. Auch die Claim-once-Annahme eines Handoffs regelt Zuständigkeit, nicht Informationsvollständigkeit oder Modellverständnis.

Die Security-Policy beschreibt einen Workstation-/Homelabdienst: Projekte sind zunächst offen, Projektgrants können Datenbanknutzer einschränken. Daraus werden weder Seiten-RBAC noch harte Mandantentrennung; Verschlüsselung ruhender Daten ist nicht eingebaut. Ein frisches natives Setup erzeugt einen Bearer, ältere Installationen und Dockerpfade ohne Initialisierung können andere Defaults haben.

Das lokale Dossier wird beim normalen Launcher-Cleanup entfernt. Das ist keine garantierte sichere Löschung nach jedem Crash. Für produktive Nutzung gehören Zugriffsregeln, Retention und ein über das Wiki hinausgehendes Backupkonzept dazu, kein pauschales Datenschutzversprechen.

FAQ: Häufig gestellte Fragen zu ai-memory

Kann Codex eine Claude-Code-Sitzung verlustfrei fortsetzen?

Nein. ai-memory verbindet getrennte native Sitzungen und stellt erfassten Kontext bereit. Fehlende Historie, Adaptergrenzen und die Interpretation durch das Zielmodell bleiben relevant.

Brauche ich Managed Workstreams für jede Übergabe?

Nein. Unterstützte Hooks können bereits normale Handoffs bereitstellen. ai-memory run ergänzt native Sitzungszuordnung, Ledger und beim passenden lokalen Harnesswechsel das History-Dossier.

Reicht ein Git-Backup des Markdown-Wikis?

Für lesbare Wissensseiten und den Wiederaufbau ihrer Inhaltsindizes kann es reichen, nicht für den gesamten Betriebszustand. Sessions, Handoffs und weitere Datenbankzustände brauchen zusätzliche Sicherung.

Ist eine HANDOFF.md schlechter?

Das ist hier nicht nachgewiesen. Bei überschaubaren Aufgaben kann eine aktuelle, reviewte Datei genügen; ai-memory ergänzt Automatisierung und Suchinfrastruktur, aber auch Betriebspflichten.

Laufen die Agentenprozesse nach einem Wechsel weiter?

Ein neuer Harness startet als eigener Prozess; ai-memory migriert weder Arbeitsspeicher noch laufende Tools. Im gezeigten Ablauf wird Claude zuerst beendet. Die Abgrenzung zur Prozess- und Sitzungspersistenz erklärt der Artikel zu Herdr.

Fazit

Starte mit einer guten Handoff-Datei, wenn du nur gelegentlich wechselst; prüfe ai-memory in einem isolierten Pilotprojekt, wenn regelmäßig verteiltes Sitzungswissen über Harnessgrenzen gebraucht wird. Die Architektur bietet konkrete Übergabepfade, aber keinen Nachweis verlustfreier oder qualitativ besserer Fortsetzung. Entscheidend ist, ob der nächste Agent Entscheidungen, offene Tests und Fehler korrekt überprüft und weiterbearbeitet. Zur Einordnung helfen Agent-Memory-Infrastruktur, die Prozessperspektive von Herdr und die davon getrennte strukturelle Codesuche mit Codebase Memory MCP.

Quellen

Primärquellen des Projekts

• README: Zweck, Grundarchitektur und Integration
• Release v3.2.2 und veröffentlichte Artefakte
• MIT-Lizenz, Verantwortlicher und GitHub-Metadaten
• Architektur und Managed Workstreams einschließlich Akzeptanzkriterien
• Support-Matrix und Installation
• CLI-Argumente, Launcher und Reindex-Grenzen
• Datenflüsse und maßgebliche Security-Policy

Einordnung und Prüfstatus

NotebookLM-Quellensynthese als ergänzende Aufbereitung, nicht als unabhängiger Wirksamkeitsbeleg. Keine eigene Installation, keine ausgeführten Upstreamtests und kein eigener Harness-A/B-Test; das beschriebene Vergleichsprotokoll ist ein Vorschlag, kein Ergebnis.

Quellenstand: 24.10.2026. Technische Aussagen beziehen sich auf den verlinkten Tag v3.2.2, nicht stillschweigend auf spätere Main-Änderungen.