sage-mem · DSH 的文件式记忆插件 (sage-mem)

Name: gezi-wen/sage-mem
Author: gezi-wen

English · README.en.md

给 DeepSeek Harness（DSH）装上跨会话记忆：每条记忆都是本地的一个 Markdown 文件。

File-based cross-session memory for DeepSeek Harness — every memory is a plain markdown file you can open, edit and delete. No database, no worker, no port.

当前发布版本：2.5.0 —— 顶部 npm 徽章是动态权威。契约基线：1.0.0 —— 第一个稳定版，公开承诺、能力边界与「明确做不到」的清单冻结在契约冻结。

如果它对你有用，给个 Star 是最直接的反馈。

这是什么

DSH 原生没有记忆系统。每开一个新会话都是一张白纸：不记得你是谁、不记得昨天做到哪、不记得项目进行到哪一步，于是你每次都要重新交代一遍。

sage-mem 补上这一层，做法是：把该记住的事写成一张张卡片，存在你自己电脑上。在 DSH 把问题交给模型之前，插件按问题挑出最相关的几张、贴在模型眼前。

所以准确的说法不是「模型记得你」，而是「在它开口之前，有人把相关的纸条递进了它手里」。撤走纸条，它又是那个失忆的同事。

记忆的形态是一条记忆一个 .md 文件（YAML frontmatter + 正文）：用编辑器就能打开、能改、能删，也能直接拿 git 管。这份记忆始终在你自己手里，不在某个数据库里。

为什么是文件，不是数据库

大多数记忆方案走「SQLite + 常驻 worker」：记忆写进数据库就不透明（想看看存了什么得去查表），事件全捕获又会让库膨胀（「用户打了个招呼」也算一条），还要额外养一个进程和一个端口。

	文件式（sage-mem）	数据库 + worker
看一眼存了什么	打开目录	查表 / 写脚本
手工改一条	编辑器直接改	走 API 或 SQL
迁移 / 备份	拷目录（能跟 git 走）	导出工具
额外进程与端口	无	通常有
存不存谁决定	由 agent 按规则判断	常见做法是无差别全捕获

核心特性

特性	说明
文件式存储	每条记忆一个 `.md`：frontmatter 存元数据，正文存内容。无数据库、无隐藏格式
自动注入	每条新问题都会重新扫一遍记忆目录，按这条问题挑出最相关的几条，在模型开口之前拼进上下文 —— 不用模型自己去翻文件
模型也能自己查	另给模型两个检索工具（`search_memory` / `read_memory`），它可以主动翻记忆、按行读原文
写入不被覆盖	你正在编辑、模型同时在改的时候，后写的不会静默盖掉先写的；冲突留成待处理记录，由你决定保留哪边
零额外服务	无 worker、无 SQLite、无端口、无常驻进程，不需要额外的 API key 或云服务（运行时唯一的依赖是普通 npm 库 `zod`）
防膨胀	靠规则引导模型判断「值不值得存」：无实质内容的不存，靠读代码 / git 能推出来的不存
可整理	可选的「自动做梦」把记忆通读一遍：合并重复、修索引与断链，改动前先建回滚点
从 Claude Code 迁移	人格（`CLAUDE.md` → `AGENTS.md`）照搬；记忆按四类整理成 `.md` 即可（见下一节）
自带使用指南	包内携带一份技能（`skills/sage-mem/`）：记忆长什么样、四类怎么分、什么不该存、frontmatter 的坑、检索怎么工作、索引坏了怎么修。装上插件就够了 —— Agent 拿到说明书，不需要手工配置

界面上还有四块能力（都可以不用）：记忆管理页、类型与标签筛选、时间线（默认是条目列表，可切星空视角）、体检与归档。

1.8.0 起，记忆管理还能从侧栏直接进：侧栏多一个「记忆管理」图标，点它把中央主区切到本页（页顶有「返回会话」）。设置页「记忆管理 → 自动做梦 → 设置」里可以关掉这个入口（默认开，立即生效、不用重启）； 1.8.2 起，插件详情页也有同一个开关（「插件 → sage-mem」那张卡），改完立即生效； 关掉只影响侧栏图标，「设置 → 记忆管理」这个入口永远保留。从 1.8.2 开始，sage-mem 在插件列表里有了自己的图标（金色记忆卡片），不再是默认的通用方图标。

记忆管理页的「文件列表」头部还有一个「打开记忆文件夹」按钮：用系统文件管理器打开当前记忆目录（Windows Explorer / macOS Finder / Linux 文件管理器）。host 侧起一个 detached 进程就返回，不等窗口。

记忆目录还是空的时候，空态里有一个「建立索引骨架」按钮：一键写入 MEMORY.md 的引导文件（索引格式 + 四类记忆说明）。已经存在 MEMORY.md 时只提示、不覆盖；它不走新的 remote，用的是原有的保留名读取 / 写入接口。

快速开始

需要 DSH 0.1.2-rc.1 或更高（见兼容性）、Node.js >= 18。

# 把 web 换成你自己的 profile 名
dsh plugin --profile web add sage-mem

dsh plugin add 会把包装进这个 profile 并登记它的 bundle —— 不用手改 package.json（手动装法见下）。

装完重启 DSH，确认装上了：

dsh plugin --profile web list

然后开一个新会话试三步：

跟模型说「记住：我的猫叫芝麻，它喜欢晒太阳」—— 它按规则把这条写进记忆目录
再开一个新会话，问「我的猫叫什么」
它的第一个回答就该答出「芝麻」—— 记忆由插件自动检索并注入，模型没有主动去翻文件

手动安装（不想用 CLI，或要装本地开发版本）

在 profile 的 package.json 里加依赖，并把包名写进 dsh.profile.bundles：

{
  "dependencies": {
    "sage-mem": "^1.0.0"
  },
  "dsh": {
    "profile": {
      "bundles": ["sage-mem"]
    }
  }
}

本地开发用 clone 出来的源码：

{
  "dependencies": {
    "sage-mem": "link:../sage-mem"
  }
}

改完跑 pnpm install，再重启 DSH。

记忆放在哪

默认在 ~/.sage-mem/memory。想放到别处（比如放进项目仓库、跟着 git 走）就设环境变量：

SAGE_MEM_DIR=/path/to/your/memory

状态目录（配置、台账、回滚点、冲突队列）默认在记忆目录的上一层：<记忆目录>/.sage-mem。全部环境变量见配置参考。

界面预览

下面每张图都是从仓库里的界面代码渲染出来的（同一份 CSS、同一棵组件树；数据是演示用的假数据，不是真实记忆目录）。

2.5.0 起面板是四个页签：文件列表｜时间线｜自动整理｜库健康 —— 按「我要干什么」切，不按「数据从哪来」切：自动做梦与自动归档并成一屏的两张卡，冲突与体检也并成一屏的两张卡。编辑走右侧抽屉，凡是会动盘上文件的动作都先弹模态框问一句。

1.9.0 起，记忆管理这一块跟随宿主语言（设置 → 通用 → 语言）；记忆内容本身保持它被写下时的语言，2.1.0 起扩展到自动做梦（运行 / 设置 / 记录）与自动归档两张卡；只剩时间线/星图那一屏仍是中文，等下一批 i18n。

文件列表：每条记忆一个 Markdown 文件，灰底的是已归档

文件列表 —— 头部常显「体检 N 个问题」与「待重启生效」，不用点开就知道该不该处理；灰底条目是已归档，随时可以恢复，也可以点「彻底删除」真的删掉（不可恢复，要再确认一次）。

工具抽屉：归档候选 / 保留名编辑，关着时零占位

工具抽屉 —— 关着时只占一个按钮，展开后两项各带状态。

锁定：按钮在「编辑」与「归档」之间，锁上后归档被禁用

锁定 —— 重要记忆点一下就锁上：自动归档的候选里不再出现它；界面上的归档按钮被禁用，即便绕过界面，归档实现也会以 locked 明确拒绝。锁存在状态目录里、不写进记忆自己的 frontmatter —— 那会被自动整理重写掉，锁一丢它又会回到候选里。

编辑记忆：右侧抽屉，列表不再被顶下去

编辑记忆 —— 编辑走右侧抽屉，字段与校验跟以前一样，只是不再把列表顶下去；「取消」「点遮罩」「Esc」三条出口都能关掉它。

危险动作：统一模态确认，两段式不变

危险动作确认 —— 归档、彻底删除、删除记忆、回滚、归档候选（逐条 / 批量）、标失效、撤销失效、删除冲突记录，九处一律先弹这一张卡。两段式没变：那颗触发按钮是第一段，模态是第二段，永远不合并。

体检：独立一页，硬问题按类报红分节

库健康 —— 一屏回答「这个库有没有事」：冲突队列在上（要你裁决的有限队列：两条说法互斥，选哪一方作废），体检在下（索引悬空、漏索引、双链断链等结构问题按类报红）。「指向已归档」只作提示、不计入问题；也不提供一键修补 —— 改哪条由你决定。体检只报告、不修改。

更新提示 —— 只在真有新版本时出现一条横幅，写明新版本与当前版本；「看更新内容」开新标签页，「×」只是这次不看。

归档候选：每条写清「为什么建议归档」，确认后才执行

归档候选 —— 每条写清「为什么建议归档」（闲置天数 vs 该类型阈值），逐条或全选后确认才动文件。归档是把文件移进 archive/，不删除；真要删掉一条归档件，得在档案馆里单独点「彻底删除」并再确认一次。

时间线（默认视角）：按更新时间倒序的条目列表

时间线 —— 打开这个标签先看见的就是这一屏：按更新时间倒序的条目列表，最近改过的在最上面。想看图，右上角「星空」自己切。

时间线 · 星空视角：暗星是已归档的记忆

切到「星空」之后 —— 颜色对应类型、大小对应体积、亮度对应新鲜度，暗星是已归档的记忆，点开可看归档时间与理由。

自动做梦 · 设置

自动做梦 · 设置 —— 运行 / 设置 / 记录二级分组；五个注入参数两列排开，并写清「当前生效」与「重启后」。

自动归档：自动整理屏上的第二张卡 —— 自带运行 / 设置两段，一个开关、两档策略

自动归档 —— 它和自动做梦不是一件事：归档是*确定性规则（按访问台账的闲置天数算，不调模型），所以单独一张卡。2.5.0 起它和自动做梦同一个形状（自带「运行 / 设置」两段：运行段说清它做什么并放档位，设置段放三个闲置阈值），还有一个开关 —— 开关是唯一的关闭入口（原来的第三档「关闭」已拿掉），档位只剩「只出报告」与「满足条件自动跑」。关掉只停运行、不藏设置：阈值与记录照常可改。阈值保存即生效，不用重启。*

时间线 · 星空视角

「星空」视角全貌 —— 画布上只画关系与分布；悬停或点开某颗星时才显示那一条的文件名。渲染是按需重绘，画面静止时不发起任何绘制。

记忆文件格式

---
name: 可选的短名
description: 一句话说清这条记忆是什么（检索靠它，务必写准）
metadata:
  type: user        # user / feedback / project / reference
tags: [项目, 待办]   # 可选，供列表页筛选（最多 20 个、每个 40 字符）
aliases: [待办, todo] # 可选：换一种说法也能被检索到
baseline: true      # 可选：新会话第一步无条件注入（上限 8 条）
baselinePriority: 10 # 可选：多条 baseline 之间谁先注入（越大越前）
---

记忆正文。

四类记忆：

类型	存什么
`user`	用户是谁
`feedback`	工作方式指导（建议带 `Why:` 与 `How to apply:` 两行，方便判断边界）
`project`	进行中的工作与状态
`reference`	外部信息在哪找的指针

单文件上限 512 KB，读写两侧都校验（读的时候先看体积，超了就不读进来）。

检索与注入

透明的东西值得说清楚它怎么选料，因为这直接决定注入多少 token。

两段式检索：先摘要，再正文。 第一段用 description + 文件名 + aliases 打分，最多取 10 条候选；第二段对这些候选做正文段落检索（BM25，中文按双字词元），把最相关的那一段注入。比的是段落而不是整份文件，所以一份文件最多贡献一段，长文不会靠段数多霸占候选位。

摘要没写到的，正文能找回来。 摘要是精准的一句话，代价是正文细节天生检索不到；摘要一条都没命中时改由正文检索兜底。正文检索只在问题至少 4 个字符时才跑 —— 继续 这种两个字的问题拿去做正文匹配，命中的全是「继续」这个词本身。

换个说法也能命中： 打分是词面重合，不是语义的 —— 问「我有什么待办」而文件里写的是「代办清单」，差一个字就完全不命中。给这类记忆加一行 aliases: [待办, todo] 就能补上。

注入的是命中段落，不是文件开头。 命中段落标成 ### 项目_部署.md:40-52，模型据此能直接跳到那几行核对来源；段落前补一句该记忆的 description，说明这段是从哪条记忆切出来的。baseline 与没命中正文的文件仍注入开头；单条正文超过字数上限（默认 1500 字符）会截断并标 …（截断）。

相邻的重复问题不会重复注入（按会话只留一个签名），连着问两遍不会又追加一遍。注意这不是「整个会话同题只给一次」：问 A → 问 B → 再问 A，第三次会重新注入 —— 再次要求回忆时重新给证据未必是坏事。

单场会话有预算上限（默认 60 KB），拆成两本账：正文池 = 总上限 − 状态卡预留（5%，夹在 1–4 KB）。到顶之后不是「一个字都不注」，而是正文照旧不注、缺口状态卡照发，告诉你漏了什么、下一步怎么查。压缩或清空上下文之后两本账与卡的签名一起归零，又能注进来。

⚠️ 这个上限是软的，不是硬闸门。 baseline 记忆被问句命中时会照注不误、不参与降级，所以单场累计正文可能超出正文池（评测里量到 9.6% 的超支，全部来自这类记忆）。这是有意的取舍：那类记忆的语义就是「每场都该在场」。别把它当成「到 60 KB 就一刀切断」。

缺口状态卡只在真有缺口时说话：有候选没读、或有候选被预算省略时才出现，说清范围、条数、最佳线索和一个可做的动作；一条都没命中时，只有在你问自己的历史、或这条任务有检查点时才说（否则提示会被当噪音忽略）。单张卡上限 512 字节，且按内容签名去重。

「这条已经不作数了」会变成文件里可核对的事实（2.0.0 起）。 记忆的 frontmatter 可以带三个可选字段：valid_at（说法从什么时候成立）、invalid_at（从什么时候起不再作数）、superseded_by（现行口径在哪条记忆里）。注入侧会读它们：invalid_at 已经到点的那条不再进正文（理由是 expired_source）；一对未经裁决的矛盾（kind: contradiction 的 open 记录）两方都不进正文（conflict_pending），直到你在「记忆管理 → 冲突」页签里裁决。写失败型的冲突不抑制（版本过期 / 文件在别处被改过 / 合并到一半）—— 盘上那份仍然是现行内容，把它们也藏起来等于把「这次没写进去」误报成「记忆不可信」。

抑制绝不静默。 有矛盾待裁决时，状态卡会多一句「另有 N 条矛盾待裁决，相关记忆本轮未注入正文」（带具体条数，所以条数一变就能再发一次），面板头部也有一个常显徽标。工具不受影响：search_memory / read_memory 照旧能搜到、读到失效记忆，结果里会标「已失效」并带 invalidAt / supersededBy —— 问历史时旧口径是证据，不是噪音。想临时回到旧行为，把 SAGE_MEM_VALIDITY 设成 0（只关这一层过滤，本版其它修复都还在）。

摘要侧也有相关性门槛。 中文里「怎么」「什么」这类词元在大量 description 里都有，一句无关的「今天天气怎么样」可能靠一个「怎么」命中十几份记忆。门槛按语料自身的 IDF 尺度归一，无关问题的候选数因此降到约七分之一；被清掉的主要是本就该落选的弱摘要候选。

离线评测集上的对照（门槛前后）：Recall@5 84.1% → 87.0%、误注入（注入了与问题无关的记忆）14.1% → 5.6%。

⚠️ 这些是测量，不是承诺：可迁移的是相对改进，绝对水平不可外推到真实记忆目录 —— 那 30 份语料的摘要本来就是照着「能被检索到」手写的，真实记忆的摘要往往写得很随意甚至缺失。方法与局限见评测报告。

意图识别绝不在三类显式请求上抑制重复：「上次决定用 A 对吧」（核实）、「不用 A 了」（更正）、「之前为什么没选 A」（问依据）必须给原文；判不出来就不判，不猜。

模型也能自己翻：两个工具

检索的触发权分两半：一半在插件（自动注入，它猜你想看什么），一半在模型（下面这两个工具，它主动查）。

工具	用途
`search_memory(query, scope?, limit?, cursor?)`	先比摘要、再按段落查正文；返回候选、命中片段、行号，以及覆盖情况（扫了几份、几段因相关性不够被滤掉、有没有下一页）
`read_memory(name, startLine?, startByte?, maxBytes?, revision?)`	按行分页读正文。带上你上次读到的 `revision`，内容被人改过时会回 `revision_changed`，并且不返回内容 —— 否则你会拿着过期行号读错东西

两个工具走的是同一条安全读路径（文件名检查 → 符号链接与保留名身份检查 → 体积闸门），没有为工具另开一条绕过闸门的入口。它们通过宿主提供的工具服务注册 —— 不是硬依赖：宿主不提供这个服务时，插件照常工作，只是状态卡换一套「直接读记忆目录」的说法。

长任务的接力棒：任务检查点

宿主什么时候压缩上下文，插件控制不了 —— 所以不承诺「压缩前保存」。能做的是：如果 <状态目录>/tasks/<任务 id>/WORKING.md 存在，注入末尾会给一条短句柄，说清任务、revision 与去哪读。压缩后账本归零会连去重一起清掉，句柄因此重新出现 —— 这就是恢复路径。

任务 id 取 SAGE_MEM_TASK_ID（给跨会话的同一条任务用），否则用会话 id。绝不用你的问题原文去决定读哪个目录。 检查点里「已完成」的条目如果没有任何证据标记（路径、命令、测试结果），解析时会如实报出来 —— 格式完美、内容错误的交接材料仍然是错的。

写入安全

记忆是文件，所以「你正在编辑」和「模型正在改」完全可能同时发生。默认行为是后写的赢、先写的悄悄消失 —— 那是最糟的一种，因为你不会发现。

sage-mem 给记忆目录的写入加了版本守卫：写入前记下当前版本，写入时要求版本没变过。变了就明确拒绝，而不是盖掉 —— 把「静默的坏结果」变成「显式的失败」。

守卫分两条路，覆盖面不一样，说清楚：

谁在写	怎么保护	被拒时
模型用内置 `write` / `edit` 改记忆	插件在前置事件里给出「当前版本」，宿主据此拒绝过期覆盖	宿主直接拒绝（报 `FS_STALE_VERSION`）。这条路的拒绝不留冲突记录 —— 写门只提供版本，不做拒绝动作
插件自己写（自动做梦的整理）	调用方在写入时带上读到的版本	落一条待处理记录 `<状态目录>/conflicts/<id>.json`，里面留着盘上那一版和想要写的那一版 —— 只有一边等于没得判

冲突不会自动合并，保留哪边由你决定（记录是 JSON，需要时直接打开看）。静默重试和静默放弃都是在替你决定。
2.0.0 起注入侧会读这个队列：只有 kind: contradiction 且 status: open 的矛盾型两方被抑制；另外三种写失败型（stale_version / external_change / unresolved_merge）照常注入 —— 盘上那份才是现行内容。裁决入口与抑制是同一次交付，不再有「只接抑制、没有入口」的状态。
裁决在「记忆管理 → 库健康」页签的冲突卡（一屏两张卡里在上面的那张，面板头部另有常显徽标）：逐条看两份正文，动作是「标此条失效」「撤销失效」「删除记录」，危险动作两段式确认。「标失效」只往记忆 frontmatter 加一行 invalid_at（可选再写 superseded_by）—— 文件留在原位、正文一个字节不动、不改 updated；写盘幂等（连点两次不重写）、可撤销，失败时明确返回错误、记录保持待裁决。
冲突记录字段只增不改：2.0.0 在尾部追加 otherFile / decision / decidedAt / appliedVersion / invalidatedFile 五个，记录版本仍是 1；1.9.x 读端忽略不认识的键，双向都不用迁移。
手工编辑不在看守范围：直接改文件也生效（删掉 invalid_at 就恢复注入），插件不拦手改 —— 这是文件式记忆的取舍，见能力边界表 C11。
同一件事不会越积越多：一次失败如果与队列里某条未裁决记录逐字段相同（同一文件、两份正文、两个版本），不再追加副本。
宿主的文件沙箱：自动做梦在会话外运行，拿不到会话工作区。宿主用 workspace-write 时，插件给每次写入带上收窄到记忆目录的逐次沙箱策略（比回退根更窄）；宿主是 read-only 时不传策略、写入照旧被拒，且这一趟会被记成失败（不是「成功，没改什么」）。
已知边界：在 shell 里改记忆不走这条路。写门守的是「经过工具的记忆写入」，不是「所有对文件的修改」；pwsh 里的重定向之类认不出来。认不准就不认，免得把「看不到」误记成事实。

访问台账：三种「用过」分开记

<状态目录>/access.json 记三件事：

字段	含义
`injected`	插件被动注入了这份记忆
`read`	模型主动读了它
`use`	明确被采用的次数（自报）

分开记是因为这三件事的含义完全不同：被注入只说明插件觉得相关，被主动读只说明模型选了它，都不等于内容有用、更不等于内容正确。混成一个「热度」就再也分不开了。

这张台账目前只用于诊断与自动归档阈值，不参与检索排序。 观测有已知盲区：在 shell 里读记忆认不出来，那就不认。

记忆的新鲜度与引用纪律

每条记忆的标题带新鲜度：（保存于 N 天前），优先读 frontmatter 的 updated:，缺失才回落文件 mtime —— 手写的时间戳是权威，文件系统时间会被复制 / 备份还原 / checkout 整批改掉。

理由是：陈旧记忆被当事实引用时，「引用」这个动作本身会让它显得更权威而不是更可疑。所以注入文本开头还带一节引用纪律（提到路径先确认存在、提到函数先 grep、要动手先核实当前代码），而且它独立成节——它约束的是这一批内容怎么用，压成一条列表项容易和内容混在一起被跳过。

baseline: true 的记忆每场会话第一步无条件注入，最多 8 条 —— 给「你是谁」「待办清单」这类每次开场都该在场的记忆用。⚠️ 「不吃段落替换」不等于整份：它同样受单条字数上限（默认 1500 字符）截断，关键内容若落在尾部会看不到。baseline 适合放短摘要，完整正文留给工具去读。多条 baseline 之间的先后由 baselinePriority 决定（数字越大越前，缺省 0），不按文件名排。

记忆目录读不到、权限错 → 降级为不注入并写日志，不会静默失效。frontmatter 坏掉则宽容处理：解析不出来的字段回落默认（type 缺失按 reference 记），文件本身照样能被读到 —— 不会因为一行写错就让整条记忆消失。

自动做梦

可选的记忆整理功能（标识 autodream）：把记忆目录通读一遍 —— 合并重复的、删掉被推翻的、修索引与断链、把相对日期换成绝对日期，让下一次会话能快速对上位置。

默认关闭，在设置页「记忆管理 → 自动做梦」里开。三件事各自可选：

选项	取值	说明
触发	只手动 / 满足条件自动跑	自动模式走三级门控，最便宜的先查：时间门（距上次 ≥ N 小时，一次读写）→ 会话门（期间 ≥ M 个会话有更新，一次目录扫描）→ 锁（防并发）。中间夹一层 10 分钟扫描节流，免得「时间门过了、会话门没过」时每轮白扫
改动方式	只出报告 / 直接改写	「只出报告」模式下写工具根本不会挂给模型 —— 不是靠一句「请不要写」约束，是它没有手
输入源	仅记忆目录 / 记忆 + 会话记录	后者会解压会话记录（zstd）做定向关键词搜索；代价是私密对话会进入模型上下文，token 成本也更高

自动触发走插件自己的定时器（默认 30 分钟查一次门控）。整理刻意不走会话 —— 工具集由插件给、步数有上限、不写进你的会话记录。

整理用的模型可以单独指定

整理是后台批量任务，跟聊天用的不一定是同一个模型。设置页「高级设置 → 模型」可以从当前已配置的模型路线里挑一条（选项与「模型选择」里的目录同源）。

选了就只认它：路线在宿主里不存在时开工前就报错（只比对宿主已注册的目录、不发任何请求），不会跑到一半才失败，也不会静默回落到默认模型。
面板下方始终显示实际生效的是哪条；配置里那条路线万一从目录里消失了，下拉框也会把它显示出来而不是悄悄跳回默认。
拿不到模型目录时（宿主差异），退化成手填 provider 与 model。

报告写不完的时候

整理报告由模型一口气写完，而单次输出有长度上限。上限、重试、残篇标注三件事都有明确行为：

单次输出上限可配：设置页「自动做梦 → 设置 → 高级设置 → 单次输出上限」（默认 32768 token，范围 1024–131072）。思考型模型的思考与正文共用这份额度；收尾那轮思考吃满时正文会一个字不剩 —— 这类报告先把上限调大再跑。
零正文先重试：一轮额度用尽却没有任何正文（只剩思考）时，先要求它「直接输出正文、不要重新分析」重试；最多 2 次，仍为零才标残篇。撞上限但有正文的，按「从中断处继续写」续写（最多 3 轮）。
残篇会被指出来：报告首屏、整理声明、机读记录与设置页「上次运行」那一行都会标「报告被截断（残篇）」—— 不会再把半篇报成「成功」。收尾那一步没写文字时，报告写「模型没有给出文字说明」，不拿中途旁白顶替。

回滚点

只要这次是「直接改写」，开工前就先建一个回滚点（记忆目录顶层 .md 全量快照，每条带 sha256），跑完之后能在设置页看到它、也能一键退回去。

回滚点与这次运行绑定：报告里写着 runId，回滚点目录同名，两边对得上。
回滚本身也能退：动手之前会先把「现在」再存一份保护快照（不参与普通快照的轮转淘汰）。
范围可选：只恢复这次运行动过的文件，或整目录回到该时点。
全程不删文件：回滚中「不该存在」的文件一律移进 archive/，人工可捞回；有同名冲突就跳过并计数，绝不覆盖。
每次回滚都留痕：报告目录里写一份回滚报告，并在状态目录里追加一条记录。

整理声明：改了什么、为什么

每一次整理都留下一份声明，两种形态：人读的 memory/autodream/<runId>.md（报告里内嵌）、机读的 .sage-mem/autodream/runs/<runId>/manifest.json。

逐条记录：文件 / 操作（新建·改写·归档）/ 缘由 / 字节变化，外加运行前后的结构审计对比。

2.4.0 起，声明还会逐条列出「被删掉的事实」：改写与归档都可能让原来写着的几条事实不再存在，而结构审计（断链 / 格式 / 索引）看不见事实丢失 —— 它能报的每一项都可能是绿的。所以每次删到东西，声明里单开一节，把不再存在于活动记忆里的原文逐条列出来（带原文行号，方便回快照对），改写还会写明行数变化。自动归档策略收走的文件同样列。事实由宿主拿「写之前的正文」与「写进去的新正文」对比算出，不靠模型自述 —— 模型可以漏报，diff 不会。一处真实教训：2026-11-05 那趟整理把一条仍然生效的「到期 2027-10-03、不自动续费」压掉了，自报「审计 2 问题 → 0 问题」全绿。

reason 应当填写。 write_memory 不带 reason 不会被拒绝 —— 改动照样生效，但声明里会把它标成「未自述」并附上宿主能追溯到的信息（第几轮 / 什么操作 / 字节变化）。理由：为了一句解释而丢掉一次本来正确的修正，代价更大。
archive_memory 的 reason 仍必填，缺了直接拒绝；被拒的动作单列一节「未能落地的改动」，不会静默消失。

三道安全网

安全边界在工具集上，不在提示词里 —— 自动做梦时宿主只把只读工具交给模型，改写模式才多给改写工具；而且没有「删除」这个能力，归档是把文件移进 archive/，可以人工捞回。
改写前自动建回滚点，落在 <记忆目录的上一层>/.sage-mem/autodream/snapshots/<runId>/，保留最近 N 份。理由是记忆目录不在任何版本控制下、删除没有回收站，「可回滚」得自己造。
跑完自动审计 —— 索引悬空、漏索引、type 与文件名前缀不一致、CRLF、双链断链、frontmatter 里被 YAML 当注释吞掉的「空格 + #」、无 frontmatter、归档中途残留的临时文件，外加「读不动」单列一类，结果与前后对比写进报告。它只报不改。索引 MEMORY.md 是清单而不是一条记忆，因此不参与「type 与前缀」和「无 frontmatter」这两项（1.9.1 起）。

改名说明

本功能原名「做梦」（标识 dream），0.7.0 起叫 自动做梦（autodream）。旧数据不会被丢：老的配置 .sage-mem/dream.json 会被读出来并迁移到 .sage-mem/autodream.json（旧文件保留不动），老报告 memory/dream/ 仍在面板里列出并标「旧版」，老快照也仍可回滚。

从 Claude Code 迁移

如果你已经在 Claude Code（CC）里养了一个 agent，sage-mem 是「CC → DSH」迁移方案的一部分。我们自己的记忆就是这么迁过来的 —— 当时两边的记忆都已经是 Markdown 文件，直接拷过来就能用。

两样东西的搬法不一样，说清楚：

搬什么	从	到	怎么搬
人格	CC 的 `CLAUDE.md`	DSH 的 `AGENTS.md`	都是纯文本、DSH 原生加载，内容照搬即可
记忆	CC 里沉淀的跨会话语料	sage-mem 的 `memory/` 目录	一条记忆一个 `.md`，带 frontmatter，按 `user` / `feedback` / `project` / `reference` 四类归位

⚠️ 前提是形状对得上。 四类划分与 frontmatter 是 sage-mem 自己的约定：如果你在 CC 里的记忆本来就是「一条一个 Markdown + frontmatter」（我们当时是这种），拷过来即可；如果不是（比如都堆在一个 CLAUDE.md 里），需要先整理一遍 —— 这活儿正好可以交给一个 agent 做：让它读旧语料，按四类落成文件。

配置参考

环境变量

变量	默认	说明
`SAGE_MEM_DIR`	`~/.sage-mem/memory`	记忆目录
`SAGE_MEM_STATE_DIR`	`<记忆目录的上一层>/.sage-mem`	状态目录（配置、台账、锁、冲突队列、回滚点）
`SAGE_MEM_MAX_SESSION_BYTES`	`61440`（60 KiB，4096–524288）	单场会话注入总量上限
`SAGE_MEM_MAX_RESULTS`	`10`（1–30）	每轮注入的候选条数上限
`SAGE_MEM_MAX_CHARS`	`1500`（200–20000）	单条记忆注入的字符上限
`SAGE_MEM_MAX_BASELINE`	`8`（1–50）	`baseline` 名额
`SAGE_MEM_STALE_DAYS`	`1`（0–365）	标题标「保存于 N 天前」的门槛；0 = 每条都标
`SAGE_MEM_TASK_ID`	空	任务检查点的作用域；空则回落会话 id
`SAGE_MEM_DEBUG`	关	调试日志；打开后面板「工具 ▾ → 注入调试」显示最近 8 次注入的账（只读、不落盘；同时列出被已失效标注 / 未裁决矛盾挡在正文外的记忆与理由，矛盾还带冲突 id）
`SAGE_MEM_VALIDITY`	开	失效过滤与矛盾抑制的总开关。只认 `0` / `false` / `off` 为关闭（空值、拼错都按开启）；关掉后回到 1.9.x 的注入行为

取值语义：越界夹到边界，非法值（含纯空格）回落默认。

状态根的范围与迁移（2.1.13 起写清）：SAGE_MEM_STATE_DIR 是唯一的状态根 —— 设置、自动做梦配置与报告、锁表、访问台账、冲突队列、任务检查点、回滚快照、台账都在它下面，插件内所有模块（含自动做梦引擎与锁表）都从同一个值解析，不再各自按记忆目录的父目录去拼。更改状态根不会自动迁移旧数据：新根优先、旧的 .sage-mem 原样保留但不再读取，启动时会打印一行提示点名旧根里还有哪些数据；要保留请手动移动。

设置页里能改的

面板可改上面五个上限（写入 <状态目录>/settings.json，优先级 设置页 > 环境变量 > 内置默认），以及保留名（受保护、设置页不许写删的文件名，写入 <状态目录>/reserved.json）。部分项要重启 DSH 才生效，面板上会写清「当前生效 / 重启后」。

状态目录里的文件

文件	用途
`access.json`	访问台账（`injected` / `read` / `use`）
`conflicts/<id>.json`	待处理的冲突：写入失败，或一对等待裁决的矛盾
`tasks/<任务 id>/WORKING.md`	任务检查点
`settings.json` / `reserved.json` / `locked.json`	设置、保留名、锁定
`autodream.json`、`autodream/`	自动做梦的配置、快照、运行记录
`dream.json`	旧版名字，只在迁移时读一次

除 access.json、conflicts/、tasks/ 之外，其余是实现内部状态，格式可能在小版本里变，别依赖。

稳定性与版本策略

1.0.0 是这个项目的稳定线。 从这一版起，「你可以依赖什么」不再是一段自我评价，而是可被机器推翻的清单：

契约冻结 —— 公开面逐条写清定性，只有四种措辞：保证（有断言支撑，回归会红）/ 尽力（设计如此、有实测依据，但没有会红的回归断言）/ 明确做不到（能力边界，是取舍不是缺陷）/ 未验证（我们不知道）。
每条「保证」都指得出一条具体断言（某个测试套件里的一项），并在每次 npm test 里由 test/contract-binding-test.mjs 核对「这条断言真的跑过」。指不出断言的承诺，只能标「尽力」或「未验证」。
能力边界表 与契约逐行交叉引用，由 test/doc-consistency-test.mjs 核对两边定性相同。

版本号怎么涨（语义化版本）：

改动	版本
改契约里标「保证」的任何一条、改工具名或必填参数、去掉老格式台账的读兼容、改注入段名	大版本
改措辞、改排序细节、改内部状态文件格式、改面板、加新的环境变量、改性能	小版本 / 补丁

从 0.9.x 升到 1.0.0：没有破坏性变更 —— 工具名、参数、环境变量名与默认值、注入段名、台账格式一个都没改。唯一的行为变更是：整数型环境变量填纯空格时，现在回落默认值（此前会被当成 0 而夹到下限）。逐条清单见 CHANGELOG 的 1.0.0 一节。

审查材料（给愿意深挖的人）：

文件	内容
1.0.0-contract.md	公开承诺逐条定性 + 每条保证指向的断言
1.0.0-boundaries.md	38 条能力逐条定性（含依据与验证手段）
1.0.0-eval-report.md	检索质量与预算的量化结果，以及这些数字测不到什么
review-findings.md	外部复审发现的永久账：每条发现、处置、由哪条断言看着
release-checklist.md	发版纪律（脱敏四查、评测退出码、探针、四锚点）

权限与隐私

sage-mem 只做三件事，全都在你本机：

它做什么	具体范围
读记忆	只读 `SAGE_MEM_DIR`（默认 `~/.sage-mem/memory`）下的顶层 `*.md`，单文件上限 512 KB
写记忆	经模型的文件工具或设置页写同一个目录；`MEMORY.md`、`session-log.md` 等保留名受保护，设置页碰不到
注入	把选中的记忆作为上下文交给模型（最多 10 条相关 + 8 条 `baseline`，单场会话累计 60 KB —— ⚠️ 这个上限是软的，见检索与注入）

它不做什么：不开端口、不起常驻进程、不需要任何 API key；不做事件全捕获（存不存由模型按规则判断，不是「你说了什么都记」）。

两处出网 / 越界读，说清楚：

版本检查：打开「记忆管理」页时会静默请求一次 https://api.github.com/repos/gezi-wen/sage-mem/releases/latest（10 秒超时，失败一律不提示）。请求里只有插件自己的 User-Agent；不含任何记忆内容、文件路径或使用统计。环境里有 GITHUB_TOKEN / GH_TOKEN 时会带上它（把 GitHub 未认证的 60 次/小时提到 5000）。这是唯一的出网请求。
会话记录：「自动做梦」的输入源选「记忆 + 会话记录」时，它会额外读 $DSH_HOME/sessions 下的会话记录做定向搜索 —— 那会解压你的对话原文（含私密内容）并送进模型上下文。默认关闭。

唯一会调用模型的功能是「自动做梦」，默认关闭。 它的模型默认跟随当前会话默认模型，也可以在设置页单独指定一条 —— 指定了就只认它，不会静默回落。

记忆就是那个目录里的文件，随时可以打开确认 —— 这也是选文件式的原因。

记忆目录的信任边界：能写记忆目录的人就能改变注入给模型的内容 —— 这属于信任模型内部，不是插件的漏洞。读路径在检查时会拒绝符号链接、保留名别名与超过 512 KB 的文件，读取时还会复核文件身份（检查之后被换掉的文件会被拒绝，而不是照读）；但它防不住一个已经被允许修改你记忆的人。把目录权限收到你自己的账号。

兼容性

sage-mem 是纯 DSH 插件，用 package.json 的 engines.dsh 声明宿主要求：>=0.1.2-rc.1 —— 单边开区间、不设上界，所以任何未来的 DSH 版本都不会被这道声明挡住。engines.node 要求 >= 18。

已在 DSH Go（Android 客户端）上验证可用：从 App 内插件市场安装后，设置分区与侧栏面板正常、sidebar.panellist 岛屿可打开；记忆目录用 SAGE_MEM_DIR 默认的 ~/.sage-mem/memory 即可，不需要额外适配。2.1.1 修掉了手机宿主上主按钮文字不可见的问题（前景令牌兜底）。

逐版本兼容记录：

DSH 版本	状态
0.1.2-rc.1	compatible
0.1.3-alpha.1	compatible
0.1.3-alpha.2	compatible
0.1.5-rc.1	compatible
0.1.6-alpha.1	compatible
0.1.6-alpha.2	compatible
0.1.7-rc.1	compatible
0.1.7-rc.2	compatible
0.2.0-rc.1	compatible
0.2.0-rc.2	compatible
0.2.1-rc.1	compatible
0.2.1-rc.3	compatible
0.2.1-rc.4	compatible
0.2.1-rc.5	compatible

compatible 怎么读：它表示本插件的 codec / manifest 契约在该宿主代上核对过（代码层比对 + 单元/契约测试），不表示在那个确切宿主构建上跑过端到端探针。这张表是声明，核对方式总结在下面。真实宿主探针目前跑过 headless（2026-10-15）、web（2026-10-16）、0.2.1-rc.3 上的 web（2026-10-27，2.0.0 发布前：客户端激活、冲突面板裁决、注入抑制、回退到 1.9.2，23/23 项通过），以及 0.2.1-rc.4 上的 DSH Go 手机引擎（2026-10-31：App 插件市场安装、侧栏面板与设置分区原生呈现、sidebar.panellist 岛屿打开）；0.2.1-rc.5 于同日在本地一个 web 实例上按 dump/启动/面板走查核对；desktop profile 还没跑过（见 release-checklist.md §4b）。CI 在 Ubuntu 上覆盖 Node 18.x / 20.x / 24.x，peer 钉 0.2.0-rc.1 一代；macOS 与 Windows 没有 CI 覆盖，desktop 宿主探针也还没有。

两点值得说明：

同一份构建同时覆盖 0.1.x 与 0.2.x 两条线。 自 DSH 0.1.6-alpha.2 起 TypertCodec 契约从「读 schema」改为「读 create() 工厂」，仍只写 schema: 的插件会在注册阶段直接抛错、把整棵插件树拖垮。本插件的每个 codec 同时带 schema 与 create: () => schema，两个时代的 DSH 都能加载。peer 依赖 @deepseek-ai/dsh-typert-protocol 与 @deepseek-ai/dsh-client-locale 的范围去掉上界，避免以后某个大版本被这道声明误挡（这两个包在 0.1.7-rc.2 与 0.2.0-rc.1 之间导出符号零增删，逐字节比对过）。
带一层防御留痕。 注入链依赖的事件名与字段在日常升级中很稳定；如果哪天 DSH 把它们改成异步或改了名，插件会在日志里报警，而不是静默地不再注入记忆。

架构

DSH（Cordis 插件宿主）
  └─ sage-mem 插件（按问题检索 + 注入）← 本仓库
       │  Node fs 直读 / 直写
       ▼
memory/ 目录（markdown 文件，4 类）
  ├── user_*.md
  ├── feedback_*.md
  ├── project_*.md
  ├── reference_*.md
  └── MEMORY.md          ← 索引

没有 worker、没有 SQLite、没有 HTTP 端口、没有常驻进程。

模块边界（1.2.0 起）：

lib/index.js —— 组合根 + 三个 Gateway。typert manifest 的 sourceLocation 钉在这个文件上，所以 Gateway 类不搬走（搬 = 契约漂移）
lib/recall/ —— 注入链：选材（select）/ 渲染与预算（compose）/ 文本（text）/ 会话状态（state）
lib/assembly/ —— 四块挂载：autodream / 检索工具 / 观测 / 写入门
lib/memory/ —— 记忆层的纯函数与文件操作；lib/autodream/ —— 自动做梦引擎
lib/shared/ —— 跨层零依赖的小判据：文件名规则 / 本地时间戳 / 两个体积上限（只许一份，test/duplication-test.mjs 会红）
界面侧：client/*.js 按屏分片（05-shared.js 放跨屏小基元与类型词表），npm run build:client 拼成 lib/client.js
依赖方向：memory 不认识 autodream，recall 只依赖 memory，assembly 不反向依赖组合根（test/structure-test.mjs 会红）

参与开发

git clone https://github.com/gezi-wen/sage-mem
cd sage-mem
npm install
npm test          # 全部断言（含三条守卫）

断言脚本只依赖 node: 内置模块，不引测试框架，各脚本手写 ok() 并以汇总行收尾。
本仓库统一用 npm 安装 / 测试 / CI。不留 pnpm-lock.yaml：旧的锁在 fresh clone 里 --frozen-lockfile 装不动（它依赖的 workspace 文件未入库），留着只会误导。
三条守卫盯的是「测试本身站不站得住」：suite-registry-test.mjs（有没有写了不跑的套件）、 contract-binding-test.mjs（有没有说了不验的承诺）、doc-consistency-test.mjs（两份文档的定性是否逐行一致）。
CI 在 ubuntu-latest 上跑两遍（第二遍 TZ=UTC）—— 区分大小写的卷能逮到 Windows 上看不见的缺陷。
改了用户可见行为时，请同时更新契约的对应行与 CHANGELOG；写不出断言的承诺只能标「尽力」。

问题与建议：开 Issue。小而明确的修复欢迎直接提 PR；改动面较大的先开 Issue 对齐方向，免得白做。

常见问题

升级到 2.0.0 之后，注入行为变了什么？ 2.0.0 是行为变更版（所以按 MAJOR 发）：① 带 invalid_at 且已到点的记忆不再进正文；② 有未裁决矛盾的记忆两方都不进正文，直到你在「记忆管理 → 库健康」页签里裁决；③ 没有标注的旧记忆行为不变，不需要迁移，也不会有迁移脚本。回退到 1.9.x 是安全的：不会损坏任何数据，但「失效」标记会被旧版本忽略（失效记忆重新注入）、冲突页签消失 —— 那是功能消失，不是数据损坏。如果只想关掉这层过滤、保留本版其它修复，用 SAGE_MEM_VALIDITY=0（只认 0 / false / off 为关闭）。

记忆没被注入怎么办？ 先确认记忆目录对不对（SAGE_MEM_DIR，默认 ~/.sage-mem/memory），再看文件有没有 frontmatter（坏掉的 frontmatter 会被宽容解析：字段回落默认，文件照样读得到）。面板里的「体检」页会报出索引悬空、漏索引、断链这类结构问题。

为什么换个说法就搜不到了？ 检索是词面重合，不是语义的。给这条记忆加一行 aliases: [另一种说法] 即可。这是有意的取舍，不是待修的缺陷。

它会不会把我说的每句话都记下来？ 不会。存不存由模型按规则判断：无实质内容的不存，靠读代码 / git 能推出来的不存。

我想看看它到底存了什么。 打开记忆目录，全是 Markdown。GUI 里的「记忆管理」页也能浏览、编辑、删除。

多个 DSH 实例共用同一个记忆目录安全吗？ 不。写入串行只保证进程内，跨进程没有文件锁 —— 同时用两个实例写同一目录仍可能丢一次。这是已知边界。

能不用自动做梦吗？ 能，它默认就是关闭的。它和归档是两件事：归档是确定性规则（按闲置天数），不调模型、不花钱。

插件市场报「registry 上的最新版比已装还旧，更新会降级」？ 那是下载地区镜像的 /latest 缓存滞后，不是包发错了：镜像的全量元数据（pnpm 读的那份）已经是新版，但 /<包>/latest 这个快捷入口还缓存着旧值。先等一两分钟重试；仍然不行就把插件市场的「下载地区」临时切到「全球」（直连 registry.npmjs.org）更新，完成后再切回。核对实际发布版本：npm view sage-mem dist-tags。

顶部「月下载量」为什么改成了 endpoint 徽章？ npm 官方的 downloads/point/last-month 接口从 2026 年 7 月起对所有包都返回 0，npm/dm 徽章因此渲染成红色的 0/month；现在这个数字由 GitHub Actions 每天从仍然可用的 downloads/range 接口求和，发布到 badges 分支，再用 shields.io endpoint badge 渲染。若它超过约 2 天没变化，通常只是定时任务延迟（或 npm 接口故障，此时会特意保留上一次的正常值）。

卸载

dsh plugin --profile web remove sage-mem

或手动在 profile 的 package.json 里删掉 sage-mem 依赖、并从 dsh.profile.bundles 移除 "sage-mem"；pnpm install 后重启 DSH。

记忆 Markdown 文件留在原目录，不受影响。

维护者

@gezi-wen

致谢

@bjvgukv25842-cmyk（LITMUS）—— 最早的 Web 记忆管理界面，记忆管理页从这一版开始。
@miztizm（mjztjzm）—— 记忆管理面板的 i18n：字典分片、ctx.locale 接入，三屏跟随宿主语言（1.9.0）。
@DDDMUC（暮迟）—— 三处：文件列表的「打开记忆文件夹」入口；注入链的短路闸门（2.4.3，同一个问题不再每一步重算）；注入段声明 interpolate: false（2.4.2，记忆里写了双大括号不再让整轮对话崩掉）。
DeepSeek Harness —— 插件宿主与 Cordis 插件体系。

这个插件活到今天，靠的不只是我一个人。上面按代码进入仓库的顺序排。漏了谁的话开个 issue 骂我，我补上。

旧版

本仓库早期是 SQLite + worker 架构，已归档到 sqlite-worker 分支。文件式是继任实现。

License

Apache-2.0 · 见 LICENSE

sage-mem · DSH 的文件式记忆插件 (sage-mem)

English · README.en.md

给 DeepSeek Harness（DSH）装上跨会话记忆：每条记忆都是本地的一个 Markdown 文件。

File-based cross-session memory for DeepSeek Harness — every memory is a plain markdown file you can open, edit and delete. No database, no worker, no port.

如果它对你有用，给个 Star 是最直接的反馈。

这是什么

DSH 原生没有记忆系统。每开一个新会话都是一张白纸：不记得你是谁、不记得昨天做到哪、不记得项目进行到哪一步，于是你每次都要重新交代一遍。

所以准确的说法不是「模型记得你」，而是「在它开口之前，有人把相关的纸条递进了它手里」。撤走纸条，它又是那个失忆的同事。

为什么是文件，不是数据库

	文件式（sage-mem）	数据库 + worker
看一眼存了什么	打开目录	查表 / 写脚本
手工改一条	编辑器直接改	走 API 或 SQL
迁移 / 备份	拷目录（能跟 git 走）	导出工具
额外进程与端口	无	通常有
存不存谁决定	由 agent 按规则判断	常见做法是无差别全捕获

核心特性

特性	说明
文件式存储	每条记忆一个 `.md`：frontmatter 存元数据，正文存内容。无数据库、无隐藏格式
自动注入	每条新问题都会重新扫一遍记忆目录，按这条问题挑出最相关的几条，在模型开口之前拼进上下文 —— 不用模型自己去翻文件
模型也能自己查	另给模型两个检索工具（`search_memory` / `read_memory`），它可以主动翻记忆、按行读原文
写入不被覆盖	你正在编辑、模型同时在改的时候，后写的不会静默盖掉先写的；冲突留成待处理记录，由你决定保留哪边
零额外服务	无 worker、无 SQLite、无端口、无常驻进程，不需要额外的 API key 或云服务（运行时唯一的依赖是普通 npm 库 `zod`）
防膨胀	靠规则引导模型判断「值不值得存」：无实质内容的不存，靠读代码 / git 能推出来的不存
可整理	可选的「自动做梦」把记忆通读一遍：合并重复、修索引与断链，改动前先建回滚点
从 Claude Code 迁移	人格（`CLAUDE.md` → `AGENTS.md`）照搬；记忆按四类整理成 `.md` 即可（见下一节）
自带使用指南	包内携带一份技能（`skills/sage-mem/`）：记忆长什么样、四类怎么分、什么不该存、frontmatter 的坑、检索怎么工作、索引坏了怎么修。装上插件就够了 —— Agent 拿到说明书，不需要手工配置

界面上还有四块能力（都可以不用）：记忆管理页、类型与标签筛选、时间线（默认是条目列表，可切星空视角）、体检与归档。

快速开始

需要 DSH 0.1.2-rc.1 或更高（见兼容性）、Node.js >= 18。

# 把 web 换成你自己的 profile 名
dsh plugin --profile web add sage-mem

dsh plugin add 会把包装进这个 profile 并登记它的 bundle —— 不用手改 package.json（手动装法见下）。

装完重启 DSH，确认装上了：

dsh plugin --profile web list

然后开一个新会话试三步：

跟模型说「记住：我的猫叫芝麻，它喜欢晒太阳」—— 它按规则把这条写进记忆目录
再开一个新会话，问「我的猫叫什么」
它的第一个回答就该答出「芝麻」—— 记忆由插件自动检索并注入，模型没有主动去翻文件

手动安装（不想用 CLI，或要装本地开发版本）

在 profile 的 package.json 里加依赖，并把包名写进 dsh.profile.bundles：

{
  "dependencies": {
    "sage-mem": "^1.0.0"
  },
  "dsh": {
    "profile": {
      "bundles": ["sage-mem"]
    }
  }
}

本地开发用 clone 出来的源码：

{
  "dependencies": {
    "sage-mem": "link:../sage-mem"
  }
}

改完跑 pnpm install，再重启 DSH。

记忆放在哪

默认在 ~/.sage-mem/memory。想放到别处（比如放进项目仓库、跟着 git 走）就设环境变量：

SAGE_MEM_DIR=/path/to/your/memory

状态目录（配置、台账、回滚点、冲突队列）默认在记忆目录的上一层：<记忆目录>/.sage-mem。全部环境变量见配置参考。

界面预览

下面每张图都是从仓库里的界面代码渲染出来的（同一份 CSS、同一棵组件树；数据是演示用的假数据，不是真实记忆目录）。

文件列表：每条记忆一个 Markdown 文件，灰底的是已归档

工具抽屉：归档候选 / 保留名编辑，关着时零占位

工具抽屉 —— 关着时只占一个按钮，展开后两项各带状态。

锁定：按钮在「编辑」与「归档」之间，锁上后归档被禁用

编辑记忆：右侧抽屉，列表不再被顶下去

编辑记忆 —— 编辑走右侧抽屉，字段与校验跟以前一样，只是不再把列表顶下去；「取消」「点遮罩」「Esc」三条出口都能关掉它。

危险动作：统一模态确认，两段式不变

体检：独立一页，硬问题按类报红分节

更新提示 —— 只在真有新版本时出现一条横幅，写明新版本与当前版本；「看更新内容」开新标签页，「×」只是这次不看。

归档候选：每条写清「为什么建议归档」，确认后才执行

时间线（默认视角）：按更新时间倒序的条目列表

时间线 —— 打开这个标签先看见的就是这一屏：按更新时间倒序的条目列表，最近改过的在最上面。想看图，右上角「星空」自己切。

时间线 · 星空视角：暗星是已归档的记忆

切到「星空」之后 —— 颜色对应类型、大小对应体积、亮度对应新鲜度，暗星是已归档的记忆，点开可看归档时间与理由。

自动做梦 · 设置

自动做梦 · 设置 —— 运行 / 设置 / 记录二级分组；五个注入参数两列排开，并写清「当前生效」与「重启后」。

自动归档：自动整理屏上的第二张卡 —— 自带运行 / 设置两段，一个开关、两档策略

时间线 · 星空视角

「星空」视角全貌 —— 画布上只画关系与分布；悬停或点开某颗星时才显示那一条的文件名。渲染是按需重绘，画面静止时不发起任何绘制。

记忆文件格式

---
name: 可选的短名
description: 一句话说清这条记忆是什么（检索靠它，务必写准）
metadata:
  type: user        # user / feedback / project / reference
tags: [项目, 待办]   # 可选，供列表页筛选（最多 20 个、每个 40 字符）
aliases: [待办, todo] # 可选：换一种说法也能被检索到
baseline: true      # 可选：新会话第一步无条件注入（上限 8 条）
baselinePriority: 10 # 可选：多条 baseline 之间谁先注入（越大越前）
---

记忆正文。

四类记忆：

类型	存什么
`user`	用户是谁
`feedback`	工作方式指导（建议带 `Why:` 与 `How to apply:` 两行，方便判断边界）
`project`	进行中的工作与状态
`reference`	外部信息在哪找的指针

单文件上限 512 KB，读写两侧都校验（读的时候先看体积，超了就不读进来）。

检索与注入

透明的东西值得说清楚它怎么选料，因为这直接决定注入多少 token。

⚠️ 这个上限是软的，不是硬闸门。 baseline 记忆被问句命中时会照注不误、不参与降级，所以单场累计正文可能超出正文池（评测里量到 9.6% 的超支，全部来自这类记忆）。这是有意的取舍：那类记忆的语义就是「每场都该在场」。别把它当成「到 60 KB 就一刀切断」。

离线评测集上的对照（门槛前后）：Recall@5 84.1% → 87.0%、误注入（注入了与问题无关的记忆）14.1% → 5.6%。

⚠️ 这些是测量，不是承诺：可迁移的是相对改进，绝对水平不可外推到真实记忆目录 —— 那 30 份语料的摘要本来就是照着「能被检索到」手写的，真实记忆的摘要往往写得很随意甚至缺失。方法与局限见评测报告。

模型也能自己翻：两个工具

检索的触发权分两半：一半在插件（自动注入，它猜你想看什么），一半在模型（下面这两个工具，它主动查）。

工具	用途
`search_memory(query, scope?, limit?, cursor?)`	先比摘要、再按段落查正文；返回候选、命中片段、行号，以及覆盖情况（扫了几份、几段因相关性不够被滤掉、有没有下一页）
`read_memory(name, startLine?, startByte?, maxBytes?, revision?)`	按行分页读正文。带上你上次读到的 `revision`，内容被人改过时会回 `revision_changed`，并且不返回内容 —— 否则你会拿着过期行号读错东西

长任务的接力棒：任务检查点

写入安全

守卫分两条路，覆盖面不一样，说清楚：

谁在写	怎么保护	被拒时
模型用内置 `write` / `edit` 改记忆	插件在前置事件里给出「当前版本」，宿主据此拒绝过期覆盖	宿主直接拒绝（报 `FS_STALE_VERSION`）。这条路的拒绝不留冲突记录 —— 写门只提供版本，不做拒绝动作
插件自己写（自动做梦的整理）	调用方在写入时带上读到的版本	落一条待处理记录 `<状态目录>/conflicts/<id>.json`，里面留着盘上那一版和想要写的那一版 —— 只有一边等于没得判

冲突不会自动合并，保留哪边由你决定（记录是 JSON，需要时直接打开看）。静默重试和静默放弃都是在替你决定。
2.0.0 起注入侧会读这个队列：只有 kind: contradiction 且 status: open 的矛盾型两方被抑制；另外三种写失败型（stale_version / external_change / unresolved_merge）照常注入 —— 盘上那份才是现行内容。裁决入口与抑制是同一次交付，不再有「只接抑制、没有入口」的状态。
裁决在「记忆管理 → 库健康」页签的冲突卡（一屏两张卡里在上面的那张，面板头部另有常显徽标）：逐条看两份正文，动作是「标此条失效」「撤销失效」「删除记录」，危险动作两段式确认。「标失效」只往记忆 frontmatter 加一行 invalid_at（可选再写 superseded_by）—— 文件留在原位、正文一个字节不动、不改 updated；写盘幂等（连点两次不重写）、可撤销，失败时明确返回错误、记录保持待裁决。
冲突记录字段只增不改：2.0.0 在尾部追加 otherFile / decision / decidedAt / appliedVersion / invalidatedFile 五个，记录版本仍是 1；1.9.x 读端忽略不认识的键，双向都不用迁移。
手工编辑不在看守范围：直接改文件也生效（删掉 invalid_at 就恢复注入），插件不拦手改 —— 这是文件式记忆的取舍，见能力边界表 C11。
同一件事不会越积越多：一次失败如果与队列里某条未裁决记录逐字段相同（同一文件、两份正文、两个版本），不再追加副本。
宿主的文件沙箱：自动做梦在会话外运行，拿不到会话工作区。宿主用 workspace-write 时，插件给每次写入带上收窄到记忆目录的逐次沙箱策略（比回退根更窄）；宿主是 read-only 时不传策略、写入照旧被拒，且这一趟会被记成失败（不是「成功，没改什么」）。
已知边界：在 shell 里改记忆不走这条路。写门守的是「经过工具的记忆写入」，不是「所有对文件的修改」；pwsh 里的重定向之类认不出来。认不准就不认，免得把「看不到」误记成事实。

访问台账：三种「用过」分开记

<状态目录>/access.json 记三件事：

字段	含义
`injected`	插件被动注入了这份记忆
`read`	模型主动读了它
`use`	明确被采用的次数（自报）

这张台账目前只用于诊断与自动归档阈值，不参与检索排序。 观测有已知盲区：在 shell 里读记忆认不出来，那就不认。

记忆的新鲜度与引用纪律

自动做梦

默认关闭，在设置页「记忆管理 → 自动做梦」里开。三件事各自可选：

选项	取值	说明
触发	只手动 / 满足条件自动跑	自动模式走三级门控，最便宜的先查：时间门（距上次 ≥ N 小时，一次读写）→ 会话门（期间 ≥ M 个会话有更新，一次目录扫描）→ 锁（防并发）。中间夹一层 10 分钟扫描节流，免得「时间门过了、会话门没过」时每轮白扫
改动方式	只出报告 / 直接改写	「只出报告」模式下写工具根本不会挂给模型 —— 不是靠一句「请不要写」约束，是它没有手
输入源	仅记忆目录 / 记忆 + 会话记录	后者会解压会话记录（zstd）做定向关键词搜索；代价是私密对话会进入模型上下文，token 成本也更高

自动触发走插件自己的定时器（默认 30 分钟查一次门控）。整理刻意不走会话 —— 工具集由插件给、步数有上限、不写进你的会话记录。

整理用的模型可以单独指定

选了就只认它：路线在宿主里不存在时开工前就报错（只比对宿主已注册的目录、不发任何请求），不会跑到一半才失败，也不会静默回落到默认模型。
面板下方始终显示实际生效的是哪条；配置里那条路线万一从目录里消失了，下拉框也会把它显示出来而不是悄悄跳回默认。
拿不到模型目录时（宿主差异），退化成手填 provider 与 model。

报告写不完的时候

整理报告由模型一口气写完，而单次输出有长度上限。上限、重试、残篇标注三件事都有明确行为：

单次输出上限可配：设置页「自动做梦 → 设置 → 高级设置 → 单次输出上限」（默认 32768 token，范围 1024–131072）。思考型模型的思考与正文共用这份额度；收尾那轮思考吃满时正文会一个字不剩 —— 这类报告先把上限调大再跑。
零正文先重试：一轮额度用尽却没有任何正文（只剩思考）时，先要求它「直接输出正文、不要重新分析」重试；最多 2 次，仍为零才标残篇。撞上限但有正文的，按「从中断处继续写」续写（最多 3 轮）。
残篇会被指出来：报告首屏、整理声明、机读记录与设置页「上次运行」那一行都会标「报告被截断（残篇）」—— 不会再把半篇报成「成功」。收尾那一步没写文字时，报告写「模型没有给出文字说明」，不拿中途旁白顶替。

回滚点

回滚点与这次运行绑定：报告里写着 runId，回滚点目录同名，两边对得上。
回滚本身也能退：动手之前会先把「现在」再存一份保护快照（不参与普通快照的轮转淘汰）。
范围可选：只恢复这次运行动过的文件，或整目录回到该时点。
全程不删文件：回滚中「不该存在」的文件一律移进 archive/，人工可捞回；有同名冲突就跳过并计数，绝不覆盖。
每次回滚都留痕：报告目录里写一份回滚报告，并在状态目录里追加一条记录。

整理声明：改了什么、为什么

每一次整理都留下一份声明，两种形态：人读的 memory/autodream/<runId>.md（报告里内嵌）、机读的 .sage-mem/autodream/runs/<runId>/manifest.json。

逐条记录：文件 / 操作（新建·改写·归档）/ 缘由 / 字节变化，外加运行前后的结构审计对比。

reason 应当填写。 write_memory 不带 reason 不会被拒绝 —— 改动照样生效，但声明里会把它标成「未自述」并附上宿主能追溯到的信息（第几轮 / 什么操作 / 字节变化）。理由：为了一句解释而丢掉一次本来正确的修正，代价更大。
archive_memory 的 reason 仍必填，缺了直接拒绝；被拒的动作单列一节「未能落地的改动」，不会静默消失。

三道安全网

安全边界在工具集上，不在提示词里 —— 自动做梦时宿主只把只读工具交给模型，改写模式才多给改写工具；而且没有「删除」这个能力，归档是把文件移进 archive/，可以人工捞回。
改写前自动建回滚点，落在 <记忆目录的上一层>/.sage-mem/autodream/snapshots/<runId>/，保留最近 N 份。理由是记忆目录不在任何版本控制下、删除没有回收站，「可回滚」得自己造。
跑完自动审计 —— 索引悬空、漏索引、type 与文件名前缀不一致、CRLF、双链断链、frontmatter 里被 YAML 当注释吞掉的「空格 + #」、无 frontmatter、归档中途残留的临时文件，外加「读不动」单列一类，结果与前后对比写进报告。它只报不改。索引 MEMORY.md 是清单而不是一条记忆，因此不参与「type 与前缀」和「无 frontmatter」这两项（1.9.1 起）。

改名说明

从 Claude Code 迁移

两样东西的搬法不一样，说清楚：

搬什么	从	到	怎么搬
人格	CC 的 `CLAUDE.md`	DSH 的 `AGENTS.md`	都是纯文本、DSH 原生加载，内容照搬即可
记忆	CC 里沉淀的跨会话语料	sage-mem 的 `memory/` 目录	一条记忆一个 `.md`，带 frontmatter，按 `user` / `feedback` / `project` / `reference` 四类归位

配置参考

环境变量

变量	默认	说明
`SAGE_MEM_DIR`	`~/.sage-mem/memory`	记忆目录
`SAGE_MEM_STATE_DIR`	`<记忆目录的上一层>/.sage-mem`	状态目录（配置、台账、锁、冲突队列、回滚点）
`SAGE_MEM_MAX_SESSION_BYTES`	`61440`（60 KiB，4096–524288）	单场会话注入总量上限
`SAGE_MEM_MAX_RESULTS`	`10`（1–30）	每轮注入的候选条数上限
`SAGE_MEM_MAX_CHARS`	`1500`（200–20000）	单条记忆注入的字符上限
`SAGE_MEM_MAX_BASELINE`	`8`（1–50）	`baseline` 名额
`SAGE_MEM_STALE_DAYS`	`1`（0–365）	标题标「保存于 N 天前」的门槛；0 = 每条都标
`SAGE_MEM_TASK_ID`	空	任务检查点的作用域；空则回落会话 id
`SAGE_MEM_DEBUG`	关	调试日志；打开后面板「工具 ▾ → 注入调试」显示最近 8 次注入的账（只读、不落盘；同时列出被已失效标注 / 未裁决矛盾挡在正文外的记忆与理由，矛盾还带冲突 id）
`SAGE_MEM_VALIDITY`	开	失效过滤与矛盾抑制的总开关。只认 `0` / `false` / `off` 为关闭（空值、拼错都按开启）；关掉后回到 1.9.x 的注入行为

取值语义：越界夹到边界，非法值（含纯空格）回落默认。

设置页里能改的

状态目录里的文件

文件	用途
`access.json`	访问台账（`injected` / `read` / `use`）
`conflicts/<id>.json`	待处理的冲突：写入失败，或一对等待裁决的矛盾
`tasks/<任务 id>/WORKING.md`	任务检查点
`settings.json` / `reserved.json` / `locked.json`	设置、保留名、锁定
`autodream.json`、`autodream/`	自动做梦的配置、快照、运行记录
`dream.json`	旧版名字，只在迁移时读一次

除 access.json、conflicts/、tasks/ 之外，其余是实现内部状态，格式可能在小版本里变，别依赖。

稳定性与版本策略

1.0.0 是这个项目的稳定线。 从这一版起，「你可以依赖什么」不再是一段自我评价，而是可被机器推翻的清单：

契约冻结 —— 公开面逐条写清定性，只有四种措辞：保证（有断言支撑，回归会红）/ 尽力（设计如此、有实测依据，但没有会红的回归断言）/ 明确做不到（能力边界，是取舍不是缺陷）/ 未验证（我们不知道）。
每条「保证」都指得出一条具体断言（某个测试套件里的一项），并在每次 npm test 里由 test/contract-binding-test.mjs 核对「这条断言真的跑过」。指不出断言的承诺，只能标「尽力」或「未验证」。
能力边界表 与契约逐行交叉引用，由 test/doc-consistency-test.mjs 核对两边定性相同。

版本号怎么涨（语义化版本）：

改动	版本
改契约里标「保证」的任何一条、改工具名或必填参数、去掉老格式台账的读兼容、改注入段名	大版本
改措辞、改排序细节、改内部状态文件格式、改面板、加新的环境变量、改性能	小版本 / 补丁

审查材料（给愿意深挖的人）：

文件	内容
1.0.0-contract.md	公开承诺逐条定性 + 每条保证指向的断言
1.0.0-boundaries.md	38 条能力逐条定性（含依据与验证手段）
1.0.0-eval-report.md	检索质量与预算的量化结果，以及这些数字测不到什么
review-findings.md	外部复审发现的永久账：每条发现、处置、由哪条断言看着
release-checklist.md	发版纪律（脱敏四查、评测退出码、探针、四锚点）

权限与隐私

sage-mem 只做三件事，全都在你本机：

它做什么	具体范围
读记忆	只读 `SAGE_MEM_DIR`（默认 `~/.sage-mem/memory`）下的顶层 `*.md`，单文件上限 512 KB
写记忆	经模型的文件工具或设置页写同一个目录；`MEMORY.md`、`session-log.md` 等保留名受保护，设置页碰不到
注入	把选中的记忆作为上下文交给模型（最多 10 条相关 + 8 条 `baseline`，单场会话累计 60 KB —— ⚠️ 这个上限是软的，见检索与注入）

它不做什么：不开端口、不起常驻进程、不需要任何 API key；不做事件全捕获（存不存由模型按规则判断，不是「你说了什么都记」）。

两处出网 / 越界读，说清楚：

版本检查：打开「记忆管理」页时会静默请求一次 https://api.github.com/repos/gezi-wen/sage-mem/releases/latest（10 秒超时，失败一律不提示）。请求里只有插件自己的 User-Agent；不含任何记忆内容、文件路径或使用统计。环境里有 GITHUB_TOKEN / GH_TOKEN 时会带上它（把 GitHub 未认证的 60 次/小时提到 5000）。这是唯一的出网请求。
会话记录：「自动做梦」的输入源选「记忆 + 会话记录」时，它会额外读 $DSH_HOME/sessions 下的会话记录做定向搜索 —— 那会解压你的对话原文（含私密内容）并送进模型上下文。默认关闭。

记忆就是那个目录里的文件，随时可以打开确认 —— 这也是选文件式的原因。

兼容性

逐版本兼容记录：

DSH 版本	状态
0.1.2-rc.1	compatible
0.1.3-alpha.1	compatible
0.1.3-alpha.2	compatible
0.1.5-rc.1	compatible
0.1.6-alpha.1	compatible
0.1.6-alpha.2	compatible
0.1.7-rc.1	compatible
0.1.7-rc.2	compatible
0.2.0-rc.1	compatible
0.2.0-rc.2	compatible
0.2.1-rc.1	compatible
0.2.1-rc.3	compatible
0.2.1-rc.4	compatible
0.2.1-rc.5	compatible

两点值得说明：

同一份构建同时覆盖 0.1.x 与 0.2.x 两条线。 自 DSH 0.1.6-alpha.2 起 TypertCodec 契约从「读 schema」改为「读 create() 工厂」，仍只写 schema: 的插件会在注册阶段直接抛错、把整棵插件树拖垮。本插件的每个 codec 同时带 schema 与 create: () => schema，两个时代的 DSH 都能加载。peer 依赖 @deepseek-ai/dsh-typert-protocol 与 @deepseek-ai/dsh-client-locale 的范围去掉上界，避免以后某个大版本被这道声明误挡（这两个包在 0.1.7-rc.2 与 0.2.0-rc.1 之间导出符号零增删，逐字节比对过）。
带一层防御留痕。 注入链依赖的事件名与字段在日常升级中很稳定；如果哪天 DSH 把它们改成异步或改了名，插件会在日志里报警，而不是静默地不再注入记忆。

架构

DSH（Cordis 插件宿主）
  └─ sage-mem 插件（按问题检索 + 注入）← 本仓库
       │  Node fs 直读 / 直写
       ▼
memory/ 目录（markdown 文件，4 类）
  ├── user_*.md
  ├── feedback_*.md
  ├── project_*.md
  ├── reference_*.md
  └── MEMORY.md          ← 索引

没有 worker、没有 SQLite、没有 HTTP 端口、没有常驻进程。

模块边界（1.2.0 起）：

lib/index.js —— 组合根 + 三个 Gateway。typert manifest 的 sourceLocation 钉在这个文件上，所以 Gateway 类不搬走（搬 = 契约漂移）
lib/recall/ —— 注入链：选材（select）/ 渲染与预算（compose）/ 文本（text）/ 会话状态（state）
lib/assembly/ —— 四块挂载：autodream / 检索工具 / 观测 / 写入门
lib/memory/ —— 记忆层的纯函数与文件操作；lib/autodream/ —— 自动做梦引擎
lib/shared/ —— 跨层零依赖的小判据：文件名规则 / 本地时间戳 / 两个体积上限（只许一份，test/duplication-test.mjs 会红）
界面侧：client/*.js 按屏分片（05-shared.js 放跨屏小基元与类型词表），npm run build:client 拼成 lib/client.js
依赖方向：memory 不认识 autodream，recall 只依赖 memory，assembly 不反向依赖组合根（test/structure-test.mjs 会红）

参与开发

git clone https://github.com/gezi-wen/sage-mem
cd sage-mem
npm install
npm test          # 全部断言（含三条守卫）

断言脚本只依赖 node: 内置模块，不引测试框架，各脚本手写 ok() 并以汇总行收尾。
本仓库统一用 npm 安装 / 测试 / CI。不留 pnpm-lock.yaml：旧的锁在 fresh clone 里 --frozen-lockfile 装不动（它依赖的 workspace 文件未入库），留着只会误导。
三条守卫盯的是「测试本身站不站得住」：suite-registry-test.mjs（有没有写了不跑的套件）、 contract-binding-test.mjs（有没有说了不验的承诺）、doc-consistency-test.mjs（两份文档的定性是否逐行一致）。
CI 在 ubuntu-latest 上跑两遍（第二遍 TZ=UTC）—— 区分大小写的卷能逮到 Windows 上看不见的缺陷。
改了用户可见行为时，请同时更新契约的对应行与 CHANGELOG；写不出断言的承诺只能标「尽力」。

问题与建议：开 Issue。小而明确的修复欢迎直接提 PR；改动面较大的先开 Issue 对齐方向，免得白做。

常见问题

它会不会把我说的每句话都记下来？ 不会。存不存由模型按规则判断：无实质内容的不存，靠读代码 / git 能推出来的不存。

我想看看它到底存了什么。 打开记忆目录，全是 Markdown。GUI 里的「记忆管理」页也能浏览、编辑、删除。

能不用自动做梦吗？ 能，它默认就是关闭的。它和归档是两件事：归档是确定性规则（按闲置天数），不调模型、不花钱。

卸载

dsh plugin --profile web remove sage-mem

或手动在 profile 的 package.json 里删掉 sage-mem 依赖、并从 dsh.profile.bundles 移除 "sage-mem"；pnpm install 后重启 DSH。

记忆 Markdown 文件留在原目录，不受影响。

维护者

@gezi-wen

致谢

@bjvgukv25842-cmyk（LITMUS）—— 最早的 Web 记忆管理界面，记忆管理页从这一版开始。
@miztizm（mjztjzm）—— 记忆管理面板的 i18n：字典分片、ctx.locale 接入，三屏跟随宿主语言（1.9.0）。
@DDDMUC（暮迟）—— 三处：文件列表的「打开记忆文件夹」入口；注入链的短路闸门（2.4.3，同一个问题不再每一步重算）；注入段声明 interpolate: false（2.4.2，记忆里写了双大括号不再让整轮对话崩掉）。
DeepSeek Harness —— 插件宿主与 Cordis 插件体系。

这个插件活到今天，靠的不只是我一个人。上面按代码进入仓库的顺序排。漏了谁的话开个 issue 骂我，我补上。

旧版

本仓库早期是 SQLite + worker 架构，已归档到 sqlite-worker 分支。文件式是继任实现。

License

Apache-2.0 · 见 LICENSE

gezi-wen/sage-mem

sage-mem · DSH 的文件式记忆插件 (sage-mem)

目录

这是什么

为什么是文件，不是数据库

核心特性

快速开始

记忆放在哪

界面预览

记忆文件格式

检索与注入

模型也能自己翻：两个工具

长任务的接力棒：任务检查点

写入安全

访问台账：三种「用过」分开记

记忆的新鲜度与引用纪律

自动做梦

整理用的模型可以单独指定

报告写不完的时候

回滚点

整理声明：改了什么、为什么

三道安全网

改名说明

从 Claude Code 迁移

配置参考

环境变量

设置页里能改的

状态目录里的文件

稳定性与版本策略

权限与隐私

兼容性

架构

参与开发

常见问题

卸载

维护者

致谢

相关项目

旧版

License

Community comments

gezi-wen/sage-mem

sage-mem · DSH 的文件式记忆插件 (sage-mem)

目录

这是什么

为什么是文件，不是数据库

核心特性

快速开始

记忆放在哪

界面预览

记忆文件格式

检索与注入

模型也能自己翻：两个工具

长任务的接力棒：任务检查点

写入安全

访问台账：三种「用过」分开记

记忆的新鲜度与引用纪律

自动做梦

整理用的模型可以单独指定

报告写不完的时候

回滚点

整理声明：改了什么、为什么

三道安全网

改名说明

从 Claude Code 迁移

配置参考

环境变量

设置页里能改的

状态目录里的文件

稳定性与版本策略

权限与隐私

兼容性

架构

参与开发

常见问题

卸载

维护者

致谢

相关项目

旧版