33moren33 / dsh-memory-pyramid

---

装上之后，模型每次自动注入“金字塔”记忆；攒多之后，视图自动压成金字塔形：

### Memory view (40 facts)

#0-31   摘要：这段时间在打通插件加载链路，结论是...
#32-35  摘要：注入改走 systemPrompt 的动态上下文...
#36-37  摘要：数据目录改落工作区，避免家目录被运...
#38     2026-08-15 摘要树按块大小分层存储，待办...
#39     2026-08-15 定宽记录不存序号：位置即身份...

越靠近现在越是原文，越老越粗——但原文一条都没丢，随时可以下钻回去。

金字塔记忆结构

每记满两条事实，agent 就继续往上层进行摘要总结一次；两行这样的话再凑满一对，就写一行更粗的。每往上一层块数减半，形状就是一座塔：

                  [ #0-127 ]                      ← 1 行 · 代表全部 128 条
            [ #0-63 ]    [ #64-127 ]              ← 每行代表 64 条
      [#0-31] [#32-63] [#64-95] [#96-127]         ← 每行代表 32 条
   ········································
  #0 #1 #2 #3 ··················· #126 #127       ← 塔基：128 条逐字原文

开局那份视图，就是沿着塔斜着下楼梯：去年的事读塔尖一行，上个月的隔一块中层砖，昨天的直接站在塔基逐字读。塔基永远不动——粗砖只是地图，memory_zoom 两行就下到原文。所以记忆涨十倍，开局要读的行数一行不多。

形状来源：金字塔形状参考自 Victor Taelin 的 OptMem极简记忆理念。真正实现在 dsh 里自己探索、摩擦出来的，目前在致力于更加完善的记忆机制-（记忆与对话事实链接、面板、后台并行）——见后续路线图。

常见记忆机制比较

	切哪根轴	记的是
agent-instructions（AGENTS.md 门规链）	空间	在哪个目录下该守什么规矩
检索式记忆（RAG 一类）	相关性	跟当前问题像的东西
dsh-memory-pyramid	时间	先后发生过什么、当时为什么那么定

三轴正交、可以叠着用。官方目前只占了空间轴，时间轴整根空着——这就是本插件的落点。

目前仅串行，agent自主决定工具调用，没有任何后台进程。

项目后续更新路线图：1.并行后台结算（写记忆交给专职分身，主线一个字的注意力都不付，特定token与对话数后，后台更新记忆）2.记忆看板（人用时也能看到，管理项目记忆，金子塔式的直观可视化）3.唯一对话事实事实层绑定回溯，点一条跳回产生它的那段对话，看到记忆的全生命周期。

特性

金字塔机制

• 事实一行 ≤280 字节，只追加、永不修改；摘要由 agent 记录时顺带维护——无后台进程、无定时器
• 固定阅读预算：装得下就一点不压缩，装不下越老越粗、从不截断
• 摘要写坏有正式重画通道（memory_forget），并连坐丢弃由它推出的更粗摘要

🔧 dsh 原生适配

• 原生 dsh 插件积木，不是外部命令行，脚本——不需要 shell 权限
• 注入通道是拿真实账单选出来的：视图放系统提示词会打爆 prompt cache，改走官方动态上下文通道后整场命中率 40%→91%（下文有对账表）
• 会话区间锚点：每条事实记下它蒸馏自哪段对话（sessionId + seq 区间）——dsh 有全量会话流水这份原料，这是 OptMem 的运行环境里不存在的能力
• 官方AGENTS.md的机制依旧生效
• 数据目录认领 / 自动搬迁 / 拒绝拼接——宁可不工作，也不在别人的目录上写字

工程性质

• 零 npm 依赖、零原生模块，Node ≥ 19
• Windows / Linux / macOS / ARM64
• 多进程共写同一份记忆无锁且正确——靠减掉一个字段，不是加一把锁
• 数据落工作区、纯文本、对 diff 友好，可建 git 进一步管理

快速开始

系统要求

• 已安装 DeepSeek Harness，dsh web 可正常启动。
• 已安装 pnpm（dsh 用它装插件，Windows / Linux / macOS 同要求）：npm install -g pnpm
• 从仓库安装另需 git；插件本体零依赖、无构建步骤，Node.js ≥ 19。

三步上手

1. 安装：dsh plugin --profile web add dsh-memory-pyramid
2. 重启 dsh web（profile 启用了 HMR 时会直接热生效，这步可省；没见到再重启）
3. 新建会话——开局即见 Memory view，模型开始自动记忆

从 npm 安装（推荐）

一条命令，装完即激活——包自带 dsh.bundle 声明，dsh 自动把它加入 profile 层栈，一个配置文件都不用改：

dsh plugin --profile web add dsh-memory-pyramid

也可以把这条命令直接交给 dsh agent 替你执行。

从 GitHub 仓库安装（开发调试）

零依赖、纯 ESM、无构建步骤；link: 装的是引用，之后 git pull 即更新：

git clone https://github.com/33moren33/dsh-memory-pyramid.git
dsh plugin --profile web add "link:/绝对路径/dsh-memory-pyramid"

验证与卸载

装好重启 dsh web，新建会话开局出现 ### Memory view 段就是生效了；也可以用 dsh --profile web --dump-config 确认 dsh-memory-pyramid 已进合成树。启动日志里还会打印一行数据目录认领信息。

卸载：dsh plugin --profile web remove dsh-memory-pyramid，然后重启 dsh web。

想改配置（如 wakeLines）：在 profile 的 cordis.patch.yml 里对同一个 id 覆盖，热生效：

- id: memory
  config:
    wakeLines: 192

实际注入（真实会话实拍，模型不用任何工具，直接凭注入的视图作答）：

常见问题

装插件时报 pnpm not found / 装 pnpm 时报目录没有写权限？ dsh 靠 pnpm 管理插件，先 npm install -g pnpm。写权限报错常见于 Linux 用系统包管理器装的 Node——装到用户目录即可：npm install -g pnpm --prefix ~/.local，并把 ~/.local/bin 加进 PATH。

记忆到底落在哪？ 落在 dsh 服务进程的启动目录下的 dsh_memory/。headless 一任务一进程、从工作区起，落点就是工作区；但 web GUI 是一个常驻进程服务多个工作区——在界面里切换会话工作区不会切换记忆落点，所有会话共享启动目录那一份。所以：请从你的工作区目录里启动 dsh web。

peer 警告 @deepseek-ai/cordis missing 要紧吗？ 不要紧。cordis 只被类型注释引用、没有运行时 import，dsh 自己带着 cordis。v0.1.1 起已去掉这条声明；旧版本看到可直接忽略。

会话开到一半新记的东西，视图里怎么没有？ 默认就是这样：视图只在会话开局注入一次（省注入 token），会话内新写的记忆在工具回执里、模型看得见，新开会话即见全部。想要实时更新，配置里把 liveView 设为 true。

配置

键	默认	说明
namespace	无	公共区名字。填了就落在 <工作区>/<名字>/dsh_memory。只收单层目录名。
dataDir	无	完全自定义路径（绝对，或相对工作区根）。填了就压过 namespace。
migrate	true	换落点时，自动把工作区里找到的旧记忆整体搬过来。
wakeLines	96	记忆视图的行数预算。这是阅读预算不是存储预算——随时改，一块摘要都不用重算。
injectWake	true	是否把记忆视图注进开局上下文。关掉后工具照常可用，只是不再自动出现。
packs	无	只读挂几个别的记忆库到看板上当参照，形如 [{name: "示例", dir: "路径"}]。一个字节都不写：不记它的用量、不补它的摘要、不给它渲染注入视图。用处是刚装上、自己还没攒够记忆时，先看看塔长什么样——70 条与一万条完全是两回事。
liveView	false	会话中途记忆变化时是否实时更新视图。默认关：视图只在会话开局注入一次，会话内新写的记忆走工具回执、新会话开局可见全部。开了之后每次记忆变化都会给会话追加一份最新视图（多花注入 token）。改配置热生效，当前对话下一条消息起按新开关走。

默认落在 <服务进程启动目录>/dsh_memory（不写家目录；headless 下即工作区，web GUI 见上文常见问题）。LOG.txt 纯文本只追加——进 git 团队可共享一份经历；TREE/ 是纯缓存，删了不丢事实。目录已存在时：标记对得上就认领（一条不动），对不上就拒绝启动并说明原因。两份记忆绝不会被拼接（记录靠位置寻址，拼接会让所有摘要整体指错），找到多份旧记忆时拒绝启动、交给人裁决。

工具面

工具	干什么
memory_note	记一条事实。一行，≤280 字节，只追加，永不修改。
memory_summarize	交摘要树的维护费：某一块凑满时，写下将来代表它的那一行。
memory_zoom	把任意 #a-b 节点打开成它的两个半块——下钻的便宜路子。
memory_recall	用正则扫全部事实（from/to 可夹住范围），或读某段原文。命中被截断时如实报出总数。每条都带会话区间锚点。
memory_open	顺着一条事实的锚，交回它蒸馏自的那份原文全文。
memory_forget	丢掉一块写坏的摘要，排队重写。只动地图，不动领土。

记忆看板

装上之后界面右下角多一个悬浮球，点开是占右半屏的看板——记忆第一次成了人看得见的东西。

一座真的塔：一块砖就是一块摘要，最底下一排是逐条事实。亮着的那些正在注入给模型，与模型此刻收到的视图同一份数据、同一套算法，不存在第二个真相。

点一块砖读它的正文；点最底排的一条事实，可以顺着它的出处走回去——出自对话的跳回那段对话并框住整轮，出自导入文本的直接打开那份原文。没有出处的按钮是灰的，不会假装有。

右下角是当场生效的旋钮：注入行数、每条字节、冻结/实时。

看板走官方给第三方留的正门挂载；没有 web 界面的场景（如 headless）自动缺席，记忆本体照常工作。

把已有文本导进记忆

记忆目录下有个 memory_handoff/ 文件夹，把文件放进去就算上架——没有写入工具，文件夹本身就是入口。

模型读完之后写下的每条事实都带着「出自哪一份」的锚，memory_open 顺着锚交回原文全文：一行事实说不清的细节，随时回得去。

上架时记下字节数与指纹。文件事后被改过，打开时会当场点破，而不是照吐给你。

它怎么做到不随记忆量变慢

1. 定宽记录 ⇒ 位置即身份。 第 N 条永远住在第 N×384 字节，读一条是一次 pread。记录里不存序号——顺带让多进程并发追加天然正确。
2. 摘要树也定宽，每层一个稠密前缀文件。 「这层做到哪了」＝文件长度 ÷ 288，一次 stat。待办是推导出来的，没有可以失同步的队列。
3. 压缩工作量恒定。 小块（≤16 条）读原文压；大块只读两个半块的摘要。写第 10 层和写第 1 层一样便宜，旧摘要永不返工。
4. 阅读预算固定，从不截断。 二分搜索找到恰好塞进预算的粗细；装得下时一点不压。改预算不重算任何摘要。

不打断 prompt cache

纪律段（静态）住在系统提示词里；记忆视图（写一条就变）住在动态上下文里。 分界只有一条：保证上下文缓存命中。

摘要会错，这是设计的一部分

塔尖是多代传话游戏，语义会漂移。所以原文永存（地图坏了不等于领土沉了）、memory_forget 是正式重画通道、摘要缺失时视图就地拆细直到落回原文——绝不显示一块不存在的摘要。

Roadmap

• v0.1 串行版：五件工具、区间锚点、缓存安全注入、OptMem TREE/ 字节级兼容
• v0.1.1 注入开关：视图默认只在会话开局注入一次（liveView 可换回实时更新，热生效）
• 注入通道完善：增量动态注入——按每个会话已见过的水位，只注入它没见过的部分
• 记忆看板：目前 Memory view 只有模型读得到，人看不见自己的记忆。计划做时间轴列表 + 金字塔层级视图，点一条记忆跳回产生它的那段会话（锚点字段现在就写对，就是为了那一天不用迁移数据）
• 金字塔教程：配流程图与截图，讲清楚这座塔怎么建、怎么读、怎么错、怎么修
• 并行结算：写记忆交给专职分身，主线零打扰；空闲时扫未认领的对话流水补漏
• OptMem LOG.txt 迁移转换器（TREE/ 可原样搬）

已知边界

• 多进程共写支持且无锁；但子 agent 不该写记忆（它看不见已记了什么），目前靠提示词约定，未在代码强制。
• 会话锚点已如实落盘并经 memory_recall 返回，但「顺着锚点打开当时会话原文」的工具还没有——那是并行结算版的活。
• 早期版本，注入形态还在演进（见 Roadmap 第一条）。完整的可靠性结论，留给后续实际测试与 issues 反馈来检验——发现问题请开 issue。

License

本项目基于 MIT 许可证开源。