记忆宫殿（dsh-memory-palace）

把会话原文按「一轮对话」为单位、分类归档到当前工作区的 memory-palace/ 目录。 目的：在 DSH 自动压缩之前，先把较早的完整原文落到磁盘，压缩后还能查回原话。

0.3.11 发布版：本地长期记忆。归档较早的整轮原文，提供四板块分级注入、项目档案与项目热记忆、项目档案家族共用、记忆家族与根转移、摘要关键词定位与候选翻页、手动注入、20K 分段、tag 关联检索、归档触发快路径与压缩恢复；数据都在当前工作区。 0.3.11 新增项目档案附件：独立附件框、单附件切换、系统选择器/手动路径挂载、外部文件不复制、最多 5 个；同时修复统计与全量校验并发。 0.1.x 的归档基础说明仍适用。

功能总览

• 热记忆四板块：identity（角色自我）、user 板块（用户画像）、rules（规则铁律）、memories（关键记忆）。
• 分级注入：mind-seal 每轮；important 每 5 轮 / 10k 输出 token；normal 每 12 轮 / 30k；minor 压缩后一次。共享计数器，受总预算约束。
• 项目档案：会话级 Markdown 文档，支持新建/编辑/启用/停用/归档/取消归档/软删除；启用档案进入小型注入清单，停用档案可按需读取，归档档案模型只得到错误；正文按 20K 分段加载。
• 项目档案筛选：列表按启用/停用/归档过滤，分页前生效；选择写入会话配置，重启后保留，不影响家族共用查询。
• 项目档案附件：每篇档案独立附件框，一次显示一个；最多 5 个，< > 与页码切换；支持系统选择器、手动路径和 http(s) 网页链接；外部文件只挂路径、不复制、不限大小，删除只摘索引；文件丢失显示“（已丢失）”。
• 项目热记忆：按 projectLabel 绑定项目档案，可挂任意板块；项目启用才注入，停用/归档不注入、不占预算；每个会话独立存储，同名项目可并存，支持显式跨读。
• 记忆家族：母归属/子会话/脱离/让位/解散/根转移；母归属可单独修改家族显示名，不改文件夹与成员；子会话的全局热记忆只读，但可以拥有自己的项目热记忆；长记忆互读；文件锁、journal、选举、根转移与旧根只读。
• 项目档案家族共用：项目档案可授权全家族只读；拥有者控制启停、共用与归档，成员不能改；共享的项目热记忆跟随拥有者档案状态；独立会话不能启用共用；空根家族可显式接管，让位后未选举前可撤销让位。
• 自动捕获：严格命令式只负责识别，由模型按语义写入对应板块；非命令式由模型自行判断；规则只进候选。
• 手动注入：页签条目可「立即注入」；下一轮注入带【手动注入】段。
• 检索关联：项目档案检索命中后，按同项目或共享 tag 自动补最多 3 条相关文档。
• 归档快路径：压力超阈值时只用 tokenMeter 触发，检测不再全量解码日志；真正归档时才解码校验。
• 轮次摘要索引：palace_turns、轮次统计、窗口探测、自动检查与手动归档规划更快；索引不可用时自动重建，归档正文仍用完整轮次。
• 轮次双摘要：palace_turns 每轮同时显示用户与助手摘要，助手最多 200 字，便于判断归档类别。
• 全量校验：页签可手动重新检查会话日志并校正轮次索引与统计；可能耗时几十秒，不阻塞其他页签。
• 摘要定位：palace_summary(keyword=...) 先扫月度摘要，返回年月/类别/轮次；本会话未命中时可按配置回退家族、全库搜、询问用户，或仅停在候选摘要。候选按段取：每月最多 1–6 段（默认 3），用本地词法打分排序，整段摘要返回；每页最多 3 个月，月数上限 = 保底月数 + 增量（0–18），用返回的 candidateCursor 翻页。
• 彻底压缩时的归档：勾选「归档后彻底压缩」并手动归档时，除最后 archiveTailTurns（默认 2）轮外全部归档；不勾选仍按原保留窗口。
• 缓存自检：只统计缓存实际追加/重建，每 20 次写入做一次全量解码校准（可调 10–100）；重建后自动清理 manifest 未引用的旧 chunk；成功写入后顺带清理超过 24 小时的崩溃临时文件。
• 检查/安装更新：页签检查更新；安装更新需用户确认，失败可回退。
• 本地优先：归档、热记忆、项目档案、家族状态都在当前工作区 memory-palace/；不依赖外部记忆服务。

安装

dsh plugin --profile <profile> add @dafantong01/dsh-memory-palace

安装后重启 DSH，在会话页签打开「记忆宫殿」，给会话命名后才会归档。

已知限制

• 不做 embedding；检索是关键词/时间召回，口语化或跨义描述可能搜不到。
• 不自动注入项目档案全文；按需用 memory_doc_search / memory_doc_read。
• 归档、项目文档、热记忆的写锁以单 DSH 实例为前提；多实例不做强一致保证。
• 可与其他记忆工具并存；迁移前先备份并人工抽查。
• UI 的提示位置、原位编辑、保存后排序属于已知低优先级体验项。

工作方式

1. 触发检查：每 checkEveryTurns 轮（默认 5），在回合收尾处检查一次。要同时满足两道门：
   • 压力门：上下文占用 ≥ triggerPressure（默认 60%）× 窗口。 占用取 DSH 自己的计量 ctx.tokenMeter.measure(session).totalTokens——压缩后它会回落； 拿不到计量服务时才退回「日志轮次累加」，并在提示里标注「日志估算」。
   • 批量门：可归档轮数 ≥ minBatchTurns（默认 10）或 可归档文本量 ≥ 无需归档量 × batchByteFraction（默认 50%）
2. 提醒：两道门都过，插件注入一条极短提示，请模型调用归档工具（enableSteer:false 可关掉，关掉就没有自动归档）。
3. 分类（逐轮判断）：模型逐轮决定每轮属于哪个类别，用 segments 提交： [{category, fromTurn, toTurn}, …]。同一类别可以拆成多段，最后合并成一个文件； 每个 turn 只能归一类，区间不许重叠。
4. 保留：无需归档的近期文本量 = 窗口 × retainFraction（默认 12%），比这更新的轮次不动。 取整轮粒度、严格不超过该上限；只有单轮本身就超上限时，至少保留最后 1 轮。 12% 的用意：压得比 DSH 压缩尾部（约 16%）更小，压缩时不会碰到你还没归档的近期内容。
5. 写入：插件从会话日志逐字取出每个类别的轮次，按时间正序写进该类别一个文件（超 maxFileBytes 才分卷）。模型不复述内容，不会截断或改写。
6. 覆盖去重：已归档轮次记在 .state.json 的 archivedRanges；新请求先把已覆盖的轮次剔掉，只写剩下的。
7. 归档后压缩：compactAfterArchive 默认关。compactNow() 不接受范围参数，压多少由 DSH 自己决定， 可能压掉尚未归档的近期轮次（原文仍在会话日志里，可再归档）。默认不动它。

目录与文件名（会话级隔离）

<当前工作区>/
  memory-palace/
    .namespaces.json       # 会话ID → 文件夹名 的映射（插件维护）
    config.json            # 新会话的默认值（旧版遗留，仅作默认）
    <文件夹>/              # 记忆名：英文（大小写均可）+数字/空格/下划线/连字符
      config.json          # 本会话自己的开关/参数/记忆名
      .state.json          # 本会话水位、已归档区间
      index.jsonl          # 本会话的归档索引（路径相对本文件夹）
      <YYYY-MM>/           # 月份容器：归档时按归档年月找/建
        _summary.md        # 该月摘要：只追加，每段对应一次归档里的一个类别
        <category>/
          <前缀>-<category>-<YYYYMMDD-HHmmss>.md

• 文件夹名 = 页签里填的「记忆命名」：英文（大小写均可）、数字、空格、下划线、连字符，≤32 位；首尾不能有空格，中文与路径分隔符会被拒绝。
• 没命名时用会话ID，且不产生任何记忆文件（只建 config/state）。
• 在页签里改名并保存 → 文件夹就地改名，索引里的路径是相对的，不需要跟着改。
• 文件夹即归属：memory-palace/<你的文件夹>/ 里的文件都属于那个会话；文件名前缀只是历史署名，不代表归属。
• 摘要每月一份：<YYYY-MM>/_summary.md，只追加；同一次归档里每个类别写一段，段头是「归档时间 · 对话时间范围 · [类别] 轮次范围」。
  • 月份按该批对话首轮的时间归属：10-31 深夜、11-01 才归档的对话仍落进 2026-10/。
  • 文件头注明 turn = 日志事件序号（含系统指令、插件注入、工具调用），不是“第几条消息”。
• 一次归档调用里，同一类别的所有轮次进同目录下的一个文件（超 maxFileBytes 才按轮分卷 -p1/-p2）。
• 不同类别 = 不同文件，即使来自同一次调用。
• 同秒冲突自动加 -2。分类目录强制英文小写。

从旧结构迁移

早期版本用过不同的目录结构。迁移脚本只用于本项目早期数据，不包含在发布包中；新用户从 0.1.0 开始使用无需迁移。

当前采用的结构是 <会话>/<YYYY-MM>/<category>/。

工具

检索四步法（为省 token 设计）

0) 不知道在哪个月：palace_summary(limit=6)
   → 每月摘要末尾预览；找到大致年月
0b) palace_summary(month="2026-10")
   → 该月全部摘要段落（哪次归档、讲了什么）
1) palace_search(keyword="事故教训", limit=3)
   → 约 1 千字符：命中位置 + 轮次 + 行号 + 文件路径
2) palace_read(fromTurn=48, toTurn=48)
   → 该轮完整原文（思考、工具调用、返回都在）

• 单次读取默认上限 60,000 字符（约一本书的三分之一），硬上限也是 6 万。
• 单轮超过 6 万字符时，返回前 6 万并提示 用 offset=N 继续，可分段读完整个大轮（实测 12.7 万字符分 3 段读完）。
• 不给轮次、也不给 path 时只返回文件开头 6 万字符，并提示按轮次精确取。

开关（会话级，fail-closed）

真正生效要同时满足（现在收成一个统一门 gateState()，页签会显示“为什么没生效”）：

1. 全局总闸 enabled（默认开，只是允许插件工作）
2. 本会话开关：memory-palace/<文件夹>/config.json 里 enabled: true，新会话缺省为关
3. 已命名：记忆名为空时，即使开了开关也不归档（只建文件夹和配置）
4. 自动提示：injectNotice / enableSteer 任一关掉 → 工具仍可用，但不会主动 steer（页签会写明）
5. 会话可见性：palace_archive 被 capability-panel 关掉的会话整块静默

GET /memory-palace-api 额外返回 gate: { active, steer, reasons[] } 与 events（最近 20 条插件事件：归档/检索失败/门关闭等），页签直接展示，不用解压会话日志。

三个入口

• 聊天框 /palace on（off 关闭，status 查看）
• 页签「记忆回廊」里的滑块
• 让模型调用 palace_config

都只改当前会话自己那份配置——不碰 profile、不用重启。

会话页签（GUI）

会话头部会多一个「记忆回廊」页签，按当前会话显示与修改：

• 开关滑块（绿色=已开启、灰色=已关闭）
• 本会话文件夹（memory-palace/<名字>；未命名时显示会话ID并提示不会归档）
• 「记忆命名」输入框：保存即改名文件夹；只接受英文（大小写）/数字/空格/下划线/连字符、首尾不能空格；与同工作区其他会话重名会被拒绝
• 估算窗口 tokens（只读，自动探测）
• 触发阈值 %（滑块 + 输入框联动）
• 检查频率、最小归档批量、批量兜底阈值 %、无需归档比例 %
• 无需归档的近期文本量（只读，窗口 × 比例为 token 数）
• 单文件上限 MB
• 自动提示、收录深度思考、归档后压缩
• 最近 20 条归档列表

数据来自宿主路由 GET/POST /memory-palace-api（kind: exact；DSH 的 /api 是 RPC 通道，不能占用）。 非活跃会话通过会话日志头部的 session 事件取 cwd，不依赖 agent 是否在运行。

项目档案附件

项目档案详情下方是独立附件框，只显示当前档案的附件，不混进正文。

• 一次显示一个附件，< > 切换，页码标出第几个 / 共几个
• 最多 5 个；圆形按钮：添加、删除、用系统默认程序打开
• 添加方式：系统文件选择器，或手动输入本地绝对路径
• 网页链接：只接受 http:// / https://，点击用系统默认浏览器打开；删除只摘索引，不访问或修改网页
• 外部文件只挂路径，不复制、不限单文件大小；删除只移除索引
• 图片按需加载；非图片显示图标与文件名；文件被改名或移走后显示“（已丢失）”，不能打开
• 同一路径、同一链接或同一内容不能重复挂载

附件索引写在 _docs/assets/<文档 ID>/attachments.json，不写进档案正文，档案 rev 不因附件变化递增。

配置分层

1. 全局默认：插件配置（profile 级，volatile）。
2. 工作区默认：<工作区>/memory-palace/config.json，只作为新会话的初始值。
3. 本会话配置：memory-palace/<文件夹>/config.json，页签与 /palace 实际改的是这份。
4. 按会话开关：capability-panel 里关掉 palace_archive。

可被工作区覆盖：enabled、triggerPressure、retainFraction、batchByteFraction、retainBytes、 maxFileBytes、checkEveryTurns、minBatchTurns、selfNameSlug、includeReasoning、 compactAfterArchive、injectNotice。

配置项

会话配置里额外有 name（记忆命名，默认空）；会话开关是会话配置里的 enabled。

回忆强度（五档）

补充规则：

• 启动时不注入：重启后会话历史本身就在上下文里，“上一轮聊到哪”不需要摘要补；只在压缩后注入一次归档摘要。
• medium/high 不是“每轮读摘要”：它们在压缩前完全静默，只有压缩后那一条前置指引；如果用户以为中档会一直主动回忆，那是误解。
• 压缩后只注入“去读哪份摘要”的指引（硬触发）：监听 session/event 的 compaction/end；每次上下文压缩完成后，下轮请求组装前注入一条简短指引（不注入摘要全文），要求先调 palace_summary(month=…) 读最近年月的归档摘要，再继续。月份取自实际存在摘要的最新月份（不是日历当前月，跨年也不会指向空月份）；该月摘要不足 500 token 时，指引会额外给出上一个月的调用方式。优先级：系统压缩摘要优先，它没覆盖到的内容用归档摘要补充。这条指引是普通上下文消息，下次压缩自然消失——不会每轮重复强调。
• 事件失效是静默的：session/event 属于首方内部用法，DSH 升级若改名不会报错、只会不收事件。插件会在“最近事件”里记 compaction-detected 与 recall-after-compaction，页签看不到这两条就说明链路没通。
• 预算是提示不是硬约束：递归由模型执行，插件只把上限写进指令；超了要模型自己收敛。
• 强制档有成本：每条消息多一次检索往返，长会话里 token 消耗明显。
• 强制档会多一条回复：steer 是后置注入的独立消息，宿主必然为它起一轮，所以可能出现“主回答 + 一条简短的检索说明”。这是注入方式的固有成本，插件无法消除；v0.2 计划改成请求前注入。注入消息带 [记忆回廊·系统注入] 前缀和 source.kind='dsh-memory-palace'，便于识别。
• 所有档位都不改变归档行为（off 也照常归档原文）。

可靠性

• 原子写：归档文件、.state.json、config.json 都是先写临时文件再 rename。
• 数据优先：归档先写文件、再写摘要、最后写状态（摘要失败时 state 未更新，重试不会变成“已归档过”）；索引追加失败写进 .pending-index.jsonl，下次归档前自动补写；追加前会补换行，避免半行粘连。
• 边界语义：保留边界 boundary = 0 表示“全部在保留区、暂不可归档”，不是“无限制”；且永远不归档最后一轮（可能正在生成）。
• 覆盖集以索引为准：判断“已归档”时按 index.jsonl 里真实存在的行展开，不用 archivedThroughTurn 单点最大值，避免区间空洞被填平。
• 不重复：覆盖去重（区间剔除）+ 同秒 -2 兜底。
• 索引容错：读 index.jsonl 前会剥掉 UTF-8 BOM（旧文件可能带 BOM，按行 parse 会全失败）。
• 读取限制：palace_read 只能读本命名空间（或 legacy 根）下的归档，.state.json/config.json/index.jsonl/.namespaces.json 直接拒绝。
• 可观测：.state.json 记 lastCheckTurn / lastCheckAt / lastPressure / lastArchiveRange，/palace status 可见。
• 解码缓存：按日志 mtime + size 缓存（最多 8 个会话）。
• 失败静默：钩子内 catch，不阻塞对话。

依赖与失败策略

• 读 DSH 的 .zstd 日志需要 fzstd（多帧解压；Node zlib 只解第一帧）。
• 注册一个 systemPrompt 段（order 160）用于常驻检索指引，并注册一个压缩后注入的动态上下文；不监听 agent/pre-step，避免与其他插件抢接缝。

兼容性

• 需要 ctx.tools.register、agent/turn-stopping、agent.steer、ctx.webServer.register、ctx.compaction（可选）。
• 日志按 DSH v4（session.v4.jsonl.zstd）解析；格式变了会少条目而不是报错。

图片、文件与联网结果

• 图片/文件不存字节：只写一行占位符（[图片 sha256:… 1024×768｜…]），删了附件也不会崩。
• 联网搜索结果按工具返回文本归档，单块截断 40 万字符；用户/助手文本与思考各截断 20 万字符。

安装

从 npm 安装（推荐）

dsh plugin --profile <profile> add @dafantong01/dsh-memory-palace

从 GitHub 安装（钉 commit，避免拉到未发布的中间状态）

dsh plugin --profile <profile> add github:dafantong01/dsh-memory-palace#<commit>

从本地 tgz 安装

dsh plugin --profile <profile> add @dafantong01/dsh-memory-palace

装好后在 profile 的 dsh.profile.bundles 里确认有 @dafantong01/dsh-memory-palace，然后重启 DSH。

pnpm 对 file: 依赖会做 junction；如果插件树激活失败，检查 node_modules/@dafantong01/dsh-memory-palace 是否是真实目录。

兼容性与权限

• DSH 版本：engines.dsh 为 >=0.2.1-rc.2 <0.3.0-0，低于或高于此范围时市场会标记不兼容。
• 运行时权限：插件在你的 DSH 进程内运行，权限等同你本人：
  • 读 $DSH_HOME/sessions/ 下的会话日志（归档原文来源）
  • 读写当前工作区的 memory-palace/
  • 注册一个本地 HTTP 路由 GET/POST /memory-palace-api（仅本机回环）
• 不联网：不请求任何外部服务，数据全部留在本机。
• 不存附件字节：图片/文件只记占位符与哈希，原文件删除也不影响归档。

常见问题

• 页签显示「session not found」：路由拿不到该会话的 cwd，通常是日志被移走。
• /palace status 显示未开启：工作区 config.json 缺 enabled:true。
• 一直不触发：检查压力是否到阈值、可归档区间是否为空（近期内容都在保留区内）。

常驻提示词

插件常驻一段 systemPrompt（order 160，约 60 token）：

本工作区有 memory-palace 归档。需要更早的细节、旧决定、被压缩掉的历史，或用户问起“之前说过什么”时， 先用 palace_search 定位，再用 palace_read 按轮次取原文；不要凭印象编造过去的事。

工具描述也配合写成“先用它定位”。

按类别分段归档

模型逐轮判断类别，用一次调用提交多段：

palace_archive({
  "segments": [
    { "category": "dsh-plugin-dev", "fromTurn": 112, "toTurn": 114 },
    { "category": "bug-report",     "fromTurn": 115, "toTurn": 115 },
    { "category": "dsh-plugin-dev", "fromTurn": 116, "toTurn": 116 }
  ]
})

• 同一类别拆多段 → 合并写进一个文件，轮次顺序不变
• 每个 turn 只能归一类，区间重叠会报错
• 文件头会写实际轮次：连续 turn 113–114，跳号 turn 113, 114, 116, 128（4 轮，不连续）
• 索引行对不连续区间额外记 turns: [...]
• 归档正文的轮次标题改用 ## TURN n · 时间，避免正文里“引用了旧归档标题”时把 palace_read 的切片切错；老文件仍按 ## 第 n 轮 · 兼容解析

English

A DSH plugin that archives older conversation turns, verbatim, into a workspace-local memory-palace/ directory before context compaction — then lets the model search and read them back later.

Why: DSH compacts long contexts; after compaction the original wording is gone. This plugin keeps it on disk, searchable.

Install

dsh plugin --profile <profile> add @dafantong01/dsh-memory-palace

or pin a commit:

dsh plugin --profile <profile> add github:dafantong01/dsh-memory-palace#<commit>

Restart DSH afterwards. Enable per session via the Memory Palace tab or /palace on.

What it does

• Archives turns by category when context pressure crosses a threshold; never rewrites or truncates text.
• Stores memory-palace/<session>/<YYYY-MM>/_summary.md plus <category>/<file>.md.
• Tools: palace_archive, palace_summary, palace_search, palace_read, palace_turns, palace_config.
• Five recall levels (off / low / medium / high / forced); after compaction it asks the model to read the latest month's archive summary.
• Per-session configuration; data stays in the workspace.

Requirements

• DSH >=0.2.1-rc.2 <0.3.0-0.
• Runs inside your DSH process with your permissions: reads local session logs under $DSH_HOME/sessions/, reads/writes memory-palace/ in the current workspace, and registers a loopback HTTP route /memory-palace-api.
• No network calls, no attached-file bytes stored (placeholders with hashes only).

License: MIT.

Plugin-page metadata (release check)

DSH reads a plugin's plugin-page title and description through Node's package exports: @scope/pkg/locale/en.json and @scope/pkg/package.json. If those subpaths are not exported, the plugin page shows only the raw package name.

Before publishing, keep both in package.json:

"exports": {
  "./package.json": "./package.json",
  "./locale/*.json": "./locale/*.json"
},
"files": ["lib", "locale", "cordis.patch.yml", "README.md", "LICENSE", "..."],

locale/en.json and locale/zh.json must both contain:

{ "meta": { "title": "...", "description": "..." } }

Verify:

# from the repo (checks fields and files)
node scripts/check-meta.mjs .

# from a profile directory, with this script copied OUTSIDE the package
node check-meta.mjs @dafantong01/dsh-memory-palace

Run the installed-package form before every release; the source form only checks fields, not Node resolution.