长期记忆插件BPTumbleweed/dsh-agent-memory

dsh-agent-memory

一个用于 DeepSeek Harness（DSH）的长期记忆插件：实时捕获对话证据、
一个只读数据浏览器，以及 Web UI 内的状态面板。

为在 DSH 升级中存活而构建：零运行时依赖，每项能力都经过特性检测，
每个回调都被包裹——并且它刻意避开提示注入路径。

| | |
|---|---|
| ✅ 实时捕获 | 挂钩 session/event，并将人类用户消息追加到 evidence/live-messages.jsonl |
| ✅ 状态面板 | /dsh-agent-memory/panel，在对话视图中以 记忆 标签页呈现 |
| ✅ 只读数据浏览器 | /dsh-agent-memory/data/ 下的 10 个白名单端点 |
| ✅ 自检与熔断器 | 加载时探测各项能力；某项能力在 N 次错误后跳闸，且不影响 DSH |
| ❌ 无提示注入 | 注入仍由官方 @deepseek-ai/dsh-agent-instructions + $DSH_HOME/AGENTS.md 负责。本插件从不触碰 agent/pre-step / agent.inbox——这些是内部 API，也是最易受升级影响的层 |

安装

从本地检出安装
dsh plugin --profile web add link:/path/to/dsh-agent-memory

从 GitHub 安装
dsh plugin --profile web add github:/dsh-agent-memory

重启该 profile 所服务的实例
systemctl restart dsh-web-

验证实际组合出的内容——以 DSH 用户身份运行并设置 DSH_HOME，因为以 root 身份运行会读取不同的 profile：

sudo -u  env DSH_HOME=/var/lib/dsh dsh --profile web --dump-config \
| grep -A8 dsh-agent-memory

卸载 / 回滚：

dsh plugin --profile web remove dsh-agent-memory

配置

在条目的 config 中设置（参见 cordis.patch.yml），或从你自己的 profile 补丁中覆盖。
随附的默认值与机器无关：存储落在 $DSH_HOME 下。

| 键 | 默认值 | 含义 |
|---|---|---|
| storeRoot | $DSH_HOME/agent-memory | 记忆存储根目录 |
| dshHome | $DSH_HOME（或 ~/.dsh） | 用于定位 AGENTS.md |
| routePrefix | /dsh-agent-memory | 面板和数据路由的前缀 |
| breakerThreshold | 5 | 某项能力跳闸前的连续失败次数 |
| allowUnfencedPanel | false | 当浏览器信任围栏不可用时仍提供面板（默认故障关闭） |

记忆存储布局

本插件只读取此布局；配套 CLI 负责写入：

/
├── bin/                         配套 CLI（将仓库的 bin/ 符号链接或复制到此处）
├── secrets.files                可选：用于采集密钥值的额外文件
├── preferences/merlin.md        偏好集合（这就是被注入的内容）
├── preferences/evidence.md      逐项来源（不被注入）
├── skills/index.md, .md        可复用的操作手册
├── evidence/user-messages.jsonl 人类消息的滚动工作集
├── evidence/live-messages.jsonl 由本插件写入，由 CLI 合并
├── evidence/signals.jsonl       等待提炼的候选偏好
├── evidence/archive.jsonl       已压缩原始消息的账本
├── digest.md                    会话启动简报
└── bin/memory-scan.py, memory-note.py

原始消息是一个工作集，而非归档：权威副本是 DSH 自己的会话日志，因此较旧的记录会被压缩移除，并可从 $DSH_HOME/sessions 重建。

配套 CLI

只有当有东西填充存储时，面板才会显示真实数据。这正是 bin/ 所做的事：

将其指向你的 DSH home 和 memory 根目录，然后执行首次完整回填
python3 bin/memory-scan.py --full --root ~/agent-memory --dsh-home ~/.dsh

立即记录一条持久偏好（同时刷新 digest.md）
python3 bin/memory-note.py "prefers terse, evidence-backed answers" --section "沟通"

提炼候选偏好后，清除待处理计数器
python3 bin/memory-scan.py --mark-distilled

路径解析——先匹配者胜出：

| 值 | 顺序 |
|---|---|
| 存储根目录 | --root → $AGENT_MEMORY_ROOT → 脚本自身所在的存储（/bin/…） → $DSH_HOME/agent-memory |
| DSH home | --dsh-home → $DSH_HOME → ~/.dsh |
| 会话日志 | --sessions → $DSH_HOME/sessions/ |

最简单的接线方式是将 bin/ 符号链接或复制到你的存储中（/bin/）：脚本随后会自动检测存储，面板中可复制粘贴的命令也能直接使用。

用定时器运行它（5 分钟足够——一次空闲的增量扫描约耗时 0.2 秒）：

/etc/systemd/system/agent-memory.service
[Service]
Type=oneshot
User=
Environment=DSH_HOME=/var/lib/dsh
WorkingDirectory=/path/to/your/project   # used to pick the right session directory
ExecStart=/usr/bin/python3 /path/to/agent-memory/bin/memory-scan.py --quiet

CLI 如何处理机密

写入存储的所有内容都会先经过 bin/redact.py：从配置文件中采集的已知机密值*，以及结构化模式（bearer/basic 头、token=、cookie 记录和 cookie 头、JWT、sk-…、ghp_…、bcrypt 哈希、私钥、字面量 password=… 赋值）。在 /secrets.files 中列出额外来源（每行一个路径）；每个来源会被自动检测为 Netscape cookie jar、KEY=VALUE 文件或单 token 文件。当存在 $DSH_HOME/.credentials.yaml 时会读取它。运行 python3 bin/redact.py 进行自检。

存储模型

原始消息是一个工作集：每次运行后，超出 EVIDENCE_KEEP（120）的最旧记录会被压缩移除，并向 evidence/archive.jsonl 追加一行。不会丢失任何内容——权威副本是 DSH 自己的会话日志，--rebuild 可从它重新生成存储。

两层记忆

| | 全局 | 每会话 |
|---|---|---|
| 文件 | preferences/global.md | sessions/.md |
| 注入方式 | 官方 agent-instructions 通过 $DSH_HOME/AGENTS.md | 本插件，通过 agent/pre-step |
| 范围 | 每次对话 | 仅该对话 |
| 预算 | 6 KB 警告（AGENTS_WARN_BYTES） | 2 KB，超出后截断（sessionInjectMax） |

通用习惯 → 每次对话
python3 bin/memory-note.py "always back up before changing config" --section "干活"

仅此对话（会话 id 默认为 $DSH_SESSION_ID）
python3 bin/memory-note.py "this task touches CSS only" --scope session --section "约定"

该插件为每个 agent 注册一个 agent/pre-step 处理器，先调用 next() 以便其他插件继续工作，
然后在最后一条用户消息之前插入会话记忆——这样用户当前的指令仍然是最后说的内容。注入的消息带有
source: { kind: "plugin", plugin: "dsh-agent-memory", form: "session-memory" }。

该钩子属于内部 API，因此这一层被视为脆弱的一层：它会进行特性检测，
被包裹在熔断器中，并受字节预算限制。如果它停止工作，面板
会显示 sessionMemory: unavailable/tripped，而全局注入和存储不受影响。

超过 90 天未更新的会话文件会被移动到 sessions/archive/（绝不删除），
并且 sessions/index.json 会跟踪每次对话的大小/条目数/是否超预算。

端点

| 路由 | 用途 |
|---|---|
| /dsh-agent-memory/panel | 自包含的 HTML 面板，自动刷新 |
| /dsh-agent-memory/status.json | 机器可读的状态 |
| /dsh-agent-memory/data/ | human live signals preferences digest agents skills journal archive prefEvidence |

每个路由都会通过 DSH 的浏览器信任围栏（connection.requestRejection）；当围栏
不可用时，面板会故障关闭。数据端点是一个固定的白名单，因此没有
任意路径入口点。

兼容性规则

1. 零运行时依赖——仅使用 node:fs、node:path、node:os、node:module。
2. 无硬依赖——inject: []；webServer/connection 通过 ctx.inject([...], cb) 可选地等待，并降级为 unavailable。
3. 所有回调都被包裹——不会向 DSH 传播任何内容。
4. 熔断器——失败的能力只会禁用自身，原因会显示在面板中。
5. 仅在 storeRoot 下写入——绝不编辑 DSH 配置或其他插件。
6. 降级链——插件宕机 ⇒ CLI 计时器仍会收集；面板宕机 ⇒ journal/digest 仍可工作；插件消失 ⇒ 注入和存储不受影响。

package.json 包含 dsh.compatibility.dshReleases，并且面板会显示检测到的 DSH
版本，因此升级后的版本不匹配一目了然。

开发

node test/selftest.mjs    # 8 checks (plugin)
python3 bin/redact.py     # 8 checks (redaction engine)

插件检查：消息过滤/去重、面板、信任围栏（故障关闭）、熔断
器、在没有服务存在时加载、一个断言面板使用的每个值路径的守卫
脚本存在于有效载荷中，以及数据端点白名单。

许可证

MIT