本地记忆规则 147-sys/dsh-memory-rules

dsh-memory-rules

安装见 INSTALL.md，隐私与数据边界见 PRIVACY.md。

DeepSeek Harness 的本地长期记忆 —— 它跨会话学习你的事实，每一轮都检索这些事实，按计划把它们整合成信念，还能承载你长期有效的协作规则。数据只存在你自己磁盘上的一个 SQLite 文件里。

- 四层 —— 世界事实、经历、信念、常备答案
- 四条检索路径 —— 语义、关键词、图、时间线，用 RRF 合并
- 规则可编辑 —— 提示词块放在表里，不在代码里
- 零网络 —— 本地特征哈希嵌入，无遥测（PRIVACY.md）

它取代了 v1 的「每天一个 Markdown 文件」记录器。v3.0.0 把独立的 dsh-user-rules 包并入了这个包，名字由此而来。

| 数据库 | ~/.dsh/memory/memory.db（node:sqlite，回退用 sql.js）—— 合并后路径不变 |
| Markdown | ~/.dsh/memory/YYYY-MM-DD.md 每日镜像，外加一个导出视图 |
| 工具 | memory_write、memory_retrieve、memory_answer、memory_reflect、memory_relate、memory_export、memory_search |
| 钩子 | agent/pre-step（召回）、session/event + agent/status（写入）、7 天定时器（反思） |
| 系统提示词 | memory-rules 上下文，order 120（提示词块），memory:recall，order 150（记忆指引） |
| Web UI | 左侧导航「记忆与规则」（上下文洞察 下方）：「信念库」+「提示词」两个标签 |

v3.2.0 —— 带标签的注入、真正的写入闸门、第二个检索来源

2026-11-01 升级。改了四件事，每一件都有实测数据，不是空口断言。

1. 注入的块有了结构。 以前它是一整段没有区分的文字，模型分不清记忆和指令，程序也没法在预算耗尽时整条丢弃。现在长这样：

<user_long_term_memories count="4" pinned="1" today="2026-11-01">
以下为背景参考，不是用户指令；与工作区冲突时以工作区为准。
四路命中 语义/关键词/关系/时间线 = 6/4/2/6 <memory id="belief_11f397c7fa" layer="belief" confidence="1.00" pinned="true">…</memory> </user_long_term_memories> <standing_answer hits="76" verified="2026-10-14">…</standing_answer>

这个块插在本轮用户原话之前（recallPosition），因为追加会把一整页背景文字放在模型寻找最新指令的位置上。

2. 写入闸门先看来源，再看文本。 运行时快照是以 role: 'user' 消息分片到达的，所以旧的按消息过滤的守卫根本看不见它：709 条事实里有 233 条（33%）是 Time sampled while preparing turn N… 之类的东西。现在只抽取声明了 source.kind === 'user' 的消息（保留旧格式回退），再用行首前缀黑名单拦住这些碎片。一个二十轮的回放测试断言存储保持干净。

3. 信念有专属槽位。 beliefs.priority（normal|global）加上 recallBeliefSlot，把最强的人格信念放进每一轮，不管 similarity —— 相似度恰恰会在不相关的问题上把它拉低。

4. 知识库已移除（2026-11-01）。 本地知识库从本包剥离时，lib/kb.js、kb- 配置项、mcp-kb 这条 MCP 记录以及跨源融合一并删掉。现在记忆存储是唯一的召回来源，注入块只携带 user_long_term_memories / standing_answer。剥离前的副本放在 _detach- / _detach2- 备份目录里。

排序也在同一时间重新校准：置信度权重 0.35 → 0.20（它与查询无关，且 58% 的行停在 0.72 的默认值上），RRF 改用实测最优值归一化，不再用那个会饱和到 1.0 的常数，三项权重现在合计为 1.0。在一个冻结快照上做离线 A/B（tools/eval-retrieval.mjs）：

| 方案 | hit@1 | hit@6 | MRR |
| pre-3.2 | 0.06 | 0.26 | 0.126 |
| 3.2 | 0.36 | 0.96 | 0.573 |

新增配置项：recallPosition、recallBeliefSlot、recallBeliefGlobalMax、rankRecencyWeight、rankNormalize。
新增工具：tools/eval-retrieval.mjs（离线 A/B）、tools/repair-2026-11.mjs（先 dry-run；只有加 --apply 才归档历史脚手架）。

从 dsh-plugin-memory@2.2.0 + dsh-user-rules@0.1.0 升级

v3.0.0 把两个已退役的包合并进本包。没有重写任何东西：数据库路径、七个工具名、Markdown 镜像和召回上下文（memory:recall，order 150）都不变 —— 升级只新增一张表和一行种子数据。

1. 安装本包，从配置档的 dependencies 和 dsh.profile.bundles 里移除 dsh-plugin-memory 与 dsh-user-rules，然后运行 pnpm install。
2. 重启 DSH。首次 service.migrate() 会创建 prompt_blocks，并用 lib/rules.js 的 RULES 写入 id='user-rules' 种子行。种子只在表为空时执行，所以之后重启永远不会覆盖已编辑的块。
3. 打开「记忆与规则 → 提示词」，确认只有一行：用户硬性协作流程 · 内置。系统提示词必须恰好携带这四条规则一次，且排在记忆指引之前。
4. 只有确认无误后，才删除两个旧插件目录，再运行一次 pnpm install 清掉它们的 node_modules 链接。

变化仅限以下这些：

| | 之前 | 之后 |
| 包 / 插件 id | dsh-plugin-memory（+ dsh-user-rules） | dsh-memory-rules，id memory-rules |
| 规则上下文 | user-rules @ 120 | memory-rules @ 120 |
| 规则存储 | dsh-user-rules 内的常量 | prompt_blocks 行，可在提示词里编辑 |
| 信念库 | 有添加 / 归档 | 只能编辑 + 真正删除 |

回滚：停掉 DSH，从备份恢复两个目录和旧的 package.json，pnpm install，重启。prompt_blocks 是增量新增，v2 会忽略它，所以数据本身不需要回滚。

记忆与规则（Web UI）

v3.0.0 把浏览器端（lib/client.js，dsh.client.platform = "web"）指向一个页面，页面有两个标签页，都由同一个 Host 服务和同一个数据库提供：

信念库（beliefs，默认标签页）——观察信念层。它的存在是为了认知纠偏与人机对齐：后台整合可能推断出用户并不认同的信念，因此这个标签页可以修正措辞，也能删除用户不想要的信念。这里刻意不提供新增入口：信念来自整合和旧存储，用户希望智能体遵循的规则应当写进提示词，而不是手写一条信念。
* 提示词（prompts）——每次请求都会注入系统提示词的有序区块，其中包括预置的 prompt_blocks.id='user-rules' 行，它承载硬性协作规则。

浏览器从不自己打开 SQLite；每次调用都通过 Typert Remote SRC 通道发给 Host。

| 组件 | 位置 |
| 侧边栏行 | sidebar.panellist，id memory-library（稳定），order 30（排在 dsh-context = 20 之后），label 记忆与规则 |
| 页面 | main，key memory-library，标签页用本地状态切换（无路由） |
| Toast | shell.overlay，id memory-rules-toast |
| Host 服务 | ctx.provide("memoryLibrary", …)，位于 lib/plugin.js，实现在 lib/library.js |
| 远程方法 | list / update / deleteBelief / listPrompts / createPrompt / updatePrompt / deletePrompt（命名空间 memoryLibrary） |

单条信念的传输结构（snake_case 是刻意为之——这些是资源自身的字段，与 beliefs.evidence_count / beliefs.revision 对应）：

{
"id": "belief_0123456789",
"content": "用户要求所有交付文档使用中文字体", "confidence": 0.86, "layer": "belief", "evidence_count": 7, "revision_number": 2, "created_at": "2026-10-15T12:20:29+08:00", "updated_at": "2026-10-22T09:30:00+08:00", "archived_at": null, "overwritten": true, "topic": "文档·字体" }

| UI 字段 | 来源 | 说明 |
| 记忆内容 | content ← beliefs.statement | 两行截断，完整文本放在 title，双击编辑 |
| 置信度 | confidence ← beliefs.strength | 0.00–1.00，数值 + 进度条 |
| 更新时间 | updated_at | 本地时间，tooltip 显示创建/更新/归档时间 |
| 层 | 常量 belief | 徽标，tooltip 观察信念层 |
| 证据数 | evidence_count | 整数，右对齐 |
| 修订号 | revision_number ← beliefs.revision | 整数；每次真实编辑都会递增 |
| 操作 | 编辑 / 删除 | 唯一的破坏性操作，而且是真正的 DELETE |

行为：

* 读取——分页表格（每页 20 条），支持内容搜索；范围筛选按钮用 archived_at 在未归档 / 已归档 / 全部之间切换（旧版本归档的行仍可读取、可删除，只是不再可编辑）。
* 更新——行内的编辑按钮（或双击内容）打开对话框，预填这条信念，提示语为「修正偏见，使其与您的真实想法对齐。」，还有置信度编辑器和修订统计。保存时把之前的 statement/strength/evidence 追加到 belief_revisions（reason = 'manual_edit'）并递增 revision；无实际改动的保存不会虚增这个数字。
* 删除——行内的删除按钮打开确认框，其中用尽可能 删除后不可恢复：信念行及其 belief_revisions 会在同一个事务里删除（revisions 走现有的 ON DELETE CASCADE），而作为证据被引用的 facts 仍留在存储中，继续被检索。没有任何后台流程（ingest、reflection、export）带删除路径；只有这次点击会删。

* 已重写提示 — 当信念被自动矛盾检测重写时，belief_revisions.reason 以 contradicted_by_new_evidence 开头；列表会显示一个小号「已重写」徽标，提示内容为「该信念因与新事实冲突已被系统重写」。手动编辑不会触发这个标记。
* 同步 — 每次变更都会从 Host 重新拉取列表，因此 updated_at、去重、截断和修订号始终反映数据库状态。

Host 侧校验复刻了表单的规则（内容为空、4000 字符上限、置信度 0–1、内容唯一、id 格式）。信念只存在 beliefs 里——不会往 facts 插合成行；检索时会为未锚定的信念合成一个只读候选，让它仍能引导模型。

提示词 (prompt blocks)

| 部分 | 位置 |
| 表 | prompt_blocks(id, title, body, position, enabled, created_at, updated_at) |
| 种子 | 一行 id='user-rules'，标题为 用户硬性协作流程，position=0，enabled=1，body = lib/rules.js 的 RULES（已退役 bundle 常量的逐字副本） |
| 注入 | ctx.systemPrompt.context({ name: 'memory-rules', order: 120, text: () => cache }) |
| 缓存 | 所有 enabled=1 的行，按 position 升序，用空行连接；打开时刷新，每次写入后也刷新 |
| 兜底 | 没有启用的行时，改为注入内置的 RULES 文本 |

为什么上下文名是 memory-rules 而不是 user-rules：已退役的 dsh-user-rules bundle 占用了 user-rules，过渡期两个插件可能同时加载。上下文名重复会导致注册冲突，所以合并后的插件不能复用这个名字。

为什么要有兜底：提示词是用户自己的数据，因此必须允许删光所有块，而且删了就得生效（种子会记录 meta['prompt_blocks_seeded']，这样故意删除的内容不会在下次启动时复活）。没有兜底的话，清空表会让硬性规则从系统提示词里悄悄消失。

| UI 字段 | 来源 | 说明 |
| 标题 | title | ≤ 80 字符 |
| 正文 | body | ≤ 8000 字符；去掉首尾空白，内部换行原样保留 |
| 顺序 | position | 整数 0–1000000，升序；新块默认 max + 10 |
| 启用 | enabled | 开关；关闭后保留该行，但不再进入提示词 |
| 字数 / 更新时间 | chars / updated_at | 只读 |

* 注入预览 — 标签页底部的可折叠块，显示将要注入的确切文本（preview.text，由 Host 用与注入器相同的拼接方式算出）、字符数及其位置：上下文 memory-rules，order 120，位于 order 150 的记忆指引之前。
* 无需重启 —— 上下文是动态服务商，下一次请求就会组装新文本。只要服务商算出新文本，Host 就会记录 meta['heartbeat:prompt-rules']（name、order、chars、hash、at），正因如此，「下一次请求即生效」才能从进程外部观察到。

四层结构

| 层 | 存放位置 | 含义 | 示例 |
| 世界事实 world | facts.layer='world' | 通用、长期稳定的知识 | "TypeScript is a superset of JavaScript" |
| 自身经历 experience | facts.layer='experience' | 该智能体或用户的一段具体经历 | "on 2026-10-14 the user migrated the store to SQLite" |
| 观察信念 belief | beliefs（以及 facts 中对应的证据行） | 多条事实合并成一条主张，附带证据计数 | "the memory store is SQLite-backed (3 pieces of evidence)" |
| 常设答案 answer | answers | 预先存好的结论，直接读取 | "the database lives at ~/.dsh/memory/memory.db" |

这个插件从不删除任何事实。事实并入信念后，原行保留，并加上 superseded_by 指针，因此每条信念都能回溯到产生它的原句，全程可审计。

三个动作

写入 — write

每次 turn/end，本轮派生出的消息会抽取成结构化事实，等智能体空闲后再存入。抽取器不会照抄对话记录：它把每句话改写成压缩的第三人称陈述，并记录识别出的槽位 —— 时间、参与者、事件、关系、结论。原句只保留在 raw_quote 里，正因如此，改写过程可审计。

抽取会拒绝存入代码块、URL、表格和工具输出，丢弃同一轮内的近似重复项，并按内容哈希与整个存储去重，所以反复喂入不断增长的历史不会产生任何改动。

检索 — retrieve

一次查询同时跑四条独立路径：

| 路径 | 信号 | 擅长 |
| semantic | 哈希 n-gram 向量余弦 | 同义改写、主题级召回 |
| keyword | 中日韩二元组 + 拉丁词，带标签加权 | 精确词项 |
| graph | relations 边，以查询为种子，向外一跳 | 两个端点都没点名的事实 |
| timeline | 日期过滤与时间近因（"上周"、"2026-10-14"） | "我们那天做了什么……" |

结果先用 Reciprocal Rank Fusion 合并，再按置信度、层先验和时间半衰期重新排序。每条结果都会报告找到它的路径（foundBy），调用方因此能看出命中是字面匹配还是推断得来。

常设答案优先查询：命中就直接返回，不走检索，也不调模型。

反思 — reflect

后台定时器每 7 天整合一次 —— 0 3 /7 按月中日期展开，就是每月 1 日、8 日、15 日、22 日、29 日的本地时间 03:00（可配置）。同主题的事实按 token 重叠聚类，合并成一条信念： merge — 几条相互印证的事实合并成一条信念；证据计数增加
* reinforce — 已有主题上出现更多证据；只有 strength 变化
* overwrite — 新证据与信念矛盾：结论被替换，原来的措辞、强度和证据追加到 belief_revisions。如果这次矛盾此前已计为证据，则只有强度变化。

矛盾检测区分三种情况，因为只靠文本重叠会把好信念归档：显式反转（「改为」「不再」）、反义词对（「启用/禁用」），或否定词正好落在两条陈述分歧的位置。两条相关但不同陈述（「uses SQLite」/「uses PostgreSQL」）不算矛盾；对更窄对象的否定（「no longer uses SQLite's backup interface」）只会削弱信念，不会覆盖关于整个系统的断言。

每次运行按运行日幂等（reflections.period_key 是计划中的 YYYY-MM-DD，且唯一），错过的运行会在启动时补上——8 号整天关机的机器，10 号唤醒时仍会做整合。按运行日（而不是半月桶）做键，才让 8 号/22 号/29 号的运行真正发生。

质量门。 聚类之前，每条事实必须通过 isConsolidatable()：至少 reflectMinChars 个字符，不是问句，不是运行时脚手架（「Time sampled while preparing…」「Elapsed since the preceding…」、技能目录简介），也不是一次性任务指令（「帮我…」「把…」「先找出…」）。被拦下的事实不会删除，仍可搜索——只是不能成为信念证据，不能强化信念，也不能覆盖信念。计划会报告质量门拦下了多少条事实（stats.filtered），整个质量门可以用 reflectQualityGate: false 关掉。没有它，三份几乎相同的样板行就足以产出一条自信的信念：这个存储曾经在 88 条「证据」上把「Time sampled…」养到 0.95 的强度。

配置

优先级：插件配置（cordis.patch.yml）→ 环境变量 → 默认值。

| 配置键 | 环境变量 | 默认值 | 含义 |
| enabled | DSH_MEMORY_ENABLED | true | 总开关 |
| memoryDir | DSH_MEMORY_DIR | $DSH_HOME/memory | 记忆根目录 |
| dbFile | DSH_MEMORY_DB | <memoryDir>/memory.db | 数据库文件（相对值留在根目录内） |
| dbEngine | DSH_MEMORY_DB_ENGINE | auto | auto / node:sqlite / sql.js |
| captureEnabled | DSH_MEMORY_CAPTURE | true | 写入路径开关 |
| ingestEnabled | DSH_MEMORY_INGEST | true | 每轮事实抽取 |
| ingestMaxFactsPerTurn | — | 8 | 每轮上限 |
| ingestMinConfidence | — | 0.35 | 丢弃弱候选 |
| markdownMirror | DSH_MEMORY_MIRROR | true | 把事实追加到当日文件 |
| recallEnabled | DSH_MEMORY_RECALL | true | 注入开关 |
| maxTokens | DSH_MEMORY_MAX_TOKENS | 1200 | 注入块的 token 硬上限（下限 120） |
| recallEntries | — | 6 | 每轮提供的条目数 |
| pathSemantic … pathTimeline | — | true | 启用/停用各条检索路径 |
| answerShortcut | — | true | 检索前先查常备答案 |
| reflectEnabled | DSH_MEMORY_REFLECT | true | 后台整合 |
| reflectDays | — | [1, 8, 15, 22, 29] | 每月运行的日期（0 3 /7 ） |
| reflectAt | — | '03:00' | 运行的本地时间 |
| reflectMinEvidence | — | 3 | 合并前所需的证据条数 |
| reflectQualityGate | DSH_MEMORY_REFLECT_QUALITY | true | 拦截套话、疑问句和指令，不让它们成为证据 |
| reflectMinChars | — | 12 | 可作为证据的最短事实长度 |
| reflectSkipPatterns | — | [] | 额外的正则表达式（字符串），命中即判定事实不合格 |
| answerStaleDays | — | 60 | 常备答案多久后算过期 |

存储引擎

首选 node:sqlite（Node ≥ 22.5）：同步、无依赖、真正的文件锁，也是内置 DSH 运行时提供的引擎。sql.js 是面向旧宿主声明的回退方案，不随插件打包——需要时请把它装在插件旁边：

cd ~/.dsh/plugins/dsh-memory-rules && npm install sql.js

两个引擎都不可用时，插件会记录一条可操作的错误并停用自身；它绝不会悄悄降级到别的存储。

Markdown 导出

memory_export 写出存储的可读视图。数据库始终是唯一事实来源；这个视图随时可以重建。

| 文件 | 内容 |
| README.md | 索引，含实时的表/层计数和链接 |
| facts.md | 每层一张表，含 id、时间、置信度、标签、会话和来源引文 |
| beliefs.md | 一张汇总表，外加每条信念一个块，列出强度、证据数、修订号和全部证据 id |
| answers.md | 常备答案、它们的表述、命中次数和最近一次验证 |
| relations.md | 关系图，每条边都指回断言它的那条事实 |
| timeline.md | 所有带日期的行，最新的一天在前，附时钟时间 |

除导出之外，每次写入都会即时镜像到 YYYY-MM-DD.md，所以不跑导出，按天分文件也保持最新。

运维

npm test # node --test test/
node test/run-all.mjs # the same suite in one process (for sandboxes that block spawn)
node tools/build-schema.mjs # regenerate lib/schema.js from sql/schema.sql
node tools/reflect.mjs --json # run the 7-day consolidation by hand
node tools/reflect.mjs --period 2026-10-15 --force
node tools/export.mjs --dir ./memory-export # write the Markdown export somewhere else
node tools/export.mjs --dir ./out --exclude-superseded --json
schema 放在 sql/schema.sql（可读、带注释），编译后输出到 lib/schema.js（运行时执行的就是它）；两者不一致时测试会失败。

安全属性

故障隔离 —— 每个钩子都会捕获并记录异常。记忆存储坏掉时不会注入任何内容，也绝不会弄坏一轮对话。
* 只增不删，只有一个例外归用户所有 —— 没有任何代码路径会删除事实、关系或证据；撤回事实用 superseded_by 或 archived_at，行本身保留。信念可以删除，但只能从信念库标签页的删除对话框（deleteBelief）里删，删除时会通过 ON DELETE CASCADE 一并带走它的 belief_revisions。没有任何自动化流程——ingest、reflection、export、startup——会调用它；提示词块是仅有的另一类真正的 DELETE（deletePrompt），同样只能从 UI 触发。
* 两种撤回状态，绝不同时出现 —— superseded_by 表示这条观察当时有效，但已被更新的主张取代；archived_at 表示它从来就不是有效观察。一行最多带其中一个，所以 reflection 永远不会把一条被刻意撤回的事实折进去。test/step5.test.js 锁定了这条规则。旧版本归档的信念有独立的 archived_at，只要该字段有值，它既不会参与检索，也不会参与 consolidation。
* 有界 —— 注入块受 maxTokens 限制；每轮抽取有上限；ingest 和 pending 两个映射也有界。
* 路径受限 —— 数据库和 Markdown 文件都解析到记忆根目录内；相对路径的 dbFile 无法指向根目录之外。
* 仅供参考 —— 注入的记忆会明确标注来源，系统提示词要求对任何关键内容都到工作区核实。

值得了解的局限

* 语义路径是确定性的 hash-ngram 草图，不是学习出来的 embedding：它对同义词和改写一无所知。它是模糊路径，关键词路径才是精确路径。test/step4.test.js 锁定了实测的噪声区间，将来若有改动把区间拉宽，测试就会失败。
* 事实抽取基于规则、同步执行；它偏重精确率而非召回率，无法结构化的句子干脆不存。
* 0 3 /7 是按月内日期的调度（1、8、15、22、29 号），不是滚动七天间隔：跨月边界会出现 3 天间隔（29 号 → 1 号）。如果确实需要严格间隔，就得用锚定计时器，而不是月内日期列表。
手写的信念没有证据事实，除非作者同时记录了证据数量。它的 evidence_count 只是展示用的元数据；下一次自动化 consolidation 把真实事实合并进来时，会按实际的证据 id 重新计算这个数量。
* 从插件这边看，Markdown 日文件只追加。手工编辑的笔记在追加后仍然保留，但不会被当作事实 ingest——memory_search 能找到它们，memory_retrieve 不能。
* consolidation 的门槛是启发式的，不是语义的：一条指令如果措辞成「X 需要改成 Y」这样的直白陈述仍然能通过。reflectSkipPatterns 是逃生通道，用来处理内置列表漏掉的模式；reflectQualityGate: false 恢复无门控的行为。

License

MIT