dsh-layered-memory

1. 安装并启动 DeepSeek Harness：npx @deepseek-ai/dsh web
2. 在终端执行上面的安装命令（CLI 会解析插件并核验来源）
3. 用 dsh plugins list 确认已安装，必要时重启 Harness 生效

插件以当前 dsh 进程的权限运行，安装时可能执行代码。请先通读仓库源码与许可证，确认无破坏性命令与越权访问；本站只做索引，不对第三方插件安全性作担保。

事实信息来自公开插件目录快照（2026-10-01），介绍文案由本站再加工。

以下为插件仓库 README 全文（原始内容，由公开目录抓取整理）。

# dsh-layered-memory

> 为 [DeepSeek Harness (dsh)](https://github.com/deepseek-ai/deepseek-harness) 打造的分层长期记忆插件 —— 对标高端智能体个性化记忆体系，实现精细化跨会话记忆管理。

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

## 简介

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](#http-管理-api)）

## 安装

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

### 从本地目录安装

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

### 从 Git 安装

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

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

### 从 npm 安装（发布后）

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

### 验证并启动

```sh
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/`

卸载：

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

## 配置

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

```yaml
- 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
```

## 开发

```bash
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](LICENSE)