使用指南

memory 工具（action 清单）

action	参数	说明
`add`	`text`（必填）, `track`=user\|agent, `source`	保存记忆；重要条目自动请求审批，审批不可用时按 `approvalFallback` 降级
`query`	`text`, `mode`=hybrid\|exact\|semantic, `topK`, `minWeight`, `projectId`, `fragmentTypes`, `includeArchived`	查询；命中自动巩固（用进废退）
`update`	`fp`, `text`	编辑一条记忆（保留锁定/权重等元数据；文本变了向量置空重算；审计 UPDATE）
`remove`	`fp`	删除一条（删除前自动备份数据库，可回滚）
`restore`	`fp`	从最近备份回滚被删除的一条
`list`	`topK`	列出全部条目；与偏好冲突的行为记忆置顶并标注
`pin` / `unpin`	`fp`	锁定/解锁。锁定 = 不遗忘（防衰减/归档），不代表每轮必须执行
`dream`	`dryRun`, `resume`（默认 true）	记忆代谢：衰减/巩固/冲突/归档；支持断点续跑
`reflect`	`dryRun`	深度反思：主题聚类/趋势统计/冲突提醒/遗忘建议
`audit`	`type`, `sinceDays`, `aggregate`, `groupBy`（action\|day\|entry）	结构化审计查询/聚合统计

示例：

memory action=add track=user text="正式名「大肥鱼」，不用旧名" source="用户原话"
memory action=query text="UI 渲染宽度规则" mode=hybrid topK=10 minWeight=0.1 fragmentTypes=decision,preference
memory action=audit type="DECAY" sinceDays=7
memory action=audit aggregate=true groupBy=day

记忆类别（自动推断，写入时记录）：user_decision（用户明确决定）· user_preference（用户偏好）· fact（普通事实）· model_suggestion（模型建议）· model_inference（模型推测）。建议 ≠ 决定，模型建议永不冒充用户拍板。

memory_recall 工具

跨会话召回（「你还记得…吗」场景），与 memory query 同底，语义上专用于回忆：

memory_recall text="去年定下的版本规则"

/memory 命令族

命令	说明
`/memory list`	列出全部条目（冲突条目置顶）
`/memory query`	关键词 + 语义检索
`/memory add`	直接写入（人类发起，免审批）
`/memory edit`	编辑一条
`/memory remove`	删除一条（可回滚）
`/memory undo`	回滚被删除的一条
`/memory pin` / `unpin`	锁定 / 解锁
`/memory entries [词]`	列出条目（可带过滤词）
`/memory dream [--dry-run]`	记忆代谢
`/memory reflect [--dry-run]`	深度反思
`/memory audit [--since 7d] [--type DECAY]`	审计查询

冻结快照注入

会话启动时，插件自动把高价值记忆冻结注入 system prompt（注册即冻结，快照标记「会话冻结」）：

头部明确三层概念：本快照 = Applied Context（已注入 prompt）；Memory（存储层）与 Retrieved（查询候选）不在此列；检索到 ≠ 已采用。
注入顺序：锁定记忆（最高优先级，不参与衰减）→ 用户偏好（最高优先级，写入须尊重）→ 近期知识 → 近期行为。
与偏好冲突的行为记忆置顶并标注 [冲突]，由你裁决修改。
热区 token 预算 hotTokenLimit（默认 5000），超出时保留偏好与锁定段。

分级审批门

记忆类型	审批方式
用户偏好 / 项目决策 / 踩坑教训（`track=user` 或命中重要词）	人工审批（ask）
普通事实	自动写入（auto）
审批通道不可用（策略 never / 服务缺失）	按 `approvalFallback`：`auto` = 自动保存并审计降级标记 · `deny` = 拒绝写入（fail-closed）

记忆代谢（Dream）

相当于睡眠时大脑做的事——/memory dream 或 memory action=dream：

半衰期衰减（默认 7 天）：w × 0.5^(年龄/半衰期)，下限 1。
引用巩固：单条命中引用 ≥ consolidateThreshold（默认 3）次则 +1 权重，上限 weightCap（默认 20）。
冲突豁免：与偏好冲突的行为记忆不衰减不归档、保持活跃，在列表与快照中置顶浮出，由你人工裁决（编辑改掉冲突内容后恢复正常代谢），记 CONFLICT 事件。
低权重归档：权重低于 decayThreshold（默认 3）→ status=archived，移动不删除。

执行前自动备份数据库（保留最近 7 次，ROLLBACK 事件可溯）；每 100 条写检查点，中断后 resume=true 断点续跑；--dry-run 只预览不落盘。

深度反思（Reflect）

纯本地、无 LLM 的周期总结：主题聚类（TF 向量余弦相似度 ≥ 0.25）· 趋势统计（近 7 天 vs 上一周写入量）· 冲突提醒（行为与偏好潜在冲突清单）· 遗忘建议（低权重候选）。报告写入 longterm/reflections/.md，支持 --dry-run 预览。

知识库（管理 UI）

DSH 设置页「记忆工作台」五个 tab：

tab	功能
概览	存储统计（条目/锁定/分层/向量数/审计近 7 天）、模型状态、迁移状态、冲突与低权重速览
知识库	全文/语义搜索（exact/semantic/hybrid）、按分层筛选、权重/引用/时间/锁定状态展示；一键锁定/解锁、就地编辑、安全删除（先备份可回滚）；冲突条目置顶 + 红色徽标
代谢	一键执行 / 预览记忆代谢，展示衰减/巩固/冲突/归档结果
反思	一键执行 / 预览深度反思，报告罗列与冲突就地裁决（编辑或删除）
设置	全部配置项可视化编辑（含恢复默认）

审计

双通道：SQLite audit_log 表（结构化，五元组 t / actor / action / entry_id / detail，主通道）+ audit.log（人类可读一行摘要，向后兼容）。

事件类型：WRITE / DECAY / CONSOLIDATE / CONFLICT / ARCHIVE / RECALL / ROLLBACK / AUTO-DREAM / AUTO-REFLECT（其余辅助事件：PIN / UNPIN / UPDATE / REMOVE / RESTORE / MIGRATE / VECTORIZE / PREVIEW / REFLECT / CONFIG）。

/memory audit                      # 最近事件
/memory audit --since 7d           # 最近 7 天
/memory audit --type DECAY         # 只看 DECAY
memory action=audit type="DECAY" sinceDays=7
memory action=audit aggregate=true groupBy=action   # 聚合统计

语义检索

先关键词匹配；命中不足时用纯 JS 的 TF-IDF + cosine 补充召回（无原生模块、完全离线）。配置了本地嵌入模型（bge-small-zh-v1.5，512 维，存储于 ~/.dsh/models/）且可用时，自动升级为 hybrid 融合检索（RRF 变体）；模型缺失/加载失败自动降级为关键词检索，记忆功能不受影响。语义命中在输出中标注「语义」。

配置

key	默认值	说明
`halfLifeDays`	`7`	半衰期（天）：权重每过半衰期衰减一半
`decayThreshold`	`3`	权重低于此值 → 归档（移动，不删除）
`consolidateThreshold`	`3`	引用 ≥ 此次数 → 巩固（+1 权重）
`weightCap`	`20`	巩固权重上限（防膨胀）
`hotTokenLimit`	`5000`	快照注入热区 token 上限
`maxQueryResults`	`20`	查询返回上限
`approvalFallback`	`auto`	审批不可用时：`auto`=自动保存并审计降级 / `deny`=拒绝写入
`autoDreamDays`	`7`	启动时距上次代谢（meta `lastDreamAt`）≥ 此天数自动执行（`0`=关闭）
`autoReflectDays`	`3`	启动时距上次反思（meta `lastReflectAt`）≥ 此天数自动执行（`0`=关闭）
`preloadEmbeddings`	`false`	启动时是否预建向量索引（v0.8.0 起默认不加载嵌入模型，首次语义检索时才加载；置 `true` 或 `DSH_BIOMEMORY_PRELOAD=1` 可预热）
`nearDuplicateThreshold`	`0.7`	写入去重（v0.8.0）：与已有同类条目的中文 bigram 相似度（长度相近时取 Jaccard 与包含度的较大者）≥ 此值时按 `nearDuplicateAction` 处理（`0`=关闭。实测「换了说法的同一件事」约 0.7~0.8）
`nearDuplicateAction`	`merge`	命中近重复时：`merge`=合并进已有条目（追加 `｜【补充·日期】…` 并提权 +1，借鉴 @zheexinn/dsh-memory 的 merge-on-write）／`skip`=只提示不写（返回相似条目 fp 供 `update`）
`sinkWindowMinutes`	`5`	轮次结束后「请沉淀值得长期记住的内容」提醒的有效窗口（分钟，可配）。窗口内注入一次催促；超时丢弃（下一轮重新判断），避免隔很久再发消息时被一条过期的「上一轮请沉淀」打扰
`conflictOverlap`	`3`	冲突检测：行为与单条偏好的专有双字重叠阈值
`petEndpoint`	`null`	可选：本地桌宠通知服务 URL（默认关闭）

可在设置页「设置」tab 可视化修改，或通过 POST /biomemory/api/config 调整；持久化为 biomemory.config.json（透明可改）。

dsh-biomemory

安裝

說明文件