蒸留蔵 — distill-kura

エージェントのための長期記憶。蒸留され、蓄積されない。 想起は意味で働き、書き込みは証拠で制御され、1つのサーバーが複数の独立した記憶を保持できます — エージェントのモードごとに1つ — そのためモードを切り替えるとエージェントが覚えている内容も切り替わります。

DeepSeek Harness プラグイン、他のホスト向けのMCPサーバー、HTTPサービス、Pythonライブラリとして提供されます。標準ライブラリのみを使用し、ベクトルデータベースも埋め込みもフレームワークもありません。

        ┌── 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           │
        └────────────────────────────────────────────────────────┘

なぜこれが存在するのか

エージェントの長期記憶を殺す失敗は2つあり、それらは反対側から殺します。

キーワードによる検索は、必要なものを見逃します。 「SSD推論チップ」 についての質問は、「2.6TモデルをSSDティアから実行」 というタイトルの記憶と単語を共有しません — しかしそれらは同じ主題です。単語検索は何も返さず、エージェントはどこからともなく答えます。ここでの修正は埋め込みではなく認識です。インデックス全体（記憶ごとに1行、認識トリガーとして書かれる）が1つのプロンプトに入り、小さなモデルが質問に関係するものを指名します。約~500件の記憶のインデックスは約6kトークンで、現代のコンテキストウィンドウの数パーセントであり、プレフィックスキャッシュに置かれます。

すべてを書き込むとストアが汚染されます。 エージェントが何かを主張し、素朴な蒸留器がその主張を事実として記録し、次のエージェントがそれを真実として読み戻し、より自信を持って繰り返します。そのループは自己強化的であり、プロンプトの指示はそれを止めません — 測定され、想定されていません。したがって、書き込みパスは決定的なPythonによってゲートされます。すべての候補記憶は、生の素材に文字ごとに存在する引用を、どこから来たかのタグとともに持たなければなりません。

逐語的に見つからない引用は破棄されます。生き残った引用がない候補は捨てられます。[TOOL] が背後にない数字は削除されます。[USER] の引用が生き残らなかった場合、人間に決定を帰属させるテキストは最後のゲートで拒否されます。アイデアは歓迎されます — それらはシードファイルに行き、ストアには決して入らず、後の証拠が確認したときにのみ卒業します。

Related MCP server: Synapto

クイックスタート

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}'

インデックスを装着して、エージェントが常に何が知られているかを知るようにします：

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

エージェントのトランスクリプトをフィードします：

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

drain（または手動のpour）まで、ストアには何も入りません。ドラフトは証拠をHTMLコメントに載せているため、記憶がなぜ存在するかを常に確認できます。

常駐マップ

ツールによる想起は*「Xについて何を知っていますか？」*に答えます — しかしエージェントが尋ねることを決めた後にのみです。それはエージェントが尋ねようと思わない質問には決して答えません：ここに何かあるのか？ マップを見ることができないエージェントは、何が欠けているかを知らず、推測します。そしてあなたの家庭についての自信に満ちた推測は、まさにこのプロジェクトが防ぐために存在する失敗です。

したがって、インデックスも装着されます：システムプロンプト内の常設ブロックとして、毎ターン。

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

3つの層、詳細は最近のものにのみ報いるから

盲検A/Bテスト — 20の質問、太いインデックス対スリムなインデックス、どちらがどちらかを知らずに採点 — が形を決定しました：

教義の行は両方のインデックスでバイト単位で同一であり、スリムなインデックスがその帯域で依然として勝ちました：より軽い周囲が常設行をより良く機能させます。 詳細は洞察の源ではありません。それは物事がまだ動いている場所でのみその場所を獲得します。

トリガー行はscribeモデルによって書かれ、説明と予算をキーとする台帳にキャッシュされるため、定常状態での再織りはコストがかかりません。モデルに到達できない場合、織機は代わりに機械的にトリミングします — メモリシステムはGPUがダウンしているからといって空白になってはなりません。

年齢はmtimeではありません。 cp -r、復元、チェックアウトはすべてのタイムスタンプをリセットし、インデックス全体が「新規」になり、何もトリミングされず、メカニズムは静かにオフになります。したがって、織機は記憶の内部に書かれた日付を好み、ストアの5分の1が1暦日と共有するmtimeを信用しません。

それがどこに行くか、そしてなぜそれがキャッシュの決定であるか

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

プレフィックスキャッシュは、最初に変更されたバイトから失われます — 1つのローカルサーバーで測定：同一の4,029トークンのプリアンブルは0.68秒から0.14秒に再価格設定され、末尾への追加は0.14秒のままであり、先頭に1語追加するとキャッシュ全体がコストになります（0.66秒）。ペルソナは通常クロックを運ぶため、毎分変わります。マップはプロンプト内で最大のブロックであり、1日に数回変わります。大きく安定したものが、刻むものの前に置かれます。

したがって、ブロック自体には日付、クロック、カウンターが含まれません — そしてbuild()は、3週間後に不思議に遅いターンではなく、ビルド時にそれらを含むヘッダーを拒否します。

それは決して半分のマップを渡さない

切り詰められたマップは利用可能な最悪の成果物です：それは完全に見え、カットより下のすべての記憶は存在しないように見えます。weaveは収まるようにフレッシュウィンドウを短縮しますが、行を落とすことは決してありません — そして設定が予算に達しない場合、それを伝え、より良いマップを保持し、重みがどこにあるかを教えます。

ホストに組み込む

MCPのinstructionsフィールドは仕様ではMAYであり、9,000トークンのインデックスは2KBの上限を通過できないため、このプロジェクトはそうでないふりをしません。

モード：複数の蔵

「これを構築するのを手伝って」と「これを考え抜くのを手伝って」の両方に役立つ単一の記憶は、どちらもうまく機能しません：デバッグに役立つ想起は、次に何をするかについての会話ではノイズです。したがって、ストアはディレクトリであり、モードはストアにマッピングされます。

[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"

すべてのルートはセレクタを受け取るため、1つのプロセスがすべてにサービスを提供します：

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

ストアは記憶、インデックス、蒸留器の透かしを共有しません。モードを切り替えると、実際に記憶される内容が変わります — 同じ記憶が異なる声で語られるのではありません。

独立性はルーティングとしてであり、機密性としてではありません。 サーバーには認証がないため、そのポートに到達できるプロセスは、保持している任意のストアを指定できます。エージェントをバインドすると、モデルをレーンに保ちます。プロセスを排除するわけではありません。プロセスごとに1つの信頼レベル — docs/TRUST.mdは短く、プライベートストアを導入する前に読む価値があります。また、見逃しやすい2つの境界もカバーしています：1つのジャーナルルートから飲む2つのストア、および1つのモデルエンドポイントの背後にある2つのストア。

DeepSeek Harness を使用する場合

DSHはエージェントプリセットによってペルソナとツールを切り替えます。distill-kuraはストアによってメモリを切り替えます。それらをバインドすると、1つのプリセット変更で自己全体が移動します：

# .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.)

allowSwitchをデフォルトのままにすると、エージェントはkura_useも取得するため、プリセット変更なしで会話中に蔵を移動できます。ツール：kura_recall、kura_read、kura_doctor、kura_list、kura_use、およびkura_remember（ストアが書き込み可能な場合のみ）。MCPブリッジとサービス行のisolateレルムルールを含む完全な配線は、examples/dsh-presets/にあります。

ペルソナはホストの仕事であり、私たちの仕事ではありません。 このプロジェクトはペルソナをレンダリングしたり注入したりしません。ストアごとに、どのペルソナファイルがそれに属するかを記録するだけで、GET /profile?store=eqで読み取れるため、プリセットを所有する誰でも2つの半分を同期させることができます。エージェントの指示も同様にホストのAGENTS.mdメカニズムに留まります — このリポジトリのAGENTS.mdを参照して、このコードベースで作業するエージェントが従うべき規約を確認してください。

任意のMCPホストを使用する場合

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

フリーモードではKURA_STOREを未設定のままにします：ツールはオプションのstore引数を受け取り、kura_useがセッションを切り替えます。

モデル：デフォルトでは1つ、一度に1つのロールをアップグレード

3つのロール、3つのマシンではありません：

[models.thinker]だけを宣言すると、1つのモデルが3つすべてを実行します。他のいずれかを独立してアップグレードします — より大きなローカルモデル、またはオンラインAPI（OpenAI互換の/chat/completions；キーはあなたが指定する環境変数から読み取られ、設定に保存されることはありません）：

[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"

これがあなたのために処理する2つのこと：推論努力の方言はモデルファミリーごとに異なるため（reasoning_effort、thinking_effort、enable_thinking）、すべてが送信されます — 未知のものはテンプレートによって無視され、デフォルトで深い思考のままのモデルは、予算全体を推論に費やして何も返さない可能性があります。また、チャーターテキストはすべてのロールのプロンプトの先頭にバイト単位で同一に配置されるため、遅いローカルモデルでは、3つのロールが3つのプリフィルを支払う代わりに1つのキャッシュされたプレフィックスを共有します。

シンカーがダウンしても、リコールは沈黙しない。単語の重複にフォールバックし、答えにhow=wordsというラベルを付け、ツールはそれを⚠ degradedとして表示する。静かな劣化は、劣化よりも悪い。

メモリがどのようなものか

1ファイル、1ファクト。

---
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]]

そして、MEMORY.mdの1行：

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

その行は、毎回必ず読まれる唯一のものだ。これは認識トリガーであり、要約ではない。固有名詞、数字、⚠️ 地雷、到達した結論。ある行が別のメモリの行と入れ替わっても問題なく読めるのであれば、それは機能していないことになる。kura distill tidyは、機械的に検出可能なケースを見つけ出し、書き換える。

kura doctorは、カウント、デッドリンク、アイランド（何もリンクしていないメモリ）、インデックスのドリフトを報告する。これは代謝に必要な目である。

HTTPサーフェス

どのルートも?store= / ?mode=、ボディのstore/modeフィールド、または/s/<name>/…パスプレフィックスを受け付ける。認証はない。ループバックにバインドするか、何か別のもので保護すること。

変更を加える前に読む価値のある設計メモ

• docs/DESIGN.md — 検索よりも認識が優れている理由、ゲートがもたらすもの、各メカニズムの動機となった障害。

• docs/OPERATING.md — 常駐実行、スケジューラと終了コード、バックアップ、監視すべき点。

• docs/TRUST.md — ストア境界とは何か、何でないか、書き込みポリシー、見落としがちな2つの境界（共有ジャーナル、共有モデル）。プライベートストアを導入する前に読むこと。

一見すると奇妙に見えるが、防いでいる問題に直面するまで意味がわからない決定がいくつかある：

• 飲む前に予約する。 蒸留器は、ロックの下で、ジャーナルの範囲を読む前に確保し、ウォーターマークは常に前方にのみ進む。それぞれが自分のスナップショットを書き戻す2つの蒸留器は、お互いの進捗を消し去り、同じ水を何度も飲み直していた。

• ウォーターマークはアダプタごとの単位である。 追記専用トランスクリプトにはバイトオフセット、書き換えられるアーカイブにはシーケンス番号（再圧縮されたファイルへのバイトオフセットは嘘になる）。

• エコー抑制。 ストアに既に存在する引用は新しい素材ではない。ツールの結果を通してストアが自分自身を読み返しているだけだ。これがないと、メモリシステムは自分自身の内容を永遠に再発見し、再記録し続けることになる。

• 最後のゲートは人間ではなくモデルである。 すべての下書きを人間が承認しなければならないのであれば、その人間が静かにボトルネックになり、下書きは永遠に溜まり続ける。常に存在するとは限らない人間をループに含めてはならない。

• kura distill runは、何もすることがなかった場合、終了コード2で終了する。 スケジューラは「仕事をした」と「何も見つからなかった」を区別できなければならない。そうでなければ、ウォッチドッグが空のキューでスピンし、アイドル時間を必要とするステップを飢えさせてしまう。

主張する代わりに測定する

2つの質問が、たった1つの数字で答えられている。そうであるべきではない。

どれだけ小さくなるのか？ store_ratio = メモリとインデックスのトークン / 実際に消費された生のジャーナルのトークン。何が失われたのか？ それは別の測定である。100分の1のメモリを保持するストアは、最初の質問では見事なスコアを出すが、役に立たない。

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

同梱のフィクスチャと組み込みの推定器で、ここで測定した：

2つ目はバグではない。埋め草が何もない素材では、蒸留は圧縮にはならない。各メモリは理由と適用方法を追加し、ストアはトランスクリプトよりわずかに大きくなる。比率は、このツールではなく、コーパスの特性である。 だからこそ、ここに見出しとなる数字はなく、コマンドは何を数えたかを報告するのだ。

保持はモデルフリーでスコアリングされる。各仕込まれたファクトには、リコールが返すものに現れなければならないマーカーが付いているため、スコアは他の誰かのマシンでも再現可能である。妨害要素は反転する。must_not_storeとマークされたファクトは、ストアがそれを保持した場合、1点の減点となる。メモリシステムは、何を保持するかと同じくらい、何を拒否するかで判断されるからだ。

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

これは、合成フィクスチャに仕込まれた10個のファクトを、ローカルのQwen3.8-27B（NVFP4）をブレイン兼スクライブとしてmax_items = 8, coverage_passes = 2で蒸留し、シンカーと同じモデルでスコアリングしたものだ。異なるモデルは異なるスコアを与える。スコアはパイプラインとモデルを合わせたものを測定しており、フィクスチャはモデルだけが変わるように存在する。スコアが測定しているのは、ファクトが見つけられるかどうかであり、回答が読みやすいかどうかではない。散文を判断するにはモデルが必要になり、そうなるとベンチマークは再現可能でなくなる。

kura distill runはバッチごとに1行を_still/metrics.jsonlに書き込む。これが生の側のソースだ。正規の側は、エビデンスマニフェストが記録されたバッチを指しているメモリのみをカウントする。ストア全体を数バッチ分の生の素材で割るのは、桁違いに間違った方向の数字であり、このコマンドの最初のバージョンはまさにそれをやっていた。マニフェストより前のメモリは、黙って含めるのではなく、unattributedとして報告される。生の側は常に飲み込み時の蒸留器の見積もりなので、--tokenizer-commandを使うと比率はmixedと表示される。

これが依存するもの

「OpenAI互換」は「任意のプロバイダ」よりも狭い。 ベンダーのネイティブAPIは、その前にOpenAI互換ゲートウェイが必要だ。独自のURLでは不十分。厳格なサービスは未知のトップレベルフィールドを拒否するので、dialect = "openai"（または"generic"）を設定すること。デフォルトの"vllm"はchat_template_kwargsを送信するが、これはローカルサーバーが望むものであり、厳格なサーバーは400を返す。クライアントはプレーンなボディで一度だけ再試行し、すべての原因を静かなNoneに潰すのではなく、呼び出しが失敗した理由を記録する。

テスト

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

ゲートは敵対的にテストされている。すべてのケースは、実際のモデルが何かをこっそり通そうとした方法だ。test_containment.pyも同じように書かれている。すべてのケースは、ハッピーパスではなく、脱出の試みである。なぜなら、それは実際に存在した穴を守っているからだ。ストアは、パスがわかるファイルに対して答えていた。エンドツーエンドのテストは、実際のソケット上のスクリプト化されたモデルサーバーに対して、完全な蒸留→ドレインサイクルを実行する。

ライセンス

MIT。