@max-null/dsh-memory 0.11.1 → 0.12.1

package/dist/anchors.d.ts

@@ -2,12 +2,13 @@
  * 有效性锚点（2026-09-15 静默记忆机制）：把一条记忆绑定到某个**可探测的环境值**上，
  * 值变了就自动失效——解决「版本特性类记忆随环境升级静默变错」的问题。
  *
- * 第一版只做**进程内可探测**的类型：校验跑在会话启动的路径上，探测必须零 IO。
- * 需要跑子进程才能拿到的（如 PowerShell 版本）留待后续——那要先解决「插件直接
- * spawn 会绕过 DSH 的 shell 沙箱」的合规问题，不能顺手开这个口子。
+ * 探测跑在会话启动的校验路径上，因此**禁止起子进程**（那要先解决「插件直接 spawn 会绕过
+ * DSH 的 shell 沙箱」的合规问题，不能顺手开这个口子）。**文件探测不在此列**：`path-exists`
+ * 只有一次 `existsSync`，与读环境变量同量级。此前这里写的是「探测必须零 IO」，那句话把
+ * 「禁止 spawn」误写成了「禁止一切系统调用」——0.12.0 加 `path-exists` 时改正。
  */
-/** 受控词汇表：写入时只能从这三种里选，不能自创（自创的锚点无法机械校验）。 */
-export type AnchorKind = 'env' | 'tool-list' | 'self-version';
+/** 受控词汇表：写入时只能从这四种里选，不能自创（自创的锚点无法机械校验）。 */
+export type AnchorKind = 'env' | 'tool-list' | 'self-version' | 'path-exists';
 /** 一条记忆声明的锚点。 */
 export interface MemoryAnchor {
     kind: AnchorKind;
@@ -27,6 +28,13 @@ export interface AnchorProbes {
     selfVersion: string;
     /** 环境变量读取器；缺省 `process.env`。 */
     env?: (name: string) => string | undefined;
+    /**
+     * 会话工作区 cwd：`path-exists` 用它把**相对路径**解析成绝对路径（0.12.0）。
+     *
+     * 缺省时相对路径判为「**未校验**」而不是「不存在」——定位不到与文件真的不在是两件事，
+     * 混起来会让所有相对路径锚点在拿不到 cwd 的路径上集体误失效。
+     */
+    workspaceCwd?: string;
 }
 /**
  * 探测某个锚点当前的取值。

package/dist/anchors.js

@@ -2,10 +2,13 @@
  * 有效性锚点（2026-09-15 静默记忆机制）：把一条记忆绑定到某个**可探测的环境值**上，
  * 值变了就自动失效——解决「版本特性类记忆随环境升级静默变错」的问题。
  *
- * 第一版只做**进程内可探测**的类型：校验跑在会话启动的路径上，探测必须零 IO。
- * 需要跑子进程才能拿到的（如 PowerShell 版本）留待后续——那要先解决「插件直接
- * spawn 会绕过 DSH 的 shell 沙箱」的合规问题，不能顺手开这个口子。
+ * 探测跑在会话启动的校验路径上，因此**禁止起子进程**（那要先解决「插件直接 spawn 会绕过
+ * DSH 的 shell 沙箱」的合规问题，不能顺手开这个口子）。**文件探测不在此列**：`path-exists`
+ * 只有一次 `existsSync`，与读环境变量同量级。此前这里写的是「探测必须零 IO」，那句话把
+ * 「禁止 spawn」误写成了「禁止一切系统调用」——0.12.0 加 `path-exists` 时改正。
  */
+import { existsSync } from 'node:fs';
+import { isAbsolute, resolve } from 'node:path';
 /**
  * 探测某个锚点当前的取值。
  *
@@ -27,6 +30,16 @@ export function probeAnchor(anchor, probes) {
             return [...probes.toolNames].sort().join(',');
         case 'self-version':
             return probes.selfVersion;
+        case 'path-exists': {
+            if (anchor.name === undefined || anchor.name === '')
+                return undefined;
+            const relative = !isAbsolute(anchor.name);
+            // 相对路径但没有工作区：定位不到 → 未校验（不能判失效）
+            if (relative && (probes.workspaceCwd === undefined || probes.workspaceCwd === ''))
+                return undefined;
+            const target = relative ? resolve(probes.workspaceCwd, anchor.name) : anchor.name;
+            return existsSync(target) ? 'present' : 'absent';
+        }
         default:
             return undefined;
     }

package/dist/engine.d.ts

@@ -114,6 +114,14 @@ export interface MemoryFilter {
     quarantined?: boolean;
     /** 记录类别过滤（0.6.0）；缺省不过滤（工具层显式传 kind='fact' 保持旧行为）。 */
     kind?: MemoryKind;
+    /**
+     * 更新时间下界 / 上界（0.12.0；epoch ms，含端点）。
+     *
+     * **只有 `list` 读这两个字段**——给 `search` 加时间过滤要动候选集（过滤与打分、`markUsed`
+     * 记账的交互：被过滤掉的命中还算不算「用过」），那是另一件要单独论证的事，本版不做。
+     */
+    after?: number;
+    before?: number;
 }
 /** {@link MemoryEngine.update} 的补丁：省略的字段保持原值（`injected` 省略时连 `injectedAuto` 一起保持）。 */
 export interface MemoryPatch {
@@ -124,6 +132,14 @@ export interface MemoryPatch {
      * `injectedAuto: false`，此后不受自动升降影响）；省略则保持原值。
      */
     injected?: boolean;
+    /**
+     * 有效性锚点（0.12.1）：省略保持原值，给值改写，给 `null` 清除。
+     *
+     * 给值时**当场校验一次**并同步 `stale`（成立即复活、不成立即标失效、探测不到则不动）——
+     * 改写锚点的意图就是「让它重新被判定」，等到下次会话维护再判定会留下一个说不清的空窗
+     * （改了锚点却仍显示失效）。清除锚点时连「因该锚点而标的失效」一起清。
+     */
+    anchor?: MemoryAnchor | null;
 }
 export interface MemoryHit {
     record: MemoryRecord;
@@ -184,6 +200,36 @@ export type MemoryChange = {
     from: string;
     to: string;
 };
+/** 体检报告的单条记录：摘要长度与注入行同量级，便于直接念给人听或写进诊断行。 */
+export interface SweepItem {
+    id: string;
+    summary: string;
+}
+/**
+ * 只读体检的产出（{@link MemoryEngine.sweep}）。四类各有明确的消费者，不做「算了没人读」的采样
+ * ——候选与新失效会进注入诊断行（模型每轮可见），久未命中与全量留给按需调用。
+ */
+export interface SweepReport {
+    /** 当前失效的记录，带原因（锚点不符 / 被取代 / 被撤回）。 */
+    stale: Array<SweepItem & {
+        reason: string | undefined;
+    }>;
+    /** 久未被检索命中的**非常驻**记录——常驻的「没被查过」是正常的，它本来就每轮在场。 */
+    longUnused: Array<SweepItem & {
+        lastUsed: number;
+    }>;
+    /** 候选：被反复检索命中但没有被钉成常驻（见 `candidates`）。 */
+    candidates: Array<SweepItem & {
+        hitCount: number;
+    }>;
+    /** 常驻与注入预算的占用：总数 / 实际进注入 / 预算（无限制时不出现）/ 被挤掉几条。 */
+    resident: {
+        total: number;
+        injected: number;
+        budget: number | undefined;
+        omitted: number;
+    };
+}
 declare module '@deepseek-ai/cordis' {
     interface Context {
         memory: MemoryEngine;
@@ -260,6 +306,16 @@ export declare class MemoryEngine extends Service {
     private writeChain;
     /** 会话启动维护只跑一次的标记（2026-09-15）。 */
     private maintenanceDone;
+    /** 最近一次体检的结果（进程内，不落盘）：供注入侧报「本次校验发现的新失效」。 */
+    private lastSweep;
+    /**
+     * 最近一次体检结果（只读）。未跑过时为 `undefined`——注入侧据此决定要不要报那一行，
+     * 它只在真有新失效时出现，稀有所以不构成噪音。
+     *
+     * **每次 `sweep()`（含工具调用）都刷新它**（0.12.1）。此前只在会话启动维护里赋值，于是
+     * 那句提示在整个会话内不再变化，可能一直挂着早已被删掉的记录。
+     */
+    get lastSweepReport(): SweepReport | undefined;
     constructor(ctx: import('@deepseek-ai/cordis').Context, config?: MemoryConfig);
     protected [Service.init](): Promise<void>;
     /** 打开全局存储域（init 与 reload 共用；backend 复用已注册实例）。 */
@@ -363,6 +419,30 @@ export declare class MemoryEngine extends Service {
      * 未打开的层级本轮不计入，影响可忽略（链上祖先在检索路径打开后即缓存）。
      */
     indexCandidates(projectCwd?: string): MemoryRecord[];
+    /**
+     * 只读体检（0.12.0）：把「该退场的」和「钉了却没进来的」摆成一张清单，**不修改任何状态**
+     * ——连时间戳都不写。
+     *
+     * 为什么坚持只读：一只读的工具，最坏情况是报告不准，判断者按错的清单做了坏决定也能追溯；
+     * 一个会改状态的工具，最坏情况是错了都看不见。这决定了它不需要「每日一次」的守卫，也不
+     * 需要定期读者——有人问它就活着，没人问它不产生任何成本（不占预算、不落盘、不写状态）。
+     */
+    sweep(projectCwd?: string, options?: {
+        days?: number;
+        now?: number;
+    }): Promise<SweepReport>;
+    /**
+     * 候选（0.12.0）：被反复检索命中、但没有被钉成常驻的记录。**只提示，不改状态。**
+     *
+     * 筛选条件与原自动升级判据逐条对应（approved、未隔离、未被人工否决、非模板、未常驻）
+     * ——判据没变，变的只是它的作用：从「自动钉住」改为「列出来等一个判断」。`hitCount`
+     * 只增不减，所以候选会一直留着，直到被钉住、被删或记录本身消失——这不是缺陷，是提示
+     * 该有的持续性：它只在被消费之后才消失。
+     *
+     * 与 {@link indexCandidates} 的分工：那个取**全部**记录（供索引行统计规模与主题），
+     * 这个只取满足候选条件的（供体检报告与诊断行）。
+     */
+    candidates(projectCwd?: string): MemoryRecord[];
     /**
      * 按 id 定位记录所在表：global 优先，其次工作区链（自身 → 祖先，由近及远）。
      * **异步版**——写路径必须用它：`writeScope` 可能在本次进入前刚 `reload()`，
@@ -425,6 +505,9 @@ export declare class MemoryEngine extends Service {
     /**
      * 锚点探测上下文。`toolNames` 拿不到时返回 `undefined`——**不能给空数组**：那会被判成
      * 「工具全没了」，让所有 `tool-list` 锚点误失效。
+     *
+     * `workspaceCwd`（0.12.0）供 `path-exists` 把相对路径解析成绝对路径；缺省时相对路径
+     * 判为「未校验」而不是「不存在」。
      */
     private anchorProbes;
     /** 同步版定位：只查**已打开**的表（global + 链上已缓存的工作区表）。 */
@@ -434,9 +517,16 @@ export declare class MemoryEngine extends Service {
     /** {@link markUsed} 的实现体；必须经 `writeScope` 进入（`recordUse` 在此之内）。 */
     private markUsedInner;
     /**
-     * 命中记账 + 自动升级（2026-09-15 静默记忆机制）：命中次数达阈值即自动打开常驻
-     * 注入——「被反复检索命中」是它值得每轮付费的唯一客观证据。统计性字段不 emit，
-     * 只有真的改变了注入状态才发 `memory/changed`。
+     * 命中记账（2026-09-15 静默记忆机制；0.12.0 取消自动升级）。
+     *
+     * 只记 `hitCount` 与 `lastUsedAt`，**不再据此改变注入状态**。原判据是「被反复检索
+     * 命中」= 值得每轮付费的唯一客观证据，但这条证据测错了东西：命中次数度量的是
+     * **它被想起来了**，而常驻的语义是**它不能被忘**——能被检索命中的恰恰是检索已经
+     * 够用的那些，真正该常驻的（想不起来去查的）命中次数永远是 0。达到
+     * {@link CANDIDATE_HITS} 的记录改由 {@link candidates} 列出，进体检报告与诊断行
+     * 提示，改不改由判断者决定（判据详见设计文档 §二事实四）。
+     *
+     * 统计性字段不 emit：本函数现在不改变任何被订阅的状态。
      */
     private recordUse;
     /** 查询日志（惰性创建；位置见 {@link queryLogPath}）。 */
@@ -495,6 +585,13 @@ export declare class MemoryEngine extends Service {
      * @returns 本次状态发生变化的条数。
      */
     verifyAnchors(probes: AnchorProbes, projectCwd?: string): Promise<number>;
+    /**
+     * 锚点失效的原因文案：`verifyAnchorsInner` 与 `update` 的锚点改写共用一处。
+     *
+     * 共用不是为省几行——「改写或清除锚点时顺带清失效」要认得出「这条失效是本锚点标的」，
+     * 两处生成的文案必须逐字相同；认错就会把撤回、被取代标的失效一起抹掉。
+     */
+    private static anchorStaleReason;
     /** {@link verifyAnchors} 的实现体；必须经 `writeScope` 进入。 */
     private verifyAnchorsInner;
     /**
@@ -563,6 +660,33 @@ export declare class MemoryEngine extends Service {
     setInjected(id: MemoryId, injected: boolean, projectCwd?: string): Promise<MemoryRecord>;
     /** {@link setInjected} 的实现体；必须经 `writeScope` 进入。 */
     private setInjectedInner;
+    /**
+     * 语义作废（0.12.0）：把 `targetId` 标成**被 `id` 取代**。
+     *
+     * 与「改内容」的区别：`update` 会让旧内容直接消失，「取代」把痕迹留下来——检索时看到
+     * 「这条已作废，原因是 X」对被主动查的人是信息而不是干扰。`id` 只用来写原因，本身不被
+     * 改动；两条都必须定位得到，否则拒绝（写一个指向不存在记忆的原因没有意义）。
+     *
+     * 下游复用既有的 `stale` 行为：撤常驻、不排除检索、带标注等核对回写。
+     */
+    supersede(id: MemoryId, targetId: MemoryId, projectCwd?: string): Promise<MemoryRecord>;
+    /** {@link supersede} 的实现体；必须经 `writeScope` 进入。返回**被标记的那条**。 */
+    private supersedeInner;
+    /**
+     * 撤回（0.12.0）：把本条标成作废并写明原因。**内容保留**——不删除、也不排除检索，
+     * 与锚点失效后「带标注等核对」是同一条路径。
+     */
+    retract(id: MemoryId, reason: string, projectCwd?: string): Promise<MemoryRecord>;
+    /** {@link retract} 的实现体；必须经 `writeScope` 进入。 */
+    private retractInner;
+    /**
+     * 标失效的共用落点（0.12.0）：写 `stale` + 原因、撤掉常驻、发 `memory/changed`。
+     *
+     * 与 `verifyAnchorsInner` 的失效分支保持**同一组字段**（不动 `status`、不删内容、不排除
+     * 检索）——「被取代」「被撤回」「锚点不符」在下游是同一种状态，只在 `staleReason` 里区分
+     * 来源。失效是一个维度、多种来源，这是那条判据的落点。
+     */
+    private markStale;
     /**
      * 修改一条记忆的内容/关键词/注入位（0.3.1 整理记忆用）。2026-09-15 起：改动**不再**
      * 退回待审核——静默机制下记忆由系统与模型自行维护，更新即保持原有审核状态。2026-09-18

package/dist/engine.js

@@ -18,26 +18,42 @@ import { parsePromptFile, scanPromptDir, writePromptFile } from "./prompt-files.
 import { detectSensitive } from "./quarantine.js";
 import { SELF_VERSION } from "./self.js";
 import { anchorHolds } from "./anchors.js";
+import { DEFAULT_INJECTION_BUDGET, DEFAULT_SUMMARY_CHARS, deriveSummary, renderInjection, } from "./injection.js";
 import { QueryLog, rankGapCandidates, summarizeQueryLog, summarizeSources } from "./query-log.js";
 /** Brand a string as a {@link MemoryId} (compile-time only). */
 export function MemoryId(id) {
     return id;
 }
-/** 自动升常驻所需的命中次数（2026-09-15）：一次偶然命中不足以证明「每轮都值得付费」。 */
-const AUTO_INJECT_HITS = 2;
+/**
+ * 候选提示所需的命中次数（2026-09-15 起是自动升常驻的阈值；0.12.0 改为只提示）。
+ *
+ * 达到它的记录进 {@link MemoryEngine.candidates}，由体检报告与诊断行列出——**不再据此
+ * 改变注入状态**。阈值本身没动：取消自动升之后，它影响的是提示清单的宽度，不再是状态变更。
+ * 一次偶然命中不足以说明任何事，所以起点仍是 2。
+ */
+const CANDIDATE_HITS = 2;
 /**
  * 一次检索里最多把前多少条记为「被使用」（2026-09-15）。
  *
  * 不设上限时，命中计数退化成「和查询有任意字符重叠」：BM25 对常见 2-gram 会给全库打分，
- * 一句「实机验证标记」在本机就能命中 81 条，于是**两次检索把所有 approved 记忆都升成常驻**，
- * 注入预算当场被历史条目占满——「反复被命中才值得每轮付费」这个判据也就失效了。
- * 取前 K 名接近「模型真的会看的那几条」，且与检索返回值解耦（返回值不动）。
+ * 一句「实机验证标记」在本机就能命中 81 条。0.12.0 之前这会让**两次检索把所有 approved
+ * 记忆都升成常驻**、注入预算当场被历史条目占满；取消自动升之后危害降级为「候选清单被灌满
+ * 噪音」，但上限仍然必要——它保证 `hitCount` 度量的是「模型真的会看的那几条」。
+ * 与检索返回值解耦（返回值不动）。
  */
 const HIT_MARK_LIMIT = 5;
 /** 反查候选的正文摘要长度（字符）。 */
 const GAP_EXCERPT_CHARS = 160;
 /** 自动降级的天数阈值（2026-09-15）：与面板的冷数据判定（COLD_DAYS=30）对齐。 */
 const AUTO_DEMOTE_DAYS = 30;
+/**
+ * 体检里「久未命中」的默认天数阈值（0.12.0）。
+ *
+ * 比自动降级的 30 天大得多，因为两者判的不是一类东西：30 天判「自动升上来的常驻是否还有
+ * 价值」，而久未命中的对象**本来就不是常驻**——非常驻的记忆几十天不用是常态，阈值定得太低
+ * 会把正常记录报成待清理。
+ */
+const DEFAULT_SWEEP_DAYS = 90;
 const blockSchema = z.object({
     namespace: z.enum(['global', 'project']),
     status: z.enum(['suggested', 'approved', 'auto', 'suggest']),
@@ -183,6 +199,18 @@ export class MemoryEngine extends Service {
     writeChain = Promise.resolve();
     /** 会话启动维护只跑一次的标记（2026-09-15）。 */
     maintenanceDone = false;
+    /** 最近一次体检的结果（进程内，不落盘）：供注入侧报「本次校验发现的新失效」。 */
+    lastSweep;
+    /**
+     * 最近一次体检结果（只读）。未跑过时为 `undefined`——注入侧据此决定要不要报那一行，
+     * 它只在真有新失效时出现，稀有所以不构成噪音。
+     *
+     * **每次 `sweep()`（含工具调用）都刷新它**（0.12.1）。此前只在会话启动维护里赋值，于是
+     * 那句提示在整个会话内不再变化，可能一直挂着早已被删掉的记录。
+     */
+    get lastSweepReport() {
+        return this.lastSweep;
+    }
     constructor(ctx, config = {}) {
         super(ctx, 'memory');
         this.config = config;
@@ -491,6 +519,83 @@ export class MemoryEngine extends Service {
         }
         return candidates;
     }
+    /**
+     * 只读体检（0.12.0）：把「该退场的」和「钉了却没进来的」摆成一张清单，**不修改任何状态**
+     * ——连时间戳都不写。
+     *
+     * 为什么坚持只读：一只读的工具，最坏情况是报告不准，判断者按错的清单做了坏决定也能追溯；
+     * 一个会改状态的工具，最坏情况是错了都看不见。这决定了它不需要「每日一次」的守卫，也不
+     * 需要定期读者——有人问它就活着，没人问它不产生任何成本（不占预算、不落盘、不写状态）。
+     */
+    async sweep(projectCwd, options) {
+        const now = options?.now ?? Date.now();
+        const days = options?.days ?? DEFAULT_SWEEP_DAYS;
+        const threshold = now - days * 24 * 60 * 60 * 1000;
+        const summaryChars = this.config.summaryChars ?? DEFAULT_SUMMARY_CHARS;
+        const brief = (record) => deriveSummary(record.content, summaryChars);
+        const records = await this.allRecords(undefined, projectCwd);
+        const stale = records
+            .filter(record => record.stale === true)
+            .map(record => ({ id: String(record.id), summary: brief(record), reason: record.staleReason }));
+        // 只看非常驻：常驻的「没被检索过」是正常的（它本来就每轮在场，不需要被查）
+        const longUnused = records
+            .filter(record => record.injected !== true && (record.lastUsedAt ?? record.updatedAt) < threshold)
+            .map(record => ({
+            id: String(record.id),
+            summary: brief(record),
+            lastUsed: record.lastUsedAt ?? record.updatedAt,
+        }));
+        const candidates = this.candidates(projectCwd)
+            .map(record => ({ id: String(record.id), summary: brief(record), hitCount: record.hitCount ?? 0 }));
+        const resident = this.recallRecords(projectCwd);
+        const rendered = renderInjection(resident, this.config.injectionBudget ?? DEFAULT_INJECTION_BUDGET, summaryChars);
+        const report = {
+            stale,
+            longUnused,
+            candidates,
+            resident: {
+                total: resident.length,
+                injected: rendered.lines.length,
+                // `renderInjection` 用 `null` 表示「预算无限制」，而输出 schema 用「字段缺席」表达
+                // 同一件事（可选字段推导出 `number | undefined`）——在这里归一，避免两套空值语义。
+                budget: rendered.budget ?? undefined,
+                omitted: rendered.omitted,
+            },
+        };
+        // 每次体检都写回最近一次结果（0.12.1）：注入侧那句「本次校验发现 N 条失效」读的就是它。
+        // 原先只有会话启动维护会赋值，于是调用 `memory_sweep` 刷新不了它——报告里挂着早已被删掉
+        // 的记录，整个会话内不再变化。（这条只写实例字段，不影响「只读」的承诺：不落盘、不改记忆。）
+        this.lastSweep = report;
+        return report;
+    }
+    /**
+     * 候选（0.12.0）：被反复检索命中、但没有被钉成常驻的记录。**只提示，不改状态。**
+     *
+     * 筛选条件与原自动升级判据逐条对应（approved、未隔离、未被人工否决、非模板、未常驻）
+     * ——判据没变，变的只是它的作用：从「自动钉住」改为「列出来等一个判断」。`hitCount`
+     * 只增不减，所以候选会一直留着，直到被钉住、被删或记录本身消失——这不是缺陷，是提示
+     * 该有的持续性：它只在被消费之后才消失。
+     *
+     * 与 {@link indexCandidates} 的分工：那个取**全部**记录（供索引行统计规模与主题），
+     * 这个只取满足候选条件的（供体检报告与诊断行）。
+     */
+    candidates(projectCwd) {
+        const picked = (table) => this.recordsOf(table).filter(record => record.status === 'approved'
+            && record.quarantined !== true
+            && record.injected !== true
+            && record.injectedAuto !== false
+            && (record.kind ?? 'fact') !== 'prompt'
+            && (record.hitCount ?? 0) >= CANDIDATE_HITS);
+        const found = picked(this.requireTable('global'));
+        if (projectCwd === undefined || projectCwd === '')
+            return found;
+        for (const { key } of this.projectChain(projectCwd)) {
+            const table = this.projectTables.get(key);
+            if (table !== undefined)
+                found.push(...picked(table));
+        }
+        return found;
+    }
     /**
      * 按 id 定位记录所在表：global 优先，其次工作区链（自身 → 祖先，由近及远）。
      * **异步版**——写路径必须用它：`writeScope` 可能在本次进入前刚 `reload()`，
@@ -612,6 +717,9 @@ export class MemoryEngine extends Service {
         (filter?.quarantined === undefined ? record.quarantined !== true : record.quarantined === filter.quarantined)
             && (filter?.status === undefined || record.status === filter.status)
             && (filter?.injected === undefined || record.injected === filter.injected)
+            // 0.12.0：按更新时间筛——与注入排序、注入行的日期标记同一个依据，不制造第二个「新」的定义
+            && (filter?.after === undefined || record.updatedAt >= filter.after)
+            && (filter?.before === undefined || record.updatedAt <= filter.before)
             && (filter?.kind === undefined || (record.kind ?? 'fact') === filter.kind));
     }
     /**
@@ -739,9 +847,14 @@ export class MemoryEngine extends Service {
             const demoted = await this.demoteStale(projectCwd);
             if (demoted > 0)
                 this.ctx.logger?.info?.(`dsh-memory: 长期未命中，撤下常驻 ${demoted} 条`);
-            const staled = await this.verifyAnchors(this.anchorProbes(), projectCwd);
+            const staled = await this.verifyAnchors(this.anchorProbes(projectCwd), projectCwd);
             if (staled > 0)
                 this.ctx.logger?.info?.(`dsh-memory: 锚点校验更新 ${staled} 条`);
+            // 体检（0.12.0）：只读，产物存进实例字段，供注入侧报「本次校验发现的新失效」。
+            // 它在 try 内——报告没有记忆本身重要，失败由下面的 catch 兜住、不阻断启动。
+            // 写回由 `sweep()` 自己做（0.12.1），这里不再赋值——于是手工调用 `memory_sweep`
+            // 也能刷新注入里那句提示。
+            await this.sweep(projectCwd);
         }
         catch (error) {
             this.ctx.logger?.warn?.(`dsh-memory: 启动维护失败（不影响使用）：${String(error)}`);
@@ -750,8 +863,11 @@ export class MemoryEngine extends Service {
     /**
      * 锚点探测上下文。`toolNames` 拿不到时返回 `undefined`——**不能给空数组**：那会被判成
      * 「工具全没了」，让所有 `tool-list` 锚点误失效。
+     *
+     * `workspaceCwd`（0.12.0）供 `path-exists` 把相对路径解析成绝对路径；缺省时相对路径
+     * 判为「未校验」而不是「不存在」。
      */
-    anchorProbes() {
+    anchorProbes(workspaceCwd) {
         let toolNames;
         try {
             const tools = this.ctx.get('tools');
@@ -765,7 +881,11 @@ export class MemoryEngine extends Service {
         catch {
             toolNames = undefined;
         }
-        return { ...(toolNames === undefined ? {} : { toolNames }), selfVersion: SELF_VERSION };
+        return {
+            ...(toolNames === undefined ? {} : { toolNames }),
+            selfVersion: SELF_VERSION,
+            ...(workspaceCwd === undefined || workspaceCwd === '' ? {} : { workspaceCwd }),
+        };
     }
     /** 同步版定位：只查**已打开**的表（global + 链上已缓存的工作区表）。 */
     tableOf(id, projectCwd) {
@@ -812,33 +932,24 @@ export class MemoryEngine extends Service {
         }
     }
     /**
-     * 命中记账 + 自动升级（2026-09-15 静默记忆机制）：命中次数达阈值即自动打开常驻
-     * 注入——「被反复检索命中」是它值得每轮付费的唯一客观证据。统计性字段不 emit，
-     * 只有真的改变了注入状态才发 `memory/changed`。
+     * 命中记账（2026-09-15 静默记忆机制；0.12.0 取消自动升级）。
+     *
+     * 只记 `hitCount` 与 `lastUsedAt`，**不再据此改变注入状态**。原判据是「被反复检索
+     * 命中」= 值得每轮付费的唯一客观证据，但这条证据测错了东西：命中次数度量的是
+     * **它被想起来了**，而常驻的语义是**它不能被忘**——能被检索命中的恰恰是检索已经
+     * 够用的那些，真正该常驻的（想不起来去查的）命中次数永远是 0。达到
+     * {@link CANDIDATE_HITS} 的记录改由 {@link candidates} 列出，进体检报告与诊断行
+     * 提示，改不改由判断者决定（判据详见设计文档 §二事实四）。
+     *
+     * 统计性字段不 emit：本函数现在不改变任何被订阅的状态。
      */
     async recordUse(table, id, block, now) {
-        const hitCount = (block.hitCount ?? 0) + 1;
-        const normalized = normalizeBlock(block);
-        // 人工设置过的（injectedAuto === false）双向豁免：既不被降级，也不被升级。
-        // 少了这一条，人手动关掉的记忆会在下次命中时被系统重新打开——用户唯一能
-        // 表达「不要这条常驻」的动作就失效了，而这与降级侧「人工决定优先」不对称。
-        const promote = normalized.status === 'approved'
-            && block.quarantined !== true
-            && block.injectedAuto !== false
-            // 模板永不注入（0.6.0）：prompt 记录连自动升级的资格都没有。少了这一条，
-            // 模板会因「经常被搜到」而升成常驻，把注入预算花在从不该进上下文的东西上。
-            && (block.kind ?? 'fact') !== 'prompt'
-            && !normalized.injected
-            && hitCount >= AUTO_INJECT_HITS;
         const updated = {
             ...block,
-            hitCount,
+            hitCount: (block.hitCount ?? 0) + 1,
             lastUsedAt: now,
-            ...promote ? { injected: true, injectedAuto: true } : {},
         };
         await table.put(id, updated);
-        if (promote)
-            this.ctx.emit('memory/changed', { operation: 'injected', id, injected: true });
     }
     // ── 查询日志与影响力统计（⑥ 2026-09-15）────────────────────────────────
     /** 查询日志（惰性创建；位置见 {@link queryLogPath}）。 */
@@ -982,6 +1093,16 @@ export class MemoryEngine extends Service {
     async verifyAnchors(probes, projectCwd) {
         return this.writeScope(projectCwd, () => this.verifyAnchorsInner(probes, projectCwd));
     }
+    /**
+     * 锚点失效的原因文案：`verifyAnchorsInner` 与 `update` 的锚点改写共用一处。
+     *
+     * 共用不是为省几行——「改写或清除锚点时顺带清失效」要认得出「这条失效是本锚点标的」，
+     * 两处生成的文案必须逐字相同；认错就会把撤回、被取代标的失效一起抹掉。
+     */
+    static anchorStaleReason(anchor) {
+        const label = `${anchor.kind}${anchor.name === undefined ? '' : `:${anchor.name}`}`;
+        return `${label} 声明为 ${anchor.value}，当前不符`;
+    }
     /** {@link verifyAnchors} 的实现体；必须经 `writeScope` 进入。 */
     async verifyAnchorsInner(probes, projectCwd) {
         const tables = [this.requireTable('global')];
@@ -1000,13 +1121,12 @@ export class MemoryEngine extends Service {
                     continue; // 未校验：探测不到就不动
                 if ((block.stale === true) === !holds)
                     continue; // 状态没变
-                const label = `${block.anchor.kind}${block.anchor.name === undefined ? '' : `:${block.anchor.name}`}`;
                 const updated = holds
                     ? { ...block, stale: false, staleReason: undefined }
                     : {
                         ...block,
                         stale: true,
-                        staleReason: `${label} 声明为 ${block.anchor.value}，当前不符`,
+                        staleReason: MemoryEngine.anchorStaleReason(block.anchor),
                         injected: false,
                         injectedAuto: false,
                     };
@@ -1271,6 +1391,64 @@ export class MemoryEngine extends Service {
         this.ctx.emit('memory/changed', { operation: 'injected', id, injected });
         return record;
     }
+    /**
+     * 语义作废（0.12.0）：把 `targetId` 标成**被 `id` 取代**。
+     *
+     * 与「改内容」的区别：`update` 会让旧内容直接消失，「取代」把痕迹留下来——检索时看到
+     * 「这条已作废，原因是 X」对被主动查的人是信息而不是干扰。`id` 只用来写原因，本身不被
+     * 改动；两条都必须定位得到，否则拒绝（写一个指向不存在记忆的原因没有意义）。
+     *
+     * 下游复用既有的 `stale` 行为：撤常驻、不排除检索、带标注等核对回写。
+     */
+    async supersede(id, targetId, projectCwd) {
+        return this.writeScope(projectCwd, () => this.supersedeInner(id, targetId, projectCwd));
+    }
+    /** {@link supersede} 的实现体；必须经 `writeScope` 进入。返回**被标记的那条**。 */
+    async supersedeInner(id, targetId, projectCwd) {
+        if (id === targetId)
+            throw new Error(`cannot supersede a memory with itself ('${id}')`);
+        if (await this.locateRecord(id, projectCwd) === undefined) {
+            throw new Error(`cannot supersede from unknown memory '${id}'`);
+        }
+        const target = await this.locateRecord(targetId, projectCwd);
+        if (target === undefined)
+            throw new Error(`cannot supersede unknown memory '${targetId}'`);
+        return toRecord(targetId, await this.markStale(targetId, target, `被 ${String(id).slice(0, 8)} 取代`));
+    }
+    /**
+     * 撤回（0.12.0）：把本条标成作废并写明原因。**内容保留**——不删除、也不排除检索，
+     * 与锚点失效后「带标注等核对」是同一条路径。
+     */
+    async retract(id, reason, projectCwd) {
+        return this.writeScope(projectCwd, () => this.retractInner(id, reason, projectCwd));
+    }
+    /** {@link retract} 的实现体；必须经 `writeScope` 进入。 */
+    async retractInner(id, reason, projectCwd) {
+        const found = await this.locateRecord(id, projectCwd);
+        if (found === undefined)
+            throw new Error(`cannot retract unknown memory '${id}'`);
+        return toRecord(id, await this.markStale(id, found, `已撤回：${reason}`));
+    }
+    /**
+     * 标失效的共用落点（0.12.0）：写 `stale` + 原因、撤掉常驻、发 `memory/changed`。
+     *
+     * 与 `verifyAnchorsInner` 的失效分支保持**同一组字段**（不动 `status`、不删内容、不排除
+     * 检索）——「被取代」「被撤回」「锚点不符」在下游是同一种状态，只在 `staleReason` 里区分
+     * 来源。失效是一个维度、多种来源，这是那条判据的落点。
+     */
+    async markStale(id, found, reason) {
+        const updated = {
+            ...found.block,
+            stale: true,
+            staleReason: reason,
+            injected: false,
+            injectedAuto: false,
+            updatedAt: Date.now(),
+        };
+        await found.table.put(id, updated);
+        this.ctx.emit('memory/changed', { operation: 'status', id, status: normalizeBlock(updated).status });
+        return updated;
+    }
     /**
      * 修改一条记忆的内容/关键词/注入位（0.3.1 整理记忆用）。2026-09-15 起：改动**不再**
      * 退回待审核——静默机制下记忆由系统与模型自行维护，更新即保持原有审核状态。2026-09-18
@@ -1293,7 +1471,7 @@ export class MemoryEngine extends Service {
             const status = verdict.quarantined ? 'suggested' : normalized.status;
             // 常驻注入（2026-09-18）：显式给值即接管；未审核或已隔离一律不注入（与自动升级同一门槛）
             const injected = status === 'approved' ? patch.injected ?? normalized.injected : false;
-            return {
+            const patched = {
                 ...block,
                 status,
                 injected,
@@ -1306,6 +1484,35 @@ export class MemoryEngine extends Service {
                 ...(patch.keywords === undefined ? {} : { keywords }),
                 updatedAt: Date.now(),
             };
+            // 锚点（0.12.1）：省略 → 连 stale 一起保持原值
+            if (patch.anchor === undefined)
+                return patched;
+            // 给 `null` → 清除锚点，并连「因它而标的失效」一起清。别的来源（撤回、被取代）原因文案
+            // 不同，不动——「解除约束」与「撤销作废」是两件事，不能顺手一起抹掉。
+            if (patch.anchor === null) {
+                const fromAnchor = block.anchor !== undefined
+                    && block.staleReason === MemoryEngine.anchorStaleReason(block.anchor);
+                return {
+                    ...patched,
+                    anchor: undefined,
+                    ...fromAnchor ? { stale: false, staleReason: undefined } : {},
+                };
+            }
+            // 给值 → 当场校验一次并同步 stale；下面的字段组与 `verifyAnchorsInner` 的失效分支一致
+            const holds = anchorHolds(patch.anchor, this.anchorProbes(projectCwd));
+            if (holds === true)
+                return { ...patched, anchor: patch.anchor, stale: false, staleReason: undefined };
+            if (holds === false) {
+                return {
+                    ...patched,
+                    anchor: patch.anchor,
+                    stale: true,
+                    staleReason: MemoryEngine.anchorStaleReason(patch.anchor),
+                    injected: false,
+                    injectedAuto: false,
+                };
+            }
+            return { ...patched, anchor: patch.anchor }; // 探测不到：不动 stale（未校验 ≠ 失效）
         };
         // 注入位变化单独发一条事件：客户端与面板据此刷新「常驻」列，只发 status 会漏掉它
         const publish = (previous, updated) => {

package/dist/index.js

@@ -9,12 +9,38 @@ import { MemoryEngine } from "./engine.js";
 import { MemoryGateway } from "./remote.js";
 import { mountMemoryApi } from "./routes.js";
 import { SELF_DESCRIPTION } from "./self.js";
-import { DEFAULT_INJECTION_BUDGET, DEFAULT_SUMMARY_CHARS, indexNotice, neighborNotice, neutralizeBraces, omittedNotice, renderInjection } from "./injection.js";
+import { DEFAULT_INJECTION_BUDGET, DEFAULT_SUMMARY_CHARS, candidateNotice, indexNotice, neighborNotice, neutralizeBraces, omittedNotice, renderInjection, staleNotice } from "./injection.js";
 export { MemoryEngine } from "./engine.js";
 export { MemoryId } from "./engine.js";
 export { bm25FieldScores, bm25Scores, cosineSimilarity, rrfFuse, tokenize } from "./bm25.js";
 export const name = 'dsh-memory';
 export const inject = ['storage', 'systemPrompt', 'tools', 'webServer', 'webRuntime'];
+/**
+ * 解析时间过滤参数（0.12.0）：`7d` / `30d` 这类相对天数，或 `YYYY-MM-DD` 绝对日期。
+ *
+ * **为什么用字符串而不是数字**：工具参数里目前没有 number 类型的先例（`type: 'number'` 只
+ * 出现在输出 schema），不拿一个未验证的参数类型去赌；字符串也天然容纳 `7d` 这种相对写法。
+ * 解析不出（空串 / 格式不对）一律返回 `undefined` = 不过滤，**不报错**——过滤条件是辅助
+ * 信息，让它把一次查询整体打断得不偿失。
+ *
+ * 绝对日期按**本地时区**解释（`.dsh` 的存储时间戳是 epoch，用户在本地日期里思考），
+ * 相对天数以 `now` 为基准往前推。
+ */
+function parseTimeFilter(input, now) {
+    if (input === undefined)
+        return undefined;
+    const text = input.trim();
+    if (text === '')
+        return undefined;
+    const relative = /^(\d+)d$/.exec(text);
+    if (relative !== null)
+        return now - Number(relative[1]) * 24 * 60 * 60 * 1000;
+    const absolute = /^(\d{4})-(\d{1,2})-(\d{1,2})$/.exec(text);
+    if (absolute !== null) {
+        return new Date(Number(absolute[1]), Number(absolute[2]) - 1, Number(absolute[3])).getTime();
+    }
+    return undefined;
+}
 const RECORD_SCHEMA = {
     type: 'object',
     additionalProperties: false,
@@ -33,6 +59,16 @@ const RECORD_SCHEMA = {
         hitCount: { type: 'number' },
         quarantined: { type: 'boolean' },
         scope: { type: 'string', description: '来源工作区（④-A）：缺省 = 当前会话工作区；`..` / `../..` = 上级工作区。' },
+        anchor: {
+            type: 'object',
+            additionalProperties: false,
+            description: '有效性锚点：这个值一变，这条记忆就自动失效。`memory_update` 传新值即改写（当场重新校验），传 `null` 即清除。',
+            properties: {
+                kind: { type: 'string', required: true, enum: ['env', 'tool-list', 'self-version', 'path-exists'] },
+                name: { type: 'string' },
+                value: { type: 'string', required: true },
+            },
+        },
     },
 };
 const HIT_SCHEMA = {
@@ -43,6 +79,70 @@ const HIT_SCHEMA = {
         score: { type: 'number', required: true },
     },
 };
+/**
+ * 体检报告的输出（0.12.0）：四类清单一律只读。`summary` 与注入行同量级，直接念给人听
+ * 不失真——这个工具的主要用法就是「你问起时我念给你看」。
+ */
+const SWEEP_SCHEMA = {
+    type: 'object',
+    additionalProperties: false,
+    properties: {
+        stale: {
+            type: 'array',
+            required: true,
+            description: '当前失效的记录（锚点不符 / 被取代 / 已撤回），带原因。',
+            items: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    id: { type: 'string', required: true },
+                    summary: { type: 'string', required: true },
+                    reason: { type: 'string' },
+                },
+            },
+        },
+        longUnused: {
+            type: 'array',
+            required: true,
+            description: '久未被检索命中的非常驻记录——清理或归档的候选材料。',
+            items: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    id: { type: 'string', required: true },
+                    summary: { type: 'string', required: true },
+                    lastUsed: { type: 'number', required: true },
+                },
+            },
+        },
+        candidates: {
+            type: 'array',
+            required: true,
+            description: '被反复检索命中但没有被钉成常驻：要不要钉的待办。',
+            items: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    id: { type: 'string', required: true },
+                    summary: { type: 'string', required: true },
+                    hitCount: { type: 'number', required: true },
+                },
+            },
+        },
+        resident: {
+            type: 'object',
+            required: true,
+            additionalProperties: false,
+            description: '常驻与注入预算的占用；`omitted > 0` 表示「钉了却没进来」。',
+            properties: {
+                total: { type: 'number', required: true },
+                injected: { type: 'number', required: true },
+                budget: { type: 'number', description: '生效预算（字符）；无限制时不出现。' },
+                omitted: { type: 'number', required: true },
+            },
+        },
+    },
+};
 /** 模板记录（0.6.0）：不暴露本地文件路径（meta.path 引擎内部使用）。 */
 const PROMPT_RECORD_SCHEMA = {
     type: 'object',
@@ -74,6 +174,7 @@ function recordValue(record) {
         hitCount: record.hitCount,
         ...record.quarantined === true ? { quarantined: true } : {},
         ...record.scope === undefined ? {} : { scope: record.scope },
+        ...record.anchor === undefined ? {} : { anchor: record.anchor },
     };
 }
 function hitValue(hit) {
@@ -115,19 +216,24 @@ const GUIDANCE = 'Use memory tools for cross-session preferences, habits, and pr
     + '记结论时一并记下**它是怎么来的**——它为什么成立，以及是什么场景把它逼出来的。没有出处的结论像一把'
     + '没有来历的尺子：看起来天经地义，而天经地义的东西最容易被机械套用。'
     + 'Pass `injected: true` on memory_save / memory_update to pin a memory resident in every turn\'s context: '
-    + 'the same switch the settings panel exposes, exempting the record from both automatic rules (promote on '
-    + 'repeated hits, demote after long idle). Reserve it for rules, standing agreements and judgement criteria '
+    + 'the same switch the settings panel exposes, exempting the record from the remaining automatic rule '
+    + '(demote after long idle; repeated hits no longer promote anything — they only feed the candidate hint). '
+    + 'Reserve it for rules, standing agreements and judgement criteria '
     + '— the kind that must apply even when nobody thinks to search for them; facts, references and case notes '
     + 'stay search-only. '
     + '给 memory_save / memory_update 传 `injected: true` 即把这条钉成每轮常驻——与设置面板是同一个开关，'
-    + '此后不受两条自动规则（反复命中自动开启 / 长期未命中自动撤下）影响。只用于规则、长期约定与判据这类'
+    + '此后不受剩下那条自动规则（长期未命中自动撤下）影响；反复命中已不再自动开启任何东西，只喂候选提示。'
+    + '只用于规则、长期约定与判据这类'
     + '「没人想起来搜也必须生效」的记忆；事实、参考与案例留作按需检索。'
     + 'When earlier context may be relevant, call memory_search to recall it — reviewable memories '
     + '相关历史上下文可用 memory_search 检索；被隔离的记录不进检索。'
     + 'Every memory is plaintext and inspectable with memory_list; memory_forget removes one. '
     + '所有记忆均为明文，可用 memory_list 查看；memory_forget 删除一条。'
     + 'Approved + injected memories of the CURRENT session workspace are every-turn injected too. '
-    + '已审核 + 常驻注入开关打开的工作区记忆也会每轮注入（按当前会话工作区路由）。';
+    + '已审核 + 常驻注入开关打开的工作区记忆也会每轮注入（按当前会话工作区路由）。'
+    + 'When the library grows, call memory_sweep for a read-only health check (stale records with reasons, '
+    + 'long-unused ones, candidates that keep being retrieved without being pinned, and budget usage). '
+    + '库变大之后用 memory_sweep 做只读体检——失效记录（带原因）、久未命中、被反复检索却未常驻的候选、以及预算占用。';
 // 0.5.1：`memory:recall` provider 可经 AssembleContext.agent 拿到当前会话
 // 的 header.cwd——注入 = global + 当前会话工作区的 approved+injected
 // （0.3.4 起工作区记忆就按会话 cwd 路由；provider 是同步回调，只读已
@@ -147,6 +253,14 @@ function recallText(memory, projectCwd, budget, summaryChars) {
     const notice = omittedNotice(rendered);
     if (notice !== '')
         parts.push(notice);
+    // 0.12.0：新失效（稀有，出现即值得看一眼）与候选（该不该钉的待办）。
+    // 两者都不占预算；候选必须走到眼前，因为判断者就是读这段上下文的模型自己。
+    const stale = staleNotice(memory.lastSweepReport?.stale ?? []);
+    if (stale !== '')
+        parts.push(stale);
+    const candidates = candidateNotice(memory.candidates(projectCwd));
+    if (candidates !== '')
+        parts.push(candidates);
     // ① 索引行：给出「库里还有什么、按什么去搜」（不占预算、长度常数级）
     const index = indexNotice(memory.indexCandidates(projectCwd));
     if (index !== '')
@@ -261,7 +375,7 @@ export async function apply(ctx, config) {
                 additionalProperties: false,
                 description: 'Optional validity anchor: bind this memory to a probeable environment value so it auto-expires when that value changes. Use only for facts that depend on the environment (tool behaviour under a specific version, config decided by an env var). 可选锚点：把记忆绑到可探测的环境值，值变了自动失效。只用于「随环境变化的事实」。',
                 properties: {
-                    kind: { type: 'string', required: true, enum: ['env', 'tool-list', 'self-version'], description: 'env = a named environment variable; tool-list = the available tool set; self-version = this plugin version.' },
+                    kind: { type: 'string', required: true, enum: ['env', 'tool-list', 'self-version', 'path-exists'], description: 'env = a named environment variable; tool-list = the available tool set; self-version = this plugin version; path-exists = a path that should still exist (`name` = the path, `value` = `present` or `absent`).' },
                     name: { type: 'string', description: 'For kind=env: the variable name.' },
                     value: { type: 'string', required: true, description: 'The value probed at write time.' },
                 },
@@ -287,21 +401,28 @@ export async function apply(ctx, config) {
     }));
     ctx.tools.register(defineTool({
         name: 'memory_list',
-        description: 'List every stored memory, optionally filtered by namespace, status, or injected switch. Every memory is plaintext and inspectable. 列出全部记忆，可按 namespace/status/injected 过滤；均为明文可查。',
+        description: 'List every stored memory, optionally filtered by namespace, status, injected switch, or update time. Every memory is plaintext and inspectable. 列出全部记忆，可按 namespace/status/injected/更新时间过滤；均为明文可查。',
         parameters: {
             namespace: { type: 'string', enum: ['global', 'project'], description: 'Restrict to one namespace. 限定单个命名空间.' },
             status: { type: 'string', enum: ['suggested', 'approved'], description: 'Restrict to one review status. 限定审核状态（suggested=待审核 / approved=已审核）.' },
             injected: { type: 'boolean', description: 'Restrict by the persistent-injection switch. 按常驻注入开关过滤.' },
+            after: { type: 'string', description: 'Only memories updated at/after this time: `YYYY-MM-DD`, or a relative form like `7d` / `30d`. 只返回此后更新过的记忆（`YYYY-MM-DD`，或相对形式 `7d` / `30d`）.' },
+            before: { type: 'string', description: 'Only memories updated at/before this time (same forms as `after`). 只返回此前更新过的记忆（写法同 after）.' },
         },
         output: {
             schema: { type: 'array', items: RECORD_SCHEMA },
             render: (_args, value) => renderJson(value),
         },
         execute(args, exec) {
+            const now = Date.now();
+            const after = parseTimeFilter(args.after, now);
+            const before = parseTimeFilter(args.before, now);
             return memory.list({
                 ...args.namespace === undefined ? {} : { namespace: args.namespace },
                 ...args.status === undefined ? {} : { status: args.status },
                 ...args.injected === undefined ? {} : { injected: args.injected },
+                ...after === undefined ? {} : { after },
+                ...before === undefined ? {} : { before },
             }, execProjectCwd(exec)).then(records => records.map(recordValue));
         },
         presentCall: () => present('List memories', 'read'),
@@ -500,23 +621,52 @@ export async function apply(ctx, config) {
     }));
     ctx.tools.register(defineTool({
         name: 'memory_update',
-        description: 'Update the content, keywords or persistent-injection switch of one stored memory (e.g. correcting stale facts). The record keeps its review status; content that looks like a credential quarantines it instead. 修改一条记忆的内容、关键词或常驻注入开关（如修正过时信息）。改动后记忆保持原有审核状态；若新内容命中危险规则则转为隔离。',
+        description: 'Update the content, keywords, persistent-injection switch or validity anchor of one stored memory (e.g. correcting stale facts, or re-anchoring a memory whose anchor no longer holds). The record keeps its review status; content that looks like a credential quarantines it instead. 修改一条记忆的内容、关键词、常驻注入开关或有效性锚点（如修正过时信息、把失效的锚点改对）。改动后记忆保持原有审核状态；若新内容命中危险规则则转为隔离。',
         parameters: {
             id: { type: 'string', required: true, description: 'Exact memory id from memory_list. 记忆 id（来自 memory_list）.' },
             content: { type: 'string', description: 'New content; omit to keep current. 新内容；省略则保留现有内容.' },
             keywords: { type: 'array', items: { type: 'string' }, description: 'New keywords; omit to keep current. 新关键词；省略则保留现有.' },
-            injected: { type: 'boolean', description: 'Set or clear the persistent-injection switch; omit to keep the current value. Setting it records a deliberate decision — the memory stops being auto-promoted or auto-demoted. See memory_save for what deserves residency. 设置或清除常驻注入开关；省略则保持原值。给值即视为有意决定——此后不受自动升降影响。何时该常驻见 memory_save。' },
+            supersedes: { type: 'string', description: 'Mark the memory with this id as superseded by the current one (the current record is unchanged; only the other gets the void mark). 把该 id 指向的记忆标成「被本条取代」——本条不变，只写对方的作废标记。与 content / retract 互斥。' },
+            retract: { type: 'string', description: 'Retract this memory: give a reason and it is marked void (content kept, no longer injected, still searchable). 撤回本条：给一个原因即标记作废——内容保留、不再进注入，检索仍可检回。与 content / supersedes 互斥。' },
+            injected: { type: 'boolean', description: 'Set or clear the persistent-injection switch; omit to keep the current value. Setting it records a deliberate decision — the memory stops being auto-demoted (repeated hits no longer promote anything). See memory_save for what deserves residency. 设置或清除常驻注入开关；省略则保持原值。给值即视为有意决定——此后不受自动降级影响（反复命中已不再自动开启任何东西）。何时该常驻见 memory_save。' },
+            anchor: {
+                description: 'Set, replace, or clear the validity anchor; omit to keep the current one. A new value is re-probed immediately: if it holds, a stale mark left by the old anchor is dropped; if it fails, the memory is marked stale and unpinned at once. `null` clears the anchor together with the stale mark that anchor caused. 设置 / 改写 / 清除有效性锚点；省略则保持原值。给值**当场重新探测**——新锚点成立就撤掉旧锚点留下的失效标记，不成立就立刻标失效并撤下常驻；给 `null` 清除锚点，并连同它带来的失效标记一起清。',
+                oneOf: [
+                    {
+                        type: 'object',
+                        additionalProperties: false,
+                        properties: {
+                            kind: { type: 'string', required: true, enum: ['env', 'tool-list', 'self-version', 'path-exists'], description: 'env = a named environment variable; tool-list = the available tool set; self-version = this plugin version; path-exists = a path that should still exist (`name` = the path, `value` = `present` or `absent`).' },
+                            name: { type: 'string', description: 'For kind=env: the variable name. For kind=path-exists: the path (relative paths resolve against the session workspace).' },
+                            value: { type: 'string', required: true, description: 'The value probed at write time.' },
+                        },
+                    },
+                    { type: 'null' },
+                ],
+            },
         },
         output: {
             schema: RECORD_SCHEMA,
             render: (_args, value) => renderJson(value),
         },
         execute(args, exec) {
-            return memory.update(args.id, {
+            const cwd = execProjectCwd(exec);
+            const id = args.id;
+            // 三种动作互斥，按 retract > supersedes > update 的次序取第一个（与工具描述一致）：
+            // 前两个是「标状态」，第三个才是「改内容」。同时给多个时以更重的动作为准。
+            if (args.retract !== undefined)
+                return memory.retract(id, args.retract, cwd).then(recordValue);
+            if (args.supersedes !== undefined)
+                return memory.supersede(id, args.supersedes, cwd).then(recordValue);
+            return memory.update(id, {
                 ...args.content === undefined ? {} : { content: args.content },
                 ...args.keywords === undefined ? {} : { keywords: args.keywords },
                 ...args.injected === undefined ? {} : { injected: args.injected },
-            }, execProjectCwd(exec)).then(recordValue);
+                // 参数已由 tool schema 校验（对象或 null），这里的窄化只为过类型
+                ...args.anchor === undefined
+                    ? {}
+                    : { anchor: args.anchor },
+            }, cwd).then(recordValue);
         },
         presentCall: args => present('Update memory', 'other', args.id),
     }));
@@ -535,4 +685,17 @@ export async function apply(ctx, config) {
         },
         presentCall: args => present('Confirm memory', 'other', args.id),
     }));
+    ctx.tools.register(defineTool({
+        name: 'memory_sweep',
+        description: 'Read-only health check: lists stale memories (with the reason), long-unused non-resident ones, candidates that keep being retrieved without being pinned, and how much of the injection budget the resident set takes. Changes nothing. 只读体检：列出失效的记忆（带原因）、久未被检索命中的非常驻记录、被反复检索却未常驻的候选，以及常驻占用了多少注入预算。不修改任何状态——最坏情况是报告不准，而不是误改内容。',
+        parameters: {},
+        output: {
+            schema: SWEEP_SCHEMA,
+            render: (_args, value) => renderJson(value),
+        },
+        execute(_args, exec) {
+            return memory.sweep(execProjectCwd(exec));
+        },
+        presentCall: () => present('Sweep memory', 'other', 'read-only'),
+    }));
 }

package/dist/injection.d.ts

@@ -32,6 +32,14 @@ export declare function deriveSummary(content: string, maxChars: number): string
  */
 export declare function neutralizeBraces(text: string): string;
 /** 一条注入行的渲染文本（与面板预览完全一致）。 */
+/**
+ * 日期标记（0.12.0）：`YYYY-MM-DD`，按**本地时区**取，输入是 epoch ms。
+ *
+ * 用绝对日期而不是「18 天前」：相对时间每轮都在变，会把一个稳定的注入副本变成每轮漂移的
+ * 文本——`memory:recall` 本来就是动态 context，但不必要的漂移仍应避免。**减少变化的维度
+ * 是廉价的稳定性。**
+ */
+export declare function formatDay(at: number): string;
 export declare function injectionLine(record: MemoryRecord, summaryChars: number): string;
 export interface InjectionRender {
     /** 实际注入行（已按预算截断、按更新时间降序）。 */
@@ -54,9 +62,12 @@ export interface InjectionRender {
     chars: number;
 }
 /**
- * 由候选记录渲染注入行：按使用序降序（lastUsedAt 优先、缺省回退
- * updatedAt——最近使用/更新的记忆最先），逐条累加开销直到预算用尽；
- * 预算为 null 或非正数时全量注入（不过滤）。
+ * 由候选记录渲染注入行：按**更新时间**降序（最近更新的最先），逐条累加开销直到预算
+ * 用尽；预算为 null 或非正数时全量注入（不过滤）。
+ *
+ * 0.12.0 起不再看 `lastUsedAt`：那是**检索**留下的痕迹，而检索是「需要时才用」的行为
+ * ——拿它决定「谁每轮在场」，等于让「查得多的」挤掉「钉得牢的」，而且一次 `memory_search`
+ * 会当场改变下一轮的注入内容（`markUsed` 就在检索路径上）。排序只该由内容本身的变更驱动。
  */
 export declare function renderInjection(records: readonly MemoryRecord[], budget: number | null, summaryChars: number): InjectionRender;
 /**
@@ -67,6 +78,31 @@ export declare function renderInjection(records: readonly MemoryRecord[], budget
  * {@link OMITTED_NOTICE_LIMIT} 只列前 N 个。
  */
 export declare function omittedNotice(rendered: InjectionRender): string;
+/** 注入侧报「新失效」的条数上限——在稀有与有用之间取舍，只报几条就够指向问题。 */
+export declare const STALE_NOTICE_LIMIT = 3;
+/** 候选提示列出的条数上限。 */
+export declare const CANDIDATE_NOTICE_LIMIT = 3;
+/** 候选提示里每条摘要的长度：比注入行更短，这一行本身不该占太多。 */
+export declare const CANDIDATE_SUMMARY_CHARS = 24;
+/**
+ * 新失效提示行（0.12.0）：报「本次启动校验发现几条记忆失效」。
+ *
+ * **它稀有，所以不构成噪音**：一条记忆失效意味着「照它行动会出错」，值得每轮看见，直到被
+ * 核对回写或删除。与 {@link omittedNotice} 一样**不占注入预算**（调用方追加在注入行之后）。
+ */
+export declare function staleNotice(stale: ReadonlyArray<{
+    summary: string;
+}>): string;
+/**
+ * 候选提示行（0.12.0）：报「有几条被反复检索命中、但没有被钉成常驻」。
+ *
+ * **判断者是模型自己**——一份不会主动去调的体检报告等于不存在，所以候选必须自己走到它眼前。
+ * `hitCount` 只增不减，候选会一直留着直到被消费（钉住或删掉）：这不是缺陷，是提示该有的
+ * 持续性。**不占注入预算**。
+ */
+export declare function candidateNotice(candidates: ReadonlyArray<{
+    content: string;
+}>): string;
 /** 子项目索引行列出的条数上限（④-B）：超出以 `…` 结尾，防这行本身失控。 */
 export declare const NEIGHBOR_NOTICE_LIMIT = 5;
 /**

package/dist/injection.js

@@ -47,18 +47,34 @@ export function neutralizeBraces(text) {
     return result;
 }
 /** 一条注入行的渲染文本（与面板预览完全一致）。 */
+/**
+ * 日期标记（0.12.0）：`YYYY-MM-DD`，按**本地时区**取，输入是 epoch ms。
+ *
+ * 用绝对日期而不是「18 天前」：相对时间每轮都在变，会把一个稳定的注入副本变成每轮漂移的
+ * 文本——`memory:recall` 本来就是动态 context，但不必要的漂移仍应避免。**减少变化的维度
+ * 是廉价的稳定性。**
+ */
+export function formatDay(at) {
+    const date = new Date(at);
+    return `${date.getFullYear()}-${String(date.getMonth() + 1).padStart(2, '0')}-${String(date.getDate()).padStart(2, '0')}`;
+}
 export function injectionLine(record, summaryChars) {
     // ④-A：跨工作区召回时带来源标记（`..` / `../..`）；当前工作区不带，保持既有格式
     const scope = record.scope === undefined ? '' : `@${record.scope}`;
-    return `- [memory:${String(record.id).slice(0, 8)}:${record.namespace}${scope}] ${deriveSummary(record.content, summaryChars)}`;
+    // 0.12.0：日期固定在 scope 之前——日期是数字、scope 是点号，顺序固定即无歧义。
+    // 「这条是什么时候记的」直接决定要不要先核对再照它做，尤其对随环境失效的那类记忆。
+    return `- [memory:${String(record.id).slice(0, 8)}:${record.namespace}@${formatDay(record.updatedAt)}${scope}] ${deriveSummary(record.content, summaryChars)}`;
 }
 /**
- * 由候选记录渲染注入行：按使用序降序（lastUsedAt 优先、缺省回退
- * updatedAt——最近使用/更新的记忆最先），逐条累加开销直到预算用尽；
- * 预算为 null 或非正数时全量注入（不过滤）。
+ * 由候选记录渲染注入行：按**更新时间**降序（最近更新的最先），逐条累加开销直到预算
+ * 用尽；预算为 null 或非正数时全量注入（不过滤）。
+ *
+ * 0.12.0 起不再看 `lastUsedAt`：那是**检索**留下的痕迹，而检索是「需要时才用」的行为
+ * ——拿它决定「谁每轮在场」，等于让「查得多的」挤掉「钉得牢的」，而且一次 `memory_search`
+ * 会当场改变下一轮的注入内容（`markUsed` 就在检索路径上）。排序只该由内容本身的变更驱动。
  */
 export function renderInjection(records, budget, summaryChars) {
-    const ordered = [...records].sort((left, right) => (right.lastUsedAt ?? right.updatedAt) - (left.lastUsedAt ?? left.updatedAt));
+    const ordered = [...records].sort((left, right) => right.updatedAt - left.updatedAt);
     const lines = [];
     const omittedRecords = [];
     let chars = 0;
@@ -95,6 +111,40 @@ export function omittedNotice(rendered) {
     const truncated = rendered.omittedRecords.length > shown.length ? '…' : '';
     return `（另有 ${rendered.omitted} 条常驻因预算未注入：${labels.join('、')}${truncated}）`;
 }
+/** 注入侧报「新失效」的条数上限——在稀有与有用之间取舍，只报几条就够指向问题。 */
+export const STALE_NOTICE_LIMIT = 3;
+/** 候选提示列出的条数上限。 */
+export const CANDIDATE_NOTICE_LIMIT = 3;
+/** 候选提示里每条摘要的长度：比注入行更短，这一行本身不该占太多。 */
+export const CANDIDATE_SUMMARY_CHARS = 24;
+/**
+ * 新失效提示行（0.12.0）：报「本次启动校验发现几条记忆失效」。
+ *
+ * **它稀有，所以不构成噪音**：一条记忆失效意味着「照它行动会出错」，值得每轮看见，直到被
+ * 核对回写或删除。与 {@link omittedNotice} 一样**不占注入预算**（调用方追加在注入行之后）。
+ */
+export function staleNotice(stale) {
+    if (stale.length === 0)
+        return '';
+    const shown = stale.slice(0, STALE_NOTICE_LIMIT);
+    const truncated = stale.length > shown.length ? '…' : '';
+    return `（本次校验发现 ${stale.length} 条记忆失效：${shown.map(item => item.summary).join('、')}${truncated}）`;
+}
+/**
+ * 候选提示行（0.12.0）：报「有几条被反复检索命中、但没有被钉成常驻」。
+ *
+ * **判断者是模型自己**——一份不会主动去调的体检报告等于不存在，所以候选必须自己走到它眼前。
+ * `hitCount` 只增不减，候选会一直留着直到被消费（钉住或删掉）：这不是缺陷，是提示该有的
+ * 持续性。**不占注入预算**。
+ */
+export function candidateNotice(candidates) {
+    if (candidates.length === 0)
+        return '';
+    const shown = candidates.slice(0, CANDIDATE_NOTICE_LIMIT);
+    const labels = shown.map(record => deriveSummary(record.content, CANDIDATE_SUMMARY_CHARS));
+    const truncated = candidates.length > shown.length ? '…' : '';
+    return `（另有 ${candidates.length} 条被反复检索但未常驻：${labels.join('、')}${truncated}）`;
+}
 /** 子项目索引行列出的条数上限（④-B）：超出以 `…` 结尾，防这行本身失控。 */
 export const NEIGHBOR_NOTICE_LIMIT = 5;
 /**

package/dist/self.js

@@ -5,6 +5,10 @@
  * 0.9.2：补齐常驻注入机制——`injected` 参数、注入预算上限、预算诊断行的含义。
  * 0.10.0：修正工具清单（6 → 10，补提示词模板工具）与两层记忆说明——原清单漏了
  * `prompt_*` 系列，照它读会以为本插件只有记忆工具。
+ * 0.12.0：工具清单 10 → 11（补 `memory_sweep`）；删掉「命中累计 2 次自动开启常驻」
+ * （该规则已取消，命中只喂候选提示）；注入取舍依据由「最近使用」改为「最近更新」。
+ * 0.12.1：锚点那句补上「可以用 memory_update 改写或清除」——此前模型读得到锚点的作用，
+ * 却没有任何改它的手段，读起来像一条只能写死一次的东西。
  */
 import { createRequire } from 'node:module';
 export const SELF_VERSION = (() => {
@@ -19,7 +23,7 @@ export const SELF_VERSION = (() => {
     }
 })();
 export const SELF_DESCRIPTION = `[记忆系统自述] 本环境内置跨会话记忆服务（dsh-memory v${SELF_VERSION}）。`
-    + '你有 10 个工具：**记忆工具** memory_save / memory_search / memory_list / memory_update / memory_confirm / memory_forget（`memory_confirm` 仅在用户明确要求放行隔离记录时用）；**提示词模板工具** prompt_search / prompt_get / prompt_list / prompt_add（模板是 md 文件、**永不注入**，走这条通道，不会混进记忆检索）。'
+    + '你有 11 个工具：**记忆工具** memory_save / memory_search / memory_list / memory_update / memory_confirm / memory_forget / memory_sweep（`memory_confirm` 仅在用户明确要求放行隔离记录时用；`memory_sweep` 是只读体检——失效清单、久未命中、候选与预算占用，不修改任何状态）；**提示词模板工具** prompt_search / prompt_get / prompt_list / prompt_add（模板是 md 文件、**永不注入**，走这条通道，不会混进记忆检索）。'
     + '记忆分两层：`global` 跨项目（偏好 / 习惯 / 环境知识），`project` 跟随工作区（落在 `<cwd>/.dsh/storages/`，随 git 提交分享）。'
     + '**何时写入**（不必刻意找机会，遇到下面这些就动手）：'
     + '① 用户表达长期偏好或约定（「以后都…」「记住…」「我们的规矩是…」）；'
@@ -27,12 +31,12 @@ export const SELF_DESCRIPTION = `[记忆系统自述] 本环境内置跨会话
     + '③ 得出跨会话仍然有用的结论、路径或坑，而非本次任务的临时细节。'
     + '**不要记**：临时状态、未经验证的推测、能从代码或文档直接读到的事实（那类记「去哪查」即可）。'
     + '**怎么写**：一条一件事，并给多角度关键词（同义词、缩写、中英），否则将来检索不到它。'
-    + '**锚点（可选）**：若这条记忆描述的是「随某个环境值变化的事实」（某工具版本下的行为、某环境变量决定的配置），用 anchor 参数把它绑到那个值上——值变了它会自动失效并标 stale，不会再被当成仍然正确。'
+    + '**锚点（可选）**：若这条记忆描述的是「随某个环境值变化的事实」（某工具版本下的行为、某环境变量决定的配置），用 anchor 参数把它绑到那个值上——值变了它会自动失效并标 stale，不会再被当成仍然正确；绑错了用 memory_update 改（当场重新判定，成立即复活），不要了就传 `anchor: null` 清除。当前锚点随记录一起返回。'
     + '写入即生效（`approved`），人工只在例外时介入；命中密钥/凭据规则的写入会被隔离（不进注入与检索）。'
     + '**常驻注入**：每轮注入「global + 当前会话工作区」里 approved 且开着常驻开关的记忆单行摘要（形如 `- [memory:id:namespace] 摘要`）；全文要靠 memory_search 取。'
-    + '开关有两条自动规则：命中累计 2 次自动开启、30 天未命中自动撤下；**给 memory_save / memory_update 传 `injected` 即显式接管**，此后这两条都不再适用。'
+    + '开关只有一条自动规则：**自动升上来的**常驻在 30 天未命中后撤下；命中次数不再自动改变注入状态（它只喂体检报告的候选提示）。**给 memory_save / memory_update 传 `injected` 即显式接管**，此后这条规则也不再适用。'
     + '**钉的判据是「失效可察觉性」**：这条记忆若没被想起来，你会不会根本意识不到自己漏了它？会 → 钉常驻（规则 / 委托 / 判据）；不会 → 留检索（事实 / 参考 / 案例）。'
-    + '**注入有预算**（默认 1500 字符，约装 11 条），装不下的整条丢弃、按最近使用优先取舍——所以「钉了常驻」只等于「有资格排队」。'
+    + '**注入有预算**（默认 1500 字符，约装 11 条），装不下的整条丢弃、按**最近更新**优先取舍（不是最近被检索——检索是「需要时才用」的行为，拿它决定「谁每轮在场」会让查得多的挤掉钉得牢的）——所以「钉了常驻」只等于「有资格排队」。'
     + '装不下时注入末尾会出现一行 `（另有 N 条常驻因预算未注入：…短摘要…）`——**那是「有常驻记忆并不在场」的唯一信号**，看到它就该逐条评估撤下。'
     + '发现某条记忆与实际不符时用 memory_update 修正（保持生效）；确认没用的用 memory_forget。'
     + '（English: dsh-memory provides cross-session memory. Writes take effect immediately; save durable preferences, corrections and reusable conclusions — not transient state, guesses, or facts readable from the repo (record where to look instead). Always add multi-angle keywords. Pass `injected: true` to keep one resident every turn — reserve that for rules and standing agreements; facts stay search-only. Resident injection runs on a budget, so a pinned memory is only queued, never guaranteed to be in context.)';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@max-null/dsh-memory",
-  "version": "0.11.1",
+  "version": "0.12.1",
   "description": "Cross-session plaintext memory plugin for the DeepSeek Harness — deterministic BM25 recall, writes take effect immediately, signal-driven injection, no embeddings",
   "license": "MIT",
   "publishConfig": {