长期记忆插件 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/<kind> 下 10 个白名单端点 |
| ✅ 自检与熔断 | 加载时探测各项能力；某项连续出错 N 次后熔断，不影响 DSH |
| ❌ 不做提示词注入 | 注入交给官方 @deepseek-ai/dsh-agent-instructions + $DSH_HOME/AGENTS.md。本插件从不碰 agent/pre-step / agent.inbox —— 这些是内部 API，也是最容易随升级碎掉的一层 |

安装

from a local checkout
dsh plugin --profile web add link:/path/to/dsh-agent-memory

from GitHub
dsh plugin --profile web add github:<owner>/dsh-agent-memory

restart the instance the profile serves
systemctl restart dsh-web-<your-instance>

验证实际组合出来的配置 —— 要以 DSH 用户身份运行，并设置 DSH_HOME，因为用 root 跑会读到另一份配置档：

sudo -u <dsh-user> 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），也可以用你自己的配置档补丁覆盖。随附的默认值与机器无关：存储落在 $DSH_HOME 下。

| key | default | meaning |
| storeRoot | $DSH_HOME/agent-memory | 记忆存储根目录 |
| dshHome | $DSH_HOME（或 ~/.dsh） | 用来定位 AGENTS.md |
| routePrefix | /dsh-agent-memory | 面板与数据路由的前缀 |
| breakerThreshold | 5 | 某项能力熔断前允许的连续失败次数 |
| allowUnfencedPanel | false | 浏览器信任围栏不可用时是否仍提供面板（默认失败即关闭） |

记忆存储布局

插件只读这套布局；写入由配套命令行完成：

<storeRoot>/
├── bin/ companion CLI (symlink or copy the repo's bin/ here)
├── secrets.files optional: extra files to harvest secret values from
├── preferences/merlin.md the preference set (this is what gets injected)
├── preferences/evidence.md per-item provenance (not injected)
├── skills/index.md, .md reusable playbooks
├── evidence/user-messages.jsonl rolling working set of human messages
├── evidence/live-messages.jsonl written by this plugin, merged by the CLI
├── evidence/signals.jsonl 候选偏好，等待蒸馏 ├── evidence/archive.jsonl 已压缩原始消息的账本 ├── digest.md 会话启动简报 └── bin/memory-scan.py, memory-note.py

原始消息是工作集，不是归档：权威副本是 DSH 自己的会话日志，所以更早的记录会被压缩掉，之后可以从 $DSH_HOME/sessions 重建。

配套命令行

只有往存储里写入数据，面板才会显示真实数据。bin/ 就是干这个的： bash

point it at your DSH home and memory root, then do a first full backfill

python3 bin/memory-scan.py --full --root ~/agent-memory --dsh-home ~/.dsh

record one durable preference right now (also refreshes digest.md)

python3 bin/memory-note.py "prefers terse, evidence-backed answers" --section "沟通"

after distilling candidates, clear the pending counter

python3 bin/memory-scan.py --mark-distilled

路径解析 —— 先匹配到的生效：

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

最省事的接法是把 bin/ 软链或复制到你的存储里（<store>/bin/）：脚本会自动识别存储，面板里那些可直接复制的命令也就原样能用了。

用定时器跑它（5 分钟足够 —— 空闲的增量扫描大约耗时 0.2 秒）： ini

/etc/systemd/system/agent-memory.service

[Service]
Type=oneshot
User=<your-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

命令行如何处理密钥

写进存储的所有内容都先过一遍 bin/redact.py：从已配置文件中收集到的已知密钥值*，加上结构性模式（bearer/basic 头、token=、cookie 记录与 cookie 头、JWT、sk-…、ghp_…、bcrypt 哈希、私钥、字面量 password=… 赋值）。在 <store>/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/<session-id>.md |
| 注入方 | 官方 agent-instructions，经 $DSH_HOME/AGENTS.md | 本插件，经 agent/pre-step |
| 作用域 | 每个会话 | 仅该会话 |
| 预算 | 6 KB 警告（AGENTS_WARN_BYTES） | 2 KB，超出截断（sessionInjectMax） |
bash

universal habits → every conversation

python3 bin/memory-note.py "always back up before changing config" --section "干活"

only this conversation (session id defaults to $DSH_SESSION_ID)

python3 bin/memory-note.py "this task touches CSS only" --scope session --section "约定"

插件为每个智能体注册 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/<kind> | 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. 降级链——插件挂了 ⇒ 命令行定时器仍会收集；面板挂了 ⇒ journal/digest 仍可用；插件没了 ⇒ 注入和存储不受影响。

package.json 带有 dsh.compatibility.dshReleases，面板会显示检测到的 DSH 版本，升级后版本不匹配一眼就能看出来。

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

插件检查项：消息过滤/去重、面板、信任围栏（默认拒绝）、熔断器、无服务时加载、一个守卫，断言面板用到的每条取值路径脚本存在于 payload 中，数据端点白名单也一样。

License

MIT