@ascrm88/dsh-memory

dsh plugin --profile web add @ascrm88/dsh-memory

dsh-memory




面向 DeepSeek Harness 的本地优先记忆插件。记忆以 Markdown 文件为唯一事实来源，索引只是可删除、可重建的检索缓存。

Status: 0.1.x。核心协议与磁盘格式仍在收敛，升级前请阅读变更记录并保留备份。

设计细节见 [docs/dsh-memory-plugin-design.md](docs/dsh-memory-plugin-design.md)。

目录

• [设计目标](#设计目标)
• [功能概览](#功能概览)
• [工作原理](#工作原理)
• [环境要求](#环境要求)
• [安装](#安装)
• [快速开始](#快速开始)
• [配置](#配置)
• [模型工具](#模型工具)
• [命令行](#命令行)
• [侧边栏与 HTTP API](#侧边栏与-http-api)
• [存储布局](#存储布局)
• [信任与冲突](#信任与冲突)
• [检索与 recall](#检索与-recall)
• [自动捕获](#自动捕获)
• [安全模型](#安全模型)
• [性能](#性能)
• [开发](#开发)
• [已知限制](#已知限制)
• [License](#license)

设计目标

dsh-memory 解决的是编码 agent 的跨会话记忆问题，但刻意不做成“把所有东西塞进上下文”的 RAG 服务。

• 本地优先：默认写入 $DSH_HOME/memory，不依赖数据库服务或云端 API。
• 文件即事实：每条记忆一个 Markdown 文件；index.json / index.sqlite 可随时删除重建。
• 两层预算：核心层常驻系统提示词（默认 ≤ 1 KB），召回层通过工具按需读取，避免上下文膨胀。
• 人在回路：模型只能提议 candidate，验证、争议、置顶、取代等信任操作由用户完成。
• 可审计：写入、验证、争议、遗忘、注入、检索均记录到 audit.jsonl；不记录正文与查询原文。
• 可恢复：派生索引损坏或后端不可用时自动回退，不把索引当作唯一数据源。

功能概览

能力 · 说明

跨会话记忆 · 用户级、项目级、多项目 scope

核心注入 · 同步缓存，硬性字节与条数预算

per-turn recall · 根据当前用户消息注入相关记忆

检索 · BM25 + 元数据排序 + MMR 多样性

信任生命周期 · candidate / verified / disputed / superseded

冲突处理 · 双向 conflictOf，review queue 支持 keep / merge / both

索引后端 · JSON（默认）或 SQLite FTS5（可选）

用户界面 · DSH 右侧边栏、dsh-memory CLI、JSON API

自动捕获 · 可选，agent 结束时提取候选记忆

安全 · 提示词框架转义、单行化、密钥脱敏、原子写、文件锁

工作原理

用户消息
  │
  ├─ agent/inbox/claimed ──────▶ RecallService（当前轮查询）
  │
  └─ system-prompt/assemble ───▶ <memory_context> 核心层
                                 <memory_recall> 召回层
                                        │
模型 ── memory_search / memory_read ────┘
模型 ── memory_write ──▶ candidate ──▶ Markdown 文件
                                        │
                                   index.json / index.sqlite

• 核心层：从 verified 记忆中选取，按预算截断，经同步缓存进入系统提示词；text 回调不读盘。
• 召回层：在 system-prompt/assemble 阶段异步检索当前用户消息，结果放入独立段，不污染核心层。
• 工具层：模型显式调用 memory_search / memory_read 获取更完整的上下文。
• 写入层：所有写操作经过 MemoryStore，使用跨进程锁与原子替换。

环境要求

• Node.js ^22.19.0 或 >=24.0.0。
• DeepSeek Harness 及以下 peer 包（由 dsh 提供）：
• @deepseek-ai/cordis
• @deepseek-ai/dsh-agent
• @deepseek-ai/dsh-atomic-write
• @deepseek-ai/dsh-home-paths
• @deepseek-ai/dsh-llm
• @deepseek-ai/dsh-session
• @deepseek-ai/dsh-system-prompt
• @deepseek-ai/dsh-tools
• SQLite 后端使用 Node 内置 node:sqlite，不需要原生扩展；Node 构建需包含 FTS5。

安装

从本地 checkout 安装：

dsh plugin add /path/to/dsh-memory

发布到 npm 后也可以直接安装：

dsh plugin add @ascrm88/dsh-memory

插件入口为 lib/index.js，包内附带 cordis.patch.yml。典型的 profile 配置：

- id: dsh-memory
  name: '@ascrm88/dsh-memory'
  config:
    memoryDir: ~/.dsh/memory
    enableRecall: true
    indexBackend: json

快速开始

1. 安装插件并重启 dsh。

2. 让 agent 记住一条信息，例如“项目使用 pnpm 构建”。模型会通过 memory_write 写入 candidate。

3. 由用户验证：

   dsh-memory review --scope all
   dsh-memory verify <id|slug>

4. 下一次会话中，verified 记忆会进入核心层或在相关请求中进入 recall。

5. 打开 DSH 右侧边栏，点击“记忆”卡片；也可以在边栏的 + 菜单中选择“记忆”。

配置

配置由 @deepseek-ai/schemastery 声明。默认值：

配置 · 默认值 · 说明

memoryDir · $DSH_HOME/memory · 记忆根目录

maxCoreBytes · 1024 · 核心层字节预算

maxCoreItems · 8 · 核心层条数上限

maxSearchResults · 8 · 默认检索条数

maxBodyBytes · 8192 · 单条 body 上限

enableRecall · true · 按当前用户消息做 per-turn recall

recallMaxBytes · 1024 · recall 段字节预算

recallMaxItems · 5 · recall 段最大条数

recallIncludeCandidates · false · recall 是否包含未验证候选

recallTimeoutMs · 500 · recall 检索超时时间

indexBackend · json · json 或 sqlite（FTS5）

cjkUnigrams · false · 是否额外索引 CJK 单字；索引更大，支持单字查询

enableUserScope · true · 启用用户级记忆

enableAutoCapture · false · agent 结束时自动提取候选

autoCaptureMaxTokens · 2048 · 自动提取输出上限

autoCaptureMaxItems · 5 · 单次自动提取最多写入条数

trustCandidatesInCore · false · 是否允许候选进入核心层

staleAfterDays · 180 · 未使用多久视为陈旧（0 关闭）

decayHalfLifeDays · 180 · 排序衰减半衰期

projectScope · git · 项目身份：git 或 path

enablePanel · true · connection 可用时注册侧边栏客户端 API

redactPhoneAndId · false · 额外脱敏手机号/身份证号

模型工具

工具 · 作用

memory_search · BM25 + 元数据排序，返回 id、摘要、信任状态

memory_read · 读取正文、provenance、信任状态，展开一层 [[links]]

memory_write · 新建记忆始终写为 candidate；更新内容会使 verified 降级为 candidate

memory_forget · 默认静音；hard=true 永久删除，走 dsh 审批

memory_list · 只读摘要列表（调试用）

memory_refresh · 手改 Markdown 后重建派生索引

模型不能设置 trust、pinned、verifiedBy，也没有 memory_verify 工具。验证、争议、恢复、置顶等操作仅通过 CLI 或右侧边栏暴露给用户。

命令行

发布包提供 dsh-memory CLI，直接操作同一个记忆库；写操作以用户身份执行。

dsh-memory --help
dsh-memory list --scope all
dsh-memory search "pnpm build" --limit 5
dsh-memory show <id|slug>

dsh-memory write --slug use-pnpm --kind preference \
  --title "Use pnpm" --summary "Use pnpm for builds" --body "pnpm build"
dsh-memory edit <id|slug> --summary "Updated summary"
dsh-memory review --scope all

dsh-memory verify <id|slug>
dsh-memory dispute <id|slug>
dsh-memory restore <id|slug>
dsh-memory pin <id|slug>
dsh-memory unpin <id|slug>
dsh-memory forget <id|slug> [--hard]

dsh-memory resolve <keep> <other> --mode keep|merge|both [--summary "merged"]
dsh-memory supersede <old> <new>
dsh-memory refresh
dsh-memory core
dsh-memory stats
dsh-memory doctor --fix --json
dsh-memory export --scope user --format agents --out AGENTS.md
dsh-memory import ./memories --scope user

• 全局选项：--dir <path>（默认 $DSH_HOME/memory）、--cwd <path>、--json。
• write / edit 支持 --body-file <path>；write 默认 `--s

…(truncated)