Saltar al contenido principal
K

dsh-biomemory

klrsl/dsh-biomemory

Sistema de memoria biomimético para DeepSeek Harness: un único almacén SQLite (node:sqlite, WAL) cuyo árbol Markdown se mantiene como espejo de solo lectura; herramientas de memoria, inyección de instantánea congelada al inicio de la sesión, puertas de aprobación escalonada, extracción bajo demanda de la sesión actual, fusión de casi duplicados, un ciclo de vida de archivo y reemplazo, metabolismo de memoria (dream), anclajes de memoria, recuperación semántica sobre incrustaciones locales, y el comando /memory.

Instalar

dsh plugin --profile web add github:klrsl/dsh-biomemory

README

dsh-memory-layer

给 DeepSeek Harness 的记忆层:记住你的偏好和决定,换个会话它自己会想起来;数据只在本机,随时能查能改。

v0.11.3 · MIT License · DSH 0.2.x(>=0.2.0-rc.2 <0.3.0-0,0.2.1-rc.3 桌面版实测)· Node ≥ 22.19.0


它是什么

一句话:只做记忆,不做记忆平台。

  • 不做:外置服务、向量检索、嵌入模型、知识图谱、云端同步、Web UI。
  • 做:一个 SQLite 单文件 + 一个"什么时候该想起什么"的确定性规则集。

它和"记忆平台"(如外置记忆服务)的区别,不是功能多少,而是没有额外要跑的东西:装完就是一个插件,数据在你自己机器的 .dsh/biomemory/biomemory.db 里,拷走文件就是迁移。

四层结构

1. 存储层:单文件 SQLite

字段含义
realm隔离维度:user 或 project:<工作目录>
mtype记忆类型:workflow / error / decision / fact
trigger触发信号串(见下)
mkey同键覆盖用的主题键
text正文
created_at / last_accessed / last_used / hits生命周期:写入时间 / 最近被注入 / 最近真实使用 / 真实使用次数
statusactive / archived / deleted(remove 是墓碑,不物理删;只有 purge 不可逆)

另有两张辅助表:chains(工作流链)、trigger_counts(触发次数,用于工作流升级)。

v0.11:last_accessed(被看到)与 last_used(真被用上)必须分开。 混为一谈时,触发召回每组装一次提示词就把命中条目刷新成"刚用过", 清理规则的 30/90 天判据会被自己喂饱、永不触发。

2. 召回层:触发信号驱动

不等模型"自己想起来",而是看当前会话发生了什么:

  • 信号来源:当前会话工作目录(session.cwd)+ 最近 12 次工具调用的名字与参数(文件路径、命令、错误代号都从这里来)。
  • 触发串只有三种形态,可读可解释:
    • file:<文件名> —— 例如 file:package.json
    • tool:<工具名> —— 例如 tool:pwsh
    • err:<错误代号> —— 例如 err:MODULE_NOT_FOUND
  • 命中即注入,排序 workflow > error > decision > fact,同类型按最近访问;命中工作流链则整条链一起注入。
  • 注入预算:每次最多 8 条、最多 1200 字符;没命中就一个字都不注入(不占 token)。
  • 偏好/决定通道(v0.11):触发串只能从文件名/错误代号里提取,而"偏好/决定"是纯自然语言 (实测 8 条典型偏好里 6 条没有任何 trigger)。给它们一条独立小预算(默认 ≤3 条 / ≤400 字符), 不与触发召回抢 1200 字符。
  • 冷启动兜底(v0.11):库还很小、还没攒出 trigger 关联时,零命中也不至于颗粒无收 (回落注入最近写入的几条;库一大就自动让位给触发召回)。

2.5 注入 ≠ 使用(v0.11)

被注入只刷新 last_accessed;只有下面两种情况才算真实使用、推进 hits 与 last_used:

  • memory action=query 的关键词命中;
  • 显式 memory action=used fp=<指纹>。

清理规则只认真实使用。这样"被想起过"不会阻止一条记忆最终被淘汰。

3. 清理层:五条可解释规则

/memory compact 执行,每次淘汰都写 compact.log:

  1. 同 realm + type + key 的新记忆覆盖旧记忆(旧条目标墓碑)——写在写入路径上(全等比较,不做前缀匹配);
  2. fact:真实使用超过 30 天没发生过(使用次数 ≤1)→ 进墓碑;
  3. workflow / error / decision:不设有效期;真实使用超过 90 天前 → 权重减半;
  4. error 与 decision 永不自动删除;
  5. 每条淘汰/降权都记 compact.log(时间 · 指纹 · 命中规则 · 摘要)。

锁定(pinned)的条目豁免全部规则;compact 只把 status 改成 deleted(墓碑,restore 能翻回来),所以写库路径不产生备份副本——需要事前快照请自己 dump 或拷库。

4. 适配层:工作流从重复里自己长出来

同一个触发串出现 超过 3 次,相关记忆自动升级为 workflow,并按时间顺序拼成一条链:

当 file:package.json 时:先看 package.json → 跑测试 → 再改代码

链是顺序记录,不是因果推断——不假装知道为什么,只如实记下"你上次是这么做的"。

安装

桌面版:按包名安装(推荐)

  1. 打开 DSH 桌面版 → 左侧 插件 → 加插件;
  2. 在包名输入框填 dsh-memory-layer,点 安装(安装完自动启用)。

命令行等价:

# 把 desktop 换成你的 profile 名
dsh plugin --profile desktop add dsh-memory-layer
dsh plugin --profile desktop add link:./dsh-memory-layer

安装完重启 DSH 生效(开了 HMR 的 profile 会热挂载)。

用法

工具 memory

action说明
add写入一条记忆(text 必填;`track=user
query关键词查询(text/topK/fragmentTypes/includeArchived);关键词命中记一次真实使用
used标记"这条刚才真的用上了"(推进 hits 与 last_used,影响清理规则)
list / update浏览 / 改
remove标墓碑(行还在库里,restore 可回滚)
purge物理删除(不可逆;不落备份副本——备份会把该消失的内容留在同一台机器上)——只给误存密钥这类场景
restore / pin / unpin回滚 / 锁定 / 解锁
compact按五条规则清理(dryRun=true 只预览;实跑只改 status,不备份)
dump导出人类可读 Markdown(含工作流链;保留最近 10 份)

写入(add / update)时,若正文含「今天 / 昨天 / 下周」等相对时间却没有绝对日期锚点(YYYY-MM-DD、M月D日、20xx年),成功返回的 note 会附一行提醒;写入照常成功,不拒绝——因为拒绝会丢信息。

还有一个 memory_recall 工具,用于"你还记得…吗"式的显式召回。

命令 /memory

/memory list | query <词> | add <内容> | edit <fp> <新内容> | entries [词]
/memory remove <fp> | purge <fp> | undo <fp> | unarchive <fp> | used <fp>
/memory pin <fp> | unpin <fp>
/memory stats | why <fp> | preview
/memory compact [--dry-run] | dump | help
  • stats:健康度——活跃条数、墓碑/归档数、类型与 realm 分布,以及 trigger 覆盖率 (有多少记忆没有任何触发串 = 永远不会被主动想起,只能靠偏好通道或常驻快照出场)。
  • why <fp>:这条记忆为什么(不)会被注入——命中了哪个触发串、realm 是否匹配、优先级、 真实使用次数。
  • preview:预览"如果现在组装提示词,会注入什么"(含偏好通道、触发命中、冷启动三段与预算占用)。

写入审批

重要记忆(用户偏好/决定/纠正类)走 DSH 官方审批:批准才落库,审批服务不可用时默认拒绝(fail-closed,可用配置 approvalFallback=auto 放宽)。

数据与隐私

  • 全部本地:零外部请求、零外部 API、零遥测。
  • 数据库:<DSH_BIOMEMORY_DIR || ~/.dsh/biomemory>/biomemory.db(SQLite,WAL)。
  • 删除是墓碑(可恢复),compact 也只在库内改状态;写库路径一律不产生备份副本(purge 尤其不能留副本),需要快照就 dump 出 Markdown 或自己拷库。
  • 环境变量:DSH_BIOMEMORY_DIR(数据目录)、DSH_MEMORY_ROOT(Markdown 备份/日志目录)。
  • 配置目录说明:配置文件在 <DSH_MEMORY_ROOT || ~/.dsh/memory>/biomemory.config.json (v0.11 修正:旧文档写成 ~/.dsh/biomemory/,与实现不符——库在 biomemory/、配置与导出在 memory/)。
  • 本地 HTTP 端点(宿主 webServer 存在时注册 /biomemory/api):默认只接受本机来源, 跨站请求一律 403;必要时可用 DSH_MEMORY_API_ORIGINS 放开指定 Origin, 或 DSH_MEMORY_API_NOAUTH=1 关闭校验(不建议)。

配置

<DSH_MEMORY_ROOT || ~/.dsh/memory>/biomemory.config.json(或 bundle config)可覆盖:

键默认说明
nearDuplicateThreshold0.7写入去重的相似度阈值(0=关闭)
nearDuplicateActionmerge命中近重复时合并 / skip 只提示
approvalFallbackdeny审批不可用时拒绝 / auto 自动保存
decayThreshold3状态页"低权重待处理"的阈值
hotTokenLimit2000常驻快照注入的 token 上限(v0.11:5000→2000,让触发召回成为主通道)
maxQueryResults20查询返回上限
weightCap20权重上限(防膨胀)
sinkWindowMinutes5轮次结束后"请沉淀"提示的有效窗口(分钟)
decisionChannelMax3偏好/决定通道每轮最多注入条数(0=关闭)
decisionChannelChars400偏好/决定通道每轮字符预算(0=关闭)
coldStartFallbackMax3冷启动兜底条数(0=关闭)
injectSnapshottrue宿主注入开关:记忆快照段(order -50)。false = 该段完全不注册
injectRecalltrue宿主注入开关:触发式召回段(order -40)
injectSummarytrue宿主注入开关:轮次结束沉淀提醒段(order 200)

三个 inject* 是「宿主注入开关」:默认 true 保持现行为;退成纯数据层(只存只查、不进 prompt)时全置 false。它们在插件 apply 时读取,改完需重启宿主或重载插件才生效(只改 biomemory.config.json 不会热切换)。

设计上刻意不做的事

  • 不做向量/嵌入检索:相同输入必须给相同结果,检索要可解释。
  • 不做自动"反思":没有模型就不假装会归纳;工作流只从重复里浮出来。
  • 不做删除即销毁:一切删除留墓碑,误删可回滚。
  • 不做跨机同步:那是另一类产品;这里只保证文件可以整体搬走。

版本历史

版本日期变更
v0.11.32026-10-31退成数据层的准备 + 日期校验:新增宿主注入开关 injectSnapshot / injectRecall / injectSummary(默认 true 保持现行为;全置 false = 只存只查、完全不进 prompt;apply 时读取,改后需重载)。写入含相对时间(今天/昨天/下周…)且无绝对日期锚点时,add / update 的成功返回附一行提醒,写入照常成功(锚点:YYYY-MM-DD / M月D日 / 20xx年;「最近 / 目前」不触发)
v0.11.22026-10-31按已发布的 0.11.1 回灌仓库 + 收口:0.11.0/0.11.1 的源码树丢失,以 tgz 为准恢复模块(代码与 0.11.1 逐字节一致,功能无变更);README 版本曝光、ARCHITECTURE 测试指向、SECURITY 支持版本与 audit.log 说明、CI Node 22.19 矩阵、.gitignore 白名单同步修正;删除 2 条 0.10 语义旧用例、同键覆盖用例改为全等键;删除 stale pnpm-lock.yaml。详见 CHANGELOG.md
v0.11.12026-10-28写库不再自动备份 + 测试随包发布:compact / purge / 指纹迁移口径统一为「不落备份副本」(墓碑可 restore,purge 反而不能留副本,backupDb() 降为手工入口);files 补 tests 并新增 tests/core.test.mjs(零依赖,装完即可 npm test)。详见 CHANGELOG.md
v0.11.02026-10-27数据正确性与可观测性:修 includeArchived 会返回已删除墓碑条目;remove 改为真墓碑(物理删除收敛到 purge);指纹改全文哈希(旧算法前 20 字撞车会静默丢记忆)+ 一次性重算迁移;同键覆盖改全等(前缀匹配会误墓碑);注入与真实使用分开计数(last_accessed / last_used),清理规则不再被自反馈喂饱;写入路径按会话 cwd 推断 realm;沉淀状态与会话信号按会话分桶;本地 HTTP 端点加来源校验;selfHeal 不再抛出。新增:偏好/决定独立通道、冷启动兜底、/memory stats(含 trigger 覆盖率)/ why / preview / used / purge / unarchive / help、快照缓存、dump 轮转
v0.10.22026-10-25简介换成「记住偏好与决定、换会话自动带上」的说法,桌面版实测版本改 0.2.1-rc.3;功能无变更
v0.10.12026-10-25插件卡片文案重写:中英双语显示名与一句话简介(locale 的 meta),description 去掉版本号与功能罗列;功能无变更
v0.10.02026-10-05重构为「记忆层」:新增触发式召回(trigger + realm + mtype + mkey 四列)、类型优先级排序、五条清理规则 + 墓碑 + compact.log、工作流从重复中升级并成链、注入预算(≤8 条 / ≤1200 字符)、compact/dump;移除记忆代谢(dream)、深度反思(reflect)、冲突裁决、结构化审计与自动 Markdown 镜像
v0.9.22026-09-29删死模块与死配置键;文档与实现对齐(配置表/API 表/测试数)
v0.9.12026-09-29移除管理 UI,插件退化为纯宿主能力
v0.9.02026-09-29移除嵌入模型与 semantic/hybrid 检索,改单一确定性检索路径
v0.8.22026-09-20合规化批次:审计双写修复、配置按类型落库、近重复写入去重
v0.8.02026-09-16写入去重(bigram 相似度)+ 合并/跳过两种策略
v0.7.02026-09-17镜像同步钩子(v0.10.0 已移除)
v0.6.42026-09-06单轨制:SQLite 为唯一事实来源,Markdown 降级只读备份
v0.6.02026-08-19架构拆分(shared/store/retrieve/snapshot/gate)+ 会话沉淀
v0.5.02026-08-15数据层迁移到 SQLite(node:sqlite)

License

MIT — 详见 LICENSE。

Plugins relacionados