分层长期记忆Olalaye/dsh-layered-memory

dsh-layered-memory

为 DeepSeek Harness (dsh) 打造的分层长期记忆插件 —— 对标高端智能体个性化记忆体系，实现精细化跨会话记忆管理。

License: MIT

简介

dsh-layered-memory 是 dsh 的静态 bundle 插件，为智能体增加一套分层长期记忆：把会话内容按三层沉淀——瞬时（当前会话要点）、情景（每次会话一条摘要）、语义（长期事实与偏好）。它自动捕获用户消息、由模型提炼成长期记忆，并在后续会话按相关度召回，实现「跨会话记住你」。

与早期「动态插件」形式不同，本仓库是可全局安装的 bundle：通过 dsh plugin add 安装后随 Harness 启动自动加载、重启不丢失（记忆数据持久在磁盘）。安装后零配置，模型自动使用；也可通过 HTTP API 浏览、检索、编辑记忆。

特性

- 三层记忆架构：瞬时（transient）/ 情景（episodic）/ 语义（semantic），各层独立存储、独立容量上限
- 自动捕获：agent/pre-step 实时捕获用户消息要点到瞬时层，零配置
- AI 自动提炼：注册 4 个模型工具 + 系统提示词段落，模型自动保存用户使用习惯、写作风格、业务需求（按 habit / style / business / preference / fact 分类），任务收尾自动提交情景摘要
- 跨会话精准召回：CJK 感知分词（单字 + 双字 + 英文词）、重要性加权、45 天指数衰减、语义层权重、标签命中加成的排序评分
- 语义去重合并：相似度 ≥ 0.5 自动合并重复事实并累计 hits，防止语义层膨胀
- 持久化：JSON 文件存储于 ~/.dsh-memory/，跨会话、跨工作区共享，可直接查看/备份；串行写队列防并发损坏
- 管理 HTTP API：/api/memory/ 提供浏览、检索、编辑、删除、清空、统计（见管理 API）

安装

一个 bundle 就是「npm 包 + dsh.bundle 清单 + 补丁层」三件套，通过 dsh plugin 装入 profile。本项目是纯 JavaScript，无构建步骤，从本地目录、npm 或 Git 均可直接安装。

从本地目录安装

dsh plugin --profile demo add ./dsh-layered-memory

从 Git 安装

dsh plugin --profile demo add github:Olalaye/dsh-layered-memory

本项目为纯 JS（无 prepare 构建脚本），因此 Git 安装无需 allowBuilds 白名单即可直接运行。

从 npm 安装（发布后）

dsh plugin --profile demo add dsh-layered-memory

验证并启动

dsh --profile demo --dump-config   # 应看到 "# == dsh-layered-memory" 配置层
dsh --profile demo                 # 启动（Web GUI 默认 http://127.0.0.1:3080）

安装后：

- 模型获得 memory_recall / memory_remember / memory_commit / memory_stats 四个工具
- 系统提示词自动注入「分层长期记忆系统」使用规则（memory-system，order 150）
- 启动后记忆数据写入 ~/.dsh-memory/

卸载：

dsh plugin --profile demo remove dsh-layered-memory

配置

所有可调参数通过 Config schema 暴露，可在 profile 的 cordis.patch.yml 中覆盖：

- override:
- id: dsh-layered-memory
config:
storageDir: ~/.dsh-memory   # 记忆存储目录（默认 ~/.dsh-memory）
maxTransient: 300           # 瞬时层容量上限
maxEpisodic: 500            # 情景层容量上限
maxSemantic: 800            # 语义层容量上限
minScore: 0.08              # 召回最低分数阈值

| 字段 | 默认 | 说明 |
|---|---|---|
| storageDir | ~/.dsh-memory | 记忆 JSON 存储目录（支持 ~ 与相对路径） |
| maxTransient | 300 | 瞬时层容量上限（超出按 ts 裁剪最旧） |
| maxEpisodic | 500 | 情景层容量上限 |
| maxSemantic | 800 | 语义层容量上限 |
| minScore | 0.08 | 召回最低分数 |

使用方法

1. 日常使用（全自动，零操作）

安装后无需任何配置，模型会按提示词规则自动使用记忆系统：

| 场景 | 模型自动行为 |
|---|---|
| 会话开始，或你说"之前/上次/记得吗/照旧/按老规矩" | 自动调用 memory_recall 检索相关历史后再回答 |
| 你明确说出可长期复用的偏好（习惯、写作风格、业务要求等） | 自动调用 memory_remember 保存并分类 |
| 一段工作完成、任务收尾、或你说"今天先到这/再见" | 自动调用 memory_commit 提交会话摘要并沉淀要点 |
| 任何会话中的用户消息 | 插件自动捕获到瞬时层（无需模型参与） |

2. 手动指令（给模型发消息即可）

不需要记忆相关术语，用自然语言即可：

记住：我汇报时喜欢用表格
以后写文档都用中文，标题用 ## 两级
上次我们讨论的 X 项目结论是什么？
把这个会话记下来
查一下我上次说的关于 Y 的要求
忘记我之前说的那件事吧
模型会对应调用 memory_remember / memory_recall / memory_commit 完成操作。（注：删除/清空请使用 HTTP API，模型工具暂不提供删除入口。）

3. 数据文件管理

记忆以纯 JSON 存储于 ~/.dsh-memory/（跨会话、跨工作区共享）：

.dsh-memory/
├── transient.json   # 瞬时记忆（上限 300 条）
├── episodic.json    # 情景记忆（上限 500 条）
└── semantic.json    # 语义记忆（上限 800 条）

- 备份：直接复制这三个文件即可；恢复时放回原目录
- 迁移：把目录复制到另一台机器的用户目录下，重新安装插件即可读取
- 隐私：记忆包含个人数据，位于用户目录、不在仓库内

HTTP 管理 API

Web GUI 运行时，插件注册一组 /api/memory/ 路由（需自行鉴权，dsh Web 服务默认仅监听 127.0.0.1）：

| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /api/memory/stats | 各层条数与存储位置 |
| GET | /api/memory/list?layer=&category=&limit= | 列出记忆条目 |
| GET | /api/memory/search?query=&layer=&limit= | 带匹配度的全文检索 |
| POST | /api/memory/add | 手动新增 {layer, text, category?, importance?, tags?} |
| POST | /api/memory/update | 编辑 {id, patch:{text?, category?, importance?, tags?}} |
| POST | /api/memory/remove | 删除单条 {id} |
| POST | /api/memory/clear | 清空一层或全部 {layer}（all） |

早期动态插件形式的 React 设置页「记忆管理」依赖客户端 UI 槽位，属于独立的 client 插件包、无法由 dsh plugin add 注入；本 bundle 以 HTTP API 提供等价的管理能力（见已知边界）。

架构

记忆分层

| 层 | 存储文件 | 内容 | 来源 | 容量 |
|---|---|---|---|---|
| 瞬时 transient | transient.json | 当前会话要点（用户消息） | agent/pre-step 自动捕获（2s 冷却、300 字符截断）+ memory_remember(layer=transient) | 300 |
| 情景 episodic | episodic.json | 每会话一条记录（标题、时间、要点、交互数） | memory_commit 提交；agent/disposed 自动沉淀兜底 | 500 |
| 语义 semantic | semantic.json | 长期事实（习惯/风格/业务/偏好/事实/其他） | memory_remember / memory_commit(facts)；相似度 ≥ 0.5 自动合并 | 800 |

存储目录：~/.dsh-memory/（默认，由 config.storageDir 覆盖，跨会话、跨工作区共享）。

数据模型

每条记忆条目：
json
{
"id": "s_mstyq3l9-asx1jy",
"layer": "semantic",
"text": "用户偏好用 Markdown 表格汇报数据",
"category": "preference",
"source": "agent",
"importance": 4,
"tags": ["汇报", "markdown"],
"ts": 1786773359277,
"updatedAt": 1786773359277,
"sessionId": "session-xxx",
"hits": 2
}

字段按层略有差异：情景条目另含 sessionTitle / messageCount，瞬时条目不含 hits。

召回算法

score = (0.15 × min(命中词数, 3)          # 命中基础分
+ 0.40 × 查询覆盖率                # matched / queryTokens
+ 0.10 × 条目密度                  # matched / entryTokens
+ 0.15 × 标签命中)                 # 可选
× (0.75 + 0.25 × importance/5)    # 重要度加权
× (0.40 + 0.60 × e^(-ageDays/45))  # 45 天指数衰减
× 层级权重                          # semantic 1.15 / episodic 1.0 / transient 0.55

阈值 MIN_SCORE = 0.08（可配），结果按分数降序、同时按更新时间次排序。

模型工具 API

memory_recall(query, layer?, category?, limit?)

跨层检索相关历史。会话开始或用户提到"之前/上次/照旧"时优先调用。

| 参数 | 类型 | 说明 |
|---|---|---|
| query | string (必填) | 检索关键词：主题、人名、项目、术语等 |
| layer | enum | all（默认）/ transient / episodic / semantic |
| category | enum | 语义层分类筛选：habit / style / business / preference / fact / other |
| limit | integer | 返回条数，默认 8，最大 20 |

返回 { query, count, results[], context }——context 是可直接注入系统上下文的紧凑文本块。

memory_remember(text, category?, importance?, tags?, layer?)
写入语义事实（自动去重合并并累计 hits）或瞬时笔记。适用于用户明确表达的长期偏好、习惯、风格、业务需求。

memory_commit(summary, facts?, title?)

提交当前会话：写入情景记忆（摘要），并把 facts 数组 [{text, category?, importance?}] 沉淀到语义层。适用于工作完成、任务收尾、用户告别时。

memory_stats()

各层条数与存储位置。

事件钩子

| 事件 | 模式 | 用途 |
|---|---|---|
| agent/session-start | emit | 初始化会话跟踪器 |
| agent/pre-step | waterfall（必须 return next()） | 捕获标准 UserMessage[] → 瞬时层 |
| agent/disposed | emit | 自动沉淀情景记录（兜底） |

系统提示词段落

memory-system（order 150）注入使用规则：

1. 会话开始或用户提到“之前/上次/记得吗/照旧”时，先 memory_recall 再作答；
2. 用户表达可长期复用的习惯、风格、业务要求、偏好时，memory_remember 并选对 category；
3. 工作完成、任务收尾或告别时，memory_commit 提交情景摘要 + facts 沉淀；
4. 检索结果只用于辅助回答，不原样复述。

目录结构

dsh-layered-memory/
├── index.js          # 插件入口：name / inject / Config / apply
├── lib/
│   ├── store.js      # 记忆存储引擎：分词、召回、去重、CRUD、持久化
│   ├── tools.js      # 四个模型工具定义（defineTool）
│   ├── prompt.js     # 系统提示词段落文本
│   └── http.js       # 管理 HTTP API（可选，ctx.webServer 存在时注册）
├── package.json      # dsh.bundle 清单 + 依赖
├── cordis.patch.yml  # 配置层：插入本插件行
├── README.md
├── LICENSE           # MIT
└── .gitignore

开发

npm install                 # 安装依赖（@deepseek-ai/dsh-tools / schemastery）
node --check index.js       # 语法校验（各 lib/.js 同理）

本插件是纯 ESM JavaScript，无构建步骤；apply(ctx, config) 内的一切注册（工具、事件、提示词段落）都经 ctx 完成，插件卸载时由 Cordis 自动清理。

已知边界

- 管理 UI 为 HTTP API：早期动态插件形式的 React 设置页依赖客户端 UI 槽位，属于独立 client 插件包（浏览器端模块图），无法由 dsh plugin add（宿主 bundle）注入；本仓库以 /api/memory/ HTTP API 提供等价能力，如需图形化界面可另行开发 client 插件（Roadmap）
- Web 服务仅回环：dsh Web 默认只监听 127.0.0.1，HTTP API 不对外暴露
- 插件重启后会话计数器（messageCount/notes）重置，不影响已落盘数据；情景记录以 memory_commit 为主路径、agent/disposed 为兜底
- 删除/清空操作通过 HTTP API 完成；词面去重阈值保守（0.5），语义级去重由模型在提交时判断
- 记忆数据（~/.dsh-memory/）为个人隐私数据，位于用户目录、不在仓库内

Roadmap

- [ ] 客户端 UI 插件：把「记忆管理」设置页迁到 dsh client 插件包，复用 HTTP API
- [ ] 记忆导入/导出（JSON/Markdown）
- [ ] 语义层自动晋升（hits ≥ 阈值时从情景层自动提炼）
- [ ] 多语言召回（CJK 双字分词已在中文/英文下工作，计划扩展日韩）
- [ ] 可选向量检索后端（当前为确定性词面评分，零依赖）

版本历史

- v1.0.0 (bundle) — 从「动态插件」彻底迁移为 dsh 静态 bundle：ESM 入口（name/inject/Config/apply）、defineTool 工具注册、ctx.systemPrompt.section 提示词、agent/* 事件、node:fs 持久化、可配置 Config schema、HTTP 管理 API。可 dsh plugin add 全局安装、重启持久。
- v0.x（动态插件，历史） — 早期以 cordis_define/cordis_run 动态定义插件运行，依赖进程内 harness 沙箱，重启即失效；本仓库从 bundle 版（v1.0.0）起重新维护。

License

MIT