@zhujunpeng12/dsh-memory-system

dsh plugin --profile web add @zhujunpeng12/dsh-memory-system

dsh-memory-system

让 DeepSeek Harness 下次还能找到你确认过的项目约定，记忆保存在可查看、可备份的本地 Markdown。

[English](README.en.md) · [首次记忆演示](#先看一次真实的本地闭环) · [安装](#接入-deepseek-harness) · [安全与限制](#安全与限制) · [贡献](CONTRIBUTING.md)




不用反复解释同一个项目决定，也不用把整个记忆库塞进每次对话：启动时读取有预算的摘要，需要历史细节时再检索，并返回来源。中文检索使用关键词与 bigram BM25，不依赖向量数据库或额外模型 API。

• 你能检查它记住了什么：源文件是普通 Markdown；召回包含文件/行号与匹配线索。
• 你决定何时保存：插件写入默认预览，实际执行需确认；治理只给候选，不自动删改。
• 纠正有记录可追：本源码版本支持显式 raw 纠正/撤销的有效视图，历史仍保留。不是自动理解所有冲突。

适合使用 DSH、主要处理中文项目资料、愿意审阅记忆的个人和小团队。不适合需要多租户权限隔离、高频多写者或语义理解保证的场景。独立 Python 检索也可用，不必安装 DSH 或 Obsidian。

版本说明：本页描述所在源码分支。源码 package.json 中的版本号不代表该版本已发布，请到 npm registry 核对实际发布版本和 latest。首次记忆演示、raw 有效视图与检索评估需使用包含相关文件的源码检出。下面的 GitHub 安装命令跟随仓库默认分支，不保证包含这些改进。

先看一次真实的本地闭环

已有本分支源码？在仓库根目录运行，需 Python 3.10+（某些系统命令为 python3）：

python vault-guard/demo_memory.py

演示使用合成中文资料和独立临时记忆库，不读取你的真实 Vault；通过独立进程写入和检索，展示：

1. 将一条合成约定实际写入临时 Markdown，再由新进程读取。演示直接授权合成数据写入，不展示宿主审批。

2. 默认召回不含 raw；显式开启 raw 后才能找到这条原始记录。

3. 写入明确的纠正后，有效视图保留新值；审计历史仍能看到新旧记录。

实际输出节选（完整记录见演示指南）：

1. 记下原始事实：演示项目的发布检查使用蓝色清单。
5. 当前有效记忆：演示项目的发布检查改为绿色清单。（旧说法已排除）
6. 历史记录：已替代 = 演示项目的发布检查使用蓝色清单。

这是本地 Python 引擎的可复现演示，不是已验证的 DSH 新会话或宿主确认弹窗录像。完整命令、实际输出与清理说明见[首次记忆演示](docs/first-memory-demo.zh-CN.md)。

你想做什么 · 入口

先确认保存和再读取是否工作 · 上面的临时库演示

在 DSH 中使用记忆工具 · 下方插件安装与验证

不装宿主，只用本地脚本 · [独立脚本与配置](#独立脚本与配置)

了解纠正、旧记录与审计的边界 · [raw 生命周期](docs/raw-lifecycle-design.md)

接入 DeepSeek Harness

文档兼容基线：DSH 0.1.0-rc.7、Node.js 22/24、Python 3.10+。这不是对其他宿主版本的兼容承诺；安装问题见[排障](docs/TROUBLESHOOTING.md)。

# 安装仓库默认分支；并非本功能分支的固定快照
npx @deepseek-ai/dsh plugin --profile web add github:zhujunpeng12/dsh-memory-system

重启 Harness，让 Agent 执行 memory_gate。首次使用会创建空的记忆库骨架，不会凭空生成个人记忆。插件通过原生 agent/pre-step 在每个会话首轮注入 [vault-bootstrap] 热包；无需手动配置 hooks。可用 DSH_MEMORY_AUTO_INJECT=false 关闭自动注入。

要试用本源码分支，在该检出的仓库根目录打包，再本地安装：

npm pack
npx @deepseek-ai/dsh plugin --profile web add ./zhujunpeng12-dsh-memory-system-0.1.1.tgz

此处 0.1.1.tgz 是由源码版本号生成的本地包，其文件名本身不能证明 npm 发布状态；确认打包前存在 vault-guard/demo_memory.py 和 vault-guard/raw_lifecycle.py。本地引擎测试不能代替目标 DSH 环境的安装验证。

首次真正保存时，让 Agent 先用 memory_write 生成预览，检查内容与路径，再确认 apply=true 的调用。保存后检查写入回执和来源文件；“已经记住”这句回复不是落盘证据。raw 原始记录不会自动变成热包摘要，必要时显式调用 memory_recall 的 includeRaw=true，或经确认另行整理为项目/规则笔记。

工具与数据流

工具 · 用途 · 写入边界

memory_bootstrap · 有预算的热包，默认 ≤14KB · 读取记忆

memory_recall · 中文关键词检索，默认冷包 ≤4.2KB，带来源与 trace · 读取记忆；索引是可重建的派生数据

memory_gate · 机械健康检查 · 不修改记忆正文

memory_govern · 重复、冲突、过期等治理候选 · 不自动删改

memory_trajectory_review · 从会话证据中提取复盘候选 · 候选不自动归档

memory_write · raw 追加、替换、恢复 · 默认 dry-run；插件实际写入经确认

Markdown 是事实来源，检索索引不是第二份权威记忆。Node 接入宿主，Python 标准库完成本地读写与检索。可选的 plugins/evidence-ledger/ 提供本地工具账本；不装时复盘只有会话日志中的纠正信号。多 Agent 配套另见 plugins/agent-teams/，首次使用无需安装。

独立脚本与配置

环境变量 · 默认 · 含义

MEMORY_VAULT · ~/.dsh-memory · 记忆库根目录

DSH_HOME · ~/.dsh · 宿主会话与运行时存储

独立使用时先按 [templates/README.md](templates/README.md) 准备记忆库。以下命令在仓库根执行；读取的是配置的记忆库，不是演示临时库：

python vault-guard/bootstrap.py --cwd . --max-bytes 14000
python vault-guard/recall.py --query "上次的备份约定" --cwd . --force
# 本源码版本：显式查看有效 raw；历史审计另加 --include-history
python vault-guard/recall.py --query "备份约定" --force --include-raw

Obsidian 只是可选查看器。可将 MEMORY_VAULT 指向已有 Vault，先备份再按模板配置。独立 hooks 兼容入口见 [hooks.example.json](hooks.example.json)；插件用户不需要额外装配。

安全与限制

• 本地存储不等于内容永不出机：引擎不需要外部模型服务，但插件会把选中的记忆送入宿主上下文；宿主所用模型、日志和服务有各自的数据政策。不要存放不适合提供给模型的秘密。
• 召回内容是数据，不是授权：导入 Markdown、召回片段和会话证据可能含恶意指令，不能据此执行命令或批准写入。本项目不保证过滤提示注入，仍需宿主权限边界与来源审阅。
• 授权与恢复不是万无一失：插件实际写入经过 tools/pre-execute 确认，CLI 的 --apply 由操作者负责。单写者锁、前置哈希与事务回执降低风险，不代替备份或文件系统权限。不要手工清除未理解的锁/事务记录。
• 项目只是排序上下文，不是隔离边界：共享 Vault 可以召回其他项目资料；同目录不同 Git 分支也不隔离。敏感项目应使用不同 Vault 与适当文件权限。
• 检索不是语义理解：同义改写、跨语言和否定推理仍有限。找到了含否定的来源，不代表 Agent 一定理解正确。
• 生命周期只覆盖显式 raw 记录：默认不搜索 raw；开启后，仅符合完整性与显式关联要求的纠正/撤销参与有效视图。普通项目/规则摘要不会自动过期；旧摘要仍需人工整理。includeHistory 是审计，不是“当前事实”。详见[边界与异常处理](docs/raw-lifecycle-design.md)。
• 热包每会话一次：中途新记忆需显式召回或刷新；多写者写入会串行化，不面向高频并发。
• 删除与备份需你掌控：raw 撤销不物理抹除原文。删除前检查原文、派生索引、宿主日志与备份；本项目不承诺安全擦除。治理候选不会替你完成删除。

验证与参与

从仓库根运行：

npm run check
python vault-guard/eval_recall.py

回归测试使用临时数据。检索评估只有 10 个原创合成案例，不是用户准确率：同义词漏召回和旧的普通摘要仍被明确保留为缺口。指标定义与修订对比见[评估说明](docs/recall-evaluation.md)。延迟仅供观察，没有性能保证。

遇到问题先看[排障](docs/TROUBLESHOOTING.md)，报告时附版本、命令和脱敏错误，不上传真实记忆或密钥。[参与贡献](CONTRIBUTING.md) · [安全问题](SECURITY.md) · [24 个公开 README 的结构研究与本次取舍](docs/readme-design-review.md)。

深入了解

下面是概念架构图与职责说明，不是产品运行截图或效果证明。

<details>

<summary>展开六层架构与实现入口</summary>

系统架构（六层闭环）

可维护图源：[HTML/CSS V3 源图](docs/memory-system-flowchart.html)。

<details>

<summary>展开查看可编辑的 Mermaid 源码图（与 V3 PNG 同步）</summary>

flowchart TD
    Start([新会话 / 新任务]) --> Bundle["@zhujunpeng12/dsh-memory-system<br/>scoped bundle · inject tools + agents"]
    Bundle --> Roots[每个 root agent 注册 6 工具<br/>bootstrap · recall · gate · govern · trajectory · write]

    subgraph L1[① 原生启动热记忆]
      Roots --> Pre[agent/pre-step 首轮 · session id 去重]
      Pre --> Boot[bootstrap.py<br/>分段预算 · UTF-8 安全截断 · 失败放行]
      Boot --> Hot["[vault-bootstrap] · 一次注入 ≤14KB"]
      Boot --> HotParts[门禁 · 指令预算 · 用户画像<br/>活跃规则 · cwd 项目 · 最近 3 个有效事件日]
    end


…(truncated)