agent-context-substrate

Das Substrat ist das Kapital; das Modell ist ein austauschbarer Client.

git clone https://github.com/thomaskawas/agent-context-substrate.git
cd agent-context-substrate
make setup && make demo

Anforderungen: Python 3.12+, Docker, make. make setup erstellt eine venv und installiert die Abhängigkeiten, etwa 1,4 GB, da die Demo auf CPU läuft und die CUDA-Wheels überspringt; rechnen Sie auf einer langsamen Verbindung mit ein paar Minuten. Die Datenbank bindet 127.0.0.1:5432, also stoppen Sie alles, was diesen Port bereits belegt.

Warum dies existiert

Ich baue langfristige Projekte mit KI-Agenten, und das Wiederherstellen des Kontexts zu Beginn jeder Sitzung war die Steuer, die ich am häufigsten zahlte. Dieselben Dateien hochladen, dieselben Entscheidungen erneut erklären, zusehen, wie der nützliche Teil des Fensters mit Material gefüllt wird, das das Modell bereits zweimal gesehen hatte. Ein besseres Modell würde erscheinen, und nichts davon würde übertragen. Das Problem war nie, dass der Kontext fehlte. Es war, dass der Kontext nicht adressierbar war: keine Möglichkeit, eine Frage zu stellen und nur das zurückzubekommen, was sie beantwortet, also sendet man alles und hofft. Die Lösung war, aufzuhören, Kontext als etwas zu behandeln, das man in eine Sitzung mitbringt, und anzufangen, ihn als etwas zu behandeln, das man abfragt.

Eine Referenzimplementierung eines modellunabhängigen Gedächtnis-Substrats für KI-Agenten: Das Projektgedächtnis lebt außerhalb des Modells in einem abfragbaren, versionierten Speicher, der über ein MCP-Gateway bereitgestellt wird. Tauschen Sie das Modell; behalten Sie alles. Claude heute, Gemini oder GPT morgen, dasselbe Projektgedächtnis darunter. Anstatt die Historie in jede Sitzung einzufügen, wählt der Abruf die kleine Menge an Datensätzen aus, die die aktuelle Aufgabe tatsächlich benötigt.

Dieses Repository ist eine Clean-Room-Referenzimplementierung dieses Musters, von Grund auf gegen einen synthetischen Korpus geschrieben, sodass jede Zahl auf dieser Seite aus einem sauberen Klon mit den gepinnten Abhängigkeiten reproduzierbar ist. Es ist das Muster, nicht das System, das ich für meine eigene Arbeit verwende.

Keine API-Schlüssel erforderlich: make demo läuft vollständig auf lokalen Komponenten. Die gepinnten lokalen Modelle (Name und Revision) sind das Standard-Adapterprofil, local (make warmup, automatisch von make demo ausgeführt, lädt einmalig ~180 MB vor); das hermetische, downloadfreie deterministic-Profil unterstützt die Tests und das immer aktive CI-Gate.

Related MCP server: AI Memory MCP Server

Aufbau

src/acs/adapters/base.py ist die These in Code: vier kleine Schnittstellen, hinter denen jede externe Fähigkeit sitzt. src/acs/store/ behandelt Gedächtnis als System of Record (versioniert, auditierbar, wirklich löschbar). src/acs/retrieval/ ist die Pipeline als kleine, separat testbare Stufen. eval/ ist das Gate: Änderungen werden ausgeliefert, wenn sie baseline.lock.json erreichen oder übertreffen, sonst nicht.

Die Design-Begründung liegt in docs/adr/: neun Entscheidungsprotokolle. Die meisten sind eine halbe Seite; drei sind länger, wo das Argument den Raum brauchte.

Ebenfalls in docs/: architecture.md für die Frage, warum jede Schicht existiert, threat-model.md für die adversarischen Grenzen und wo jede Verteidigung lebt, principles.md für die Regeln, aus denen der Rest folgt, und build-your-own.md für die Build-Reihenfolge, der dieses Repository gefolgt ist.

Was es demonstriert

• Ingest schreibt beide Repräsentationen in einem Durchgang: Embeddings für Ähnlichkeit, einen Entitäts-/Beziehungsgraphen für Struktur. Jedes Dokument wird eingebettet; ein Dokument, das keine Beziehung angibt, trägt keine Kanten bei.

• Retrieval ist eine vierstufige Pipeline: hybride Vektor- + Volltextsuche mit einstellbarer Mischung, Multi-Query-Fusion (RRF), Cross-Encoder-Rerank und eine entitätsverankerte Partition, bei der der Graph die neu bewertete Liste neu ordnet, sodass ein thematischer Reranker aufhört, eine Komponente mit ihrem ähnlich benannten Geschwister zu verwechseln. Abrufprofile pro Verbraucher sind Daten, kein Code.

• Governance: Abrufänderungen werden ausgeliefert, indem sie eine gesperrte Eval-Baseline erreichen oder übertreffen. Gedächtnis ist SCD2-versioniert mit Zeitreise-Lesevorgängen, Purge löscht wirklich (Vektoren eingeschlossen), und das Audit-Log verweigert Mutationen auf Datenbankebene.

• Zugriff: Ein MCP-Gateway stellt das Substrat jedem MCP-Client zur Verfügung, pro Aufrufer abgegrenzt. Eine unter Quarantäne gestellte Forschungsschleife füllt Lücken mit zitierpflichtigem Rückschreiben.

• Portabilität: Jeder Anbieter sitzt hinter einem Adapter; der Embedder ist absichtlich gepinnt.

Die Lineage-ID und die Zeitstempel stammen beide aus make history: ohne Argument listet es aktuelle Gedächtnisse mit ihren IDs; mit LINEAGE=<id> durchläuft es die Versionskette eines Gedächtnisses und gibt das Gültigkeitsfenster jeder Version aus. Diese Fenster sind ISO-Zeitstempel, sodass ein TS=, das Sie zurück einfügen, zu der Version aufgelöst wird, die Sie tatsächlich gelesen haben, und nicht zu einer, die eine Sekunde daneben liegt. IDs werden pro Klon generiert, daher werden Ihre nicht mit den hier gezeigten übereinstimmen.

make purge löscht wirklich (einschließlich Golden-Set-Zielen, wenn sie zum gelöschten Subjekt gehören), sodass eine Benchmark gegen einen gelöschten Korpus sich weigert, als unvollständig zu laufen, anstatt stillschweigend eine niedrigere Recall zu melden. make demo setzt auf einen sauberen Korpus zurück.

Jede Benchmark-Zahl auf dieser Seite stammt aus einer Ablation über einen seedeten synthetischen Korpus (corpus/generate.py), reproduzierbar aus einem sauberen Klon und in CI überwacht (das deterministische Profil bei jedem Push, das lokale Profil auf dem bench-local-Label) gegen eine gesperrte Baseline, die auch den Korpus-Digest sperrt. Lesen Sie die Deltas, nicht die Absolutwerte: recall@5 / mrr@5 auf einem synthetischen Korpus zeigen, was jede Stufe beiträgt, niemals reale Qualität. Um zu sehen, wo eine Stufe ihr Delta verdient, führen Sie .venv/bin/python eval/run_benchmark.py --by-family aus.

Die Ablation, lokales Profil

Jede Stufe bringt etwas anderes ein, was das Argument für eine Pipeline ist und nicht für einen einzigen besseren Retriever. tests/test_readme_table.py schlägt fehl, wenn diese Tabelle und eval/baseline.lock.json jemals nicht übereinstimmen, sodass die Tabelle nicht von den Zahlen abweichen kann, die das Gate durchsetzt. Das Gate ist eine Untergrenze, sodass eine Änderung, die eine Metrik verbessert, es besteht, und die Zahlen hier gelten, bis die Baseline absichtlich mit make lock-baseline neu gesperrt wird, was dann diese Tabelle fehlschlagen lässt, bis sie angepasst wird. Lokales Profil, 120 Golden-Queries, k=5, Stage-1-Merge rank, Korpus-Digest ad7bf7ca. Reproduzieren Sie mit make demo.

Was diese Zahlen unterstützen und was nicht, einschließlich der Frage, warum der Modell-Spur-Vergleich eine Grenze und keine Kurve ist, wird in docs/limitations.md dargelegt.