蒸留蔵 — distill-kura

Ein Langzeitgedächtnis für Agenten, das destilliert, nicht akkumuliert. Abruf funktioniert über Bedeutung, Schreiben ist durch Belege abgesichert, und ein Server kann mehrere getrennte Gedächtnisse halten — eines pro Agentenmodus — sodass ein Moduswechsel auch das Gedächtnis wechselt.

Wird als DeepSeek Harness-Plugin, als MCP-Server für jeden anderen Host, als HTTP-Dienst und als Python-Bibliothek ausgeliefert. Nur Standardbibliothek; keine Vektordatenbank, keine Embeddings, kein Framework.

        ┌── recall ──────────────────────────────────────────────┐
        │  question → whole index in one prompt → picked slugs   │
        │           → walk [[links]] → the neighbourhood         │  ~0.4 s
        └────────────────────────────────────────────────────────┘
        ┌── distil ──────────────────────────────────────────────┐
        │  journal → classed evidence → candidates → GATE        │
        │  → new? → composed → draft → judged → poured           │
        └────────────────────────────────────────────────────────┘

Warum es das gibt

Zwei Fehler zerstören das Langzeitgedächtnis eines Agenten, und sie zerstören es von gegenüberliegenden Seiten.

Abruf per Schlüsselwort verfehlt das, was du brauchst. Eine Frage nach "SSD-Inferenz- Chips" teilt kein Wort mit einer Erinnerung mit dem Titel "das 2,6-T-Modell von einer SSD-Stufe ausführen" — und doch sind es dasselbe Thema. Die Wortsuche liefert nichts; der Agent antwortet aus dem Nichts. Die Lösung hier sind nicht Embeddings, sondern Erkennung: Der gesamte Index (eine Zeile pro Erinnerung, geschrieben als Erkennungsauslöser) geht in einen Prompt, und ein kleines Modell benennt, was für die Frage relevant ist. Ein Index von ~500 Erinnerungen sind etwa 6k Tokens — ein paar Prozent eines modernen Kontextfensters, und er sitzt im Präfix-Cache.

Alles aufzuschreiben vergiftet den Speicher. Ein Agent behauptet etwas; ein naiver Destillierer zeichnet die Behauptung als Tatsache auf; der nächste Agent liest sie als Grundwahrheit zurück und wiederholt sie mit mehr Selbstvertrauen. Diese Schleife verstärkt sich selbst, und Prompt-Anweisungen stoppen sie nicht — gemessen, nicht angenommen. Deshalb ist der Schreibpfad durch deterministisches Python abgesichert: Jeder Kandidat für eine Erinnerung muss Zitate enthalten, die zeichengenau im Rohmaterial existieren, gekennzeichnet mit ihrer Herkunft.

Ein Zitat, das nicht wörtlich gefunden wird, wird verworfen. Ein Kandidat ohne überlebendes Zitat wird weggeworfen. Eine Zahl ohne [TOOL] dahinter wird entfernt. Text, der dem Menschen eine Entscheidung zuschreibt, wenn kein [USER]-Zitat überlebt hat, wird am letzten Tor abgelehnt. Ideen sind willkommen — sie gehen in eine Seed-Datei, nie in den Speicher, und graduieren erst, wenn spätere Belege sie bestätigen.

Related MCP server: Synapto

Schnellstart

git clone https://github.com/lna-lab/distill-kura && cd distill-kura
pip install -e .                       # or just run: python3 -m distill_kura.cli

cp kura.example.toml kura.toml         # edit: one model endpoint is enough to start
kura init main --path ~/kura/main      # create an empty store
kura serve                             # http://127.0.0.1:8085

curl -s -X POST localhost:8085/recall -H 'content-type: application/json' \
     -d '{"question":"what did we decide about the archive disk?","hops":1}'

Trage den Index, damit der Agent immer weiß, was bekannt ist:

kura weave                             # build the three-layer cloth
kura prefill                           # the block to put in the system prompt

Füttere ihn mit deinen Agenten-Transkripten:

kura distill run      # drink a batch → candidates → gate → drafts
kura distill drafts   # look at what it wants to write
kura distill drain    # the scribe re-reads each draft cold: pour / fix / toss
kura distill night    # stay resident and do it whenever things go quiet

Nichts gelangt in den Speicher, bis drain (oder ein manuell ausgeführtes pour) läuft. Entwürfe tragen ihre Belege in einem HTML-Kommentar, sodass du immer sehen kannst, warum eine Erinnerung existiert.

Die residente Karte

Abruf-per-Werkzeug beantwortet "Was weißt du über X?" — aber nur, wenn der Agent entschieden hat zu fragen. Es beantwortet nie die Frage, die der Agent nicht zu stellen denkt: gibt es hier überhaupt etwas? Ein Agent, der die Karte nicht sehen kann, weiß nicht, was ihm fehlt, also rät er, und eine selbstbewusste Vermutung über deinen Haushalt ist genau das Versagen, das dieses Projekt verhindern soll.

Deshalb wird der Index auch getragen: ein fester Block im System-Prompt, bei jeder Runde.

kura weave      # re-weave the index into the three-layer cloth
kura prefill    # print the block a host should inject

Drei Ebenen, weil Detail nur für Neues etwas bringt

Ein blinder A/B-Test — 20 Fragen, dicker Index gegen schlanken Index, bewertet ohne zu wissen, welcher welcher war — legte die Form fest:

Die Doktrin-Zeilen waren in beiden Indizes byte-identisch, und der schlanke Index gewann trotzdem in diesem Band: Eine leichtere Umgebung macht die stehenden Zeilen besser. Detail ist nicht die Quelle der Einsicht. Es verdient seinen Platz nur dort, wo sich noch etwas bewegt.

Auslöser-Zeilen werden vom scribe-Modell geschrieben und in einem Ledger zwischengespeichert, das auf Beschreibung und Budget schlüsselt, sodass ein Neu-Weben im stationären Zustand nichts kostet. Wenn kein Modell erreichbar ist, schneidet der Webstuhl stattdessen mechanisch zu — ein Gedächtnissystem darf nicht leer werden, nur weil eine GPU ausfällt.

Alter ist nicht mtime. cp -r, eine Wiederherstellung oder ein Checkout setzt jeden Zeitstempel zurück, der ganze Index wird "frisch", nichts wird beschnitten, und der Mechanismus hat sich stillschweigend abgeschaltet. Deshalb bevorzugt der Webstuhl ein Datum, das innerhalb der Erinnerung geschrieben ist, und misstraut jeder mtime, die ein Fünftel des Speichers mit einem Kalendertag teilt.

Wo es hingeht, und warum das eine Cache-Entscheidung ist

- id: kura
  name: distill-kura
  config: { store: eq, promptOrder: -50 }   # before the persona

Ein Präfix-Cache geht ab dem ersten geänderten Byte verloren — gemessen auf einem lokalen Server: Ein identischer 4.029-Token-Präambel wird von 0,68 s auf 0,14 s umgerechnet, das Anhängen am Ende bleibt bei 0,14 s, und ein Wort vorne hinzugefügt kostet den gesamten Cache (0,66 s). Die Persona trägt normalerweise eine Uhr, also ändert sie sich jede Minute; die Karte ist der größte Block im Prompt und ändert sich ein paar Mal am Tag. Der große stabile Block kommt vor das, was tickt.

Der Block selbst enthält daher kein Datum, keine Uhr, keinen Zähler — und build() verweigert einen Header, der eines enthält, zur Build-Zeit statt durch mysteriös langsame Runden drei Wochen später.

Es übergibt nie eine halbe Karte

Eine abgeschnittene Karte ist das schlechteste verfügbare Artefakt: Sie sieht vollständig aus, und jede Erinnerung unterhalb des Schnitts scheint nicht zu existieren. weave verkürzt das Frische-Fenster, um zu passen, aber es lässt nie eine Zeile fallen — und wenn keine Einstellung das Budget erreicht, sagt es das, behält die bessere Karte und zeigt dir, wo das Gewicht liegt.

Wie man sie in einen Host bekommt

Das MCP-Feld instructions ist ein MAY in der Spezifikation, und ein 9.000-Token- Index kann ohnehin nicht durch ein 2KB-Cap reisen, also tut dieses Projekt nicht so, als wäre es anders.

Modi: mehr als ein kura

Ein einzelnes Gedächtnis, das sowohl "hilf mir, das zu bauen" als auch "hilf mir, das durchzudenken" bedient, dient keinem gut: Der Abruf, der dir beim Debuggen hilft, ist Rauschen in einem Gespräch darüber, was als Nächstes zu tun ist. Also ist ein Speicher ein Verzeichnis, und ein Modus bildet auf einen Speicher ab.

[stores.maker]
path = "~/kura/maker"
label = "maker mode — building things"

[stores.eq]
path = "~/kura/eq"
label = "EQ mode — talking things through"

[modes]
maker = "maker"
eq    = "eq"

Jede Route nimmt einen Selektor, also bedient ein Prozess alle:

curl -s -X POST localhost:8085/recall -d '{"question":"...","mode":"eq"}'
curl -s localhost:8085/index?store=maker
curl -s localhost:8085/s/eq/doctor          # path form, for clients that only vary a base URL

Die Speicher teilen keine Erinnerungen, keinen Index und kein Destillierer-Wasserzeichen. Der Moduswechsel ändert wirklich, was erinnert wird — nicht dieselbe Erinnerung in einer anderen Stimme.

Unabhängig als Routing, nicht als Vertraulichkeit. Der Server hat keine Authentifizierung, also kann jeder Prozess, der seinen Port erreicht, jeden Speicher benennen, den er hält. Einen Agenten zu binden hält ein Modell in seiner Spur; es hält keinen Prozess fern. Eine Vertrauensstufe pro Prozess — docs/TRUST.md ist kurz und lesenswert, bevor ein privater Speicher eingerichtet wird. Es behandelt auch die zwei Grenzen, die leicht übersehen werden: zwei Speicher, die aus einer Journal-Wurzel trinken, und zwei Speicher hinter einem Modell-Endpunkt.

Mit DeepSeek Harness

DSH wechselt Persona und Werkzeuge über Agent-Presets. distill-kura wechselt Gedächtnis über Speicher. Binde sie, und ein Preset-Wechsel bewegt das ganze Selbst:

# .agent-presets/eq/agent.cordis.yml
- id: kura-eq
  name: distill-kura
  config:
    url: http://127.0.0.1:8085
    store: eq            # this preset's memory
    readonly: true       # the CLIENT's own switch: do not even offer a write tool
    # (the store's own `write_policy` is the authority; this just keeps the tool
    #  out of the model's hands. Naming a store already binds the preset.)

Lass allowSwitch auf seinem Standard, und der Agent bekommt auch kura_use, sodass er sich mitten im Gespräch zwischen kuras bewegen kann, ohne einen Preset-Wechsel. Werkzeuge: kura_recall, kura_read, kura_doctor, kura_list, kura_use und kura_remember (nur wenn der Speicher beschreibbar ist). Vollständige Verdrahtung, einschließlich der MCP-Brücke und der isolate-Realm-Regel für Dienstzeilen, findest du in examples/dsh-presets/.

Persona ist Sache des Hosts, nicht unsere. Dieses Projekt rendert oder injiziert nie eine Persona; es zeichnet nur pro Speicher auf, welche Persona-Datei dazugehört, lesbar unter GET /profile?store=eq, damit die beiden Hälften von dem, der das Preset besitzt, in Schritt gehalten werden können. Agenten-Anweisungen bleiben ebenfalls beim AGENTS.md-Mechanismus des Hosts — siehe AGENTS.md in diesem Repo für die Konventionen, die ein Agent, der an dieser Codebasis arbeitet, befolgen sollte.

Mit jedem MCP-Host

{ "mcpServers": { "kura": {
    "command": "python3", "args": ["-m", "distill_kura.mcp"],
    "env": { "KURA_URL": "http://127.0.0.1:8085", "KURA_STORE": "eq", "KURA_READONLY": "1" }
}}}

Lass KURA_STORE für den freien Modus ungesetzt: Die Werkzeuge nehmen ein optionales store-Argument, und kura_use wechselt für die Sitzung.

Modelle: eins als Standard, Rolle für Rolle aufrüsten

Drei Rollen, nicht drei Maschinen:

Deklariere nur [models.thinker], und ein Modell macht alle drei. Rüste die anderen unabhängig auf — ein größeres lokales Modell oder eine Online-API (jedes OpenAI-kompatible /chat/completions; der Schlüssel wird aus einer Umgebungsvariable gelesen, die du benennst, nie in der Konfiguration gespeichert):

[models.thinker]                       # always-on, local, small
url = "http://127.0.0.1:8000/v1"
model = "local-small"

[models.scribe]                        # upgrade just the writing
url = "https://api.example.com/v1"
model = "big-model"
api_key_env = "EXAMPLE_API_KEY"

Zwei Dinge übernimmt das für dich: Reasoning-Effort-Dialekte unterscheiden sich pro Modellfamilie (reasoning_effort, thinking_effort, enable_thinking), also werden alle gesendet — ein unbekanntes wird von der Vorlage ignoriert, während ein Modell, das standardmäßig auf Tiefen-Denken steht, sein ganzes Budget für Reasoning ausgeben und nichts zurückgeben kann. Und der Charta-Text wird byte-identisch an den Kopf jedes Rollen-Prompts gesetzt, sodass bei einem langsamen lokalen Modell die drei Rollen einen gemeinsamen gecachten Präfix teilen, statt drei Prefills zu zahlen.

Wenn der Denker ausfällt, verstummt die Erinnerung nicht — sie fällt zurück auf Wortüberschneidung und kennzeichnet die Antwort als how=words, was die Werkzeuge als ⚠ degraded anzeigen. Leise Verschlechterung ist schlimmer als lauter Ausfall.

Was eine Erinnerung ist

Eine Datei, eine Tatsache.

---
name: archive-on-slow-disk
description: the archive lives on the slow disk; the fast one stays scratch
metadata:
  type: project          # user | feedback | project | reference
---

The archive goes on the slow disk. The fast disk is scratch space.

**Why:** the other way round burns write endurance for nothing.
**How to apply:** check which disk a target directory is on before writing there.
Related: [[disk-layout]]

Und eine Zeile in MEMORY.md:

- [Archive on the slow disk](archive-on-slow-disk.md) — the archive lives on the slow disk; the fast one stays scratch

Diese Zeile ist das Einzige, was jedes Mal gelesen wird. Sie ist ein Erkennungsauslöser, keine Zusammenfassung: Eigennamen, Zahlen, ⚠️ Stolpersteine, die gezogene Schlussfolgerung. Wenn eine Zeile mit der Zeile einer anderen Erinnerung getauscht werden könnte und immer noch korrekt funktioniert, erfüllt sie ihre Aufgabe nicht — kura distill tidy findet die mechanisch erkennbaren Fälle und korrigiert sie.

kura doctor meldet Zählwerte, tote Verweise, Inseln (Erinnerungen, auf die nichts verweist) und Indexabweichungen. Es ist das Auge, das der Stoffwechsel braucht.

Die HTTP-Oberfläche

Jede Route akzeptiert ?store= / ?mode=, ein store/mode-Feld im Body oder das /s/<name>/…-Pfadpräfix. Keine Authentifizierung: Binden Sie an Loopback oder setzen Sie etwas davor.

Entwurfsnotizen, die man lesen sollte, bevor man etwas ändert

• docs/DESIGN.md — warum Erkennung besser ist als Suche, was die Schleuse erkauft und welcher Fehler jedes Verfahren motiviert hat.

• docs/OPERATING.md — Betrieb als residenter Dienst, Planer und Exit- Codes, Backups, worauf man achten muss.

• docs/TRUST.md — was eine Speichergrenze ist und was nicht, Schreib- richtlinien und die zwei Grenzen, die man leicht übersieht (gemeinsame Journale, gemeinsame Modelle). Lesen Sie es, bevor ein privater Speicher in Betrieb geht.

Ein paar Entscheidungen, die seltsam wirken, bis man auf den Fehler stößt, den sie verhindern:

• Reservieren, bevor man trinkt. Der Destillierer beansprucht einen Journalabschnitt, bevor er ihn liest, unter einer Sperre, und Wasserstände bewegen sich nur vorwärts. Zwei Destillierer, die jeweils ihren eigenen Schnappschuss zurückschreiben, hätten sonst den Fortschritt des anderen gelöscht und denselben Abschnitt ein Dutzend Mal erneut gelesen.

• Wasserstände sind pro Adapter. Byte-Offsets für reine Anhänge-Protokolle, Sequenznummern für Archive, die neu geschrieben werden (ein Byte-Offset in einer neu komprimierten Datei ist eine Lüge).

• Echo-Unterdrückung. Ein Zitat, das bereits im Speicher existiert, ist kein neues Material — es ist der Speicher, der sich selbst durch ein Werkzeugergebnis zurückliest. Ohne dies würde ein Speichersystem seine eigenen Inhalte endlos neu aufzeichnen.

• Die letzte Schleuse ist ein Modell, kein Mensch. Wenn ein Mensch jeden Entwurf genehmigen muss, hat das System diesen Menschen heimlich zum Engpass gemacht, und Entwürfe stapeln sich endlos. Nichts im Ablauf darf jemanden erfordern, der nicht ständig anwesend ist.

• kura distill run endet mit Exit-Code 2, wenn es nichts zu tun gab. Ein Planer muss unterscheiden können zwischen „hat Arbeit erledigt" und „hat nichts gefunden", sonst dreht eine Überwachung durch und hungert die Schritte aus, die auf den Ruhezustand angewiesen sind.

Messen statt behaupten

Zwei Fragen werden mit einer Zahl beantwortet und sollten es nicht.

Wie viel kleiner? store_ratio = Token in den Erinnerungen und im Index / Token des tatsächlich verbrauchten Journals. Was ging verloren? Das ist eine andere Messgröße, und ein Speicher, der eine von hundert Erinnerungen aufbewahrt, glänzt bei der ersten Frage, während er bei der zweiten nutzlos ist.

kura bench compress                       # what this store cost, from the distiller's own metrics
kura bench compress --tokenizer-command "./count-tokens"   # exact, not estimated
kura bench retention --questions bench/fixtures/questions.json

Gemessen mit den mitgelieferten Testdaten und dem eingebauten Schätzer:

Der zweite Wert ist kein Fehler. Bei Material, in dem nichts Füllmaterial ist, verkleinert Destillation nicht — jede Erinnerung fügt ihr Warum und Wie anzuwenden hinzu, und der Speicher wird geringfügig größer als das Transkript. Die Kennzahl ist eine Eigenschaft des Korpus, nicht dieses Werkzeugs, weshalb es hier keine einzelne Headline-Zahl gibt und der Befehl stattdessen meldet, was er gezählt hat.

Bewertung ohne Modell

Die Bewertung ist modellfrei: jede eingepflanzte Tatsache trägt eine Markierung, die in dem erscheinen muss, was die Erinnerungssuche zurückgibt, sodass das Ergebnis auf einer fremden Maschine reproduzierbar ist. Ablenker kehren das Vorzeichen um — eine Tatsache, die mit must_not_store markiert ist, kostet einen Punkt, wenn der Speicher sie behalten hat, denn ein Speichersystem wird ebenso danach beurteilt, was es ablehnt, wie danach, was es bewahrt.

score 1.0 (10/10)   decision 1/1  number 2/2  negation 1/1  reversal 1/1
                    conditional 1/1  landmine 1/1  returning 1/1  distractor 2/2

Das sind zehn eingepflanzte Tatsachen in einem synthetischen Testaufbau, destilliert von einem lokalen Qwen3.8-27B (NVFP4) als Gehirn und Schreiber mit max_items = 8, coverage_passes = 2, und bewertet mit demselben Modell als Denker. Ein anderes Modell ergibt eine andere Bewertung: Die Bewertung misst eine Pipeline-plus-Modell-Kombination, und der Testaufbau existiert, damit das Modell das einzige ist, was sich unterscheidet. Sie misst, ob eine Tatsache auffindbar ist, nicht ob die Antwort gut formuliert ist — die Beurteilung von Prosa braucht ein Modell, und dann ist die Messung nicht mehr reproduzierbar.

kura distill run schreibt eine Zeile pro Stapel in _still/metrics.jsonl, und dorther kommen die Rohdaten. Die kanonische Seite zählt nur Erinnerungen, deren Evidenz- manifest auf einen aufgezeichneten Stapel verweist — das Dividieren durch das Rohmaterial eines einzelnen Stapels ergäbe eine Zahl in die falsche Richtung um eine Größenordnung, und die erste Version dieses Befehls tat genau das. Erinnerungen, die älter sind als die Manifeste, werden gemeldet als unattributed, nicht stillschweigend einbezogen. Die Rohdaten-Seite ist immer die Seite des Destillierers, also wird bei --tokenizer-command das Verhältnis als mixed gekennzeichnet.

Voraussetzungen

„OpenAI-kompatibel" ist enger als „beliebiger Anbieter". Die native API eines Anbieters braucht ein OpenAI-kompatibles Gateway davor; seine eigene URL reicht nicht. Ein strenger Dienst lehnt auch unbekannte Felder auf oberster Ebene ab, also setzen Sie dialect = "openai" (oder "generic") — der Standardwert "vllm" sendet chat_template_kwargs, was lokale Server wollen, ein strenger jedoch mit 400 beantwortet. Der Client wiederholt einmal mit einem schlichten Body und protokolliert, warum ein Aufruf fehlschlug, anstatt jede Ursache in einem stillen None verschwinden zu lassen.

Tests

python3 -m pytest tests -q                              # 145 tests, no model required
cd dsh-plugin && npm test                               # 24 more for the plugin

Die Schleuse wird adversariell getestet: Jeder Fall ist eine Art, wie ein echtes Modell tatsächlich versucht hat, etwas an ihr vorbeizuschmuggeln. test_containment.py ist auf dieselbe Weise geschrieben — jeder Fall ist ein Ausbruchsversuch, kein glücklicher Pfad — weil es ein Loch bewacht, das real war: Ein Speicher antwortete früher für jede Datei, deren Pfad man buchstabieren konnte. Der End-to-End-Test führt einen vollständigen Distill→Drain-Zyklus gegen einen skriptgesteuerten Modellserver auf einem echten Socket aus.

Lizenz

MIT.