dsh-lite-memory 0.18.1 → 0.18.19

package/index.js

@@ -8,6 +8,8 @@ import {
   forget,
   undoChange,
   locate,
+  layersFor,
+  runtimeLayers,
   findAnywhere,
   renderIndex,
   loadIndex,
@@ -22,6 +24,8 @@ import {
   recordCitations,
   listCitations,
   readCitationBody,
+  readCitationBodyByTitle,
+  locateByTitle,
   evolutionStatus,
   controlStatus,
   setMemoryEnabled,
@@ -88,6 +92,17 @@ function memoryEnabled(scope) {
   }
 }
 
+/** 关着的原因决定下一步：恢复出来的状态要用户重新开启，而不是让人以为是自己关的。 */
+function memoryOffCopy(scope) {
+  try {
+    return controlStatus(scope).recoveryPending
+      ? '本项目记忆刚从损坏里恢复，需要你重新开启'
+      : '本项目记忆已关闭，先在面板打开';
+  } catch {
+    return '本项目记忆已关闭，先在面板打开';
+  }
+}
+
 function memoryEnabledFor(execution) {
   return memoryEnabled(scopeOf(cwdOf(execution)));
 }
@@ -136,6 +151,28 @@ function readJsonBody(req, limit = 8192) {
   });
 }
 
+/** 每个会话最近一次自动召回的判断依据；只留判断，不留正文。 */
+const recallReceipts = new Map();
+
+function noteRecall(scope, sessionId, receipt) {
+  if (!scope || typeof sessionId !== 'string' || !sessionId) return;
+  recallReceipts.set(`${scope.key}\u0000${sessionId}`, {
+    at: new Date().toISOString(),
+    reason: String(receipt.reason || ''),
+    matched: Number(receipt.matched) || 0,
+    cards: Number(receipt.cards) || 0,
+    chars: Number(receipt.chars) || 0,
+    limit: view.CARD.max,
+    bytes: view.CARD.bytes,
+  });
+  while (recallReceipts.size > 64) recallReceipts.delete(recallReceipts.keys().next().value);
+}
+
+function recallReceiptOf(scope, sessionId) {
+  if (!scope || typeof sessionId !== 'string' || !sessionId) return null;
+  return recallReceipts.get(`${scope.key}\u0000${sessionId}`) || null;
+}
+
 /**
  * 桌面壳与本地 Web 是同一个界面：认 host 自己的 origin，也认 app 内建协议。
  */
@@ -162,6 +199,7 @@ function keepHandler(webServer, cwdForSession) {
         : pathname === REMOTE_PATH + '/keep' ? 'keep'
           : pathname === REMOTE_PATH + '/citations' ? 'citations'
             : pathname === REMOTE_PATH + '/body' ? 'body'
+              : pathname === REMOTE_PATH + '/entry' ? 'entry'
               : pathname === REMOTE_PATH + '/move' ? 'move'
                 : pathname === REMOTE_PATH + '/overview' ? 'overview'
                   : pathname === REMOTE_PATH + '/control' ? 'control'
@@ -181,10 +219,18 @@ function keepHandler(webServer, cwdForSession) {
      */
     if (action === 'body') {
       const id = typeof body.id === 'string' ? body.id : '';
-      if (!id) return sendJson(res, 400, { ok: false, reason: '缺少 id' });
+      /** 界面只有标题：按标题照样能读，id 留着兼容旧引用文件。 */
+      const titleRef = typeof body.title === 'string' ? body.title.trim() : '';
+      const revisionRef = Number.isInteger(body.revision) ? body.revision : undefined;
+      if (!id && !titleRef) return sendJson(res, 400, { ok: false, reason: '缺少标题' });
+      /** 找不到时只回调用方给的那个句柄：按 id 问就回 id，按标题问就回标题。 */
+      const goneReply = () => sendJson(res, 200, titleRef
+        ? { ok: true, status: 'gone', title: titleRef }
+        : { ok: true, status: 'gone', id });
       const sessionId = typeof body.sessionId === 'string' ? body.sessionId : '';
       const cwd = typeof body.cwd === 'string' ? body.cwd : '';
       const scopeKey = typeof body.scopeKey === 'string' ? body.scopeKey : '';
+      const scopeRef = body.scope === 'global' || body.scope === 'project' ? body.scope : '';
       let found;
       if (scopeKey) {
         /**
@@ -197,8 +243,9 @@ function keepHandler(webServer, cwdForSession) {
           : listed ? { key: listed.key, dir: listed.dir, cwd: listed.cwd || '', requestedCwd: listed.cwd || '', rootSource: 'configured', confirmed: true }
             : null;
         if (!target) return sendJson(res, 404, { ok: false, reason: '没有这个项目' });
-        const located = locate(target, id, { readOnly: true });
-        if (!located) return sendJson(res, 200, { ok: true, status: 'gone', id });
+        const located = id ? locate(target, id, { readOnly: true })
+          : locateByTitle(target, titleRef, { readOnly: true, revision: revisionRef });
+        if (!located) return goneReply();
         found = {
           ...located.record,
           scope: located.scope.key === 'global' ? 'global' : 'project',
@@ -207,15 +254,17 @@ function keepHandler(webServer, cwdForSession) {
         };
       } else if (sessionId) {
         try {
-          found = readCitationBody(sessionId, id);
+          found = id ? readCitationBody(sessionId, id)
+            : readCitationBodyByTitle(sessionId, titleRef, { revision: revisionRef, scope: scopeRef });
         } catch {
           found = null;
         }
         /** 不在本会话引用里就当已消失：不给跨会话探正文，界面也只显示「已删除」。 */
-        if (!found) return sendJson(res, 200, { ok: true, status: 'gone', id });
+        if (!found) return goneReply();
       } else if (cwd) {
-        const located = locate(scopeOf(cwd), id, { readOnly: true });
-        if (!located) return sendJson(res, 200, { ok: true, status: 'gone', id });
+        const located = id ? locate(scopeOf(cwd), id, { readOnly: true })
+          : locateByTitle(scopeOf(cwd), titleRef, { readOnly: true, revision: revisionRef });
+        if (!located) return goneReply();
         found = {
           ...located.record,
           scope: located.scope.key === 'global' ? 'global' : 'project',
@@ -225,7 +274,7 @@ function keepHandler(webServer, cwdForSession) {
       } else {
         return sendJson(res, 400, { ok: false, reason: '缺少来源' });
       }
-      if (!found) return sendJson(res, 200, { ok: true, status: 'gone', id });
+      if (!found) return goneReply();
       /** 面板要分开「当前规范」和旧版本；历史只作可折叠对照，不拼进正文。 */
       const versions = Array.isArray(found.versions) ? found.versions
         : Array.isArray(found.history) ? found.history : [];
@@ -235,7 +284,6 @@ function keepHandler(webServer, cwdForSession) {
         : enums.has(learning.lastStatus) ? learning.lastStatus : '';
       return sendJson(res, 200, {
         ok: true,
-        id: found.id,
         status: found.status,
         title: found.title,
         when: found.when || '',
@@ -253,6 +301,52 @@ function keepHandler(webServer, cwdForSession) {
       });
     }
 
+    /**
+     * 面板改一条普通记忆：只改当前项目里的标题与正文，别层只读。
+     * 必须带读到的版本，写前再对一次；中间被别人改过就拒绝，不覆盖。
+     */
+    if (action === 'entry') {
+      const edit = typeof body.edit === 'string' ? body.edit : '';
+      if (edit && edit !== 'save') return sendJson(res, 400, { ok: false, reason: '不认识这个操作' });
+      const sessionId = typeof body.sessionId === 'string' ? body.sessionId : '';
+      if (!sessionId) return sendJson(res, 400, { ok: false, reason: '缺少 sessionId' });
+      const cwd = typeof cwdForSession === 'function' ? cwdForSession(sessionId) : '';
+      if (!cwd) return sendJson(res, 409, { ok: false, reason: '这个会话还没有项目目录' });
+      const scope = scopeOf(cwd);
+      if (!scope.confirmed) return sendJson(res, 409, { ok: false, reason: '项目根还没确认，先重新打开这个项目' });
+      const scopeKey = typeof body.scopeKey === 'string' ? body.scopeKey : '';
+      if (scopeKey && scopeKey !== scope.key) {
+        return sendJson(res, 409, { ok: false, reason: '别的项目只读，回到那个项目里再改' });
+      }
+      if (!memoryEnabled(scope)) return sendJson(res, 409, { ok: false, code: 'memory_disabled', reason: '本项目记忆已关闭' });
+      const id = typeof body.id === 'string' ? body.id : '';
+      const title = typeof body.title === 'string' ? body.title : '';
+      const text = typeof body.body === 'string' ? body.body : '';
+      const expectedRevision = Number(body.expectedRevision);
+      if (!id) return sendJson(res, 400, { ok: false, reason: '缺少这条记忆' });
+      if (!Number.isInteger(expectedRevision) || expectedRevision < 1) {
+        return sendJson(res, 409, { ok: false, reason: '这条记忆的版本不清楚，先刷新再改' });
+      }
+      if (!title.trim()) return sendJson(res, 400, { ok: false, reason: '标题不能为空' });
+      try {
+        const result = saveEntry(scope, { id, title, body: text, expectedRevision, scope: 'project', source: 'user_explicit' });
+        if (!result || !result.record) {
+          const reason = result && result.reasonCode === 'memory_disabled' ? '本项目记忆已关闭'
+            : result && result.needsResolution ? '改动和另一条太像，先去那条上改'
+              : '这次没有改动';
+          return sendJson(res, 409, { ok: false, reason });
+        }
+        return sendJson(res, 200, { ok: true, title: result.record.title, revision: result.record.revision, changed: result.noop !== true });
+      } catch (error) {
+        const conflict = error && error.code === 'conflict';
+        return sendJson(res, conflict ? 409 : 400, {
+          ok: false,
+          retry: conflict,
+          reason: error instanceof Error ? error.message : '这次没有改动',
+        });
+      }
+    }
+
     /**
      * 面板总览：当前会话项目、可切换的项目层与全局层，都从服务端枚举。
      * 只读；正文不进列表，点开单条再按 scopeKey 取。
@@ -400,7 +494,7 @@ function keepHandler(webServer, cwdForSession) {
         })();
       return sendJson(res, 200, {
         ok: true,
-        current: { key: scope.key, label: labelOf(scope), control: currentControl, evolution: currentEvolution },
+        current: { key: scope.key, label: labelOf(scope), control: currentControl, evolution: currentEvolution, recall: recallReceiptOf(scope, sessionId) },
         scopes,
         selected: {
           key: selectedScope.key,
@@ -575,7 +669,7 @@ function keepHandler(webServer, cwdForSession) {
 
     /** 总开关关闭时面板只能看：保留、拒绝、搬移、撤销都不落盘。 */
     if (!controlStatus(scope).enabled) {
-      return sendJson(res, 409, { ok: false, reason: '本项目记忆已关闭，先在面板打开', code: 'memory_disabled' });
+      return sendJson(res, 409, { ok: false, reason: memoryOffCopy(scope), code: 'memory_disabled' });
     }
 
     if (action === 'move' || action === 'resume-move') {
@@ -596,16 +690,19 @@ function keepHandler(webServer, cwdForSession) {
     }
 
     if (action === 'undo') {
-      if (!id) return sendJson(res, 400, { ok: false, reason: '缺少 id' });
-      if (!locate(scope, id)) return sendJson(res, 404, { ok: false, reason: '没有这条记忆' });
+      const undoTitle = typeof body.title === 'string' ? body.title.trim() : '';
+      if (!id && !undoTitle) return sendJson(res, 400, { ok: false, reason: '缺少标题' });
+      const located = id ? locate(scope, id)
+        : locateByTitle(scope, undoTitle, { revision: Number.isInteger(body.revision) ? body.revision : undefined });
+      if (!located) return sendJson(res, 404, { ok: false, reason: '没有这条记忆' });
       /** 撤销是精确动作：必须带当时看到的版本；缺版本就不猜，免得撤掉别人后来的修改。 */
       if (!Number.isInteger(body.revision) || body.revision < 1) {
         return sendJson(res, 400, { ok: false, reason: '缺少版本' });
       }
       try {
-        const undone = undoChange(scope, id, { expectedRevision: body.revision });
+        const undone = undoChange(scope, located.record.id, { expectedRevision: body.revision });
         if (!undone) return sendJson(res, 404, { ok: false, reason: '没有这条记忆' });
-        return sendJson(res, 200, { ok: true, id: undone.id, mode: undone.mode });
+        return sendJson(res, 200, { ok: true, title: undone.title, revision: undone.revision, mode: undone.mode });
       } catch (error) {
         return sendJson(res, 409, { ok: false, reason: error instanceof Error ? error.message : '撤销失败' });
       }
@@ -635,7 +732,6 @@ function keepHandler(webServer, cwdForSession) {
 /** 给界面的事件引用：只有定位与版次，不带正文，避免把维护字段当内容画出来。 */
 function refsOf(hits) {
   return hits.map((item) => ({
-    id: item.id,
     title: item.title || '',
     scope: item.scope || 'project',
     revision: item.revision || 1,
@@ -652,7 +748,7 @@ function refsOf(hits) {
 const SAVE_PARAMS = {
   type: 'object',
   properties: {
-    id: { type: 'string', description: '要更新的记忆 id（来自搜索结果或相近提示）。同一件事更新时用它，别另建一条' },
+    updateTitle: { type: 'string', description: '要更新的那条记忆的标题（原样抄搜索结果里的标题）。同一件事更新时用它，别另建一条' },
     title: { type: 'string', description: `标题：名词短语，用户一眼能认出是哪件事，不超过 ${LIMITS.titleChars} 字。它就是这条记忆的身份` },
     summary: { type: 'string', description: `一句话说清要记的内容本身——用户只看这一行决定留不留，名词短语最好，超长会自动截到这个长度` },
     body: { type: 'string', description: `正文 markdown，整段替换旧正文，不超过 ${LIMITS.entryBytes} 字节。只写原则、判断规则、触发条件和边界；不写一次性数字或代码片段，这些查当前代码或文档。` },
@@ -661,7 +757,7 @@ const SAVE_PARAMS = {
     tags: { type: 'array', items: { type: 'string' }, description: '最多 5 个标签；更新时不给就保留原值' },
     supersedes: {
       type: 'string',
-      description: '要取代的记忆 id：新内容写成新条目，旧条目标为已被取代并保留在历史里；同层才有效，已被取代过的不能再取代',
+      description: '要取代的那条记忆的标题（原样抄搜索结果里的标题）：新内容写成新条目，旧条目标为已被取代并保留在历史里；同层才有效，已被取代过的不能再取代',
     },
     resolution: {
       type: 'string',
@@ -674,13 +770,12 @@ const SAVE_PARAMS = {
     evidenceRef: { type: 'string', description: '归属判定的依据（哪条消息、哪个文件、哪次观察）；用户没说范围时用来判断能不能存' },
     sameTopicAs: {
       type: 'object',
-      description: '显式绑定到已有主题槽位：{scope, id, revision}。版本不符或目标不存在就报错，不写',
+      description: '显式绑定到已有主题槽位：{scope, title}。标题对不上就报错，不写',
       properties: {
         scope: { type: 'string', enum: ['project', 'global'] },
-        id: { type: 'string' },
-        revision: { type: 'integer' },
+        title: { type: 'string' },
       },
-      required: ['scope', 'id', 'revision'],
+      required: ['scope', 'title'],
       additionalProperties: false,
     },
     mode: {
@@ -724,9 +819,9 @@ const SAVE_PARAMS = {
         type: 'object',
         properties: {
           type: { type: 'string', enum: view.LINK_TYPES, description: '默认 related' },
-          id: { type: 'string', pattern: '^mem_[a-z0-9]{6,}$' },
+          title: { type: 'string', description: '被关联那条记忆的标题（原样抄搜索结果里的标题）' },
         },
-        required: ['id'],
+        required: ['title'],
         additionalProperties: false,
       },
     },
@@ -743,7 +838,7 @@ const SAVE_PARAMS = {
 
 const SUGGEST_PARAMS = {
   ...SAVE_PARAMS,
-  properties: Object.fromEntries(Object.entries(SAVE_PARAMS.properties).filter(([key]) => !['scope', 'id', 'resolution', 'memoryClass', 'durability', 'evidenceRef', 'sameTopicAs'].includes(key))),
+  properties: Object.fromEntries(Object.entries(SAVE_PARAMS.properties).filter(([key]) => !['scope', 'id', 'updateTitle', 'resolution', 'memoryClass', 'durability', 'evidenceRef', 'sameTopicAs'].includes(key))),
 };
 
 const SEARCH_PARAMS = {
@@ -762,28 +857,69 @@ const SEARCH_PARAMS = {
 const READ_PARAMS = {
   type: 'object',
   properties: {
-    id: { type: 'string', description: '记忆 id，来自搜索结果' },
+    title: { type: 'string', description: '记忆标题，来自搜索结果或召回卡' },
     view: { type: 'string', enum: ['full', 'links'], description: '默认 full 读正文；links 只看直接相关的记忆清单，不取正文' },
+    scope: { type: 'string', enum: ['project', 'global'], description: '只在指定层解析标题；默认先当前项目再全局' },
     contextId: { type: 'string', description: '上一轮自动索引或工具结果给出的任务上下文 id；读实验规则时带上' },
   },
-  required: ['id'],
   additionalProperties: false,
 };
 
 const FORGET_PARAMS = {
   type: 'object',
   properties: {
-    id: { type: 'string', description: '要忘掉的记忆 id' },
+    title: { type: 'string', description: '要忘掉的那条记忆的标题' },
+    scope: { type: 'string', enum: ['project', 'global'], description: '只在指定层解析标题；默认先当前项目再全局' },
     mode: {
       type: 'string',
       enum: ['archive', 'purge'],
       description: 'archive 移入归档可找回（只是不想再提）；purge 彻底忘掉，正文与受管副本清除且不可复活。没点明是哪种就两种都别做，先问用户',
     },
   },
-  required: ['id'],
   additionalProperties: false,
 };
 
+/** 对外只认标题：id 留作内部地址，模型和界面都不用碰。 */
+function refIdOf(scope, args, label = '记忆') {
+  const id = typeof args.id === 'string' ? args.id.trim() : '';
+  if (id) return id;
+  const title = typeof args.title === 'string' ? args.title.trim() : '';
+  if (!title) throw new Error(`要读或要忘一条${label}，先给标题`);
+  /** 显式指定层时只解析那一层：同名条目不会被顺手改掉，项目层也不会命中全局。 */
+  const explicit = args && args.scope === 'global' ? globalScope() : args && args.scope === 'project' ? scope : null;
+  const sources = explicit ? [explicit] : runtimeLayers(scope);
+  /** 运行时只解析当前项目与全局：别的项目正文不进本会话。 */
+  for (const target of sources) {
+    let index;
+    try { index = loadIndex(target); } catch { continue; }
+    const hit = (index.entries || []).find((entry) => entry && entry.status !== 'archived'
+      && String(entry.title || '').trim() === title);
+    if (hit) return hit.id;
+  }
+  /** 忘掉已归档的条目也要能按标题解析到；归档不会因此重新参与召回。 */
+  for (const target of sources) {
+    let index;
+    try { index = loadIndex(target); } catch { continue; }
+    const hit = (index.archived || []).find((entry) => entry
+      && String(entry.title || '').trim() === title);
+    if (hit) return hit.id;
+  }
+  throw new Error(`没有「${title}」这条记忆；先用 memory_search 对一下标题`);
+}
+
+/** 同名条目可能分布在项目层和全局层：更新前先报候选，不能先匹配。 */
+function titleCandidates(scope, title) {
+  const out = [];
+  for (const target of runtimeLayers(scope)) {
+    let index;
+    try { index = loadIndex(target); } catch { continue; }
+    const hit = (index.entries || []).find((entry) => entry && entry.status !== 'archived'
+      && String(entry.title || '').trim() === title);
+    if (hit) out.push({ id: hit.id, scope: target.key === 'global' ? 'global' : 'project' });
+  }
+  return out;
+}
+
 /** 记忆归属标记：全局 `[global]`，项目用项目目录名（如 `[DSH]`）。 */
 function projectNameOf(scope) {
   const base = scope && scope.cwd ? path.basename(scope.cwd) : '';
@@ -816,7 +952,7 @@ function humanAge(iso) {
 function describeCandidate(item, options = {}) {
   const age = humanAge(item.updated);
   const why = options.sameTopic ? '' : item.reason === 'similar_summary' ? '摘要相近' : '标题相近';
-  const parts = [`${item.id}「${item.title}」`];
+  const parts = [`「${item.title}」`];
   if (age) parts.push(`${age}更新`);
   if (item.when) parts.push(item.when);
   if (why) parts.push(why);
@@ -840,12 +976,12 @@ function statusLabel(status) {
 export const RECALL_MODES = ['adaptive', 'tool_only', 'off'];
 const RECALL_QUERY_CHARS = 400;
 const RECALL_DEADLINE_MS = 150;
-const RECALL_HEADER = '已有记忆可能相关（需要细节用 memory_read 取正文，别凭标题猜）：';
+const RECALL_HEADER = '已有记忆可能相关（需要细节用 memory_read 带标题取正文，别凭标题猜）：';
 
 /** 卡片只放够判断要不要读的几行；必要前提整条在场，装不下就整卡省略。 */
 function renderRecallCard(card) {
   const tag = card.scope === 'global' ? '[global]' : card.scopeName ? `[${card.scopeName}]` : '';
-  const parts = [`- ${tag ? `${tag} ` : ''}「${card.title}」 · ${card.id}`];
+  const parts = [`- ${tag ? `${tag} ` : ''}「${card.title}」`];
   if (card.summary) parts.push(`｜${card.summary}`);
   if (card.conditions && card.conditions.length) parts.push(`｜前提：${card.conditions.join('、')}`);
   if (card.selection) parts.push(`｜只适用于 ${card.selection}`);
@@ -936,6 +1072,17 @@ export function apply(ctx, config) {
     return win.bytes + bytes <= view.REQUEST_BYTES;
   }
 
+  /**
+   * 工具自己取的记忆另算一笔：自动注入已经用满时，模型按标题来读正文不该被连带挡掉，
+   * 否则用户看到的就是「额度已用完」这种没法处理的死路。
+   */
+  function affordableTool(win, bytes, bodies = 0) {
+    if (!win) return true;
+    if (win.reads >= view.REQUEST_LIMITS.reads) return false;
+    if (bodies && win.bodies + bodies > view.REQUEST_LIMITS.bodies) return false;
+    return (win.toolBytes || 0) + bytes <= view.TOOL_BYTES;
+  }
+
   /** 续写轮没有新消息：沿用上一次能核对的请求上下文。 */
   const lastRuntime = new Map();
   const rememberRuntime = (scope, sessionId, held) => {
@@ -954,7 +1101,7 @@ export function apply(ctx, config) {
     if (existing && existing.signature === signature) return existing;
     const next = {
       signature, sessionId, turn, messageIds,
-      bytes: 0, bodies: 0, reads: 0,
+      bytes: 0, bodies: 0, reads: 0, toolBytes: 0,
       provided: new Map(), readBodies: new Map(), at: Date.now(),
       experiment: null, contexts: new Map(), runtime: null, autoBudget: null,
     };
@@ -1025,17 +1172,18 @@ export function apply(ctx, config) {
       }
     }
     /** 同一槽位只让胜出的规范进去；冲突或条件未知的整组不进自动召回。 */
+    const groups = [...view.resolveTopics(layers.project, layers.global, context).values()];
     const records = [];
     const layerOf = new Map();
-    for (const group of view.resolveTopics(layers.project, layers.global, context).values()) {
+    for (const group of groups) {
       if (group.status !== 'ok' || !group.record) continue;
       records.push(group.record);
       layerOf.set(group.record.id, group.scope === 'global' ? 'global' : 'project');
     }
+    const gateRuntime = runtime || (win && win.runtime) || null;
+    const task = runtime && runtime.task ? runtime.task : null;
     const ranked = view.rank(records, query, {
-      limit: 8, requireApplicable: true, context,
-      runtime: runtime || (win && win.runtime) || null,
-      task: runtime && runtime.task ? runtime.task : null,
+      limit: 8, requireApplicable: true, context, runtime: gateRuntime, task,
     });
     /** 普通记忆与实验规则共用一份自动注入预算：总条数和最终完整文本字节一起算。 */
     const auto = win && win.autoBudget ? win.autoBudget : null;
@@ -1073,7 +1221,7 @@ export function apply(ctx, config) {
         win.recallHeader = true;
       }
       lines.push(line);
-      cards.push({ id: card.id, revision, scope: card.scope, title: card.title });
+      cards.push({ revision, scope: card.scope, title: card.title });
     }
     const finalText = `${RECALL_HEADER}\n${lines.join('\n')}`;
     if (auto) {
@@ -1085,8 +1233,35 @@ export function apply(ctx, config) {
         experimentCards: auto.experimentCards || 0,
       });
     }
-    if (!cards.length) return null;
-    return { text: finalText, cards, bytes: Buffer.byteLength(finalText), query };
+    /** 没卡片也要给出判断依据：面板要能回答「为什么这次没提醒我」。 */
+    let near = [];
+    if (!cards.length && !ranked.length) {
+      /** 自动召回只认完全适用；再放宽一层看有没有字面匹配，好把「条件未确认」和「没有匹配」分开。 */
+      near = view.rank(records, query, {
+        limit: 8, requireApplicable: false, context, runtime: gateRuntime, task,
+      });
+    }
+    let waiting = near.some((row) => row.status !== 'ok' || row.record.reviewState === 'legacy_unreviewed');
+    let nearMatched = near.length;
+    if (!cards.length && !ranked.length) {
+      /** 整组被条件或冲突挡下的候选没进 records，单独按同一查询算；只计数，不投放。 */
+      for (const group of groups) {
+        if (group.status !== 'conflict' && group.status !== 'needs_context') continue;
+        const hits = view.rank(group.records || [], query, {
+          limit: 1, requireApplicable: false, context, runtime: gateRuntime, task,
+        });
+        if (!hits.length) continue;
+        waiting = true;
+        nearMatched += hits.length;
+      }
+    }
+    const reason = cards.length ? 'hit'
+      : ranked.length ? 'budget'
+        : waiting ? 'needs_context'
+          : (gateRuntime && gateRuntime.enabled ? 'no_overlap' : 'needs_context');
+    const matched = ranked.length || nearMatched;
+    if (!cards.length) return { text: '', cards: [], bytes: 0, query, reason, matched };
+    return { text: finalText, cards, bytes: Buffer.byteLength(finalText), query, reason, matched };
   }
 
   /* ---------------- 项目自进化：任务锚点、读取决策、上下文解析 ---------------- */
@@ -1296,8 +1471,8 @@ export function apply(ctx, config) {
         ? `；核对：${String(checkpoint.text).slice(0, 40)}`
         : '';
       const line = short
-        ? `- 「${record.title}」${conditions ? `（${conditions}）` : ''} · ${record.id}：${body}${check}`
-        : `- 「${record.title}」 · ${record.id}（用途：${record.summary || record.title}；要用时 memory_read 取正文）`;
+        ? `- 「${record.title}」${conditions ? `（${conditions}）` : ''}：${body}${check}`
+        : `- 「${record.title}」（用途：${record.summary || record.title}；要用时 memory_read 带标题取正文）`;
       const size = Buffer.byteLength(`\n${line}`);
       if (used + size > autoCap) break;
       used += size;
@@ -1586,26 +1761,24 @@ export function apply(ctx, config) {
 
   ctx.effect(() => tools.register({
     name: 'memory_save',
-    description: `保存一条记忆。只在会改变以后判断时才存；先搜已有条目，能更新就不要新建。保存前先蒸馏：标题是结论，正文只写原则与触发条件，通常 2–4 句；路径、字段表、完整命令、版本号、尺寸数值不要抄进正文，改成文档或 skill 的指针。用户明确说「记住」时直接调用；用户自己的话已经是长期规则（「以后都这样」「别再 X」）时也直接调用，不要先问。更新同一件事时带 id：身份只看标题、旧标题和前置条件，像不像不授权覆盖。文本相近但标题不同时先不写，返回 needsResolution 与 1–2 条相近条目：确实是同一条就用那个 id 更新，确实是另一条才带 resolution="distinct" 再存。带 id 更新时没给的字段保持原值，正文整段替换，旧正文只留作内部撤回，不展示也不参与检索。条数到硬上限时把同层最久没被读的一条移进归档，结果里写明动了哪条，不拒绝新记忆；单条正文超限只报错、不截断。前置条件不同的同一标题是两条。${NOTES}`,
+    description: `保存一条记忆。只在会改变以后判断时才存；先搜已有条目，能更新就不要新建。保存前先蒸馏：标题是结论，正文只写原则与触发条件，通常 2–4 句；路径、字段表、完整命令、版本号、尺寸数值不要抄进正文，改成文档或 skill 的指针。用户明确说「记住」时直接调用；用户自己的话已经是长期规则（「以后都这样」「别再 X」）时也直接调用，不要先问。更新同一件事时用同一个标题：身份只看标题、旧标题和前置条件，像不像不授权覆盖。文本相近但标题不同时先不写，返回 needsResolution 与 1–2 条相近条目：确实是同一条就改成那个标题重存，确实是另一条才带 resolution="distinct" 再存。按标题更新时没给的字段保持原值，正文整段替换，旧正文只留作内部撤回，不展示也不参与检索。条数到硬上限时把同层最久没被读的一条移进归档，结果里写明动了哪条，不拒绝新记忆；单条正文超限只报错、不截断。前置条件不同的同一标题是两条。${NOTES}`,
     parameters: SAVE_PARAMS,
     output: {
       presentationMeta: (_args, value) => ({
         kind: 'memory-save',
-        id: value.id || '',
         title: value.title || '',
         scope: value.scope || '',
         revision: value.revision || 0,
         changed: value.changed === true,
         recordKind: typeof value.kind === 'string' && value.kind ? value.kind : '',
         mode: value.needsScope ? 'needs_scope'
-          : value.existingId ? 'duplicate'
+          : value.existingTitle ? 'duplicate'
             : value.needsResolution ? 'needs_resolution'
               : value.changed === false ? 'unchanged' : value.merged ? 'updated' : 'created',
       }),
       schema: {
         type: 'object',
         properties: {
-          id: { type: 'string' },
           title: { type: 'string' },
           summary: { type: 'string' },
           when: { type: 'string' },
@@ -1620,34 +1793,35 @@ export function apply(ctx, config) {
           needsResolution: { type: 'boolean' },
           needsScope: { type: 'boolean' },
           reason: { type: 'string' },
-          existingId: { type: 'string' },
+          existingTitle: { type: 'string' },
           existingScope: { type: 'string' },
           crossLayer: { type: 'boolean' },
+          crossScope: { type: 'string', enum: ['global', 'project'] },
           sameTopic: { type: 'boolean' },
-          similarIds: { type: 'string' },
+          similarTitles: { type: 'string' },
           similar: { type: 'string' },
-          supersededId: { type: 'string' },
+          supersededTitle: { type: 'string' },
           archived: { type: 'string' },
           pendingConflicts: { type: 'integer' },
         },
-        required: ['id', 'title', 'summary', 'when', 'revision', 'merged', 'changed', 'scope', 'needsResolution', 'archived'],
+        required: ['title', 'summary', 'when', 'revision', 'merged', 'changed', 'scope', 'needsResolution', 'archived'],
         additionalProperties: false,
       },
       render: (_args, value) => [{
         type: 'text',
         text: value.needsScope
           ? value.reason === 'memory_disabled'
-            ? 'memory · 本项目记忆已关闭，先在面板打开'
+            ? `memory · ${memoryOffCopy(projectScope)}`
             : value.reason === 'unconfirmed_project'
             ? `memory · 当前目录还不能确认属于哪个项目：「${value.title}」\n先确认项目根目录，或显式 scope="global"`
             : `memory · 归属还没定：「${value.title}」\n补 memoryClass（personal_preference / project_fact / environment_fact / portable_procedure）或显式 scope；设备事实还要给设备条件`
-          : value.existingId
+          : value.existingTitle
             ? `memory · 已有相同记忆：「${value.title}」（${value.existingScope}）\n要改成另一条，加 resolution="distinct"`
             : value.needsResolution
-          ? `memory · 需要确认：「${value.title}」与已有条目相近${value.crossLayer ? '（在另一层）' : ''}${value.sameTopic ? '（同一主题槽位）' : ''}\n${value.similar}\n要更新它，用 id 重存；确实是另一条，加 resolution="distinct"`
+          ? `memory · 需要确认：「${value.title}」与已有条目相近${value.crossLayer ? '（在另一层）' : ''}${value.sameTopic ? '（同一主题槽位）' : ''}\n${value.similar}\n要更新它：用同一个标题${value.crossScope === 'global' ? '、并带 scope="global"' : ''}再存一次；确实是另一条，加 resolution="distinct"`
           : value.changed === false
             ? `memory · unchanged ${withTag(value, `"${value.title}"`)}`
-            : `memory · ${value.merged ? 'merged' : 'saved'} ${withTag(value, `"${value.title}"`)}${value.when ? `（${value.when}）` : ''}${value.similar ? ` · 相近：${value.similar}` : ''}${value.archived ? ` · 已归档「${value.archived}」腾位` : ''}${value.fullTextSaved ? ' · 完整原句已另存' : ''}${value.supersededId ? ' · 已取代旧说法' : ''}`,
+            : `memory · ${value.merged ? 'merged' : 'saved'} ${withTag(value, `"${value.title}"`)}${value.when ? `（${value.when}）` : ''}${value.similar ? ` · 相近：${value.similar}` : ''}${value.archived ? ` · 已归档「${value.archived}」腾位` : ''}${value.fullTextSaved ? ' · 完整原句已另存' : ''}${value.supersededTitle ? ` · 已取代「${value.supersededTitle}」` : ''}`,
       }],
     },
     execute: async (args, execution) => {
@@ -1655,15 +1829,44 @@ export function apply(ctx, config) {
       const projectScopeName = projectNameOf(projectScope);
       if (!memoryEnabled(projectScope)) {
         return {
-          id: '', title: String(args.title || ''), summary: '', when: '', revision: 0,
+          title: String(args.title || ''), summary: '', when: '', revision: 0,
           merged: false, changed: false, scope: '', needsScope: true, reason: 'memory_disabled',
-          needsResolution: false, similarIds: '', similar: '', archived: '',
+          recoveryPending: controlStatus(projectScope).recoveryPending,
+          needsResolution: false, similarTitles: '', similar: '', archived: '',
         };
       }
-      const saved = saveEntry(projectScope, { ...args, writeMode: args.mode || 'patch' });
+      const supersedes = String(args.supersedes || '').trim();
+      const supersedesId = supersedes && !/^mem_[a-z0-9]+$/.test(supersedes)
+        ? (() => { try { return refIdOf(projectScope, { title: supersedes }, '记忆'); } catch { return ''; } })()
+        : supersedes;
+      const draft = { ...args, writeMode: args.mode || 'patch' };
+      if (supersedes) { if (supersedesId) draft.supersedes = supersedesId; else delete draft.supersedes; }
+      /** 更新句柄也用标题：id 只是底层实现，模型抄标题就行。 */
+      const updateTitle = String(args.updateTitle || '').trim();
+      if (updateTitle) {
+        const candidates = args.scope ? [] : titleCandidates(projectScope, updateTitle);
+        if (candidates.length > 1) {
+          return { error: `memory · 「${updateTitle}」在项目层和全局层各有一条：改全局加 scope="global"，改项目加 scope="project"` };
+        }
+        const updateId = (() => { try { return refIdOf(projectScope, { title: updateTitle, scope: args.scope }, '记忆'); } catch { return ''; } })();
+        if (!updateId) return { error: `memory · 没有「${updateTitle}」这条记忆；要新增就不用 updateTitle` };
+        draft.id = updateId;
+      }
+      /** 关联目标同样按标题解析成内部 id 再落盘。 */
+      if (Array.isArray(args.links) && args.links.length) {
+        const resolved = [];
+        for (const link of args.links) {
+          const title = typeof link?.title === 'string' ? link.title.trim() : '';
+          if (!title) return { error: 'memory · 关联要写成 {type, title}：给被关联那条记忆的标题' };
+          const targetId = (() => { try { return refIdOf(projectScope, { title }, '记忆'); } catch { return ''; } })();
+          if (!targetId) return { error: `memory · 没有「${title}」这条记忆，关联没写成` };
+          resolved.push({ type: link.type || 'related', id: targetId });
+        }
+        draft.links = resolved;
+      }
+      const saved = saveEntry(projectScope, draft);
       if (saved.needsScope) {
         return {
-          id: '',
           title: saved.draft?.title || '',
           summary: saved.draft?.summary || '',
           when: saved.draft?.when || '',
@@ -1674,14 +1877,13 @@ export function apply(ctx, config) {
           needsScope: true,
           reason: saved.reasonCode,
           needsResolution: false,
-          similarIds: '',
+          similarTitles: '',
           similar: '',
           archived: '',
         };
       }
       if (saved.existing) {
         return {
-          id: saved.existing.id,
           title: saved.existing.title || saved.draft?.title || '',
           summary: '',
           when: '',
@@ -1691,10 +1893,10 @@ export function apply(ctx, config) {
           scope: saved.existing.scope,
           scopeName: saved.existing.scope === 'global' ? '' : projectScopeName,
           needsScope: false,
-          existingId: saved.existing.id,
+          existingTitle: saved.existing.title || saved.draft?.title || '',
           existingScope: saved.existing.scope,
           needsResolution: false,
-          similarIds: '',
+          similarTitles: '',
           similar: '',
           archived: '',
         };
@@ -1702,7 +1904,6 @@ export function apply(ctx, config) {
       const scope = saved.chosenScope === 'global' || (args.scope === 'global' && !saved.chosenScope) ? globalScope() : projectScope;
       if (saved.needsResolution) {
         return {
-          id: '',
           title: saved.draft.title,
           summary: saved.draft.summary,
           when: saved.draft.when,
@@ -1713,8 +1914,9 @@ export function apply(ctx, config) {
           needsScope: false,
           needsResolution: true,
           crossLayer: Boolean(saved.crossLayer),
+          crossScope: saved.crossScope === 'global' ? 'global' : 'project',
           sameTopic: Boolean(saved.sameTopic),
-          similarIds: saved.similarList.map((item) => item.id).join('、'),
+          similarTitles: saved.similarList.map((item) => item.title).join('、'),
           similar: saved.similarList.map((item) => describeCandidate(item, { sameTopic: saved.sameTopic })).join('；'),
           archived: '',
           pendingConflicts: Number(saved.pendingConflicts) || 0,
@@ -1722,7 +1924,6 @@ export function apply(ctx, config) {
       }
       recordCitations(scope, sessionIdOf(execution), [saved.record]);
       return {
-        id: saved.record.id,
         title: saved.record.title,
         summary: saved.record.summary,
         when: saved.record.when || '',
@@ -1736,8 +1937,8 @@ export function apply(ctx, config) {
         scopeName: scope.key === 'global' ? '' : projectScopeName,
         needsScope: false,
         needsResolution: false,
-        similarIds: saved.similarList.map((item) => item.id).join('、'),
-        supersededId: String(args.supersedes || ''),
+        similarTitles: saved.similarList.map((item) => item.title).join('、'),
+        supersededTitle: supersedes && supersedesId ? supersedes : '',
         archived: (saved.archived || []).map((item) => item.title).join('、'),
         pendingConflicts: Number(saved.pendingConflicts) || 0,
         ...(saved.similar ? { similar: `「${saved.similar.title}」` } : {}),
@@ -1758,7 +1959,6 @@ export function apply(ctx, config) {
           title: { type: 'string' },
           id: { type: 'string' },
           reason: { type: 'string' },
-          targetId: { type: 'string' },
           targetTitle: { type: 'string' },
         },
         required: ['asked'],
@@ -1767,7 +1967,7 @@ export function apply(ctx, config) {
       render: (_args, value) => [{
         type: 'text',
         text: value.asked
-          ? `memory · suggested "${value.title}"${value.targetId ? ` · 确认后更新「${value.targetTitle}」` : ''}`
+          ? `memory · suggested "${value.title}"${value.targetTitle ? ` · 确认后更新「${value.targetTitle}」` : ''}`
           : `memory · skipped${value.reason ? `\n${value.reason}` : ''}`,
       }],
     },
@@ -1781,14 +1981,14 @@ export function apply(ctx, config) {
         asked: true,
         title: noted.title,
         id: noted.id,
-        ...(noted.targetId ? { targetId: noted.targetId, targetTitle: noted.targetTitle } : {}),
+        ...(noted.targetTitle ? { targetTitle: noted.targetTitle } : {}),
       };
     },
   }), 'lite-memory: memory_suggest');
 
   ctx.effect(() => tools.register({
     name: 'memory_search',
-    description: `按需检索已有记忆：先搜，命中再 memory_read 读正文。用户提到「记住了什么 / 上次 / 规范 / 约定 / 路径 / 凭据怎么取」，或者眼前反复出现的报错、弹窗、异常时，先查这里有没有记过解法。跨项目的通用条目以 [global] 开头，项目条目以 [项目名] 开头。中文长句可以直接当查询。每行带 id，更新时把 id 传回 memory_save。默认只列当前有效的；已经归档或被更新替换的旧说法不混进来，要查历史就在参数里显式要 history。`,
+    description: `按需检索已有记忆：先搜，命中再 memory_read 读正文。用户提到「记住了什么 / 上次 / 规范 / 约定 / 路径 / 凭据怎么取」，或者眼前反复出现的报错、弹窗、异常时，先查这里有没有记过解法。跨项目的通用条目以 [global] 开头，项目条目以 [项目名] 开头。中文长句可以直接当查询。每行给标题与适用范围；要更新就用那个标题重存。默认只列当前有效的；已经归档或被更新替换的旧说法不混进来，要查历史就在参数里显式要 history。`,
     parameters: SEARCH_PARAMS,
     output: {
       presentationMeta: (_args, value) => ({
@@ -1809,7 +2009,6 @@ export function apply(ctx, config) {
             items: {
               type: 'object',
               properties: {
-                id: { type: 'string' },
                 title: { type: 'string' },
                 scope: { type: 'string' },
                 revision: { type: 'integer' },
@@ -1819,7 +2018,7 @@ export function apply(ctx, config) {
                 when: { type: 'string' },
                 updated: { type: 'string' }, // ui-copy-ignore
               },
-              required: ['id', 'title', 'scope', 'revision', 'status', 'origin', 'kind', 'when'],
+              required: ['title', 'scope', 'revision', 'status', 'origin', 'kind', 'when'],
               additionalProperties: false,
             },
           },
@@ -1830,7 +2029,7 @@ export function apply(ctx, config) {
       render: (_args, value) => [{
         type: 'text',
         text: value.status === 'budget_exhausted'
-          ? 'memory · 本请求的记忆额度已用完'
+          ? 'memory · 这条消息已停止检索，下一条消息再查'
           : value.status === 'memory_disabled'
             ? 'memory · 记忆检索已关闭'
             : value.status === 'needs_context'
@@ -1844,7 +2043,7 @@ export function apply(ctx, config) {
       if (recallMode() === 'off' || !memoryEnabledFor(execution)) return { count: 0, chars: 0, text: '', status: 'memory_disabled', refs: [] };
       const agent = execution?.agent;
       const win = windowOf(agent);
-      if (win && !affordable(win, 0)) return { count: 0, chars: 0, text: '', status: 'budget_exhausted', refs: [] };
+      if (win && !affordableTool(win, 0)) return { count: 0, chars: 0, text: '', status: 'budget_exhausted', refs: [] };
       const wantsBind = args.bindForRequest === true;
       const contextId = wantsBind && !args.contextId ? toolContextFor(execution) : args.contextId;
       if (wantsBind && !contextId) {
@@ -1895,8 +2094,9 @@ export function apply(ctx, config) {
         };
         if (win) {
           const bytes = jsonBytes(value);
-          if (!affordable(win, bytes)) return { ...value, status: 'budget_exhausted', text: '' };
+          if (!affordableTool(win, bytes)) return { ...value, status: 'budget_exhausted', text: '' };
           win.bytes += bytes;
+          win.toolBytes += bytes;
           win.reads += 1;
         }
         return value;
@@ -1906,18 +2106,20 @@ export function apply(ctx, config) {
         const empty = { count: 0, chars: 0, text: '', status: 'ok', reasonCode: 'no_match', noTriggerReason: '没有匹配的记忆', refs: [] };
         if (win) {
           const bytes = jsonBytes(empty);
-          if (!affordable(win, bytes)) return { ...empty, status: 'budget_exhausted' };
+          if (!affordableTool(win, bytes)) return { ...empty, status: 'budget_exhausted' };
           win.bytes += bytes;
+          win.toolBytes += bytes;
           win.reads += 1;
         }
         return empty;
       }
       if (win) {
         let kept = shown.length;
-        while (kept > 0 && !affordable(win, jsonBytes(valueOf(kept)))) kept -= 1;
+        while (kept > 0 && !affordableTool(win, jsonBytes(valueOf(kept)))) kept -= 1;
         if (kept === 0) return { count: 0, chars: 0, text: '', status: 'budget_exhausted', refs: [] };
         const value = valueOf(kept);
         win.bytes += jsonBytes(value);
+        win.toolBytes += jsonBytes(value);
         win.reads += 1;
         recordCitations(scope, sessionIdOf(execution), hits.slice(0, kept));
         return value;
@@ -1930,13 +2132,12 @@ export function apply(ctx, config) {
 
   ctx.effect(() => tools.register({
     name: 'memory_read',
-    description: '读一条记忆的正文。搜索结果里只有一行摘要，需要细节时按 id 读。索引里还有、正文文件丢了会直接报错，不会返回空正文。',
+    description: '读一条记忆的正文。搜索结果里只有一行摘要，需要细节时按标题读。索引里还有、正文文件丢了会直接报错，不会返回空正文。',
     parameters: READ_PARAMS,
     output: {
       schema: {
         type: 'object',
         properties: {
-          id: { type: 'string' },
           title: { type: 'string' },
           when: { type: 'string' },
           revision: { type: 'integer' },
@@ -1949,13 +2150,13 @@ export function apply(ctx, config) {
           links: { type: 'string' },
           repeat: { type: 'boolean' },
         },
-        required: ['id', 'scope', 'status'],
+        required: ['scope', 'status'],
         additionalProperties: false,
       },
       render: (_args, value) => [{
         type: 'text',
         text: value.status === 'budget_exhausted'
-          ? 'memory · 本请求的记忆额度已用完'
+          ? 'memory · 这条消息已停止读记忆，下一条消息再读'
           : value.status === 'memory_disabled'
             ? 'memory · 记忆检索已关闭'
             : value.repeat
@@ -1976,7 +2177,6 @@ export function apply(ctx, config) {
       }],
       presentationMeta: (_args, value) => ({
         kind: 'memory-read',
-        id: value.id || '',
         title: value.title || '',
         scope: value.scope || '',
         revision: value.revision || 0,
@@ -1986,11 +2186,13 @@ export function apply(ctx, config) {
       }),
     },
     execute: async (args, execution) => {
-      if (recallMode() === 'off' || !memoryEnabledFor(execution)) return { id: '', scope: '', status: 'memory_disabled' };
+      if (recallMode() === 'off' || !memoryEnabledFor(execution)) return { scope: '', status: 'memory_disabled' };
       const resolved = resolveRequestContext(execution, args.contextId);
-      if (!resolved.ok) return { id: '', scope: '', status: resolved.status || 'needs_context' };
+      if (!resolved.ok) return { scope: '', status: resolved.status || 'needs_context' };
       const scope = resolved.scope;
       const scopeName = scope.key === 'global' ? '' : projectNameOf(scope);
+      /** 明确指定层时只在那一层解析标题，同名条目不会串到别的层。 */
+      const readScope = args.scope === 'global' ? globalScope() : scope;
       const context = resolved.context;
       const allowExperimental = resolved.experimental === true;
       const agent = execution?.agent;
@@ -1998,48 +2200,57 @@ export function apply(ctx, config) {
       const gateRuntime = resolved.held || win?.runtime
         || { projectId: scope.key, context, experimental: resolved.experimental === true };
       if (args.view === 'links') {
-        const source = locate(scope, args.id);
-        if (source && !view.eligibility(source.record, gateRuntime, 'read').ok) {
-          return { id: '', scope: '', status: 'needs_context', links: '' };
-        }
-        const found = readLinks(scope, args.id, { context, allowExperimental, runtime: gateRuntime, now: Date.now() });
-        if (!found) throw new Error(`没有 ${args.id} 这条记忆`);
+        const refId = refIdOf(readScope, args);
+        const source = locate(readScope, refId);
+        const gateOk = !source || view.eligibility(source.record, gateRuntime, 'read').ok;
+        if (!gateOk) return { scope: '', status: 'needs_context', links: '' };
+        const found = readLinks(readScope, refId, { context, allowExperimental, runtime: gateRuntime, now: Date.now() });
+        if (!found) throw new Error(`没有「${String(args.title || args.id || '').trim()}」这条记忆`);
         if (found.status !== 'ok') {
-          const withheld = { id: '', scope: '', status: found.status, links: '' };
+          const withheld = { scope: '', status: found.status, links: '' };
           if (win) {
             const bytes = jsonBytes(withheld);
-            if (!affordable(win, bytes)) return { id: '', scope: '', status: 'budget_exhausted' };
+            if (!affordableTool(win, bytes)) return { scope: '', status: 'budget_exhausted' };
             win.bytes += bytes;
+            win.toolBytes += bytes;
             win.reads += 1;
           }
           return withheld;
         }
         const rows = found.links.filter((link) => link.status === 'invalid' || link.status === 'ok')
           .map((link) => (link.status === 'invalid'
-          ? `- ${link.id} · 已失效`
-          : `- ${link.scope === 'global' ? '[global] ' : (scopeName ? `[${scopeName}] ` : '')}「${link.title}」 · ${link.id}`));
+          ? '- 有一条已失效'
+          : `- ${link.scope === 'global' ? '[global] ' : (scopeName ? `[${scopeName}] ` : '')}「${link.title}」`));
         const text = rows.join('\n') || '(无)';
-        const value = { id: found.id, scope: found.scope, scopeName, status: found.status, links: text };
+        const value = { scope: found.scope, scopeName, status: found.status, links: text };
         if (win) {
           const bytes = jsonBytes(value);
-          if (!affordable(win, bytes)) return { id: '', scope: '', status: 'budget_exhausted' };
+          if (!affordableTool(win, bytes)) return { scope: '', status: 'budget_exhausted' };
           win.bytes += bytes;
+          win.toolBytes += bytes;
           win.reads += 1;
         }
         return value;
       }
-      const record = readEntry(scope, args.id, { context, allowExperimental });
-      if (!record) throw new Error(`没有 ${args.id} 这条记忆`);
+      const record = readEntry(readScope, refIdOf(readScope, args), {
+        layers: args.scope ? [readScope] : undefined,
+        context,
+        allowExperimental,
+        /** 只有真正把正文交出去的读取才算用过：条件未知/被取代/过期不更新使用记录。 */
+        usage: (item) => view.eligibility(item, gateRuntime, 'read').ok,
+      });
+      if (!record) throw new Error(`没有「${String(args.title || args.id || '').trim()}」这条记忆`);
+      /** 归档条目还能按标题找到：只回状态，不交正文，也不把它当成「不存在」。 */
+      if (record.status === 'archived') return { title: record.title, scope: record.scope, status: 'archived', body: '' };
       const gate = view.eligibility(record, gateRuntime, 'read');
-      if (!gate.ok) return { id: '', scope: record.scope, status: gate.status, body: '' };
-      /** 条件未知或不适用的条目只报状态：正文和标题都不能绕过自动召回的门槛。 */
-      if (record.status !== 'ok') {
-        return { id: '', scope: record.scope, status: record.status === 'needs_context' ? 'needs_context' : 'not_applicable', body: '' };
+      if (!gate.ok) return { scope: record.scope, status: gate.status, body: '' };
+      /** 条件未知或不适用的条目只报状态：标题只能定位，不能证明适用，正文一律不先返回。 */
+      if (record.status !== 'ok' && record.status !== 'archived') {
+        return { scope: record.scope, status: record.status === 'needs_context' ? 'needs_context' : 'not_applicable', body: '' };
       }
       const revision = record.revision || 1;
       const body = String(record.body ?? '');
       const value = {
-        id: record.id,
         title: record.title,
         when: record.when || '',
         revision,
@@ -2050,19 +2261,21 @@ export function apply(ctx, config) {
         body,
       };
       if (win) {
-        if (!affordable(win, 0)) return { id: '', scope: '', status: 'budget_exhausted' };
+        if (!affordableTool(win, 0)) return { scope: '', status: 'budget_exhausted' };
         const seenRevision = win.readBodies.get(record.id);
         if (seenRevision === revision) {
           const receipt = { ...value, body: '', repeat: true };
           const bytes = jsonBytes(receipt);
-          if (!affordable(win, bytes)) return { id: '', scope: '', status: 'budget_exhausted' };
+          if (!affordableTool(win, bytes)) return { scope: '', status: 'budget_exhausted' };
           win.bytes += bytes;
+          win.toolBytes += bytes;
           win.reads += 1;
           return receipt;
         }
         const bytes = jsonBytes(value);
-        if (!affordable(win, bytes, 1)) return { id: '', scope: '', status: 'budget_exhausted' };
+        if (!affordableTool(win, bytes, 1)) return { scope: '', status: 'budget_exhausted' };
         win.bytes += bytes;
+        win.toolBytes += bytes;
         win.bodies += 1;
         win.reads += 1;
         win.readBodies.set(record.id, revision);
@@ -2080,13 +2293,12 @@ export function apply(ctx, config) {
       schema: {
         type: 'object',
         properties: {
-          id: { type: 'string' },
           title: { type: 'string' },
           scope: { type: 'string' },
           scopeName: { type: 'string' },
           mode: { type: 'string', enum: ['archive', 'purged', 'needs_resolution', 'purge_pending', 'memory_disabled'] },
         },
-        required: ['id', 'mode'],
+        required: ['mode'],
         additionalProperties: false,
       },
       render: (_args, value) => [{
@@ -2103,7 +2315,6 @@ export function apply(ctx, config) {
       }],
       presentationMeta: (_args, value) => ({
         kind: 'memory-forget',
-        id: value.id || '',
         title: value.title || '',
         scope: value.scope || '',
         mode: value.mode,
@@ -2112,25 +2323,33 @@ export function apply(ctx, config) {
     execute: async (args, execution) => {
       const scope = scopeOf(cwdOf(execution));
       const projectScopeName = projectNameOf(scope);
-      if (!memoryEnabled(scope)) return { id: String(args.id || ''), title: '', scope: '', mode: 'memory_disabled' };
-      const located = locate(scope, args.id);
-      if (!located && !args.mode) throw new Error(`没有 ${args.id} 这条记忆`);
+      if (!memoryEnabled(scope)) return { title: '', scope: '', mode: 'memory_disabled' };
+      const forgetTitle = String(args.title || args.id || '').trim();
+      if (!args.scope && args.mode) {
+        const candidates = titleCandidates(scope, forgetTitle);
+        if (candidates.length > 1) {
+          throw new Error(`「${forgetTitle}」在项目层和全局层各有一条：删全局加 scope="global"，删项目加 scope="project"`);
+        }
+      }
+      const onlyLayer = args.scope === 'global' ? globalScope() : args.scope === 'project' ? scope : null;
+      const refId = refIdOf(scope, args);
+      const located = locate(scope, refId, onlyLayer ? { layers: [onlyLayer] } : {});
+      if (!located && !args.mode) throw new Error(`没有「${String(args.title || args.id || '').trim()}」这条记忆`);
       if (!args.mode) {
-        return { id: args.id, title: located.record.title || '', mode: 'needs_resolution', scope: located.scope.key === 'global' ? 'global' : 'project' };
+        return { title: located.record.title || '', mode: 'needs_resolution', scope: located.scope.key === 'global' ? 'global' : 'project' };
       }
       let dropped;
       try {
-        dropped = forget(scope, args.id, { mode: args.mode });
+        dropped = forget(scope, refId, onlyLayer ? { mode: args.mode, layers: [onlyLayer] } : { mode: args.mode });
       } catch (error) {
         if (error && error.code === 'purge_pending') {
           const layer = located ? located.scope : scope;
           try {
             state.resumePurge(layer);
-            dropped = forget(scope, args.id, { mode: args.mode });
+            dropped = forget(scope, refId, onlyLayer ? { mode: args.mode, layers: [onlyLayer] } : { mode: args.mode });
           } catch (again) {
             if (again && again.code === 'purge_pending') {
               return {
-                id: args.id,
                 title: located ? located.record.title : '',
                 mode: 'purge_pending',
                 scope: layer.key === 'global' ? 'global' : 'project',
@@ -2143,11 +2362,10 @@ export function apply(ctx, config) {
           throw error;
         }
       }
-      if (!dropped) throw new Error(`没有 ${args.id} 这条记忆`);
+      if (!dropped) throw new Error(`没有「${String(args.title || args.id || '').trim()}」这条记忆`);
       const layerKey = dropped.scopeKey || (located ? located.scope.key : scope.key);
       if (dropped.mode === 'purged') revokeLearningUse(layerKey);
       return {
-        id: dropped.id,
         title: dropped.title || (located ? located.record.title : ''),
         mode: dropped.mode,
         scope: layerKey === 'global' ? 'global' : 'project',
@@ -2286,7 +2504,7 @@ export function apply(ctx, config) {
       const ids = fresh.map((message) => String(message?.id ?? '')).filter(Boolean).sort();
       const win = openWindow(agent, { sessionId, turn, messageIds: ids });
       const budgetBefore = win ? {
-        bytes: win.bytes, bodies: win.bodies, reads: win.reads,
+        bytes: win.bytes, bodies: win.bodies, reads: win.reads, toolBytes: win.toolBytes || 0,
         provided: new Map(win.provided), readBodies: new Map(win.readBodies),
         recallHeader: win.recallHeader, experimentBytes: win.experimentBytes,
         autoBudget: win.autoBudget ? JSON.parse(JSON.stringify(win.autoBudget)) : null,
@@ -2306,6 +2524,7 @@ export function apply(ctx, config) {
       }
       const scope = scopeOf(cwd);
       if (!memoryEnabled(scope)) {
+        noteRecall(scope, sessionId, { reason: 'memory_off' });
         clearPrepared(agent);
         return decision;
       }
@@ -2318,6 +2537,7 @@ export function apply(ctx, config) {
       if (win && runtime) win.runtime = runtime.held;
       rememberRuntime(scope, sessionId, runtime && runtime.held);
       if (recallMode() !== 'adaptive') {
+        noteRecall(scope, sessionId, { reason: 'tools_only' });
         clearPrepared(agent);
         return decision;
       }
@@ -2334,12 +2554,16 @@ export function apply(ctx, config) {
         ? rememberFeedback(scope, sessionId, fresh, runtime.held, turn)
         : null;
       const snapshot = projectRecall(scope, query, recalledContext, win, runtime ? runtime.held : null);
+      noteRecall(scope, sessionId, {
+        reason: snapshot.reason, matched: snapshot.matched, cards: snapshot.cards.length, chars: snapshot.bytes,
+      });
       /** 没发布出去的投影要退还额度：不能因为一次超时把本请求的召回额度耗掉。 */
       const rollbackBudget = () => {
         if (!win || !budgetBefore) return;
         win.bytes = budgetBefore.bytes;
         win.bodies = budgetBefore.bodies;
         win.reads = budgetBefore.reads;
+        win.toolBytes = budgetBefore.toolBytes;
         win.provided = budgetBefore.provided;
         win.readBodies = budgetBefore.readBodies;
         win.recallHeader = budgetBefore.recallHeader;
@@ -2362,7 +2586,7 @@ export function apply(ctx, config) {
         return decision;
       }
       /** 实验上下文即使本轮零注入也要留着：工具绑定后同一请求还能补上规则。 */
-      if (!snapshot && !experiment) {
+      if ((!snapshot || !snapshot.cards.length) && !experiment) {
         rollbackBudget();
         clearPrepared(agent);
         return decision;
@@ -2370,7 +2594,7 @@ export function apply(ctx, config) {
       let evolutionEpoch = '';
       try { evolutionEpoch = String(evolutionStatus(scope).epoch || ''); } catch { evolutionEpoch = ''; }
       const state = {
-        text: snapshot ? snapshot.text : '',
+        text: snapshot && snapshot.cards.length ? snapshot.text : '',
         experimentText: experiment ? experiment.text : '',
         experimentParts: experiment && experiment.held ? (experiment.held.experimentParts || null) : null,
         validUntil: experiment && experiment.held ? (experiment.held.validUntil || '') : '',
@@ -2535,7 +2759,7 @@ export function apply(ctx, config) {
       if ((feedbackRevisions.get(scope.key) || 0) !== candidate.feedbackRevision) {
         throw new Error('反馈已更新，这轮结果没采用');
       }
-      const parsed = learning.parseOutput(text, { finish, refs: input.refs, rules: input.rules, ranges });
+      const parsed = learning.parseOutput(text, { finish, refs: input.refs, rules: input.rules, ranges, expectedTarget: candidate.expectedTarget });
       if (!parsed.ok) throw new Error(parsed.reason);
       /** 用户已经把要求说成长期规则，模型仍返回空时至少留一条规则，不让这条反馈无声消失。 */
       const changes = parsed.changes.length