@avantf/dsh-mem 0.8.1 → 0.10.0

package/README.md

@@ -1,38 +1,34 @@
 # @avantf/dsh-mem
 
-DSH（DeepSeek Harness）原生记忆插件：给 agent 一份可长期检索的**记忆**和一个**文档知识库**——
-它跨会话记得你说过的事，也能把文档收进库里按语义查回来。装上后提供 7 个模型工具、三段用法提示
-和两个主窗口标签页（记忆 / 知识）。
+DSH（DeepSeek Harness）原生记忆插件：给 agent 一份可长期检索的**记忆**——它跨会话记得你说过的事，
+也能按语义、全文、实体、标题与时间把它找回来。装上后提供 3 个模型工具、一段用法提示
+和一个主窗口标签页（记忆）。
+
+> 文档知识库不在本插件里：它已拆到独立插件 **`dsh-knowledges`**（`knowledge.db`、受管文档、`kb_*` 工具、
+> 知识页与文档转换都在那边）。本插件既不读也不删 `~/.avantf/knowledge/**`。
 
 ## 主要功能
 
-- **7 个模型工具**
-  - `mem_remember`：新增 / 改写 / 删除事实（写入后立刻做矛盾检测）
-  - `mem_recall`：混合检索（语义 + 全文 + 实体）、三元组方向问答、实体探查、多实体联合推理、矛盾查询
-  - `mem_admin`：列表 / **导出 / 导入 / 快照重建**。文件路径**只允许本次运行的数据根内**
+- **3 个模型工具**
+  - `mem_remember`：新增 / 改写 / 删除事实（写入后立刻做矛盾检测），分两层——`journal`（做了什么 /
+    聊了什么，必带 `event_date` 与短 `title`，同一事务复用同一 title）与 `note`（稳定事实 / 偏好 /
+    约定 / 坑，可带 `relations` 三元组）
+  - `mem_recall`：`search` 内容检索（先对整句做字面精确匹配，再按查询形态返回事实集合 / 关系结构 /
+    模糊检索；只给 `time` 就是纯时间召回）与 `titles` 标题检索（写 journal 前查重、标题纠错用）
+  - `mem_admin`：`list` 列举 / `contradictions` 列出未处理的矛盾对 / **导出 / 导入 / 快照重建**。
+    文件路径**只允许本次运行的数据根内**
     （默认导出到 `<数据根>/backups/memory-YYYYMMDD-HHMMSS.json.br`，原子写，结果不含文档正文）；
     `import` 按**文件头**自动识别 SQLite（只读合并另一份 `memory.db`，报告 `mode:'db'`）与 JSON 导出文档
     （`mode:'json'`）；`restore_snapshot` 必须显式 `confirm: true`，且只接受**空 facts 表**，恢复后同一宿主
     进程立即可检索。
-  - `kb_add` / `kb_list` / `kb_remove`：新增文档（文本 / 文件 / URL，或批量导入目录，同名拒绝）、
-    列表（带出受管 `.md` 的绝对路径与切片详情）、删除；
-    **改一篇既有文档就是改那份 `.md`**（用文件工具改，索引自动跟随）
-  - `kb_query`：跨「记忆事实 + 文档切片」的统一检索，结果带来源标注，可据此引用原文
-  - 诊断、策展（pin / 归档恢复 / 反馈 / 矛盾裁决）与索引修复（重建索引、向量修复）是**操作者动作**：
-    在「记忆」「知识」页与 CLI 里可用，不占用模型工具面。
-- **记忆与知识一起检索**：对记忆事实与文档切片做统一排序，两类结果处在同一分数刻度上，
-  所以"我之前定过的约定"和"文档里怎么写的"能一次问出来。
-- **记忆是活的**：按活跃使用结算，支持有效期、遗忘、去重与修订链；同一主题的改动会被识别成
+  - 诊断、策展（pin / unpin / 归档恢复 / 矛盾裁决）与索引修复（重建索引、向量修复）是**操作者动作**：
+    在「记忆」页与 CLI 里可用，不占用模型工具面。
+- **混合检索**：语义 + 全文 + 实体三腿融合；`search` 按查询形态给出事实集合（多实体并列）、关系结构
+  （谁管理谁这类方向问句）、纯时间召回或模糊检索。
+- **记忆是活的**：按活跃使用日结算、支持遗忘、去重与修订链；同一主题的改动会被识别成
   对旧事实的**修订**而不是简单叠加，写入时顺带做矛盾检测。
-- **资料随手入库**：文本、本地文件、目录、URL 都能收；Markdown 按标题分块，PDF、`.docx`、`.xlsx`
-  等常见格式也能直接入库（转换过程有问题会明确回报，不静默丢内容）。
-- **知识可维护**：每篇文档在数据目录里留一份可编辑的 Markdown 副本，用你自己的编辑器改，
-  插件会在其后自动把改动同步回索引；删除文档只删这份副本，你原来的文件不动。
-- **两个主窗口标签页**（排在 对话 / 轨迹 之后）：**记忆**（浏览、编辑、归档恢复、反馈、矛盾裁决）
-  与**知识**（文档列表，每行可查看切片 / 编辑 / 打开目录 / 重新摄入 / 删除；另有跨库查询与入库——
-  URL / 本地文件 / 本地目录 / 粘贴文本共用一个输入）。
-- 系统提示词里只加**三段**用法提示（何时该主动记忆、何时该先查记忆、何时该先查知识库 / 怎么改一篇
-  既有文档）。
+- **一个主窗口标签页**（排在 对话 / 轨迹 之后）：**记忆**（浏览、编辑、pin/unpin、归档恢复、矛盾裁决）。
+- 系统提示词里只加**一段**用法提示（何时该主动记忆、journal 与 note 怎么分、同一事务怎么复用 title）。
 
 ## 接入 dsh
 
@@ -64,19 +60,21 @@ dsh plugin --profile <PROFILE> add @avantf/dsh-mem@<version>
 ```
 
 ```text
-把 ~/docs/cgroup-v2.pdf 收到知识库的 ops 域下。
+上周做了什么？（按事件时间召回 journal 条目）
 ```
 
 ```text
-看看知识库里关于「内存保护」的原文。
+谁负责发布流程？（关系问句直接返回关系结构）
 ```
 
 ```text
 把「每周四发布」改成「每周三发布」，并说明依据。
 ```
 
-改一篇已经入库的文档：让模型"更新这篇文档"即可；也可以用任意文件工具直接编辑那份受管
-`.md`（先用 `kb_list` 拿到路径），改完会自动同步，「知识」页的「重新摄入」是手动兜底。
+查重与改标题：写 journal 前先让模型用 `mem_recall` 的 `titles` 找候选，读到候选就 `update`、
+读不到才 `add`；标题写错时用 `update` 带 `retitle: true` 纠正一次（旧标题保留为别名，仍能检索到）。
+
+要改一篇**文档**：那是 `dsh-knowledges` 的事（`kb_*` 工具与「知识」页在那边），本插件不提供文档入口。
 
 常见维护动作（在「记忆」页或 CLI 里）：
 
@@ -87,8 +85,7 @@ dsh plugin --profile <PROFILE> add @avantf/dsh-mem@<version>
 
 ### 相关性门槛：严格 / 宽松
 
-「记忆」「知识」页的查询面板有**严格 / 宽松**选择（工具面的 `mem_recall` / `kb_query` 也接受
-`floors: 'strict' | 'loose'`）：
+「记忆」页的查询面板有**严格 / 宽松**选择（工具面的 `mem_recall` 也接受 `floors: 'strict' | 'loose'`）：
 
 - **严格**（面板默认）：只有明确够相关的才返回，所以"没有结果"是一个可信的答案。
 - **宽松**：门槛更低，用来找回边角相关的条目——仍有一条底线，不是无门槛。
@@ -97,17 +94,19 @@ dsh plugin --profile <PROFILE> add @avantf/dsh-mem@<version>
 
 ## 配置、数据与提示词
 
-- **数据目录**：默认 `~/.avantf`。记忆库、知识库（含受管文档副本）与模型缓存都在其中；
+- **数据目录**：默认 `~/.avantf`。记忆库（`memory/memory.db`）、配置与提示词文件、备份与模型缓存都在其中；
   环境变量 `AVANTF_HOME` 可以改变它。
-- **配置**：`~/.avantf/configs/` 下的三份 YAML —— `common.yaml`（公共项，缺失时按注释模板自动创建）、
-  `memory.yaml`、`knowledge.yaml`。只写你要改的项，其余取内置默认。
-- **提示词文件**：`~/.avantf/prompts/` 下的 `mem-memory-usage.md`、`mem-knowledge-usage.md`、
-  `mem-kb-edit.md`。缺失或为空时插件写入默认内容，**只在启动时读一次**，改完重启生效。
-  可以按自己的领域改写：内置默认刻意不出现任何领域名词，只给判据与两种形状——
-  - 事实型：`用户不吃香菜；订餐默认备注不要香菜。`（谁 / 什么范围 / 偏好或要求或术语是什么）
-  - 规则型：`只有「注销式回购」减少总股本，库存股回购不减少——比较 EPS 影响时要区分。`
-  - 不适合写进记忆：一次调查的过程叙述、数据表、命令与链接——依据归知识库文档，记忆里只留
-    **结论 + 位置**（路径 / 来源 / 名称）；敏感信息同理，只记存放位置，不记明文。
+- **配置**：`~/.avantf/configs/` 下的两份 YAML —— `common.yaml`（公共项，缺失时按注释模板自动创建）与
+  `memory.yaml`。只写你要改的项，其余取内置默认。寿命按**活跃使用日**表达（`trust.base_lifetime_days` 是新事实的
+  寿命，默认 **90**；`trust.max_retention_days` 是召回加强能换来的最长寿命，默认 **174**；
+  `lifecycle.purge_after_archived_days` 是归档后的回收窗口）；没有单条到期字段，也没有日历兜底。
+- **提示词文件**：`~/.avantf/prompts/` 下的 `mem-memory-usage.md`。缺失或为空时插件写入默认内容，
+  **只在启动时读一次**，改完重启生效。
+  可以按自己的领域改写：内置默认刻意不出现任何领域名词，只给判据与记忆的两层——
+  - `journal`：一项实质性工作 / 话题完成或阶段性收敛时主动记一条，必须带 `event_date` 与短 `title`；
+  - `note`：稳定的偏好 / 约定 / 坑，直接记录，规则写成「当……应……」。
+  - 不适合写进记忆：临时聊天、一次性中间状态、容易查到的内容——依据归文档（`dsh-knowledges` 的文档库），
+    记忆里只留 **结论 + 位置**（路径 / 来源 / 名称）；敏感信息同理，只记存放位置，不记明文。
 - **升级前建议先备份 `~/.avantf`**：数据库迁移是单向的，用旧版本打开新库会被明确拒绝。
 
 ## 升级 / 卸载
@@ -120,8 +119,8 @@ dsh plugin --profile <PROFILE> add @avantf/dsh-mem@<version>
 dsh plugin --profile <PROFILE> remove @avantf/dsh-mem
 ```
 
-两者都要重启 dsh 生效。卸载**不动 `~/.avantf`**：记忆库、知识库、模型缓存全部保留。DSH Desktop 在
-「插件」页上卸载。
+两者都要重启 dsh 生效。卸载**不动 `~/.avantf`**：记忆库与模型缓存全部保留（`~/.avantf/knowledge/**` 属
+`dsh-knowledges`，同样不动）。DSH Desktop 在「插件」页上卸载。
 
 ## 环境要求