蒸留蔵 — distill-kura

为智能体设计的长期记忆，靠蒸馏而非累积。 回忆靠语义工作，写入由证据把关，一个服务器可以容纳 多个独立的记忆——每种智能体模式一个——因此切换模式就会切换 智能体记住的内容。

作为一个 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           │
        └────────────────────────────────────────────────────────┘

为什么存在

两个失败会毁掉智能体的长期记忆，而且它们从相反的方向摧毁它。

按关键词检索会漏掉你需要的东西。 一个关于 "SSD 推理芯片" 的问题与一条标题为 "从 SSD 层运行 2.6T 模型" 的记忆没有共享任何词——然而它们是同一个主题。单词搜索返回为空；智能体凭空回答。这里的修复方案不是嵌入，而是识别：整个索引（每个记忆一行，作为识别触发器写入）放入一个提示中，由一个小模型指出哪些与问题相关。约 500 条记忆的索引大约 6k token——只占现代上下文窗口的百分之几，而且它位于前缀缓存中。

什么都写会毒化存储。 智能体断言某事；天真的蒸馏器将断言记录为事实；下一个智能体将其作为事实读回，并以更强的信心重复。这个循环是自我强化的，提示指令无法阻止它——这是测量出来的，不是假设出来的。因此写入路径由确定性的 Python 把关：每个候选记忆必须携带在原始材料中逐字存在的引用，并标记来源。

未逐字找到的引用将被丢弃。没有幸存引用的候选记忆将被丢弃。没有 [TOOL] 支持的数字将被剥离。当没有 [USER] 引用幸存时，将决定归功于人类的文本会在最后一道关卡被拒绝。想法是受欢迎的——它们进入种子文件，永远不会进入存储，只有在后续证据确认后才能毕业。

Related MCP server: Memsolus MCP Server

快速开始

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

三层，因为细节只对近期事物有价值

一个盲测 A/B 测试——20 个问题，胖索引对比精简索引，评分时不知道哪个是哪个——确定了形态：

原则行在两个索引中逐字节相同，而精简索引仍然赢得了该区间：更轻的环绕让常驻行更有效。 细节不是洞察的来源。它只在其仍在变化的地方赢得一席之地。

触发行由 scribe 模型编写，并缓存在一个以描述和预算为键的账本中，因此稳态下的重新编织不花费任何代价。在没有模型可达时，织机改为机械裁剪——记忆系统不能因为 GPU 宕机就变成空白。

年龄不是 mtime。 cp -r、恢复或检出会重置每个时间戳，整个索引变成"新鲜"，没有内容被裁剪，机制在静默地关闭自己。因此织机更倾向于使用记忆内部写入的日期，并且不信任任何与五分之一存储共享一个日历日的 mtime。

它去哪里，以及为什么这是一个缓存决策

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

前缀缓存从第一个更改的字节开始失效——在一个本地服务器上测量：一个相同的 4,029 token 前缀从 0.68 秒重新计价到 0.14 秒，在末尾追加保持 0.14 秒，而在开头加一个词则会使整个缓存失效（0.66 秒）。角色通常携带时钟，所以它每分钟都在变化；地图是提示中最大的块，每天变化几次。大的稳定的事物放在滴答作响的事物前面。

因此该块本身不包含日期、时钟、计数器——而 build() 会在构建时拒绝包含这些内容的头部，而不是在三周后通过神秘变慢的轮次来发现问题。

它永远不会交出一半的地图

截断的地图是最糟糕的产物：它看起来完整，而截断线以下的每个记忆都像不存在一样。weave 会缩短新鲜窗口以适应，但它永远不会丢弃一行——如果没有设置能达到预算，它会说明这一点，保留更好的地图，并告诉你重量在哪里。

如何将其接入宿主

MCP instructions 字段在规范中是 MAY，而且 9,000 token 的索引无论如何也无法通过 2KB 的上限，所以这个项目不会假装不是这样。

模式：不止一个 kura

一个同时服务于"帮我构建这个"和"帮我思考这个"的记忆，两者都服务不好：帮助你调试的回忆，在关于下一步做什么的对话中就是噪音。所以存储是一个目录，模式映射到存储。

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

每条路由都接受一个选择器，所以一个进程服务所有：

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

这些存储不共享记忆、索引或蒸馏器水印。切换模式真正改变的是记住的内容——而不是用不同的声音说同样的记忆。

房间在对话之前就被选择。 模式是宿主发送的内容——一个 DSH 预设、MCP 环境中的 KURA_STORE、CLI 上的 -s——它是整个会话的家。这个项目中没有什么是读取消息并决定它属于哪个存储的；一个从构建漂移到感受的对话会留在它开始的地方，宿主可能会为下一个会话提供另一个房间。未知的选择器在门口就是一个错误，而不是悄悄回退到默认值。

一个房间，多个标签。 一条记忆恰好存在于一个存储中，并且可以携带多个描述其特征的标签（decision、landmine、emotion-carried 等）。标签是词，不是权重：没有东西按它们排序，没有东西计算它们，一个标记为 emotion-carried 的 Develop 记忆仍然是 Develop 记忆。没有命令可以将记忆移动或复制到另一个存储，模式更改只影响未来的会话。在两个房间中提出的相同主题会产生两条记忆，每条都从该房间自己的证据中蒸馏——Research 的"我们学到了什么"和 Develop 的"我们做了什么"是不同的东西，没有任何东西跨越边界去重它们。

宽阔的房间回忆起来会柔和一些。 具有固定章程的狭窄存储识别得敏锐。一个接受一切的存储——一个跟随人而不是目的的用户房间——预计会更松散，作为交换，它的理解可能会增长：一个 profile.md 放在其章程旁边，用句子写成，在章程之后阅读，从其自身记忆中起草并由人应用。五个这样的房间，连同它们的章程和配置，在 examples/rooms/ 中。

独立是路由层面的，不是机密性层面的。 服务器没有身份验证，所以任何能访问其端口的进程都可以命名它持有的任何存储。绑定一个智能体让模型留在自己的车道上；它不能阻止进程进入。每个进程一个信任级别——docs/TRUST.md 很短，在放入私有存储之前值得一读。它还涵盖了两个容易错过的边界：两个存储共用一个日志根，以及两个存储共用一个模型端点。

使用 DeepSeek Harness

DSH 通过代理预设切换角色和工具。distill-kura 通过存储切换记忆。将它们绑定在一起，一个预设更改就能改变整个自我：

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

一个依赖，以及为什么它是对等的。 该插件从 @deepseek-ai/dsh-tools 导入 defineTool。配置文件本地的第二个副本可能会破坏包的模块本地 Symbol 身份——即使在相同版本下——并导致第一个工具调用因 undefined.prepare 而失败。因此，该插件将包声明为 "*" 对等依赖，以便配置文件提供其副本而不会出现版本不匹配。过时的物理副本仍然可能需要去重；请参阅 examples/dsh-presets/ 中的安装检查。

将 allowSwitch 保留为默认值，智能体还将获得 kura_use，这样它就可以在对话中切换 kura 而无需更改预设。工具：kura_recall、kura_read、kura_doctor、kura_list、kura_use 和 kura_remember（仅当存储可写时）。完整的接线，包括 MCP 桥接和用于服务行的 isolate 领域规则，都在 examples/dsh-presets/ 中。

Persona 是宿主的事，不是我们的事。 这个项目从不渲染或注入 persona；它只按存储记录哪个 persona 文件属于它，可通过 GET /profile?store=eq 读取，这样两半可以由拥有预设的人保持同步。Agent 指令同样留在宿主的 AGENTS.md 机制中——参见本仓库中的 AGENTS.md，了解在这个代码库上工作的 agent 应遵循的约定。

配合任何 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 为会话切换。

模型：默认一个，逐角色升级

三个角色，不是三台机器：

只声明 [models.thinker]，一个模型承担全部三个角色——你对话的模型同时也是编辑，负责写入和评判你的记忆。这是默认配置，也是合理的：一个能力足够的 GPU 模型在空闲时足以胜任编辑工作，而 kura tend 会在你回来时立刻停止它（见下文"无人值守"）。

升级路径是给编辑一个独立的席位——更大的模型、在线 API，或一个完全不与 GPU 竞争的 CPU 模型，这样在你对话时维护工作可以继续进行。这个项目诞生的房子在 CPU 上运行一个 1 万亿参数的 MoE 作为编辑，速度约为每秒 3 个 token：很慢，但它从不触碰对话使用的席位，而且它五天来写下的记忆如今占了存储的三分之一。另外两个角色可以独立升级——更大的本地模型，或在线 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"

它为你处理两件事：推理强度（reasoning-effort）的方言因模型家族而异（reasoning_effort、thinking_effort、enable_thinking），所以全部都会发送——未知的会被模板忽略，而默认开启深度思考的模型可能把整个预算花在推理上却什么都不返回。而且章程文本以字节完全相同的方式放在每个角色提示词的开头，这样在慢速本地模型上，三个角色共享一个缓存前缀，而不是付出三次预填充（prefill）的代价。

慢速编辑需要前缀。 章程以字节完全相同的方式位于每次调用的开头，所以一个 3 tok/s 的 CPU 编辑每次静默只付一次预填充，而不是每份草稿付一次；在 llama.cpp 上，对循环模型不要使用 --cache-reuse 0，让服务器保持其槽位温暖（--slot-save-path）。编辑的调用是那些故意等待一小时（timeout=3600）的调用。

如果 thinker 宕机，召回不会沉默——它回退到词重叠，并将答案标记为 how=words，工具将其显示为 ⚠ degraded。安静的降级比降级更糟。

无人值守：kura tend

蒸馏器、浇注器和织机本应在安静时段运行，而决定何时是安静时段的守望者不需要模型：

kura distill catchup -s maker   # first: start from today, do not drink a year of history
kura tend -s maker              # stays resident; one process per store
kura tend -s maker --once       # one tick, for a scheduler or a test

当你把蒸馏器指向一个它从未见过的日志时，先运行一次 catchup——否则它的第一个动作就是喝掉全部历史，对于一年的日志来说，这相当于花几天模型时间重新学习存储可能已经知道的东西。它只向前移动标记，所以永远不会丢失进度。

"安静"指最新日志文件的 mtime。静默 idle_min（10）分钟后，它排空等待中的草稿（编辑冷读每一份：浇注 / 修复 / 丢弃），如果没有草稿则运行一次蒸馏；当有东西被浇注时，它重新编织一次常驻映射；每次静默整理一次索引。无事可做的轨道以退出码 2 退出，并休息 backoff_min（20）分钟，这样空日志不会空转。它统计工作——浇注、丢弃、修复、起草——从不启动。每条轨道的输出保存在 _still/tend.log 中。它还写入一个 kura doctor 读取的心跳（tending.alive），因为一个悄然死去的守望者正是守望者绝不能有的失败。

当日志发生变化时，运行中的轨道会被停止：编辑通常就是你要对话的那块 GPU。当编辑在独立席位时——CPU 模型、另一台机器——在 [distill] 下设置 yield_on_return = false，进行中的判定会被允许完成。这就是房子用 CPU 编辑运行了五天的守望者，根据它教会的教训重建；docs/OPERATING.md 中有 systemd 单元。

这个项目不提供的是：一个自主研究循环，自行阅读论文并扩展存储。房子有一个；它需要一个每个问题可以独自运行一小时的模型，而且它的结果不是门（gate）所使用意义上的证据。它留在界线属于房子的那一边。

一条记忆长什么样

一个文件，一个事实。

---
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
  tags: ["decision", "landmine"]
  evidence_manifest: sha256:…
belongs_because: this store keeps how the machine is laid out and why
keep: which disk, and the reason
may_fade: the df figures from that afternoon
---

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 中的一行：

- [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 会找出机械可检测的情况并重写它们。

metadata 下/顶部的四行是策展，不是事实：tags 是关于记忆特征的词——多个是正常的，在它们存在之前写下的记忆自然没有——三句话说明它为什么属于这个存储、什么意义必须比任何后来的精简更长久、什么细节不必保留。蒸馏器对照存储的章程提出它们；声称关于人的标签（entrusted、emotion-carried、recurred）会对照引语进行检查，检查结果记录在清单中。recurred 由蒸馏器写入一次，当人从另一个会话再次提起某个话题时——它是一个属性，不是计数器，背后没有数字。

kura doctor 报告计数、死链、孤岛（没有任何链接指向的记忆）、索引漂移、无法读取的标签行、记忆指向但已消失的清单、学习到的画像的状态，以及存储的四种单位并排的容量——记忆数、索引 token、正文 token、字节——limit 和 pressure 保持 None。它是新陈代谢需要的眼睛。书架满了会发生什么尚未决定：参见 docs/DESIGN.md §8。

HTTP 接口

任何路由都接受 ?store= / ?mode=、请求体中的 store/mode 字段，或 /s/<name>/… 路径前缀。无认证：绑定到回环地址，或在前面放点什么。

改动之前值得阅读的设计笔记

• docs/DESIGN.md — 为什么识别胜过搜索、门带来什么，以及每个机制背后的失败动机。

• docs/OPERATING.md — 常驻运行、调度器和退出码、备份、需要关注什么。

• docs/TRUST.md — 存储边界是什么、不是什么、写入策略，以及两个容易忽略的边界（共享日志、共享模型）。在加入私有存储之前阅读它。

一些看起来奇怪的决定，直到你遇到它们所防止的问题才明白：

• 先预留再饮用。 蒸馏器在读取日志之前，在锁下认领一段日志，水印只向前移动。两个蒸馏器各自写回自己的快照，抹掉了彼此的进度，并重复饮用了同一段水十几次。

• 水印是每个适配器的单位。 追加式转录用字节偏移，会被重写的归档用序列号（对重新压缩的文件使用字节偏移是谎言）。

• 回声抑制。 存储中已存在的引语不是新材料——它是存储通过工具结果读回自己。没有这个，记忆系统会永远重新发现并重新记录自己的内容。

• 最后的门是模型，不是人。 如果每份草稿都必须由人批准，系统就悄悄地把那个人变成了瓶颈，草稿会永远堆积。循环中没有任何东西可以要求一个不总是在场的人。

• kura distill run 在无事可做时以退出码 2 退出。 调度器必须能区分"做了工作"和"什么都没找到"，否则看门狗会在空队列上空转，饿死需要空闲时间的步骤。

测量它，而不是声称它

两个问题用一个数字回答，但不应如此。

小了多少？ store_ratio = 记忆和索引中的 token / 实际消耗的原始日志 token。失去了什么？ 这是另一个测量，一个只保留百分之一记忆的存储在第一个指标上得分漂亮，却毫无用处。

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

在这里测量，使用随附的测试数据和内置估算器：

第二个不是 bug。在没有填充内容的材料上，蒸馏并不会压缩——每条记忆都会加上它的为什么和如何应用，存储结果会比转录文本略大。该比率是语料库的属性，而不是这个工具的属性，这就是为什么这里没有醒目的数字，也是为什么命令会报告它统计了什么。

保留率是无模型评分的：每个植入的事实都带有一个标记，该标记必须出现在召回返回的内容中，因此该分数可以在别人的机器上复现。干扰项是反向的——如果存储保留了标记为 must_not_store 的事实，就会扣一分，因为记忆系统的评判标准既在于它保留了什么，也在于它拒绝了什么。

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

这是十个植入的事实，放在一个合成夹具中，由本地 Qwen3.8-27B（NVFP4）作为大脑和记录员进行蒸馏，使用 max_items = 8, coverage_passes = 2，并用同一个模型作为思考者进行评分。不同的模型会给出不同的分数：该分数衡量的是流水线加模型，而夹具的存在就是为了让模型成为唯一变化的变量。它衡量的是一个事实是否可找到，而不是答案读起来是否通顺——评判文字需要模型，那样基准测试就不再可复现了。

kura distill run 每批向 _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。