dsh-hypatia-auto-memory 2.3.0 → 2.4.0

package/README.md

@@ -2,7 +2,7 @@
 
 > 中文：[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
@@ -225,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
@@ -380,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()`.
@@ -668,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
@@ -711,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

package/README.zh-CN.md

@@ -3,7 +3,7 @@
 > 本文件是 [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) 归档级联、带裁决的工作单元抽取）——全部走**专用模型路由**，
 主会话零模型工作。
 
@@ -180,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` 边从摘要精确下钻的召回方式，而不是按语义命中原始
@@ -292,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 自己的运行时上下文段。
 
@@ -525,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` 原因）和会话关闭是被尊重的；一个覆盖三个无关话题的会话会被总结成一条。
@@ -553,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 时，它用会话种子指明的那个，只有种子没指明时才用

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-hypatia-auto-memory",
-  "version": "2.3.0",
+  "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",

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 }
 }