dsh-cross-memory
Verifieddsh-cross-memory · v0.2.5 · MIT · Web UI
Cross-session memory for the DeepSeek Harness: project-scoped and global memories with an explicit memory tool, idle-time background extraction, consolidation, and layered summary injection
Install
dsh plugin add dsh-cross-memory Confirm the layer applied with dsh --profile default --dump-config — see the install guide.
Source
Tags
Creators
Readme
dsh-cross-memory
给 DeepSeek Harness(DSH)的跨会话记忆插件:把会话里值得长期保留的内容抽取成条目,按作用域存进本机记忆库,在后续会话里按需注入。适合长期用 DSH 做开发、希望助手记住项目约定与个人偏好的用户;记忆库默认只在本机,可审计、可恢复。
# 最短安装:装进目标 profile,装完重启该 profile 的进程
dsh plugin --profile <profile> add dsh-cross-memory
- 两种作用域:
global(所有项目共享)与project(按工作区隔离)。 - 三条协同路径:模型可调用的
memory工具、空闲时的后台抽取、有界的摘要注入与按需召回。 - 只写本机:记忆库默认在
$DSH_HOME/memories,不上传任何服务;多机同步需要你自己配置一个 Git 仓库。 - 可审计:每条记忆带来源、时间与(自动抽取时的)会话证据;归档可恢复,不静默删除。
安装
包是标准 DSH profile bundle,用 dsh plugin 装进目标 profile。上面是从 npm 安装的最短路径;也可以从本仓库的本地检出安装(这个包在 monorepo 的 packages/dsh-cross-memory):
# 从本地检出安装:先在仓库根构建,再按实际路径装
pnpm install && pnpm run build
dsh plugin --profile <profile> add /path/to/packages/dsh-cross-memory
安装后重启该 profile 的进程(dsh web 这类长驻进程不会热加载新 bundle)。dsh --profile <profile> --dump-config 里应能看到下面这一行:
- id: memories # 插件在 profile 里的固定 `id`,设置页与配置项都按它寻址
name: dsh-cross-memory
插件在组合里的
id始终是memories,与包名无关。从旧包名迁移时,删掉旧的插件行、按新包名重装即可;记忆数据目录不变。
lib/是构建产物、不入库,从源码安装前要先构建(pnpm install && pnpm run build);包自己的prepare钩子(npm run build)执行的是同一条构建命令。pnpm 默认拦截依赖的安装脚本,按它打印的 key 加进allowBuilds后重跑即可;从 npm 安装不需要这一步。在本仓库里用
file:从本地路径安装时,macOS 上是硬链接副本:pnpm build会写穿已存在的文件,但新增文件或git checkout/merge之后链接会断,用pnpm verify:profile自查(--fix补链接);Windows 上是符号链接,没有这个问题。
快速上手
在一个会话里说一句值得记住的事,然后:
/memories mine # 立刻从当前会话抽取一次打开 设置 → 记忆 查看条目;或让模型直接调用
memory工具:memory write scope=global title="Prefer pnpm over npm" body="..." kind=preference下一个会话开始时,摘要会自动注入;之后可用
memory search或/memories search <query>检索细节。
功能
| 能力 | 说明 |
|---|---|
| 显式写入 | 模型调用 memory 工具写入/更新/检索/读取/遗忘;标题即身份,同名再写是更新。 |
| 后台抽取 | 会话空闲或按周期被扫描,用一次辅助模型调用抽取可复用的事实;落盘前做密钥擦除。 |
| 合并重整 | 受限子代理对一批记忆去重、改写、退役;有风险的决定进入「待裁决」由你决定。 |
| 分层注入 | 每个会话注入一次有界摘要;另有按需补注(当前这轮明显相关时)、标题轮转与增量块。 |
| 按需召回 | 关键词 + 时间衰减 + 一跳扩展;命中原因可在日志里核对。 |
| 原始片段(可选) | 补注块可附带来源会话的原文片段,默认关闭,因为它会把别的会话的原文带进当前上下文。 |
| persona | 维护「这个人是谁」的画像(persona/human.md),注入在记忆摘要之前,默认预算 12000 字节;设置 → 记忆 → 画像 可查看/编辑,并可锁定不让后台改写。 |
| 开放承诺 | 把会话里答应过、但还没到期/没做的事记成台账,到期未闭环会提醒。 |
| 反思与技能草稿 | 每周从记忆里提炼跨项目观察(必须引用来源记忆);可把重复流程提成技能草稿,需你手动晋升。 |
| GUI | 设置 → 记忆:浏览/搜索/新增/删除、画像查看/编辑与锁定、配置项、待裁决;插件页该包下也有同一张配置卡。 |
画像
- 在哪看:画像是记忆库里的
persona/human.md(旧的单文件persona.md仍兼容读取)。每次会话开始时它被包进<persona>…snapshot 日期…</persona>,注入在记忆摘要之前;超过personaMaxBytes(默认 12000,0 关闭)的部分按行截断。 - 怎么编辑:设置 → 记忆 → 画像,改完点「保存画像」即写回,不经过后台合并,不用重启宿主。
- 锁定:同一页勾选「锁定画像」会在画像旁边写
persona/human.lock;锁定后后台 consolidation 即使提出画像改写也会跳过(日志会记persona is locked; the automatic profile update was skipped),只有你手动保存才会改变它。取消勾选即解除。
更细的设计说明见 docs/DETAIL.zh.md(英文版 docs/DETAIL.md)。
配置
配置分两层,都在插件那一行的 config 下。
部署层(4 项,改完需要重挂这一行):
- id: memories
config:
# dshHome: /custom/dsh-home # 默认 $DSH_HOME(未设置时为 ~/.dsh)
memoriesDir: /custom/path # 默认 $DSH_HOME/memories
projectRootMarkers: ['.git'] # 向上找工作区根的标记
# logFile: /custom/path/log # 默认 $DSH_HOME/logs/dsh-cross-memory.log;显式写空串关闭文件日志
可调项(65 项,都是 .volatile() 字段):修改后立即生效,不需要重启,也不会重挂插件实例。可以在设置 → 记忆 → 配置里改,也可以直接改当前 profile 的 patch。常用项如下:
| 键 | 默认 | 说明 |
|---|---|---|
maxSummaryBytes |
8192 |
每会话注入摘要的总字节预算;0 关闭注入,只留工具 |
maxSummaryEntries |
20 |
每个作用域最多列出几条 |
globalSummaryEntries |
6 |
全局段最多列几条(两作用域共用总预算,全局段先渲染) |
globalSummaryBytes |
1200 |
全局段单独占的字节预算;0 不注入全局段 |
summaryFreshSlots |
3 |
每作用域预留几个名额给从未出现过的记忆,避免老条目长期占位 |
recallMode |
on-demand |
once 只注一次摘要 / on-demand 额外按需补注 / off 只用工具 |
recallMinScore |
6 |
按需补注的相关度下限;与 recallMinTerms 一起构成精度门槛 |
recallMinTerms |
1 |
补注所需的实词数。中文改写常只共享一个实词,故默认 1,靠分数门槛控噪声 |
recallMaxPerConversation |
8 |
一个会话最多按需补注多少条记忆;0 关闭 |
recallMaxBytes |
2400 |
每个按需补注块的字节预算;0 关闭 |
injectDelta |
true |
摘要注入后新写入的记忆以增量块补发,每会话最多两次 |
deltaMaxBytes |
1600 |
每个增量块的字节预算;一条完整条目约 200–350 字节,0 关闭增量块 |
rotationEntries |
16 |
每会话额外列出多少个未出现过的标题;0 关闭标题轮转 |
rotationEveryTurns |
8 |
同一个长会话里每隔多少个用户轮重新发一次标题轮转块;0 只发一次 |
rawRecall |
false |
补注块是否附带来源会话的原文片段(默认关闭) |
maxEntriesPerScope |
0(不限制) |
每作用域保留上限;0 表示不设上限,条目一直保留,由召回排序决定用哪些。设了上限后超出部分归档最久没被读到或注入的条目(手写、pinned、permanent 除外) |
maxUnusedDays |
0(关闭) |
多久没用就归档(手写、pinned、permanent 除外);0 关闭。关闭时未读条目只是排序靠后,不会消失 |
snapshotMaxAgeDays |
0(关闭) |
durability: snapshot 条目的过期天数;0 关闭 |
dedupeSimilarity |
0.7 |
标题与正文字词重合度超过多少时,新记忆取代旧记忆 |
sweepIntervalHours |
12 |
定期整理间隔;0 关闭 |
autoExtract |
true |
是否启用空闲后台抽取 |
autoExtractIdleMs |
300000 |
空闲多久后触发一次抽取 |
extractIntervalMinutes |
30 |
周期性抽取间隔;0 关闭周期检查 |
minIdleHours |
6 |
会话至少空闲多久才可被抽取 |
maxAgeDays |
10 |
超过这么多天没活动的会话不再抽取 |
consolidate |
true |
是否启用合并重整 |
consolidateCooldownHours |
6 |
两次合并之间的最小间隔 |
autoDecide |
true |
允许 AI 裁决本会排队等你的合并决定 |
syncRemote |
空 | 记忆库同步用的 Git remote;空 = 只在本机提交 |
syncClock |
12:05,18:05 |
定时同步的本地时刻;空则回退到 syncIntervalMinutes |
syncIntervalMinutes |
10 |
后台同步间隔;0 关闭定时器 |
syncDebounceSeconds |
2 |
一批连续写入合并成一次本地提交的等待时间 |
extractProvider / extractModel |
空 | 抽取调用的模型路由;空则沿用会话路由 |
logLevel |
info |
插件日志详细程度:off/error/warn/info/debug |
完整字段与逐项说明以设置页「配置」标签为准(也可 dsh --profile <profile> --dump-config)。
memory 工具
| action | 参数 | 作用 |
|---|---|---|
write |
scope + title + body;可选 tags、keys、kind、appliesTo、durability、asOf、pinned、permanent |
写入或更新一条记忆 |
search |
query? + scope? + tags? + kind? + limit? |
检索;query 为空时按最近更新列出;limit 默认 8、上限 25 |
read |
id + scope? |
读全文(默认先项目、后全局) |
forget |
id + scope? |
删除一条(不可恢复) |
evidence |
id 或 evidenceSession,可加 scope? |
读这条记忆背后的会话证据笔记与逐字引文 |
kind 取值:fact / preference / knowledge / failure / procedure。
/memories 命令
/memories 显示用法(等同 /memories help)
/memories list [global|project] 列出记忆
/memories search <query> [--kind <kind>] 检索
/memories show <id> 看全文
/memories add <global|project> <text> [--kind <kind>] 手工写入
/memories forget <id> 删除(不可恢复)
/memories archive [global|project] 列出已归档
/memories restore <id> 从归档取回
/memories mode [on|off] 本次会话临时关闭/开启记忆(也可直接 /memories on、/memories off)
/memories mine 立刻从当前会话抽取一次
/memories backfill [--apply] [--days N] [--limit N] 回填本进程没见过的历史会话(默认只估算,`--days` 默认 30,`--limit` 默认 3)
/memories consolidate 立刻跑一次合并
/memories plan / apply / reject 查看与裁决待处理合并
/memories sweep 立刻跑一次保留整理
/memories notices [test | ack <id> [acted|dismissed|snoozed]] 查看通知队列,test 发一条系统通知
/memories loops [done <id>] 查看承诺台账,或把一条标记为已完成
/memories reflect [now|list] 查看反思文件;now 只提示它按周在维护路径上运行
/memories stale 列出引用了已不存在文件的记忆
/memories skills / promote <name> / discard <name> 技能草稿管理
/memories stats 存储位置与计数
数据存储
记忆库默认在 $DSH_HOME/memories($DSH_HOME 未设置时为 ~/.dsh)。条目是人类可读的 Markdown + 简单 frontmatter,文件是唯一真相;水位线、任务租约、用量计数等状态放在同目录的 SQLite(state.db,Node 内置 node:sqlite,无外部依赖):
$DSH_HOME/memories/
├── index.json # 可重建的索引缓存
├── entries/<id>.md # 每条全局记忆一个文件
├── archive/<id>.md # 归档的全局记忆(可恢复)
├── projects/<slug>/
│ ├── project.json # slug 与根路径映射
│ ├── hosts/ # 用过这个项目的机器
│ ├── entries/<id>.md
│ ├── archive/<id>.md
│ └── index.json # 该项目作用域的索引缓存
├── sessions/<session-id>.md # 证据笔记(被挖掘过的会话)
├── skills/<name>/SKILL.md # 技能草稿(未晋升前 DSH 看不到)
├── persona/ # persona 画像(human.md;human.lock 存在表示已锁定)
├── reflections/ # 每周反思
├── pending/consolidation.json # 待裁决的合并方案
├── loops.json # 承诺台账
├── notices.json # 通知队列
└── state.db # SQLite 状态
插件自己的日志默认写在 $DSH_HOME/logs/dsh-cross-memory.log,单文件到 2 MB 时轮转一代(旧文件改名为 <path>.1,只保留这一代)。npm run report 只读地汇总日志与 state.db:默认读 $DSH_HOME(未设置时 ~/.dsh),--home=<dir> 指定别处,--examples=N 控制每节展示条数。
隐私边界
- 默认不联网。记忆只写在
$DSH_HOME下,不往你的工作区仓库写文件;Git 同步默认关闭。 - 后台模型调用会经过你配置的模型路由(默认沿用会话自己的路由)。抽取输入是会话尾部,只取用户与助手正文,丢弃工具结果和插件注入的内容,避免记忆自噬;落盘前做密钥擦除(
sk-…、ghp_…、AKIA…、JWT、私钥块、api_key=…、Bearer …等)。 - 注入的内容是背景数据,不是指令:注入块会明确告诉模型,记忆记录的是写入时的事实,不一定现在仍成立。
- 原始片段是 opt-in:
rawRecall默认关闭;打开后补注块会附带来源会话的原文(只读本机会话日志)。 - 通知可选:默认通过操作系统通知提醒(每日摘要、积压警告、到期承诺),
noticeQuietHours可设置静默时段,noticesEnabled: false完全关闭。通知投递目前只在 macOS 生效(走osascript);其他平台投递失败,通知仍留在队列里,可用/memories notices查看。 - 彻底关掉后台行为:
autoExtract: false、consolidate: false、reflectionEnabled: false;再设maxSummaryBytes: 0或recallMode: off就只剩memory工具与/memories命令。 - 归档与合并只动
$DSH_HOME下的文件;归档条目可restore,合并失败的改动会回滚。
多机同步(Git)
记忆库本身就是一个 Git 工作副本。把 syncRemote 指向你自己创建的私有仓库,多台机器就会共用同一份记忆:
- id: memories
config:
syncRemote: https://github.com/<you>/dsh-cross-memory-store.git
# 或 [email protected]:<you>/dsh-cross-memory-store.git
- 写入路径只做本地提交(
syncDebounceSeconds默认 2 秒合并一次);拉取与推送在后台定时进行。 - 默认同步时刻
syncClock: 12:05,18:05(DeepSeek 谷时开始后几分钟,冲突合并成本最低);留空则按syncIntervalMinutes(默认 10 分钟);0关闭定时器,只保留手动同步。 - 冲突处理:能安全合并的自动合并;可能丢信息的进入 设置 → 记忆 → 待裁决(或
/memories plan)。autoDecide开启时由 AI 先判断「这次改动是否丢信息」。 - 不入库的状态:
state.db*、各级index.json、pending/、project.json、*.log、.DS_Store。 - 同步仓库需要你自己创建并保护;插件不会替你创建远端,也不会向未配置的地址发送数据。
兼容性
| 依赖 | 区间 |
|---|---|
| DSH | ^0.2.1-rc.2 || ^0.2.2-alpha.2 |
| Node.js | >=24(与 DSH 宿主自带运行时一致) |
| Cordis | ^4.0.5 || ^4.0.6-alpha.1 |
| Schemastery | ^3.18.5 || ^3.18.6-alpha.1 |
@deepseek-ai/* 均为 peerDependencies,由宿主提供,插件不另装内核包。本包在 DSH 内核 0.2.2-rc.1 上开发和测试(devDependencies 锁定 Cordis 4.1.0、Schemastery 3.19.0)。不同内核版本的子代理约定差异(预设路线 / 无预设直调 / 老内核黑名单路线)已在插件内适配。
开发
npm i # 或 pnpm i;prepare 钩子会构建一次
npm run typecheck # tsc --noEmit
npm run build # tsc + 客户端 bundle,产物在 lib/
npm test # 编译后跑 node --test
npm run smoke # 用真实 Cordis 根加载插件,检查注册结果
npm run report # 只读汇总日志与 state.db
src/是 TypeScript 源码,client/是浏览器半边(构建时拼成lib/client.js),lib/是构建产物、不入库。scripts/下有回填、检索评测、召回日志评测等运维与评测脚本;bench/是基准与真实会话评测,其数据与语料不入库。- 改动宿主半边(
src/*.ts,重新npm run build后)需要重启 DSH 宿主才生效;只改浏览器半边刷新页面即可。
License
MIT © 2026 Cooper Zhuang