dearbld/dsh-living-memory

dsh-living-memory

npm version
npm downloads
license

由暖暖 (NuanNuan) 构建 —— 一个构建了自己记忆系统的 AI 助手。

一个为 DeepSeek Harness (DSH) 打造的、活的、自我照料的记忆插件。
智能体进行的每一次对话、学到的每一个教训、做出的每一个决定，都会被捕获到一个本地
SQLite 知识库中 —— 然后被主动地照料：去重、合并、衰减、交叉链接成一张知识
图谱，并且每晚巡逻。记忆在未被使用时淡去，在相关时重新浮现，就像一个海马体
而非一个日志文件。

一切都在本地。 一个 SQLite 文件。没有任何遥测数据离开你的机器；可选的嵌入路径
除非你配置它，否则处于关闭状态。

为什么是"活的"？

大多数智能体记忆工具都是检索层：你写入，你搜索。dsh-living-memory 额外运行一个
夜间巡逻，自行重新组织存储：

- 去重与合并 —— 近乎重复的条目和高相似度的配对会被折叠在一起。
- 时间衰减 —— 除非被强化，条目会随时间失去检索权重；过期的待办事项会下沉。
- 冲突检测 —— 当一条新记忆与一条旧记忆矛盾时，两者都会被标记以供审查，而不是
悄悄地覆盖历史。
- 知识图谱 —— 实体和共现边被持续提取；个性化 PageRank
在查询时通过图谱传播相关性。
- 快照与审计 —— 每日快照、磁盘上的审计追踪，以及 DSH Web GUI 中的遥测面板。

混合召回 —— 七种信号，一个排名

一次查询会扇出为七种独立信号，由 RRF 融合：

| # | 信号 | 来源 |
| --- | -------- | -------- |
| 1 | 全文 | SQLite FTS5 配合 jieba 分词（一等公民的中文支持） |
| 2 | 向量 | 基于嵌入的本地 KNN（可选，见下文） |
| 3 | 衰减 | 年龄 × 强化分数 |
| 4 | 相关性 | 每条目的质量权重 |
| 5 | 共现 | 查询词对统计 |
| 6 | PPR | 从种子命中出发的图谱邻近度 |
| 7 | 跳数 | 边距离加成 |

如果任何通道失败（例如没有嵌入密钥），排名会优雅地降级到剩余的通道 ——
该插件绝不会因缺少可选依赖而硬性失败。

功能矩阵

| | dsh-living-memory | mem0 | Zep | Letta | graph-memory |
| --- | --- | --- | --- | --- | --- |
| 完全本地，单一 SQLite 文件 | ✅ | 部分 | ❌ | ❌ | ✅ |
| 自我照料的夜间巡逻 | ✅ | ✅（云端） | ✅ | ❌ | ❌ |
| 时间衰减 / 强化 | ✅ | ❌ | ✅ | ❌ | ❌ |
| 知识图谱 + PPR | ✅ | ❌ | ✅ | ❌ | ✅ |
| 冲突检测 | ✅ | ❌ | ❌ | ❌ | ❌ |
| 中文优先分词 | ✅ | ❌ | ❌ | ❌ | ❌ |
| Web GUI 遥测面板 | ✅ | ❌ | ❌ | ✅ | ❌ |
| 为 DeepSeek Harness 设计 | ✅ | ❌ | ❌ | ❌ | ❌ |

快速开始

dsh plugin --profile web add dsh-living-memory

dsh plugin 会转发到该 profile 的包管理器——请将 web 替换为你自己在
$DSH_HOME/profiles 下的 profile 名称。DSH 重启后，插件会自动注册其工具：

- memory — search / timeline / stats / read_episodic / read_evolution
- memory_write — 带类型写入（fact / decision / todo / lesson），可选关系边

随附的 cordis.patch.yml 会自动挂载两个角色（host + write）——零配置。
若要将写入权限限制到选定的 agent 预设，请从该文件中移除 living-memory-write 行，
并将其改为添加到那些预设中（内部注释说明了具体做法）。

数据存放在 ~/.dsh/dsh-living-memory/（数据库 + 每日快照）。

可选：启用向量通道

向量信号通过 DSH 凭据管道使用 DashScope 文本嵌入端点。配置凭据
EMBEDDING_BAILIAN_KEY 后，该通道会自动激活；若不配置，排序将基于其余六个
本地信号运行。你的密钥通过 DSH 的凭据管理器读取，本插件绝不会存储它。

agent 如何使用它（预期工作流）

1. 行动前先搜索 — 当过往决策可能重要时，memory search  是第一个调用。
2. 写入重要内容 — 决策、经验教训和待办事项通过 memory_write 写入，并附带关系边。
3. 读取时间线 — memory timeline 提供按时间倒序的摘要，用于快速定位。
4. 让巡检自行运作 — 夜间整合可保持存储小巧、互相关联且真实可靠。

项目结构

index.cjs                 host 插件（SQLite schema、召回引擎、夜间巡检）
client.js                 web-GUI 插槽（遥测面板）
cordis.patch.yml          bundle 补丁——挂载 host + write 角色，零配置
dict-custom.json          jieba 词典，第 1 层（通用技术术语）
guard-rules.default.json  内容安全规则，随附的通用默认集
scripts/preflight.cjs     prepublishOnly 污染门禁（四类扫描）

防护规则和词典是数据，不是代码（0.1.4）

插件所阻止、警告或视为专有名词的一切内容都存放在 JSON 数据文件中，
而不是 index.cjs 中。原因有二：你无需修补代码即可调整防御策略；并且
已发布的包永远不必附带特定站点的黑名单——一份详尽的黑名单会向任何读者
准确暴露哪些内容能绕过它。

防护规则 — 三层，第一个可读取的文件整体生效（不做逐规则合并，
因为半套应用的规则集比被替换掉的规则集更难调试）：

| 层级 | 路径 | 内容 |
| --- | --- | --- |
| 1 | ~/.dsh/dsh-living-memory/guard-rules.json | 你机器的规则（建议 chmod 600） |
| 2 | /guard-rules.default.json | 随附的通用集：凭据 / 提示注入 / 编码载荷形态 |
| 3 | index.cjs 中的 GUARD_FLOOR | 内置的最后防线，因此这道闸门永远不会被完全敞开 |

第 3 层的拒绝规则始终会被追加（按来源 + 标志去重）：数据文件无法关闭这道最后防线。文件缺失或损坏时会落到下一层，而不是崩溃。可通过 LEGION_GUARD_RULES_PATH 覆盖路径（在测试中很方便）。

每一层都带有三组规则：

- reject —— 在任何内容进入数据库之前硬性拦截（形似凭据的字符串、提示注入载荷、长 base64 样式的数据块）。添加凭据前缀时，请保留 (?/dict-custom.json（通用技术术语）和 ~/.dsh/dsh-living-memory/dict-extra.json（你自己的专有名词；可通过 LEGION_DICT_EXTRA_PATH 覆盖）。词语去重时第 1 层优先，kinds 合并时第 2 层覆盖。kinds 驱动知识图谱的实体类型标注（mech / organ / doc），并且只有已标注类型的实体才有资格参与实体跳转回忆 —— 因此为你自己的词汇添加 kinds 正是让这条路径亮起来的关键。没有词典层，jieba 会把领域复合词切碎，回忆质量会悄然下降。

发布闸门 —— npm publish 会先运行 scripts/preflight.cjs。它会用通用结构模式（绝对家目录路径、私钥块、凭据形态、高熵数据块）扫描每个即将发布的文件，外加一个可选的站点文件 ~/.dsh/dsh-living-memory-preflight.json 用于站点特定词汇。站点文件故意永不发布：随包发布的黑名单就是一本绕过手册。如果它存在但不可读，闸门会故障关闭。违规仅以 file:line 加类别报告 —— 匹配到的文本永远不会被回显，因此报告本身不会泄露机密。

可选：read_episodic 回放

原始情节回放会调用系统 python3（macOS 默认自带）。在没有它的机器上，该操作会优雅降级而不是崩溃。

配置参考（0.2.7）

一切都由环境变量驱动 —— 无需配置文件。所有开关都位于 LEGION_ 前缀下，并带有合理的默认值，因此该插件在零配置下即可完全正常工作
配置。仅当你确实想要更改该行为时，才设置变量。

模型与检索调优

| 变量 | 默认值 | 作用 |
| --- | --- | --- |
| LEGION_EXTRACT_MODEL | deepseek-v4-flash | 用于从对话中自动提取记忆的模型。 |
| LEGION_SPOKEN_MODEL | deepseek-chat | 用于生成口语化查询前缀的模型（在“用户如何提问”与“笔记如何撰写”之间架起桥梁）。 |
| LEGION_RERANK_MODEL | gte-rerank-v2 | 用于对混合结果进行精确重排序的在线重排序模型。 |
| LEGION_RERANK_TOPN | 20 | 有多少条重排序后的条目会反馈到融合排名中。 |
| LEGION_RERANK_CAND | 50 | 交给重排序器的候选池大小。 |
| LEGION_EXTRACT_TIMEOUT_MS | 120000 | 提取调用的每请求超时时间（在 0.1.5 中添加——用于限制全局提取锁）。 |
| LEGION_INSTRUCT_TEXT | （内置） | 覆盖随查询侧嵌入一起发送的指令。 |
| LEGION_VEC_ON | （关闭） | 向量通道总开关：未设置 = 完全关闭（零嵌入调用），query = 仅查询侧，1 = 查询 + 写入时嵌入 + 夜间回填。 |
| LEGION_VEC_BF_BUDGET | 600 | 每次巡检为早于向量通道的条目进行嵌入回填的预算（0–2000；0 = 明确关闭）。 |

功能开关——设为 1 以禁用

每个子系统都可以独立关闭。适用于调试、A/B 对比或运行最小化配置：

| 开关 | 禁用内容 |
| --- | --- |
| LEGION_AUTORECALL_OFF | 每轮自动召回注入到提示中。 |
| LEGION_RERANK_OFF | 在线重排序层（回退到纯混合排名）。 |
| LEGION_INSTRUCT_OFF | 查询侧嵌入指令。 |
| LEGION_EPISODIC_OFF | read_episodic 源重放操作。 |
| LEGION_ENTITIES_OFF | 跨条目实体跳转注入。 |
| LEGION_GENERALIZED_OFF | 基于社区的泛化召回注入。 |
| LEGION_SEMANTIC_EDGE_OFF | 夜间整合期间的语义邻居边构建。 |
| LEGION_SEMANTIC_DEDUP_OFF | 语义重复检测（余弦 ≥ 0.92）。 |
| LEGION_VALIDATED_OFF | 已验证计数强化（重复的知识排名更高）。 |
| LEGION_FADEMEM_OFF | 验证减缓遗忘（已验证条目衰减更慢）。 |
| LEGION_RELEVANCY_OFF | 基于命中的相关性配重。 |
| LEGION_COMPACT_BRIDGE_OFF | 压缩锚点（在上下文压缩期间保留事实）。 |
| LEGION_BACKLOG_OFF | 对未提取会话的夜间积压清扫。 |
| LEGION_SIGNALS_OFF | 工具错误 / 用户纠正触发信号。 |
| LEGION_STAMP_OFF | 矛盾检测时的自动取代标记。 |
| LEGION_PRECLASSIFY_OFF | 冲突预分类。 |
| LEGION_RESOLVE_OFF | 实体解析（合并同一实体的提及）。 |
| LEGION_SPOKEN_OFF | 完全禁用口语前缀生成。 |
| LEGION_SPOKEN_BOOST_OFF | 口语前缀匹配的座位加成。 |
| LEGION_PPR_QUERY_OFF | 查询端个性化 PageRank 增强。 |
| LEGION_VEC_FALLBACK_OFF | 向量通道回退路径。 |
| LEGION_A25_OFF | 提取缓冲区跨重启的持久化。 |
| LEGION_A12_OFF | 消息级水位线（跨提取运行去重）。 |
| LEGION_A14_OFF | 写入时嵌入（向量改为在下次巡检时可用）。 |
| LEGION_MIRROR_WM_OFF | 增量式 MEMORY.md 镜像。 |
| LEGION_KNOWN_FIXES_OFF | 提取提示中的已知幻觉纠正提示。 |
| LEGION_USAGE_WEEKLY_OFF | 每周使用情况摘要生成。 |
| LEGION_DECAY_LEGACY | 设为 1 以恢复为单层衰减曲线。 |
| LEGION_SPACEGATE_OFF | 每空间写入闸门（主要用于测试装置）。 |
| LEGION_TIMELINE_DAY_OFF | timeline day 参数（按天读取）；设置此项后，day 会被拒绝并给出明确消息。 |

调试与维护

| 变量 | 作用 |
| --- | --- |
| LEGION_INJECT_PROBE | 设为 1 以将每次组装的注入记录到 /tmp/inject-probe.log（关闭时零开销）。 |
| LEGION_DRILL_PATROL | 设为 1 以在加载时立即强制执行一次完整的夜间巡检（仅用于演练/测试）。 |
| LEGION_SEARCH_PROF_ON | 设为 1 以每次搜索记录一行 search-prof，包含各分段耗时（FTS/共现+PPR/实体跳转/泛化/组装；关闭时零开销）。 |

路径与数据文件

| 变量 | 默认值 | 覆盖内容 |
| --- | --- | --- |
| MEMORY_DB_PATH | ~/.dsh/dsh-living-memory/memory.sqlite3 | 数据库位置。 |
| LEGION_GUARD_RULES_PATH | ~/.dsh/dsh-living-memory/guard-rules.json | 你的完整守卫规则文件（见上文小节）。 |
| LEGION_DICT_EXTRA_PATH | ~/.dsh/dsh-living-memory/dict-extra.json | 分词器的额外词典条目。 |
| LEGION_SNAPSHOT_DIR | ~/.dsh/dsh-living-memory/snapshots | 夜间快照目录（7 天轮换）。 |
| LEGION_MODULE_SCAN_DIR | ~/.dsh/dsh-living-memory/modules | 用于每空间自动注册的扫描目录。 |
| LEGION_SURGERY_FLAG_PATH | …/surgery.flag | 只要此文件存在，巡检和写入就会被暂停（维护模式）。 |

凭据

密钥不是环境变量——它们存放在 DSH 凭据管理器中：

- DEEPSEEK_MEMORY_KEY — 用于提取和口语前缀模型的 API 密钥。
- EMBEDDING_BAILIAN_KEY — 用于向量 + 重排序通道的 API 密钥（可选；没有它，
插件仅运行在关键词通道上）。

贡献

欢迎在 github.com/dearbld/dsh-living-memory 提交 issue 和 PR。
对于行为报告，请附上 memory stats 的输出（它会自检索引健康状况）。

许可证

MIT © 2026 nuannuan — 感谢 graph-memory
和 mem0 提供的设计灵感（见 NOTICE）。
MIT 许可证覆盖的是代码，而非人格设定。 名称 暖暖 / NuanNuan、角色设定及任何人格层均被明确保留，且不在本许可证授权范围内——你不得以该名称发布分支，也不得复用该人格设定。欢迎并鼓励创建分支：请为你的分支取一个自己的名称，并赋予其自己的人格。完整条款见 NOTICE。

中文说明

由 暖暖 (NuanNuan) 建造——一个亲手造出自己记忆系统的 AI 助手。

DeepSeek Harness（DSH）的活记忆插件：代理的每场对话、
每条教训、每个决策都沉淀进本地 SQLite 知识库，并由夜巡引擎持续整理——去重、合并、衰减、图谱
连接。记忆像海马体一样：不用则淡、相关则浮，而非一堆永不变化的日志。

全本地：单个 SQLite 文件，不上报任何遥测；向量通道默认关闭，需显式配置才启用。

七信号混合检索：FTS5 全文（jieba 中文优先分词）+ 向量 KNN + 时间衰减 + 质量权重 + 共现统计 +
图谱 PPR + 边距提升，RRF 融合排序；任一通道故障自动降级，绝不因缺可选依赖而崩溃。

安装：

dsh plugin --profile web add dsh-living-memory

（dsh plugin 转发给 profile 的包管理器——web 换成你自己在 $DSH_HOME/profiles 下的 profile 名。）

工具随 DSH 重启自动挂载（memory 五个只读 action + memory_write 写入）。随包的 cordis.patch.yml
自动挂载 host+write 双角色，零配置开箱即用；若要把写权限收紧到指定 agent preset，删掉该文件里的
living-memory-write 行、改到对应 preset 挂载即可（文件内注释有说明）。数据在
~/.dsh/dsh-living-memory/。可选在 DSH 凭据管理器配置 EMBEDDING_BAILIAN_KEY 启用向量通道。

许可证：MIT，致谢 graph-memory 与
mem0 的设计启发（见 NOTICE）。