dsh-hypatia-auto-memory 2.2.2 → 2.4.0

package/README.md

@@ -2,14 +2,15 @@
 
 > 中文：[README.zh-CN.md](./README.zh-CN.md)
 
-Event-driven [Hypatia](https://github.com/tkliuxing/hypatia) memory for
+Event-driven [Hypatia](https://github.com/MarchLiu/hypatia) memory for
 [DSH](https://github.com/deepseek-ai/deepseek-harness): automatic conversation
 logging and background consolidation — span summaries, a log₁₆(n) archive
 cascade, and adjudicated work-unit extraction — all on a **dedicated model
 route**, with zero model work in the main session.
 
 Writing is automatic; **reading is the agent's job**, through the bundled
-`hypatia-memory` skill. That split is deliberate — see *Recall* below.
+`hypatia-memory` skill, with the bundled `smart-memory` preset carrying the
+retrieval discipline. That split is deliberate — see *Recall* below.
 
 **This plugin replaces `dsh-hypatia`.** That plugin left the writing to the
 agent, which in practice did not happen: in the deployment this one was written
@@ -35,14 +36,25 @@ The first call logs which the binary offers
 
 The plugin also needs **dsh ≥ 0.1.7**, and dsh enforces that itself rather than
 this README: the package declares
-`peerDependencies["@deepseek-ai/dsh"]: ">=0.1.7-rc.1"` (the same range also
-sits under `dsh.engines.dsh` for display), and dsh checks every
-`@deepseek-ai/dsh*` peer against the running version when a bundle is installed
-and again at startup — an older runtime refuses the install instead of loading a
-plugin built for API it does not have, and `dsh plugin allow-version` grants an
-exact-version exemption when the risk is accepted deliberately. The peer is
-marked optional in `peerDependenciesMeta` so that neither npm nor a profile
-installation pulls the runtime in as a dependency: the launcher supplies it.
+`peerDependencies["@deepseek-ai/dsh"]: ">=0.1.7-rc.1 || ^0.2.0-rc.1 || ^0.2.1-alpha.1"`
+(the same range also sits under `dsh.engines.dsh` for display), and dsh checks
+every `@deepseek-ai/dsh*` peer against the running version when a bundle is
+installed and again at startup — an older runtime refuses the install instead of
+loading a plugin built for API it does not have, and `dsh plugin allow-version`
+grants an exact-version exemption when the risk is accepted deliberately. The
+range names each published channel explicitly rather than one open lower bound:
+node-semver admits a prerelease only when the range carries a comparator with the
+same `[major, minor, patch]`, so a bare `>=0.1.7-rc.1` matches no `0.2.x`
+release candidate at all.
+
+Every peer the running dsh already supplies — `@deepseek-ai/dsh`,
+`@deepseek-ai/cordis`, and the `dsh-llm` / `dsh-tools` / `dsh-storage-domain`
+services — is marked `optional` in `peerDependenciesMeta`, so that neither npm
+nor a profile installation pulls a copy of its own: the launcher supplies them,
+and two copies of a package whose instances must be shared is how a plugin ends
+up beside the wrong one. dsh ignores the flag — its check reads
+`peerDependencies` alone — so the ranges above are still enforced at install and
+at startup.
 
 ```bash
 # from a local checkout (development)
@@ -86,6 +98,66 @@ renaming its directory in place is not enough, because DSH names a skill by its
 frontmatter `name`. The startup warning names the directory. The skill center shows the global view, so it can list this plugin
 as a skill's provider while sessions load the disk copy.
 
+## Agent preset: smart-memory（长程记忆）
+
+The bundle ships one agent preset. `cordis.patch.yml` inserts a
+`preset-smart-memory` row declaring `@deepseek-ai/dsh-agent-preset` with
+`config.id: smart-memory`, so the profile's bundle layer is what puts it in the
+agent-preset picker beside the shipped `standard`, `ptc` and `minimal`: install
+the plugin and a memory-first agent is available, with no hand-written profile
+patch.
+
+**It carries the reading half of the split, and nothing else.** Writing here is
+already automatic — logging, consolidation, the session seed. The preset carries
+the discipline the automatic layer cannot: *when* the agent must go and look
+(before planning, at every milestone, when an unfamiliar internal name or a
+familiar-looking bug shows up, before anything destructive — commit, push,
+delete or overwrite, config change, install or upgrade, migration, release —
+whenever the user refers to history, and periodically across a long run), the
+retrieval quality rules (query the concept rather than the user's words;
+`hypatia similar` for ideas and `hypatia search` for exact identifiers; always
+exclude the operational layer), and the one write rule no background pass can
+enforce: a durable rule, taboo or correction the user states is written
+immediately, as `knowledge-update` on an existing entry rather than
+delete-and-recreate.
+
+The persona states *when*; the `hypatia-memory` skill carries *how* — the
+commands, their flags, and the shelf and scope rules. The preset deliberately
+does not restate that protocol or mount it: it is a prompt, not a second
+provider, so load the skill when the work touches memory.
+
+**Tool set.** The `standard` roster with the plan-mode group and `present`
+removed (46 tools on a web profile). Its sub-plugins — `@deepseek-ai/dsh-persona`,
+the `dsh-tool-*` rows, `dsh-skill-filesystem` — come from the dsh installation
+and are deliberately **not** dependencies of this package; the launcher supplies
+them.
+
+**Nothing here mounts the plugin's own machinery.** The preset starts no second
+collector, consolidator, recall listener or auto-approval. Those belong to the
+`hypatia-auto-memory` row above and behave identically whichever preset a session
+runs under, so a session on this preset writes memory exactly like one on
+`standard`.
+
+**Selecting it.** Pick 长程记忆 in the new-session preset picker, or make it the
+default for a surface from the profile's own patch file:
+
+```yaml
+- id: agent-preset-registry
+  name: '@deepseek-ai/dsh-agent-preset-registry'
+  config:
+    selectedDefault: smart-memory
+```
+
+**Replacing a hand-written copy of it.** If you declared this preset yourself
+before it shipped here, delete that copy. The packaged row deliberately reuses
+the row id `preset-smart-memory`, and rows sharing a row id collapse to the later
+one — the profile's patch file is applied *after* every bundle layer, so a
+leftover copy wins and masks the packaged declaration, and the Plugin Manager
+then reports that row as `unaddressable` because its id has two candidate rows.
+Two *distinct* rows declaring one `config.id` fail the other way, with `Duplicate
+agent preset: smart-memory` from the registry. A comment where the row used to be
+is enough.
+
 ## How it works
 
 ```
@@ -153,6 +225,18 @@ agent/created ──▶ rules/taboos inject()
   do have text/image content. In either mode **tool outputs themselves are never
   stored** in the log layer.
 
+- **A message the user took back is not remembered.** `dsh-rewind-plugin`
+  (`/rewind`) and the two `plugin:rollback` plugins hide messages from the model
+  by appending a surface replacement; the log is append-only, so the messages
+  themselves stay in the session. This plugin reads that record: a hidden message
+  is not written, and one an earlier flush already wrote is deleted from the
+  shelf. The sources are a whitelist of producers verified to mean "the user
+  discarded this branch" — DSH's own compaction is not on it, because what it
+  folds is history the user keeps, and neither is any editor plugin. Two limits:
+  a summary written before the rewind still carries the withdrawn text
+  (summaries are never rewritten), and a rewind that lands after the session's
+  last flush is not seen at all. See `docs/rewind-memory-consistency.md`.
+
 - **The log layer is not embedded.** `msg-*` and `session-*` entries and the
   `belongTo` / `summary` edges are written `embed: false` (hypatia #26): stored,
   full-text indexed and reachable by JSE, but given no vector. The protocol has
@@ -308,7 +392,7 @@ agent/created ──▶ rules/taboos inject()
 - **Recall** preloads project/global rules and taboos at session start. Nothing
   else is pushed, except one line naming the shelf when it is not `default`, so
   the agent's own `hypatia` calls look where the plugin writes. Retrieval is the agent's job through the bundled skill, which
-  is what [`memory-nolinear.md`](https://github.com/tkliuxing/hypatia/blob/main/docs/memory-nolinear.md)
+  is what [`memory-nolinear.md`](https://github.com/MarchLiu/hypatia/blob/main/docs/memory-nolinear.md)
   prescribes for agents that hold context and can call tools; the previous
   per-turn injector also vetoed DSH's own runtime context section by returning
   from `agent/pre-step` without calling `next()`.
@@ -596,7 +680,7 @@ now only projects plugin Config forms.)
 Deliberate, and worth knowing before you rely on them:
 
 - **No topic-shift detection.**
-  [`memory-nolinear.md`](https://github.com/tkliuxing/hypatia/blob/main/docs/memory-nolinear.md)
+  [`memory-nolinear.md`](https://github.com/MarchLiu/hypatia/blob/main/docs/memory-nolinear.md)
   ranks topic switches as the strongest session-splitting signal, above task
   boundaries and time gaps. Detecting one needs a model call every turn, which contradicts this
   plugin's central trade-off (zero model work in the main session), so it is not
@@ -639,7 +723,7 @@ Deliberate, and worth knowing before you rely on them:
   one the first attempt intended.
 - **Two of the three bundled skills are vendored copies.** `hypatia` and
   `hypatia-dream` are copied from the [hypatia
-  repository](https://github.com/tkliuxing/hypatia)'s `skills/`, because a
+  repository](https://github.com/MarchLiu/hypatia)'s `skills/`, because a
   published package cannot reach outside itself. Nothing refreshes them: when
   the originals change upstream, copy them in by hand. `hypatia` is
   byte-identical. `hypatia-dream` carries two local patches, which a refresh
@@ -666,7 +750,7 @@ Deliberate, and worth knowing before you rely on them:
 ```
 dsh-hypatia-auto-memory/
 ├── package.json          # bundle + client manifest, deps
-├── cordis.patch.yml      # bundle layer inserting id=hypatia-auto-memory
+├── cordis.patch.yml      # bundle layer: the plugin row + the smart-memory preset
 ├── tsconfig.json         # browser TS/TSX type-check config
 ├── tsconfig.build.json   # declaration emit for client bundle
 ├── tsdown.config.ts      # browser CJS factory build

package/README.zh-CN.md

@@ -3,12 +3,13 @@
 > 本文件是 [README.md](./README.md) 的中文版。若两者不一致，以英文版为准。
 
 面向 [DSH](https://github.com/deepseek-ai/deepseek-harness) 的事件驱动
-[Hypatia](https://github.com/tkliuxing/hypatia) 记忆：自动记录对话、后台巩固
+[Hypatia](https://github.com/MarchLiu/hypatia) 记忆：自动记录对话、后台巩固
 （span 摘要、log₁₆(n) 归档级联、带裁决的工作单元抽取）——全部走**专用模型路由**，
 主会话零模型工作。
 
-写入是全自动的；**读取由 Agent 负责**，通过随包附带的 `hypatia-memory` 技能完成。
-这种分工是有意为之——见下文 *Recall*。
+写入是全自动的；**读取由 Agent 负责**，通过随包附带的 `hypatia-memory` 技能完成，
+检索纪律则由同样随包附带的 `smart-memory` 预设承载。这种分工是有意为之——见下文
+*Recall*。
 
 **本插件取代 `dsh-hypatia`。** 后者把写入留给 Agent，实际上并没有发生：在编写本
 插件的那个部署环境里，模型加载了协议，却在十五个会话中只有一个会话主动执行了
@@ -29,12 +30,20 @@
 filters yes`）。
 
 本插件还需要 **dsh ≥ 0.1.7**，而且这个下限由 dsh 自己强制执行，不靠本 README：
-包里声明了 `peerDependencies["@deepseek-ai/dsh"]: ">=0.1.7-rc.1"`（同样的范围也写在
-`dsh.engines.dsh` 里，供展示），dsh 在安装 bundle 时、以及每次启动时，会把每个
-`@deepseek-ai/dsh*` peer 与自身版本比对——运行时太旧会直接拒绝安装，而不是加载一个
-面向它并不具备的 API 写成的插件；确实要接受风险时，用 `dsh plugin allow-version`
-授予精确版本豁免。该 peer 在 `peerDependenciesMeta` 里标为 optional，这样 npm 和
-profile 安装都不会把运行时本身拉成依赖：运行时由 launcher 提供。
+包里声明了
+`peerDependencies["@deepseek-ai/dsh"]: ">=0.1.7-rc.1 || ^0.2.0-rc.1 || ^0.2.1-alpha.1"`
+（同样的范围也写在 `dsh.engines.dsh` 里，供展示），dsh 在安装 bundle 时、以及每次启动时，
+会把每个 `@deepseek-ai/dsh*` peer 与自身版本比对——运行时太旧会直接拒绝安装，而不是加载
+一个面向它并不具备的 API 写成的插件；确实要接受风险时，用 `dsh plugin allow-version`
+授予精确版本豁免。范围把每条已发布通道逐一写出来，而不是只写一个开放下界：node-semver
+只在区间里存在同 `[major, minor, patch]` 的比较子时才接受预发布版，因此单写
+`>=0.1.7-rc.1` 其实一个 `0.2.x` 候选版都匹配不到。
+
+凡是运行中的 dsh 已经提供的 peer——`@deepseek-ai/dsh`、`@deepseek-ai/cordis`，以及
+`dsh-llm` / `dsh-tools` / `dsh-storage-domain` 三个服务——都在 `peerDependenciesMeta`
+里标为 `optional`，这样 npm 和 profile 安装都不会各自再拉一份：它们由 launcher 提供，
+而"需要共享实例的包存在两份"正是插件用错那一份的来源。dsh 会忽略这个标记——它的检查只读
+`peerDependencies`——所以上面的范围在安装时和启动时依旧生效。
 
 ```bash
 # 从本地 checkout 安装（开发）
@@ -73,6 +82,52 @@ user）只在一层内打破平局。Agent 预设（`st`、`standard`、…）
 目录名。技能中心展示的是全局视图，所以它可能把本插件列为某技能的提供者，而会话
 实际加载的是磁盘拷贝。
 
+## Agent 预设：smart-memory（长程记忆）
+
+本插件包内置一个 Agent 预设。`cordis.patch.yml` 插入一行 `preset-smart-memory`
+声明 `@deepseek-ai/dsh-agent-preset`、`config.id: smart-memory`，因此是 profile 的
+bundle 层把它送进 Agent 预设选择器，与自带的 `standard`、`ptc`、`minimal` 并列：
+装上插件就有一个「记忆优先」的 Agent 可用，不必再手写 profile 补丁。
+
+**它承载的是分工里「读」的那一半，仅此而已。** 这里的写入本来就是自动的——日志
+记录、巩固、会话开场的规则种子。预设承载的是自动层做不到的纪律：**什么时候必须去
+查**（制定计划前、每个里程碑、出现陌生内部名称或眼熟的 bug 时、任何破坏性操作之前
+——commit、push、删除或覆盖、改配置、安装或升级、迁移、发布——用户提到历史时，以及
+长程任务中的周期性回顾），检索质量要求（查询写成概念而非用户原话；想法用
+`hypatia similar`，精确标识符用 `hypatia search`；始终排除运维层），以及唯一一条
+后台流程无法强制执行的写入规则：用户给出的永久性规则、禁忌或纠正立即落库，且对已存在
+条目用 `knowledge-update`，而不是删除后重建。
+
+人设规定的是*什么时候*，`hypatia-memory` 技能承载的是*怎么做*——命令、参数，以及
+shelf 与 scope 的规则。预设刻意不重述这套协议，也不挂载它：它只是提示词，不是第二个
+提供者，所以在工作涉及记忆时加载该技能。
+
+**工具集。** 即 `standard` 的花名册去掉 plan mode 组与 `present`（web profile 下
+46 个工具）。它的子插件——`@deepseek-ai/dsh-persona`、各 `dsh-tool-*` 行、
+`dsh-skill-filesystem`——来自 dsh 安装本身，**刻意不**作为本包的依赖；由 launcher
+提供。
+
+**这里不挂载插件自身的任何机制。** 预设不会启动第二个 collector、consolidator、
+recall 监听或自动批准。那些属于上面那行 `hypatia-auto-memory`，且无论会话跑在哪个
+预设下行为一致；因此用本预设的会话写记忆的方式与 `standard` 完全相同。
+
+**怎么选。** 在新会话的预设选择器里选「长程记忆」，或在 profile 自己的补丁文件里把它
+设为该界面的默认值：
+
+```yaml
+- id: agent-preset-registry
+  name: '@deepseek-ai/dsh-agent-preset-registry'
+  config:
+    selectedDefault: smart-memory
+```
+
+**替换手写的那一份。** 如果你在本预设随包分发之前自己声明过它，请删掉那份拷贝。包内的
+行刻意沿用 row id `preset-smart-memory`，而同名 row id 的两行会折叠为靠后的那一行
+——profile 的补丁文件在所有 bundle 层**之后**应用，所以残留的拷贝会取胜并遮蔽包内
+声明；插件管理器随后会把该行报成 `unaddressable`，因为同一个 id 出现了两个候选行。
+另一种失败是两行**不同** row id 声明同一个 `config.id`：registry 会用
+`Duplicate agent preset: smart-memory` 拒绝第二次注册。在原处留一段注释即可。
+
 ## 工作原理
 
 ```
@@ -125,6 +180,15 @@ agent/created ──▶ rules/taboos inject()
   文本/图片内容的助手消息记录一份精简台账（`1. \`read\` ×5 — ✅ 1.2s total`）。无论
   哪种模式，**工具输出本身永远不会存入**日志层。
 
+- **被用户撤回的消息不会记入记忆。** `dsh-rewind-plugin`（`/rewind`）与两个
+  `plugin:rollback` 插件都靠追加一条 surface 替换，把消息从模型视野里藏起来；而日志
+  是 append-only 的，消息本身仍留在会话里。本插件读这条记录：被藏起来的消息不写，
+  早先的 flush 已经写出的则从 shelf 上删掉。来源是一份白名单，只收语义确实是"用户丢
+  弃了这个分支"的生产者——DSH 自己的压缩不在其中（它折叠的是用户保留的历史），编辑
+  类插件也不在其中。两个边界：回退之前已经写出的摘要仍带着被撤回的原文（摘要从不重
+  写），以及落在会话最后一次 flush 之后的回退完全看不到。见
+  `docs/rewind-memory-consistency.md`。
+
 - **日志层不嵌入。** `msg-*` 和 `session-*` 条目以及 `belongTo` / `summary` 边都以
   `embed: false` 写入（hypatia #26）：已存储、可全文检索、可被 JSE 找到，但不生成
   向量。协议设计了沿 `summary` 边从摘要精确下钻的召回方式，而不是按语义命中原始
@@ -237,7 +301,7 @@ agent/created ──▶ rules/taboos inject()
 - **Recall** 在会话启动时预载项目/全局的 rules 和 taboos。除此之外什么都不推送，
   除了一行在 shelf 不是 `default` 时指明 shelf 名字，好让 Agent 自己的 `hypatia`
   调用去插件写入的地方找。检索由 Agent 通过随包技能完成，这正是
-  [`memory-nolinear.md`](https://github.com/tkliuxing/hypatia/blob/main/docs/memory-nolinear.md)
+  [`memory-nolinear.md`](https://github.com/MarchLiu/hypatia/blob/main/docs/memory-nolinear.md)
   为那些持有上下文、能调用工具的 Agent 所开出的方案；此前的每轮注入器还会因为从
   `agent/pre-step` 返回而不调用 `next()`，否决掉 DSH 自己的运行时上下文段。
 
@@ -470,7 +534,7 @@ shelf 清单本来就不是配置，而设置域现在只投影插件的 Config
 刻意为之，依赖它们之前值得了解：
 
 - **没有话题切换检测。**
-  [`memory-nolinear.md`](https://github.com/tkliuxing/hypatia/blob/main/docs/memory-nolinear.md)
+  [`memory-nolinear.md`](https://github.com/MarchLiu/hypatia/blob/main/docs/memory-nolinear.md)
   把话题切换列为最强的会话切分信号，排在任务边界和时间间隔之上。检测它需要每个 turn
   一次模型调用，这与本插件的核心取舍（主会话零模型工作）相悖，所以未实现。任务边界
   （`turn/end` 原因）和会话关闭是被尊重的；一个覆盖三个无关话题的会话会被总结成一条。
@@ -498,7 +562,7 @@ shelf 清单本来就不是配置，而设置域现在只投影插件的 Config
 - **级联在批次中途崩溃会移动分组边界。** 已连接的成员离开该层的未归档集合，所以
   重试会归档另一批。每样东西仍恰好归档一次；只是分组不再是第一次尝试想要的。
 - **三个随包技能里有两个是 vendored 拷贝。** `hypatia` 和 `hypatia-dream` 从
-  [hypatia 仓库](https://github.com/tkliuxing/hypatia) 的 `skills/` 拷贝而来，因为
+  [hypatia 仓库](https://github.com/MarchLiu/hypatia) 的 `skills/` 拷贝而来，因为
   已发布的包够不到自身之外。没有任何东西刷新它们：上游原件变了就手工拷进来。
   `hypatia` 逐字节相同。`hypatia-dream` 带两处本地补丁，刷新时必须重新打：
   - **Shelf。** 请求里没给 shelf 时，它用会话种子指明的那个，只有种子没指明时才用
@@ -518,7 +582,7 @@ shelf 清单本来就不是配置，而设置域现在只投影插件的 Config
 ```
 dsh-hypatia-auto-memory/
 ├── package.json          # bundle + client manifest、依赖
-├── cordis.patch.yml      # 插入 id=hypatia-auto-memory 的 bundle 层
+├── cordis.patch.yml      # bundle 层：插件行 + smart-memory 预设
 ├── tsconfig.json         # 浏览器 TS/TSX 类型检查配置
 ├── tsconfig.build.json   # client bundle 的声明产物
 ├── tsdown.config.ts      # 浏览器 CJS 工厂构建

package/cordis.patch.yml

@@ -21,3 +21,152 @@
 - insert:
     - id: hypatia-auto-memory
       name: dsh-hypatia-auto-memory
+
+# ── Agent preset: smart-memory（长程记忆） ─────────────────────────────────────
+# The plugin owns the memory *writing* side; this preset owns the *reading*
+# discipline. Installing this bundle therefore ships a memory-first agent — the
+# preset is part of the package, not a profile patch a user has to hand-write.
+# The two rows are independent: the preset mounts none of the plugin's own
+# machinery (collector, consolidation, recall, autoApprove), and the plugin row
+# above registers no preset.
+#
+# The row declares `@deepseek-ai/dsh-agent-preset` with `config.id: smart-memory`
+# — the id the preset registry and a session header record. Its `config.plugins`
+# is the `standard` preset's roster with the plan-mode group and `present`
+# removed, under a memory-first persona; the sub-plugins (`@deepseek-ai/dsh-persona`,
+# the `dsh-tool-*` rows, `dsh-skill-filesystem`) come from the dsh installation
+# and are deliberately not dependencies of this package.
+#
+# The row id is deliberately the one hand-written profile patches used
+# (`preset-smart-memory`), so such a profile only has to drop its copy. Rows
+# sharing a row id collapse to the later one, and the profile's own
+# cordis.patch.yml is applied after every bundle layer, so a leftover copy wins
+# and masks this declaration; the Plugin Manager also reports that row as
+# `unaddressable`, because its id then has two candidate rows. Two *distinct*
+# rows declaring one `config.id` are refused instead: the registry throws
+# `Duplicate agent preset: smart-memory` on the second registration.
+#
+# Edits saved from the Web preset editor override this row's `config.plugins`
+# by id from the profile patch.
+- insert:
+    - id: preset-smart-memory
+      name: '@deepseek-ai/dsh-agent-preset'
+      config:
+        id: smart-memory
+        name: 长程记忆
+        description: >-
+          长程任务下强化 hypatia 记忆库的主动检索与落库：任务开始、里程碑、 发现新线索、重要操作前都先回忆，永久规则与纠正立即写库。
+        order: 2
+        plugins:
+          - id: persona
+            name: '@deepseek-ai/dsh-persona'
+            config:
+              prefix: |-
+                你是 {{model}} 驱动的长程记忆型编码 agent。默认假设是：这件事之前很可能已经被讨论、决定或踩过坑——先读记忆，再动手。
+
+                ## 记忆系统怎么分工
+                会话日志、span 摘要、work unit 固化和会话开场的规则/禁忌种子都由 dsh-hypatia-auto-memory 在后台完成，不要手工重复写这些。你负责两件事：在正确时机主动**检索**；在用户给出永久性规则、禁忌或纠正时**立即落库**。具体命令与查询配方在 hypatia-memory 技能里（用 skill 工具加载，CLI 细节见 hypatia 技能）——本段只规定纪律。
+
+                ## 检索纪律（下列时机是必须做的动作，不是建议）
+                1. 任务开始、制定计划前：先建立"已知决策 / 项目约定 / 已踩过的坑"的基线，再规划。
+                2. 每个里程碑或阶段边界：重新对齐一次，避免局部最优违背既有决策。
+                3. 任务中途发现新线索：出现陌生的内部名称或模块名、看不懂的报错、眼熟的 bug，或你意识到任务真正主题与开头不同时，立刻补查。
+                4. 重要或破坏性操作前：git commit / push、删除或覆盖文件、改配置、安装或升级插件与依赖、数据库迁移、发布或对外发送内容之前。
+                5. 用户提到历史时：例如"之前怎么定的""上次那个""为什么这么做"。
+                6. 长程任务周期性回顾：上下文已经很长，或目标已跨多轮续跑时，重新检索当前的关键主题。
+
+                检索质量要求：查询写成你想找的那个**概念**，不要照抄用户原话；语义检索用 `hypatia similar`，精确标识符用 `hypatia search`；始终排除运维层（`msg-`、`sum-`、`session-`、`hypatia-dream-run-` 开头，或带 `message`/`summary`/`session` 标签的行）；一次空结果不等于记忆里没有——换措辞、提高 `--limit` 再试。
+
+                ## 检索结果怎么用
+                查到既有决策就遵循它，并在回答里点明依据（条目名或结论）。记忆与当前代码或用户要求冲突时，明确说出冲突，以用户当前指令为准，并用 `supersedes` 语句把新结论落库——绝不删除旧条目。确实没有记录时，直接说明"记忆库中没有相关记录"，再按第一性原理推进，不要编造记忆内容。
+
+                ## 写入纪律
+                用户给出永久性规则、禁忌或纠正时立即写库（`rule` / `taboo` / `memory`，scope 用本项目的实际 scope）：先 `knowledge-get`，已存在就 `knowledge-update`，不存在才 `knowledge-create`，不要删除后重建。过程流水不要手工写。
+
+                ## 长程任务
+                复杂任务先用 todo_write 拆解并跟踪；跨轮目标用 goal 机制续跑，没有完成证据不要宣称完成。阶段收尾时把"值得留存的结论"落库，而不是把过程日志落库。
+              suffix: |-
+                你的工作目录是 {{cwd}}。记忆的检索与落库通过 bash 调用 hypatia CLI 完成，scope 归属由插件决定。
+          - id: agent-instructions
+            name: '@deepseek-ai/dsh-agent-instructions'
+            config:
+              maxBytes: 65536
+          - id: tool-bash
+            name: '@deepseek-ai/dsh-tool-bash'
+            disabled: !!js process.platform === 'win32'
+          - id: tool-pwsh
+            name: '@deepseek-ai/dsh-tool-pwsh'
+            disabled: !!js process.platform !== 'win32'
+          - id: tool-fs
+            name: '@deepseek-ai/dsh-tool-fs'
+          - id: tool-fs-search
+            name: '@deepseek-ai/dsh-tool-fs-search'
+            config:
+              sampleOverCapGlobResults: false
+          - id: tool-jobs
+            name: '@deepseek-ai/dsh-tool-jobs'
+          - id: skill-filesystem
+            name: '@deepseek-ai/dsh-skill-filesystem'
+          - id: tool-skill
+            name: '@deepseek-ai/dsh-tool-skill'
+          - id: command-goal
+            name: '@deepseek-ai/dsh-command-goal'
+          - id: tool-goal
+            name: '@deepseek-ai/dsh-tool-goal'
+          - id: compaction
+            name: cordis:group
+            group: true
+            isolate:
+              compaction: true
+              toolResultPruner: true
+            config:
+              - id: compaction-basic
+                name: '@deepseek-ai/dsh-compaction-basic'
+              - id: command-compact
+                name: '@deepseek-ai/dsh-command-compact'
+              - id: tool-result-pruner
+                name: '@deepseek-ai/dsh-compaction-tool-result-pruner'
+                config:
+                  thresholdChars: 8192
+                  headChars: 4096
+                  tailChars: 1024
+          - id: delegation
+            name: cordis:group
+            group: true
+            isolate:
+              workflowEngine: true
+            config:
+              - id: tool-subagent-control
+                name: '@deepseek-ai/dsh-tool-subagent-control'
+              - id: tool-subagent-list-agents
+                name: '@deepseek-ai/dsh-tool-subagent-control/list-agents'
+              - id: tool-subagent
+                name: '@deepseek-ai/dsh-tool-subagent'
+                config:
+                  provider: spawn
+                  toolName: subagent
+                  modelSelectionSettings: true
+                  backgroundMode: continuable
+              - id: tool-subagent-fork
+                name: '@deepseek-ai/dsh-tool-subagent'
+                config:
+                  provider: fork
+                  toolName: subagent_fork
+                  backgroundMode: continuable
+              - id: workflow-ptc
+                name: '@deepseek-ai/dsh-workflow-ptc'
+                config:
+                  provider: spawn
+              - id: tool-workflow
+                name: '@deepseek-ai/dsh-tool-workflow'
+          - id: tool-ask-user
+            name: '@deepseek-ai/dsh-tool-ask-user'
+          - id: tool-todo
+            name: '@deepseek-ai/dsh-tool-todo'
+            config:
+              allowParallelInProgress: true
+          - id: tool-web
+            name: '@deepseek-ai/dsh-tool-web'
+            config:
+              fetch: true
+              searchTimeoutMs: 60000

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-hypatia-auto-memory",
-  "version": "2.2.2",
+  "version": "2.4.0",
   "description": "Event-driven Hypatia memory for DSH: automatic conversation logging via session events, queued background consolidation (span summaries + work-unit extraction) with a dedicated model route, and recall injection — zero per-call model work in the main session.",
   "icon": "./icon.svg",
   "type": "module",
@@ -31,7 +31,7 @@
   },
   "dsh": {
     "engines": {
-      "dsh": ">=0.1.7-rc.1"
+      "dsh": ">=0.1.7-rc.1 || ^0.2.0-rc.1 || ^0.2.1-alpha.1"
     },
     "bundle": {
       "patch": "./cordis.patch.yml"
@@ -49,25 +49,37 @@
     "node": "^22.19.0 || >=24.0.0"
   },
   "dependencies": {
-    "@deepseek-ai/schemastery": "^3.18.2",
+    "@deepseek-ai/schemastery": "^3.18.2 || ~3.18.5-alpha.1",
     "zod": "^4.4.3"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.2 || ~4.0.5-alpha.1",
-    "@deepseek-ai/dsh": ">=0.1.7-rc.1",
+    "@deepseek-ai/dsh": ">=0.1.7-rc.1 || ^0.2.0-rc.1 || ^0.2.1-alpha.1",
     "@deepseek-ai/dsh-llm": "^0.1.7-rc.1 || ^0.2.0-rc.1 || ^0.2.1-alpha.1",
     "@deepseek-ai/dsh-storage-domain": "^0.1.7-rc.1 || ^0.2.0-rc.1 || ^0.2.1-alpha.1",
     "@deepseek-ai/dsh-tools": "^0.1.7-rc.1 || ^0.2.0-rc.1 || ^0.2.1-alpha.1",
     "react": "^18.2.0"
   },
   "peerDependenciesMeta": {
+    "@deepseek-ai/cordis": {
+      "optional": true
+    },
     "@deepseek-ai/dsh": {
       "optional": true
+    },
+    "@deepseek-ai/dsh-llm": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-storage-domain": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-tools": {
+      "optional": true
     }
   },
   "devDependencies": {
     "@deepseek-ai/cordis": "^4.0.2 || ~4.0.5-alpha.1",
-    "@deepseek-ai/cordis-plugin-loader": "^1.0.5",
+    "@deepseek-ai/cordis-plugin-loader": "^1.0.5 || ~1.0.6-alpha.1",
     "@deepseek-ai/dsh-agent": "^0.1.7-rc.1",
     "@deepseek-ai/dsh-api-remotes": "^0.1.7-rc.1",
     "@deepseek-ai/dsh-api-session-controller": "^0.1.7-rc.1",

package/src/collector.js

@@ -136,6 +136,158 @@ export function countLoggableMessages(events) {
   return count
 }
 
+/**
+ * Event sources whose surface replacement means "the user took this branch
+ * back", as opposed to the producers that fold history without discarding it.
+ *
+ * Only a `replace` event carrying one of these `data.source.kind` values is a
+ * withdrawal (docs/rewind-memory-consistency.md §2.2–§2.4). The distinction is
+ * load-bearing, because every other producer's replacement is real history:
+ *
+ * - `compact-checkpoint` — DSH's own compaction, and `dsh-clear-mind`'s wrapper
+ *   around the same seam: the folded region is summarised for the model, never
+ *   discarded by the user.
+ * - `system-prompt` — the runtime-context snapshot (`system/message`) replaced
+ *   by its own next version; observed on a real log as seq 395/396.
+ * - `context-editor` — an edit or condensation, whose own restore action brings
+ *   the messages back.
+ *
+ * The list stays a whitelist on purpose. A denylist of "known non-withdrawal
+ * producers" fails open: the next plugin that uses `replace` for an edit would
+ * have its history deleted as if the user had taken it back. Members are added
+ * only after reading the producer's code and confirming the semantics, and each
+ * one gets a test in test/collector-withdrawn.test.mjs.
+ *
+ * Audited 2026-10-14: `dsh-rewind-plugin` (`dsh-rewind`) and the two rollback
+ * plugins that share `plugin:rollback` (`@domitor-syh/dsh-rollback`,
+ * `@nianchu/dsh-rollback`).
+ *
+ * The kind alone is not enough — a member also has to cite **exactly** the nodes
+ * it shadowed, see {@link withdrawnRanges}. `plugin:rollback` is the generic
+ * `plugin:<name>` spelling, so any future plugin calling itself `rollback`
+ * matches it too. Accepted knowingly: a rename shows up as a test failure,
+ * whereas a narrower string would silently stop matching the plugin it was
+ * written for.
+ */
+export const WITHDRAWAL_SOURCE_KINDS = Object.freeze(['dsh-rewind', 'plugin:rollback'])
+
+/**
+ * The withdrawn ranges a log slice contains, one entry per withdrawal marker.
+ *
+ * What a marker hid comes from its `sourceEventSeqs`, and the host only requires
+ * that list to **include** every shadowed node: citing extra, earlier seqs is
+ * legal (`assertSourceEventReferences` checks for `missing`, not equality).
+ * Everything cited here is deleted, so this reads exactly as far as the producer
+ * can be trusted — which is a per-member property, verified by reading each
+ * member of {@link WITHDRAWAL_SOURCE_KINDS}: `dsh-rewind-plugin` passes
+ * `[...plan.shadowedSeqs]` (its own `surface.slice(targetIndex)`), and the
+ * rollback plugins pass `seqsForStorage(shadowed)` — that same set, reordered
+ * for three or more seqs so the store's range encoder cannot compress it, which
+ * is why the **set**, not the order, is what this keeps.
+ *
+ * A new member needs that check too (docs/rewind-memory-consistency.md §2.4): a
+ * producer that also cited, say, the anchor it rewound to would have that message
+ * deleted here.
+ *
+ * @param {readonly any[]} events - a log slice that may contain markers. Callers
+ *   must read to `session.seq`, not merely to their own task range: a marker's
+ *   seq is greater than every seq it shadows, so it can sit past the range being
+ *   logged (docs/rewind-memory-consistency.md §3 fact 5).
+ * @returns {Array<{from: number, to: number, at: number, kind: string, seqs: Set<number>}>}
+ */
+export function withdrawnRanges(events) {
+  const ranges = []
+  for (const event of events ?? []) {
+    const op = event?.surfaceOp
+    if (op?.op !== 'replace') continue
+    // Only a user message can carry these markers. This also rules out the
+    // runtime-context snapshot (`system/message`) and the tool-result pruner
+    // (`tool/result`), both of which replace a single node with itself.
+    if (event.type !== 'user/message') continue
+    const kind = event.data?.source?.kind
+    if (typeof kind !== 'string' || WITHDRAWAL_SOURCE_KINDS.includes(kind) === false) continue
+    const cited = Array.isArray(event.sourceEventSeqs) ? event.sourceEventSeqs : []
+    const seqs = new Set(cited.filter((seq) => Number.isInteger(seq)))
+    // The host refuses an empty list on a replacement, so a marker citing nothing
+    // is one this build cannot read. Reading `[startSeq, endSeq]` instead would
+    // be a guess, and wrong in the case that matters most: those two numbers
+    // denote SURFACE order, so a slice containing a compaction checkpoint can
+    // have `startSeq > endSeq`.
+    if (seqs.size === 0) continue
+    ranges.push({ from: op.startSeq, to: op.endSeq, at: event.seq, kind, seqs })
+  }
+  return ranges
+}
+
+/** Every shadowed seq of every marker in the slice, as one lookup set. */
+export function withdrawnSeqs(events) {
+  const seqs = new Set()
+  for (const range of withdrawnRanges(events)) {
+    for (const seq of range.seqs) seqs.add(seq)
+  }
+  return seqs
+}
+
+/**
+ * The dense entry ordinal each of `seqs` was named by — `msg-<session>-<N>`.
+ *
+ * Same count as `countLoggableMessages`, over the same prefix, so a name derived
+ * here cannot drift from the name the span wrote: a withdrawal that arrives
+ * after its messages were logged has to retract them by name, and the only
+ * durable record of that name is the log itself.
+ *
+ * @param {readonly any[]} events - events covering the counting prefix, i.e. from
+ *   the inherited prefix through the shadowed seqs.
+ * @param {Set<number>} seqs - shadowed seqs, as `withdrawnSeqs` returns them.
+ * @param {number} [inherited] - size of the prefix a fork inherited, which
+ *   contributes no ordinals of its own.
+ * @returns {Map<number, number>} seq -> ordinal. A shadowed seq that is not a
+ *   loggable message is absent: it never had an entry.
+ */
+export function withdrawnOrdinals(events, seqs, inherited = 0) {
+  const ordinals = new Map()
+  if (seqs === undefined || seqs.size === 0) return ordinals
+  let index = 0
+  for (const event of events ?? []) {
+    if (event.seq < inherited || isLoggableMessage(event) === false) continue
+    if (seqs.has(event.seq)) ordinals.set(event.seq, index)
+    index += 1
+  }
+  return ordinals
+}
+
+/**
+ * What one log task must do about the withdrawals it can see — the whole
+ * decision, as a pure function of the log, so the executor only carries it out.
+ *
+ * A withdrawal has two faces, and they are told apart by position rather than by
+ * state: a shadowed message *inside* the range being written must not be written
+ * at all, while one *before* it was written by an earlier span and has to be
+ * retracted by name. Which of the two it is, is `seq < fromSeq`.
+ *
+ * @param {{log: readonly any[], prefix: readonly any[], fromSeq: number, inherited?: number}} input
+ *   `log` is the marker window: from the start of the range being written to the
+ *   end of the session log, because a marker's seq is greater than every seq it
+ *   shadows and a window cut at the task's own end can miss one. `prefix` is
+ *   `[inherited, fromSeq)`, where the messages an earlier span already wrote are
+ *   counted — the same prefix `baseIndex` counts, so a retraction names the entry
+ *   the span named.
+ * @returns {{seqs: Set<number>, retract: Map<number, number>}} `seqs` are the
+ *   shadowed seqs in the window (in-span members are matched against the items
+ *   about to be written); `retract` maps each shadowed seq *before* `fromSeq` to
+ *   the dense entry ordinal it was named by. Shadowed seqs that are not loggable
+ *   messages appear in neither: they never had an entry.
+ */
+export function withdrawalWork({ log, prefix, fromSeq, inherited = 0 }) {
+  const seqs = withdrawnSeqs(log)
+  if (seqs.size === 0) return { seqs, retract: new Map() }
+  const before = new Set([...seqs].filter((seq) => seq < fromSeq))
+  return {
+    seqs,
+    retract: before.size === 0 ? new Map() : withdrawnOrdinals(prefix, before, inherited),
+  }
+}
+
 /**
  * @param {{
  *   ctx: import('@deepseek-ai/cordis').Context,

package/src/consolidator.js

@@ -15,7 +15,7 @@
  */
 
 import { absolutizeDates, blocksToText, eventDate, redactSecrets } from './content-policy.js'
-import { countLoggableMessages, isCompactionReplacement, isLoggableMessage } from './collector.js'
+import { countLoggableMessages, isCompactionReplacement, isLoggableMessage, withdrawnSeqs } from './collector.js'
 import { messageName, summaryName } from './writer.js'
 import { EMPTY_PROGRESS, advanceProgress } from './progress.js'
 import { TaskDeferredError } from './queue.js'
@@ -251,13 +251,15 @@ function consolidationInstruction(maxWorkUnits) {
  * @param {{maxInputTokens: number}} config
  * @param {Date} now - base for relative dates in an event that carries no
  *   timestamp; otherwise each line is resolved against its own event's time.
- * @param {{before?: any}} [context] - the event just ahead of the span, so a
- *   leading compaction replacement is recognised (it restates an old result).
+ * @param {{before?: any, withdrawn?: Set<number>}} [context] - the event just
+ *   ahead of the span, so a leading compaction replacement is recognised (it
+ *   restates an old result); and the seqs a withdrawal marker took out of the
+ *   model's view, which must not reach the summariser at all.
  * @returns {{text: string, lastSeq: number, complete: boolean}} `lastSeq` is the
  * seq of the last event included; `complete` is false when the budget forced
  * later events out of this run.
  */
-export function buildTranscript(events, config, now = new Date(), { before } = {}) {
+export function buildTranscript(events, config, now = new Date(), { before, withdrawn } = {}) {
   const bySeq = new Map(events.map((event) => [event.seq, event]))
   // Tool results cite their call by id; the readable name lives on the call.
   const toolNames = new Map()
@@ -272,6 +274,12 @@ export function buildTranscript(events, config, now = new Date(), { before } = {
   /** @type {Array<{seq: number, line: string}>} */
   const entries = []
   for (const event of events) {
+    // A withdrawn message never reaches the summariser. Retracting it is only
+    // half the job: a summary written from it would carry the branch the user
+    // took back into the summary layer, where no later delete can reach it,
+    // because summaries are immutable and named by span
+    // (docs/rewind-memory-consistency.md §4.4).
+    if (withdrawn?.has(event.seq) === true) continue
     if (event.type === 'user/message') {
       if (event.data?.source?.kind !== 'user') continue
       const text = clean(blocksToText(event.data?.content ?? []), event)
@@ -696,7 +704,13 @@ export function createConsolidator({ queue, progress, sessions, llm, cli, writer
     const events = session.snapshotEvents(fromSeq, task.toSeq)
     const now = new Date()
     const before = fromSeq > 0 ? session.snapshotEvents(fromSeq - 1, fromSeq)[0] : undefined
-    const { text: transcript, lastSeq, complete } = buildTranscript(events, consolidation, now, { before })
+    // Read the markers to `session.seq` rather than to `task.toSeq`: a marker's
+    // seq is greater than every seq it shadows, so this span's upper bound — and
+    // here that is `min(session.seq, lastLoggedSeq)` — can cut one off. Same
+    // visibility problem as the log executor (docs/rewind-memory-consistency.md
+    // §3 fact 5).
+    const withdrawn = withdrawnSeqs(session.snapshotEvents(fromSeq, session.seq ?? 0))
+    const { text: transcript, lastSeq, complete } = buildTranscript(events, consolidation, now, { before, withdrawn })
     if (transcript.trim() === '') {
       await advanceProgress(progress, task.sessionId, () => ({ lastConsolidatedSeq: task.toSeq }))
       return
@@ -829,7 +843,13 @@ export function createConsolidator({ queue, progress, sessions, llm, cli, writer
     const items = []
     for (const event of events) {
       if (!isLoggableMessage(event)) continue
-      if (event.seq < coveredToSeq) items.push(messageName(task.sessionId, itemIndex))
+      // A withdrawn message has no entry to cite, and `items` is by contract the
+      // list of entries the span actually produced (writer.js `writeSummary`), so
+      // the ordinal is still counted but the name is not asserted. Counting it
+      // keeps the remaining ordinals aligned with the log.
+      if (event.seq < coveredToSeq && withdrawn.has(event.seq) === false) {
+        items.push(messageName(task.sessionId, itemIndex))
+      }
       itemIndex += 1
     }
     await writer.writeSummary({

package/src/hypatia-cli.js

@@ -183,13 +183,19 @@ export function createHypatiaCli(ctx, config) {
    * about `--no-embed` — they gained it together, but the answer is only worth
    * having if it is true of each command it gates.
    *
-   * @returns {Promise<{noEmbed: boolean, similarFilters: boolean}>}
+   * @returns {Promise<{noEmbed: boolean, similarFilters: boolean, deleteKnowledge: boolean}>}
    */
   async function probeFeatures() {
-    const [knowledge, statement, similar] = await Promise.all([
+    const [knowledge, statement, similar, remove] = await Promise.all([
       run(['knowledge-create', '--help']),
       run(['statement-create', '--help']),
       run(['similar', '--help']),
+      // Asked like the others, answered differently: a binary from before
+      // `knowledge-delete` existed (hypatia #22) prints a clap usage error and
+      // exits 2, and that is an answer ("cannot delete"), not a broken binary —
+      // the three required probes above still decide whether the client works at
+      // all. A withdrawal is therefore skipped rather than retracted there.
+      run(['knowledge-delete', '--help']),
     ])
     for (const result of [knowledge, statement, similar]) {
       if (result.exitCode !== 0) {
@@ -203,6 +209,7 @@ export function createHypatiaCli(ctx, config) {
     return {
       noEmbed: knowledge.stdout.includes('--no-embed') && statement.stdout.includes('--no-embed'),
       similarFilters: similar.stdout.includes('--exclude-tags'),
+      deleteKnowledge: remove.exitCode === 0,
     }
   }
 
@@ -216,7 +223,7 @@ export function createHypatiaCli(ctx, config) {
         // with its own error; the answer here only decides which flags that
         // call carries, and the conservative answer is none.
         featuresProbe = undefined
-        return { noEmbed: false, similarFilters: false }
+        return { noEmbed: false, similarFilters: false, deleteKnowledge: false }
       })
     }
     return featuresProbe
@@ -281,6 +288,31 @@ export function createHypatiaCli(ctx, config) {
       return runCreate(argv)
     },
 
+    /**
+     * Remove one knowledge entry.
+     *
+     * Deleting a name that is already gone exits 1 with `Error: not found:
+     * knowledge '<name>'` — a normal outcome for a caller whose retraction may
+     * be replayed, so it is reported as `false` instead of thrown. Statements
+     * mentioning the name are deliberately kept by hypatia
+     * (`wu-knowledge-delete-retains-statements-7487bf50`), which is why a
+     * withdrawal leaves `belongTo` / `summary` edges behind and nothing here
+     * tries to remove them.
+     *
+     * @returns {Promise<boolean>} true when this call removed an entry.
+     */
+    async knowledgeDelete(name, shelf = shelfOf()) {
+      const result = await run(['knowledge-delete', name, '--shelf', shelf])
+      if (result.exitCode === 0) return true
+      const stderr = result.stderr.trim()
+      if (/^Error: not found:/.test(stderr)) return false
+      throw new HypatiaCliError(`hypatia exited ${result.exitCode}: knowledge-delete ${name}`, {
+        code: 'NONZERO_EXIT',
+        stderr: stderr.slice(0, 500),
+        exitCode: result.exitCode,
+      })
+    },
+
     /**
      * `embed: false` as on `knowledgeCreate`. A statement has no update
      * command, so the choice is made once, here.

package/src/hypatia-client.js

@@ -61,7 +61,7 @@ export function createHypatiaClient(ctx, config, { status, connection }) {
     if (!announced) {
       announced = true
       const yes = (flag) => (flag ? 'yes' : 'no')
-      status.info?.(`hypatia over ${usesMcp() ? 'mcp' : 'cli'}: no-embed ${yes(found.noEmbed)}, similar filters ${yes(found.similarFilters)}`)
+      status.info?.(`hypatia over ${usesMcp() ? 'mcp' : 'cli'}: no-embed ${yes(found.noEmbed)}, similar filters ${yes(found.similarFilters)}, delete ${yes(found.deleteKnowledge)}`)
     }
     return found
   }
@@ -71,6 +71,7 @@ export function createHypatiaClient(ctx, config, { status, connection }) {
     features,
     knowledgeGet: (...args) => via('knowledgeGet', args),
     knowledgeCreate: (...args) => via('knowledgeCreate', args),
+    knowledgeDelete: (...args) => via('knowledgeDelete', args),
     statementCreate: (...args) => via('statementCreate', args),
     search: (...args) => via('search', args),
     similar: (...args) => via('similar', args),

package/src/hypatia-mcp.js

@@ -58,7 +58,7 @@ export const REQUIRED_TOOLS = Object.freeze([
  * The names mirror hypatia-cli.js's `features()`.
  *
  * @param {Array<{name?: string, inputSchema?: {properties?: object}}>} tools
- * @returns {{noEmbed: boolean, similarFilters: boolean}}
+ * @returns {{noEmbed: boolean, similarFilters: boolean, deleteKnowledge: boolean}}
  */
 export function featuresOf(tools) {
   const accepts = (name, argument) => Object.hasOwn(
@@ -68,6 +68,11 @@ export function featuresOf(tools) {
   return {
     noEmbed: accepts('knowledge_create', 'embed') && accepts('statement_create', 'embed'),
     similarFilters: accepts('similar', 'exclude_tags'),
+    // Presence, not schema: `knowledge_delete` takes nothing this client does not
+    // already send. It is a capability rather than a REQUIRED_TOOL — a server
+    // that cannot delete is still a server worth writing memory to, and
+    // rejecting its whole MCP over it would push every call back to the CLI.
+    deleteKnowledge: tools.some((tool) => tool?.name === 'knowledge_delete'),
   }
 }
 
@@ -499,6 +504,23 @@ export function createHypatiaMcp(connection, config) {
       return (await create('knowledge_create', lists(args, entry))) !== undefined
     },
 
+    /**
+     * Remove one knowledge entry. A name that is already gone arrives as a tool
+     * error (`not found: knowledge '<name>'`, classified `NOT_FOUND`), which is
+     * a normal outcome for a replayable retraction rather than a failure.
+     *
+     * @returns {Promise<boolean>} true when this call removed an entry.
+     */
+    async knowledgeDelete(name, shelf = shelfOf()) {
+      try {
+        await invoke('knowledge_delete', { name, shelf })
+        return true
+      } catch (error) {
+        if (error instanceof HypatiaCliError && error.code === 'NOT_FOUND') return false
+        throw error
+      }
+    },
+
     /**
      * `embed: false` as on `knowledgeCreate`.
      * @param {{data?: string, scopes?: string[], embed?: boolean, shelf?: string}} [entry]

package/src/index.js

@@ -37,7 +37,9 @@ import { createHypatiaClient } from './hypatia-client.js'
 import { createHypatiaCli } from './hypatia-cli.js'
 import { createWriter } from './writer.js'
 import { TaskDeferredError, createQueue } from './queue.js'
-import { countLoggableMessages, createCollector, formatSpan } from './collector.js'
+import {
+  countLoggableMessages, createCollector, formatSpan, withdrawalWork, withdrawnOrdinals, withdrawnSeqs,
+} from './collector.js'
 import { createCascade } from './cascade.js'
 import { createConsolidator, PLUGIN_NAME } from './consolidator.js'
 import {
@@ -371,6 +373,18 @@ function applyCollect(ctx, configHandle, status) {
       // is replay-stable by construction and cannot drift out of sync.
       const inherited = session.inheritedEventCount ?? 0
       const baseIndex = countLoggableMessages(session.snapshotEvents(inherited, task.fromSeq))
+      // The marker window ends at `session.seq`, never at the task's own end: a
+      // marker's seq is greater than every seq it shadows, so it can sit past the
+      // range being logged — which is exactly the case where what it hid was
+      // written by an earlier run (docs/rewind-memory-consistency.md §3 fact 5).
+      // Everything else about the decision is collector.js's, where it is a pure
+      // function over the log and therefore testable without a session.
+      const { seqs: withdrawn, retract } = withdrawalWork({
+        log: session.snapshotEvents(task.fromSeq, session.seq ?? 0),
+        prefix: session.snapshotEvents(inherited, task.fromSeq),
+        fromSeq: task.fromSeq,
+        inherited,
+      })
       const formatted = formatSpan(events, {
         now: new Date(),
         maxAssistantChars: config.collector.maxAssistantChars,
@@ -379,14 +393,28 @@ function applyCollect(ctx, configHandle, status) {
         baseIndex,
         before: task.fromSeq > 0 ? session.snapshotEvents(task.fromSeq - 1, task.fromSeq)[0] : undefined,
       })
+      // A message the user took back is skipped, and one an earlier run wrote
+      // before the marker landed is retracted below. Anchored on the log range,
+      // never on "does the entry exist": a replayed span sees the same marker
+      // again, which is what keeps a retracted message from being written back.
+      const skipped = new Set()
       for (const item of formatted) {
+        const isWithdrawn = withdrawn.has(item.seq)
+        if (isWithdrawn) skipped.add(item.index)
         await writer.writeMessage({
           sessionId: task.sessionId,
           index: item.index,
           markdown: item.markdown,
           project: task.project,
+          withdrawn: isWithdrawn,
         })
       }
+      // Retracting is idempotent, and the attempts stop once the watermark passes
+      // the marker's own seq, after which it leaves every later window too.
+      for (const index of retract.values()) {
+        skipped.add(index)
+        await writer.retractMessage({ sessionId: task.sessionId, index })
+      }
       const linkTo = baseIndex + formatted.length
       // `belongTo` edges only exist once the session node does. Most sessions
       // never produce one (it needs a host-supplied summary), so this stays a
@@ -397,8 +425,11 @@ function applyCollect(ctx, configHandle, status) {
           sessionId: task.sessionId,
           markdown: '',
           project: task.project,
+          // The cursor counts every loggable message, withdrawn ones included, so
+          // the ordinals stay aligned with the log; only the edges are skipped.
           linkFrom: before.lastBelongToIndex,
           linkTo,
+          skip: skipped,
         })
       }
       // Awaited: the task must not be reported done — and deleted — before the
@@ -432,12 +463,21 @@ function applyCollect(ctx, configHandle, status) {
       const inherited = session.inheritedEventCount ?? 0
       const current = state.progress.get(task.sessionId) ?? EMPTY_PROGRESS
       const linkTo = countLoggableMessages(session.snapshotEvents(inherited, current.lastLoggedSeq))
+      // This node links every message logged so far, so it owes the same skip set
+      // the log executor used — without it this node's own range would settle
+      // edges to messages that have no entry to link from. The markers are read
+      // from the whole log (the node is written once per session), and a marker
+      // anywhere in it can only hide earlier seqs: one slice, two passes.
+      const log = session.snapshotEvents(inherited, session.seq ?? 0)
+      const withdrawn = withdrawnSeqs(log)
+      const skip = new Set(withdrawnOrdinals(log, withdrawn, inherited).values())
       await writer.writeSessionNode({
         sessionId: task.sessionId,
         markdown,
         project: task.project,
         linkFrom: current.lastBelongToIndex,
         linkTo,
+        skip,
       })
       await advanceProgress(state.progress, task.sessionId, (progressRow) => ({
         hasSessionNode: 1,

package/src/writer.js

@@ -116,6 +116,52 @@ export function summaryName(sessionId, fromSeq, toSeq) {
  * relationship rather than a guessed one.
  */
 export function createWriter(cli, { status, adjudicate }) {
+  /**
+   * Whether this shelf can delete at all, warned about once.
+   *
+   * `knowledgeDelete` is a capability, not part of the baseline: a hypatia from
+   * before `knowledge-delete` existed (hypatia #22), or an MCP server without
+   * the tool, answers `features()` false. A withdrawal is then skipped instead
+   * of retracted — the message is still never written again, because the
+   * decision is anchored on the log range rather than on state this plugin
+   * keeps, so the only cost is one entry left for the user to remove by hand.
+   */
+  let warnedNoDelete = false
+  async function canRetract() {
+    const { deleteKnowledge } = await cli.features()
+    if (deleteKnowledge === false && warnedNoDelete === false) {
+      warnedNoDelete = true
+      status.warn('withdrawn messages cannot be retracted: this hypatia has no knowledge-delete, so they are skipped instead of removed')
+    }
+    return deleteKnowledge !== false
+  }
+
+  /**
+   * Take back one message the user withdrew.
+   *
+   * Get before delete, because the entry usually does not exist yet: a
+   * withdrawal is normally seen by the very span that would have written it.
+   * The get is also what makes a replay safe — `knowledge-delete` on a missing
+   * name is an error on the CLI and `NOT_FOUND` over MCP.
+   *
+   * Statements that mention the name are kept by hypatia on purpose
+   * (`wu-knowledge-delete-retains-statements-7487bf50`), so a withdrawal can
+   * leave a `belongTo` or `summary` edge pointing at an entry that is gone.
+   * That is the recorded, accepted graph semantic; nothing here removes them.
+   *
+   * @param {{sessionId: string, index: number}} entry
+   * @returns {Promise<{name: string, retracted: boolean}>}
+   */
+  async function retractMessage({ sessionId, index }) {
+    const name = messageName(sessionId, index)
+    const existing = await cli.knowledgeGet(name)
+    if (existing.found === false) return { name, retracted: false }
+    if ((await canRetract()) === false) return { name, retracted: false }
+    const removed = await cli.knowledgeDelete(name)
+    if (removed) status.count('retracted')
+    return { name, retracted: removed === true }
+  }
+
   /**
    * Log one conversation message. Duplicates (same name already stored, e.g.
    * from a replayed task) are counted and skipped — the watermark must still
@@ -128,9 +174,14 @@ export function createWriter(cli, { status, adjudicate }) {
    * stored and full-text searchable; only the vector is not made. On a binary
    * without `--no-embed` the flag is dropped by the transport.
    *
-   * @param {{sessionId: string, index: number, markdown: string, project: string}} entry
+   * @param {{sessionId: string, index: number, markdown: string, project: string,
+   *          withdrawn?: boolean}} entry - `withdrawn` marks a message a
+   *   withdrawal marker took out of the model's view: it is not written, and one
+   *   an earlier run already wrote is removed. The executor decides this from
+   *   the log (`withdrawnSeqs` in collector.js); here it is only carried out.
    */
-  async function writeMessage({ sessionId, index, markdown, project }) {
+  async function writeMessage({ sessionId, index, markdown, project, withdrawn = false }) {
+    if (withdrawn) return { ...(await retractMessage({ sessionId, index })), written: false }
     const name = messageName(sessionId, index)
     const existing = await cli.knowledgeGet(name)
     if (existing.found) {
@@ -201,18 +252,23 @@ export function createWriter(cli, { status, adjudicate }) {
    * without one is simply skipped rather than given an invented summary
    * (`skills/hypatia-memory/SKILL.md`, "do not fabricate session summaries").
    *
-   * hypatia has no `knowledge-update`, so a second title cannot replace the
-   * first; the original stands and the caller is told nothing was written.
+   * This writer never rewrites a session node: the plugin does not use
+   * `knowledge-update` on the log layer, so a second title cannot replace the
+   * first — the original stands and the caller is told nothing was written.
    *
    * Node and `belongTo` edges are written `embed: false`, as the messages are:
    * the node is bookkeeping for the traversal, and its title is what
    * `session/title` already gave DSH.
    *
    * @param {{sessionId: string, markdown: string, project: string,
-   *          linkFrom: number, linkTo: number}} entry - `[linkFrom, linkTo)` is
-   * the half-open range of message ordinals still needing a `belongTo` edge.
+   *          linkFrom: number, linkTo: number, skip?: Set<number>}} entry -
+   *   `[linkFrom, linkTo)` is the half-open range of message ordinals still
+   *   needing a `belongTo` edge. `skip` holds ordinals that must NOT be linked:
+   *   a message withdrawn from the model's view has no entry to link from, while
+   *   the cursor still advances past it, so the caller keeps counting every
+   *   loggable message (docs/rewind-memory-consistency.md §4.5).
    */
-  async function writeSessionNode({ sessionId, markdown, project, linkFrom = 0, linkTo = 0 }) {
+  async function writeSessionNode({ sessionId, markdown, project, linkFrom = 0, linkTo = 0, skip }) {
     const name = sessionNodeName(sessionId)
     const existing = await cli.knowledgeGet(name)
     if (existing.found) {
@@ -227,10 +283,13 @@ export function createWriter(cli, { status, adjudicate }) {
       await cli.knowledgeCreate(name, { data: markdown, tags: ['session'], scopes: [project], embed: false })
       status.count('written')
     }
+    let links = 0
     for (let index = linkFrom; index < linkTo; index += 1) {
+      if (skip?.has(index) === true) continue
       await cli.statementCreate(messageName(sessionId, index), 'belongTo', name, { scopes: [project], embed: false })
+      links += 1
     }
-    return { name, written: existing.found === false, links: Math.max(0, linkTo - linkFrom) }
+    return { name, written: existing.found === false, links }
   }
 
   /**
@@ -349,5 +408,5 @@ export function createWriter(cli, { status, adjudicate }) {
     return { name, written: existing.found === false, verdict, nearest }
   }
 
-  return { writeMessage, writeSummary, writeSessionNode, writeWorkUnit, findCandidates, messageName, summaryName }
+  return { writeMessage, retractMessage, writeSummary, writeSessionNode, writeWorkUnit, findCandidates, messageName, summaryName }
 }