dsh-hermes-memory

Persistent memory for DeepSeek Harness (DSH) that keeps two separate banks — MEMORY.md for what the agent learns about the world, USER.md for what it learns about you — plus a built-in web panel to inspect and edit both.

DeepSeek Harness 的双库记忆插件：把 agent 的记忆分成两个独立的库——MEMORY.md（关于世界的事实：环境、项目约定、工具怪癖）和 USER.md（关于你的画像：偏好、沟通风格、工作习惯），各自独立预算、独立淘汰。模型用一个 memory 工具自主策展，跨会话持久化，每个会话以冻结快照重新注入；附带内置网页面板，直接查看和修改两个记忆库。机制源自 NousResearch/hermes-agent 的 MemoryStore，零外部依赖、纯 DSH 原生接缝实现。

为什么分两个库

大多数 agent 记忆方案把什么都装进一个池子——用户画像和项目事实、快变和慢变的信息混在一起。三个后果：

• 抢预算：一个字符上限的池子里，"用户喜欢简洁回答"和"这个项目的构建命令"互相挤占，谁该留谁该删没有依据。
• 淘汰一刀切：用户画像是慢变的（几个月不变），项目事实是快变的（每次迭代都更新），单库只能给两类信息套同一个淘汰策略。
• 策展互相干扰：模型决定"该记什么"时，关于你的信息和关于代码的信息搅在一起，两类判断互相污染。

Hermes 的答案是分开：两个独立的库，各自的上限、各自的淘汰节奏。本插件把这个设计忠实落到 DSH。

Features

记忆面板（Memory Panel）

安装后，DSH Web 界面侧边栏底部会出现「记忆」入口，点击打开记忆面板：

功能

• 查看：MEMORY 与 USER 两个记忆库的全部条目、各自占用率（84% — 1,859/2,200 chars）与条数
• 编辑：每行「编辑」按钮 → 行内文本域直接修改 → 保存；替换保留条目身份（seq 不变）
• 删除：每行「删除」按钮，按条目精确匹配移除
• 添加：分区底部输入新条目，回车或「添加」按钮提交（自动去重）
• 实时同步：每次操作立即写入 ~/.dsh/storages/hermes_memory.json（原子写、跨重启持久），状态行给出反馈

设计

黑白灰、大量留白、细线分割、克制动效 —— 吸收水墨美学的克制气质，不堆砌装饰：面板即工具，所见即所得。编辑/删除按钮常显（浅灰弱化），悬停加深，不会干扰阅读。

架构

浏览器（client 半边，__ModuleLoader__ 模块）
 ├─ sidebar.footer.action「记忆」入口 + shell.overlay 浮层面板（React）
 └─ 同源 fetch → /hermes-memory/stats（GET 统计）
                    /hermes-memory/ops （POST add/replace/remove/list）
宿主（host 半边）
 └─ webServer 服务注册上述路由 → applyBatch → KvUnit `hermes_memory` → 落盘

面板与模型 memory 工具读写同一份存储，两边看到的内容永远一致 —— 模型策展的记忆，你可以随时亲眼查看和修正。

Quick Start

方式 A：dsh bundle 安装（推荐，部署级、重启自动加载）

本仓库是标准 dsh bundle（package.json 声明 dsh.bundle + cordis.patch.yml），一行安装：

dsh plugin --profile web add github:isheng-eqi/dsh-hermes-memory
# 或 npm 源（走 registry CDN，通常更快更稳）
dsh plugin --profile web add dsh-hermes-memory
# 或本地路径
dsh plugin --profile web add /path/to/dsh-hermes-memory

安装后插件在部署级生效（所有会话可见）：模型获得 memory / memory_search / memory_list / memory_stats / memory_debug 工具，每个会话开始自动注入记忆冻结快照，Web 界面侧边栏出现「记忆」面板入口。

存储行归属说明：json storage 三行（storage / storage-json / storage-domain）是宿主表面自带的组合——web bundle 默认携带；headless / TUI / 自定义 profile（dsh plugin --profile <名字> add 初始化为 base-only）默认没有，且 bundle 层不允许重复声明相同行 id（会报 duplicate loader entry id 启动失败），所以本插件 patch 不含这些行。在无 storage 的 profile 上插件仍会挂载并打一次启动警告，但写入/快照不可用；如需启用，把下面三行加到该 profile 自己的 cordis.patch.yml（web profile 无需）：

- insert:
    - id: storage
      name: '@deepseek-ai/dsh-storage'
    - id: storage-json
      name: '@deepseek-ai/dsh-storage-json'
      config:
        root: !!js dshHomePath('storages')
    - id: storage-domain
      name: '@deepseek-ai/dsh-storage-domain'
      config:
        backend: json

方式 B：动态 Cordis 插件（进程级，无需改部署配置）

在任意 DSH 会话中，让模型执行 cordis_define（Host 半边代码 = host.js，Client 半边 = client.js，额外带 Run 卡记忆面板）与 cordis_run。注意动态插件随进程退出而消失，重启后需重新运行（数据不丢）。

动态形态无配置通道：字符上限与 nudge 间隔为硬编码（2200/1375/10），与 bundle 形态默认值一致；如需调整请使用方式 A。

使用

• 让模型记：直接对模型说"记住 XXX"即可；每个新会话开始会自动注入记忆快照
• 自己看/改：点击侧边栏「记忆」→ 面板直接查看、编辑、删除、添加条目
• 数据存储：~/.dsh/storages/hermes_memory.json（DSH storage hub 的 json 后端，原子写、人类可读、跨会话跨重启持久）

Tools

memory

唯一的记忆写入入口，与 hermes-agent 契约一致：

• action：add / replace / remove / batch（必填）
• target：memory（默认，= MEMORY.md）/ user（= USER.md）
• content：新增/替换条目文本
• oldText：replace/remove 时的匹配文本（精确匹配优先，无精确命中回退唯一子串匹配）
• operations：batch 时的操作数组（全有或全无，可在一次调用里腾空间+写入）

辅助工具

• memory_search — 确定性关键词检索两个记忆库
• memory_list — 列出条目（按存储顺序）
• memory_stats — 用量统计（3% — 79/2,200 chars）
• memory_debug — 诊断存储句柄表与 store 状态

Architecture

┌────────────────────────────────────────────────────────────┐
│  Web UI 记忆面板（client 半边）                              │
│  └─ sidebar.footer.action 入口 + shell.overlay 浮层         │
│     └─ /hermes-memory/* 路由 ↔ 同源 fetch                   │
├────────────────────────────────────────────────────────────┤
│  systemPrompt / agent/pre-step                             │
│  └─ 冻结快照注入（会话首步一次）+ nudge 提醒（每 10 轮）      │
├────────────────────────────────────────────────────────────┤
│  `memory` 工具（harness.defineTool/registerTool）            │
│  └─ MemoryStore 语义：add/replace/remove/batch，§ 分隔条目    │
│     字符预算（2200/1375），超限合并协议，失败上限 3/轮         │
│     精确匹配优先（UI 场景），子串匹配回退（模型场景）          │
├────────────────────────────────────────────────────────────┤
│  DSH storage hub → json 后端 → KvUnit `hermes_memory`       │
│  └─ ~/.dsh/storages/hermes_memory.json（原子写、版本化）      │
└────────────────────────────────────────────────────────────┘

• 写链串行：单进程内所有写入经 promise 链排队，先落盘后更内存。
• 自愈：更新/重启插件时若旧纤维的单元句柄未释放（unit already open），自动强制关闭僵尸句柄并重开；disposer 返回 Promise 等待 close 完成。
• webServer 迟到处理：路由注册等待 webServer 服务（500ms 轮询，最多 30s）；无 webServer 的环境（TUI/headless）自动跳过面板层，工具与注入不受影响。
• 面板与模型共用同一存储：面板操作走与 memory 工具相同的 applyBatch 写链，天然一致。
• 注入格式（逐字符对齐 hermes-agent MemoryStore._render_block）：

  <system-reminder>
  <hermes-memory-snapshot>
  Persistent memory, maintained with the `memory` tool. ...
  ══════════════════════════════════════════════
  MEMORY (your personal notes) [3% — 79/2,200 chars]
  ══════════════════════════════════════════════
  entry one § entry two
  ...
  </system-reminder>
  

  条目内 </system-reminder> 被转义，文件内容无法破坏框架。

Design Decisions（与 Hermes 原版的差异）

• 存储介质：Hermes 用 ~/.hermes/memories/*.md 文件 + 文件锁/原子 rename；本插件改用 DSH 原生 json 存储单元（本身原子写、版本化、人类可读），单进程内无需文件锁。
• 注入载体：Hermes 注入系统提示词；本插件经 agent/pre-step 注入 durable user 消息（source {kind:'plugin', plugin:'hermes-memory'}），会话日志可重建（model-visible ⟺ logged）。
• 匹配策略：Hermes 的 replace/remove 是纯子串匹配；本插件改为精确匹配优先——UI 传完整文本时永远唯一命中（修复短文本条目"11"是其他条目子串时的冲突），模型子串语义保留为回退，两边行为都更稳。
• 失败上限只约束模型：Hermes 的"每轮最多失败 3 次"协议仅作用于模型 memory 工具调用；面板操作（sessionId 'ui'）每次失败都返回原始错误，不会被协议文案卡死。
• 可视化面板：Hermes 无 UI；本插件用 DSH 原生 slot（sidebar.footer.action / shell.overlay）+ webServer 路由实现浏览器面板，零前端依赖、零构建步骤。
• 未实现（与社区移植版一致）：write_approval 审批门、提示注入安全扫描（信任度与 AGENTS.md 相同）、session_search（Hermes 用 SQLite FTS5 检索会话历史；DSH 原生 sessionQuery 可作后续接入点）。

社区收录

本插件为 DSH 社区生态的一部分。已收录于 awesome-dsh-plugin。

License

MIT