dsh-memento 0.2.0 → 0.3.0

package/index.mjs

@@ -13,6 +13,7 @@
 import { defineTool } from '@deepseek-ai/dsh-tools'
 import Schema from '@deepseek-ai/schemastery'
 import { KNOWN_SESSION_EVENT_TYPES } from '@deepseek-ai/dsh-session'
+import { readFileSync } from 'node:fs'
 import {
   TRACKS,
   SCOPES,
@@ -20,6 +21,8 @@ import {
   DEFAULT_SOURCE,
   SESSION_EVENTS,
   PANEL_AUDIT_CEILING,
+  EXPORT_SCHEMA,
+  MAX_IMPORT_ENTRIES,
 } from './lib/constants.mjs'
 import {
   MemoryError,
@@ -49,7 +52,7 @@ import { extractEventText } from './lib/extract.mjs'
  * @typedef {object} StoreHandle - ctx.memory 依赖的 Provider 面。
  * @property {(filter?: {track?: string, scope?: string, text?: string, limit?: number}) => MemoryQueryResult} queryEntries
  * @property {() => MemoryEntry[]} listEntries
- * @property {(track: string, scope: string, match: string) => MemoryEntry[]} matchCandidates
+ * @property {(track: string, scope: string, match: string, opts?: {agentKey?: string, workspaceKey?: string}) => MemoryEntry[]} matchCandidates
  * @property {(track: string, scope: string) => number} usage
  * @property {(input: object) => MemoryEntry} insertEntry
  * @property {(inputs: object[]) => MemoryEntry[]} seedEntries
@@ -253,8 +256,10 @@ export class MemoryService {
    * 查询条目（无审批；带 sessionId 时记一条 recalled 审计）。
    * 显式合法 limit 生效但被 Provider 硬钳到 MAX_QUERY_LIMIT（1000）；缺省/非法 limit 用
    * maxEntriesPerQuery（Config 默认 20，语义是"默认返回上限"而非硬顶）。
+   * opts.agentKey 给定时按会话可见集过滤（共享层 + 指定 agent 键）；缺省不过滤——
+   * 管理面（/memory 命令、面板）与无会话上下文的插件调用保持全量视图。
    * @param {{track?: string, scope?: string, text?: string, limit?: number}} [filter] - {track, scope, text, limit}。
-   * @param {{sessionId?: string, session?: MemorySessionLike | null}} [opts] - {sessionId, session}；session 用于 memory/recalled
+   * @param {{sessionId?: string, session?: MemorySessionLike | null, agentKey?: string}} [opts] - {sessionId, session, agentKey}；session 用于 memory/recalled
    *   事件的按已知类型自适应派发（与写事件同一 maybeAppendSessionEvent 门）。
    * @returns {MemoryQueryResult}。
    */
@@ -264,6 +269,7 @@ export class MemoryService {
       ...(filter.scope === undefined ? {} : { scope: filter.scope }),
       ...(typeof filter.text === 'string' && filter.text.length > 0 ? { text: filter.text } : {}),
       limit: Number.isInteger(filter.limit) && filter.limit > 0 ? filter.limit : this.maxEntriesPerQuery,
+      ...(typeof opts.agentKey === 'string' ? { agentKey: opts.agentKey } : {}),
     })
     if (opts.sessionId !== undefined) {
       this.store.auditAppend({
@@ -291,19 +297,40 @@ export class MemoryService {
    * approval/decided 审计对）。write.gate 为可选自定义传输（/memory 命令在
    * turn 外使用：同一 approval/request waterfall + 同一 answerer 链裁决，
    * 会话级 never 策略由调用方预检；审计落在插件审计表 + command/done）。
+   * 被拒（rejected/cancelled/unavailable/off）一律落 `<action>-denied` 审计行再抛——
+   * turn 外 gate 路径没有审批审计对，这是拒绝的唯一证据链。
    * @param {WritePayload} payload - {action, track, scope, text, count?}。
    * @param {MemoryWriteContext} write - {agent, callId?, signal?, gate?}。
    * @returns {Promise<{outcome: string, source: 'approval'|'gate'}>} 实际裁决结果与传输来源（审计标签用）。
+   * 被拒（rejected/cancelled/unavailable/off）一律落 `<action>-denied` 审计行再抛——
+   * turn 外 gate 路径没有审批审计对，这是拒绝的唯一证据链。
    */
   async #ask(payload, write) {
-    if (typeof write.gate === 'function') {
-      const outcome = await write.gate(payload, write)
-      this.#assertOutcome(outcome)
-      return { outcome, source: 'gate' }
+    try {
+      const via = typeof write.gate === 'function'
+        ? { outcome: await write.gate(payload, write), source: /** @type {'approval'|'gate'} */ ('gate') }
+        : { outcome: await askApproval(this.approval, payload, write), source: /** @type {'approval'|'gate'} */ ('approval') }
+      this.#assertOutcome(via.outcome)
+      return via
+    } catch (error) {
+      if (error instanceof WriteDeniedError) {
+        const outcome = typeof error.details.outcome === 'string' ? error.details.outcome : 'denied'
+        const viaLabel = typeof write.gate === 'function'
+          ? `${outcome} (via write gate)`
+          : `${outcome} (via approval, writePolicy ${this.writePolicy})`
+        this.store.auditAppend({
+          action: `${payload.action}-denied`,
+          track: payload.track,
+          scope: payload.scope,
+          entryId: null,
+          text: payload.text,
+          outcome: viaLabel,
+          source: payload.source ?? this.sourceLabel,
+          sessionId: write.agent?.session?.id ?? null,
+        })
+      }
+      throw error
     }
-    const outcome = await askApproval(this.approval, payload, write)
-    this.#assertOutcome(outcome)
-    return { outcome, source: 'approval' }
   }
 
   /** 审计 outcome 标签：审批传输标注策略，gate 传输标注 gate（真实裁决来源，不张冠李戴）。 */
@@ -349,13 +376,18 @@ export class MemoryService {
     const { track, scope, text } = this.#validateEntry(input, write)
     this.#assertMatch(input)
     // 审批前先定位：零/多命中在打扰用户之前就响亮失败。
-    const initial = this.#resolveMatch(input, track, scope)
+    const initial = this.#resolveMatch(input, track, scope, write)
     this.#assertBudget(track, scope, this.store.usage(track, scope), text.length - initial.text.length)
-    const via = await this.#ask({ action: 'replace', track, scope, text, source: input.source ?? this.sourceLabel }, write)
+    // 审批载荷携带将被改写的旧条目全文（approve-what-you-see：人批准的不是抽象动作，是具体变更）。
+    const via = await this.#ask({
+      action: 'replace', track, scope,
+      text: `from:\n${initial.text}\n\nto:\n${text}`,
+      source: input.source ?? this.sourceLabel,
+    }, write)
     this.#throwIfAborted(write)
     // 审批等待期间目标条目可能已被并发写改动：以此刻重新定位的 previous 为权威重算净变化，
     // 再用此刻用量复审。复审与 replaceEntry 之间无 await，判断与实际写入之间不存在窗口。
-    const current = this.#resolveMatch(input, track, scope)
+    const current = this.#resolveMatch(input, track, scope, write)
     const net = text.length - current.text.length
     this.#assertBudget(track, scope, this.store.usage(track, scope), net)
     // 事务内重新定位+更新：零/多命中仍会响亮报错（不静默）。
@@ -383,8 +415,9 @@ export class MemoryService {
     this.#assertScope(input.track, input.scope)
     this.#assertMatch(input)
     // 审批前先定位：零/多命中在打扰用户之前就响亮失败。
-    const target = this.#resolveMatch(input, input.track, input.scope)
-    const via = await this.#ask({ action: 'remove', track: input.track, scope: input.scope, text: input.match, source: target.source }, write)
+    const target = this.#resolveMatch(input, input.track, input.scope, write)
+    // 审批载荷携带将被删除的条目全文（approve-what-you-see），而非裸子串。
+    const via = await this.#ask({ action: 'remove', track: input.track, scope: input.scope, text: target.text, source: target.source }, write)
     this.#throwIfAborted(write)
     const removed = this.store.removeEntry({ track: input.track, scope: input.scope, match: input.match })
     this.#auditWrite('remove', input.track, input.scope, removed, write, via)
@@ -452,14 +485,21 @@ export class MemoryService {
     const { track, scope, text } = this.#validateEntry(input, write)
     this.#assertConsolidateMatches(input)
     // 审批前先定位全部目标：零/多命中在打扰用户之前就响亮失败。
-    const initial = input.matches.map((match) => this.#resolveMatch({ match }, track, scope))
+    const initial = input.matches.map((match) => this.#resolveMatch({ match }, track, scope, write))
     const removalBefore = initial.reduce((sum, entry) => sum + entry.text.length, 0)
     this.#assertBudget(track, scope, this.store.usage(track, scope), text.length - removalBefore)
-    const plan = `${input.matches.map((match) => `remove: ${match}`).join('\n')}\nnew text: ${text}`
+    // 审批载荷携带每个目标的定位条目原文（单条超长只截前 300 字，避免 20×满预算条目撑爆载荷）。
+    const plan = [
+      ...initial.map((entry, index) => {
+        const body = entry.text.length > 300 ? `${entry.text.slice(0, 300)}…` : entry.text
+        return `remove: ${input.matches[index]}\n${body}`
+      }),
+      `new text: ${text}`,
+    ].join('\n')
     const via = await this.#ask({ action: 'consolidate', track, scope, text: plan, source: input.source ?? this.sourceLabel }, write)
     this.#throwIfAborted(write)
     // 审批等待期间目标可能被并发写改动：重新定位并以此刻为权威重算净变化。
-    const current = input.matches.map((match) => this.#resolveMatch({ match }, track, scope))
+    const current = input.matches.map((match) => this.#resolveMatch({ match }, track, scope, write))
     const removalNow = current.reduce((sum, entry) => sum + entry.text.length, 0)
     this.#assertBudget(track, scope, this.store.usage(track, scope), text.length - removalNow)
     const { removed, entry } = this.store.consolidateEntries({
@@ -528,9 +568,18 @@ export class MemoryService {
     return { track: input.track, scope: input.scope, text: input.text }
   }
 
-  /** 审批前定位替换/删除目标（唯一子串语义，大小写不敏感，零/多命中结构化报错）。 */
-  #resolveMatch(/** @type {{match: string}} */ input, /** @type {string} */ track, /** @type {string} */ scope) {
-    const hits = /** @type {MemoryEntry[]} */ (this.store.matchCandidates(track, scope, input.match))
+  /**
+   * 审批前定位替换/删除目标（唯一子串语义，大小写不敏感，零/多命中结构化报错）。
+   * 写定位 = 会话可见集：agentKey 共享 + 写方会话键（显式 input 覆盖）；scope='workspace'
+   * 时按写方会话 cwd 键过滤——跨 agent/跨工作区条目对本会话不可见、也不可被误改。
+   */
+  #resolveMatch(/** @type {{match: string, agentKey?: string, workspaceKey?: string}} */ input, /** @type {string} */ track, /** @type {string} */ scope, /** @type {MemoryWriteContext} */ write) {
+    const agentKey = typeof input.agentKey === 'string' && input.agentKey.length > 0 ? input.agentKey : this.#agentKeyOf(write)
+    const workspaceKey = typeof input.workspaceKey === 'string' && input.workspaceKey.length > 0 ? input.workspaceKey : this.#workspaceKeyOf(write)
+    const hits = /** @type {MemoryEntry[]} */ (this.store.matchCandidates(track, scope, input.match, {
+      agentKey,
+      workspaceKey: scope === 'workspace' ? workspaceKey : undefined,
+    }))
       .filter((entry) => entry.text.toLowerCase().includes(input.match.toLowerCase()))
     if (hits.length === 0) throw new EntryNotFoundError({ track, scope, match: input.match })
     if (hits.length > 1) {
@@ -830,7 +879,12 @@ export function makeMemoryTool(service, language = 'en') {
                 ...(args.text === undefined ? {} : { text: args.text }),
                 ...(args.limit === undefined ? {} : { limit: args.limit }),
               },
-              { sessionId: exec.agent?.session?.id, session: exec.agent?.session },
+              {
+                sessionId: exec.agent?.session?.id,
+                session: exec.agent?.session,
+                // 会话内读按可见集过滤（共享 + 本 agent），与冻结快照同一语义。
+                agentKey: agentKeyOf(/** @type {string | undefined} */ (exec.agent?.session?.header?.agentPreset)),
+              },
             )
             return {
               action: 'query',
@@ -1268,12 +1322,20 @@ function makeCommandGate(ctx, write) {
  * @property {string} consolidateNeedsText
  * @property {(track: string, scope: string, removed: number, text: string, used: number, limit: number) => string} consolidated
  * @property {string} exportUsage
+ * @property {string} importUsage
+ * @property {string} importBadJson
+ * @property {(path: string, message: string) => string} importReadFailed
+ * @property {(schema: string) => string} importBadSchema
+ * @property {string} importNoEntries
+ * @property {(max: number) => string} importTooMany
+ * @property {string} importBadEntry
+ * @property {(n: number) => string} imported
  * @property {(verb: string) => string} unknownVerb
  * @property {(message: string) => string} commandFailed
  */
 const COMMAND_TEXT = /** @type {{en: CommandTextBundle, zh: CommandTextBundle}} */ ({
   en: {
-    usage: 'Usage: /memory list | query <word> | add <text> | remove <substring> | consolidate <substring...> => <new text> | proposals [approve|dismiss <id>] | budgets | audit | export',
+    usage: 'Usage: /memory list | query <word> | add <text> | remove <substring> | consolidate <substring...> => <new text> | proposals [approve|dismiss <id>] | budgets | audit | export | import <path>',
     memoryEmpty: 'Memory is empty.',
     entries: (total, shown) => `Memory entries (${total} total, showing first ${shown}):`,
     entriesFull: (total) => `Memory entries (${total}):`,
@@ -1299,11 +1361,19 @@ const COMMAND_TEXT = /** @type {{en: CommandTextBundle, zh: CommandTextBundle}}
     consolidateNeedsText: 'consolidate needs new text (right of =>)',
     consolidated: (track, scope, removed, text, used, limit) => `Consolidated (${track}/${scope}): removed ${removed}, added 1.\nNew entry: ${text}\nLayer usage: ${used}/${limit}`,
     exportUsage: 'export dumps all entries + budgets as one JSON document (read-only; redirect it to a file for backup/migration): /memory export',
-    unknownVerb: (verb) => `Unknown subcommand "${verb}". Usage: /memory list | query <word> | add <text> | remove <substring> | consolidate <substring...> => <new text> | proposals [approve|dismiss <id>] | budgets | audit | export`,
+    importUsage: 'import restores entries from an export document (a file path, or inline JSON starting with {): /memory import <path> | /memory import \'{"plugin":"dsh-memento",...}\'',
+    importBadJson: 'import: inline JSON could not be parsed',
+    importReadFailed: (path, message) => `import: cannot read ${JSON.stringify(path)}: ${message}`,
+    importBadSchema: (schema) => `import: not a dsh-memento export document (expected schema "${schema}")`,
+    importNoEntries: 'import: the export document contains no entries',
+    importTooMany: (max) => `import: the export document has more than ${max} entries; split it and import in batches`,
+    importBadEntry: 'import: every entry needs a string track, scope, and non-empty text',
+    imported: (n) => `Imported ${n} entries into memory (single approval; budgets re-checked). Entries get fresh ids and timestamps; proposals, audit rows and recall counts are not migrated.`,
+    unknownVerb: (verb) => `Unknown subcommand "${verb}". Usage: /memory list | query <word> | add <text> | remove <substring> | consolidate <substring...> => <new text> | proposals [approve|dismiss <id>] | budgets | audit | export | import <path>`,
     commandFailed: (message) => `memory command failed: ${message}`,
   },
   zh: {
-    usage: '用法：/memory list | query <词> | add <文本> | remove <唯一子串> | consolidate <唯一子串...> => <新文本> | proposals [approve|dismiss <id>] | budgets | audit | export',
+    usage: '用法：/memory list | query <词> | add <文本> | remove <唯一子串> | consolidate <唯一子串...> => <新文本> | proposals [approve|dismiss <id>] | budgets | audit | export | import <路径>',
     memoryEmpty: '记忆为空。',
     entries: (total, shown) => `记忆条目（共 ${total} 条，显示前 ${shown} 条）：`,
     entriesFull: (total) => `记忆条目（${total} 条）：`,
@@ -1329,7 +1399,15 @@ const COMMAND_TEXT = /** @type {{en: CommandTextBundle, zh: CommandTextBundle}}
     consolidateNeedsText: 'consolidate 需要新文本（=> 右侧）',
     consolidated: (track, scope, removed, text, used, limit) => `已整合（${track}/${scope}）：删除 ${removed} 条，新增 1 条。\n新条目：${text}\n该层用量：${used}/${limit}`,
     exportUsage: 'export 把所有条目 + 预算导出为一份 JSON 文档（只读；可重定向到文件做备份/迁移）：/memory export',
-    unknownVerb: (verb) => `未知子命令「${verb}」。用法：/memory list | query <词> | add <文本> | remove <唯一子串> | consolidate <唯一子串...> => <新文本> | proposals [approve|dismiss <id>] | budgets | audit | export`,
+    importUsage: 'import 从导出文档恢复条目（文件路径，或以 { 开头的内联 JSON）：/memory import <路径> | /memory import \'{"plugin":"dsh-memento",...}\'',
+    importBadJson: 'import：内联 JSON 无法解析',
+    importReadFailed: (path, message) => `import：无法读取 ${JSON.stringify(path)}：${message}`,
+    importBadSchema: (schema) => `import：不是 dsh-memento 导出文档（要求 schema "${schema}"）`,
+    importNoEntries: 'import：导出文档没有任何条目',
+    importTooMany: (max) => `import：导出文档超过 ${max} 条；请拆分后分批导入`,
+    importBadEntry: 'import：每条都需要字符串 track、scope 与非空 text',
+    imported: (n) => `已导入 ${n} 条记忆（单次审批；预算已复检）。条目获得新 id 与新时间戳；提案、审计行与召回计数不迁移。`,
+    unknownVerb: (verb) => `未知子命令「${verb}」。用法：/memory list | query <词> | add <文本> | remove <唯一子串> | consolidate <唯一子串...> => <新文本> | proposals [approve|dismiss <id>] | budgets | audit | export | import <路径>`,
     commandFailed: (message) => `memory 命令失败：${message}`,
   },
 })
@@ -1337,12 +1415,12 @@ const COMMAND_TEXT = /** @type {{en: CommandTextBundle, zh: CommandTextBundle}}
 /** 命令注册描述与输入提示（双语）。 */
 const COMMAND_DESCRIPTION = /** @type {{en: {description: string, hint: string}, zh: {description: string, hint: string}}} */ ({
   en: {
-    description: 'View/manage dsh-memento memory: list | query <word> | add [--track=user|agent] [--scope=user-global|workspace] <text> | remove <substring> | consolidate <substring...> => <new text> | proposals [approve|dismiss <id>] | budgets | audit | export',
-    hint: 'list | query <word> | add <text> | remove <substring> | consolidate <substring...> => <new text> | proposals [approve|dismiss <id>] | budgets | audit | export',
+    description: 'View/manage dsh-memento memory: list | query <word> | add [--track=user|agent] [--scope=user-global|workspace] <text> | remove <substring> | consolidate <substring...> => <new text> | proposals [approve|dismiss <id>] | budgets | audit | export | import <path>',
+    hint: 'list | query <word> | add <text> | remove <substring> | consolidate <substring...> => <new text> | proposals [approve|dismiss <id>] | budgets | audit | export | import <path>',
   },
   zh: {
-    description: '查看/管理 dsh-memento 记忆：list | query <词> | add [--track=user|agent] [--scope=user-global|workspace] <文本> | remove <唯一子串> | consolidate <唯一子串...> => <新文本> | proposals [approve|dismiss <id>] | budgets | audit | export',
-    hint: 'list | query <词> | add <文本> | remove <唯一子串> | consolidate <唯一子串...> => <新文本> | proposals [approve|dismiss <id>] | budgets | audit | export',
+    description: '查看/管理 dsh-memento 记忆：list | query <词> | add [--track=user|agent] [--scope=user-global|workspace] <文本> | remove <唯一子串> | consolidate <唯一子串...> => <新文本> | proposals [approve|dismiss <id>] | budgets | audit | export | import <路径>',
+    hint: 'list | query <词> | add <文本> | remove <唯一子串> | consolidate <唯一子串...> => <新文本> | proposals [approve|dismiss <id>] | budgets | audit | export | import <路径>',
   },
 })
 
@@ -1441,7 +1519,12 @@ async function runMemoryCommand(ctx, service, invocation) {
           { track: proposal.track, scope: proposal.scope, text: proposal.text, source: 'proposal', workspaceKey: proposal.workspaceKey, agentKey: proposal.agentKey },
           { agent: invocation?.agent, gate: makeCommandGate(ctx, invocation) },
         )
-        service.store.proposalDecide(id, 'approved')
+        try {
+          service.store.proposalDecide(id, 'approved')
+        } catch (error) {
+          // 并发裁决（面板/另一命令已 approve/dismiss）：写已成功，别用提案状态错误掩盖它。
+          if (!(error instanceof ProposalNotFoundError)) throw error
+        }
         return { kind: 'success', text: text.proposalApproved(proposal.track, proposal.scope, result.entry.text, result.usage.used, result.usage.limit) }
       }
       if (sub === 'dismiss') {
@@ -1460,7 +1543,7 @@ async function runMemoryCommand(ctx, service, invocation) {
       const entries = service.store.listEntries()
       const payload = {
         plugin: 'dsh-memento',
-        schema: 'memory-export-v1',
+        schema: EXPORT_SCHEMA,
         exportedAt: new Date().toISOString(),
         budgets: service.budgets(),
         entries: entries.map((/** @type {MemoryEntry} */ entry) => ({
@@ -1479,6 +1562,50 @@ async function runMemoryCommand(ctx, service, invocation) {
       }
       return { kind: 'success', text: JSON.stringify(payload, null, 2) }
     }
+    case 'import': {
+      const arg = rest.join(' ').trim()
+      if (arg.length === 0) return { kind: 'error', text: text.importUsage }
+      let payload
+      if (arg.startsWith('{')) {
+        try {
+          payload = JSON.parse(arg)
+        } catch {
+          return { kind: 'error', text: text.importBadJson }
+        }
+      } else {
+        try {
+          payload = JSON.parse(readFileSync(arg, 'utf8'))
+        } catch (error) {
+          const message = error instanceof Error ? error.message : String(error)
+          return { kind: 'error', text: text.importReadFailed(arg, message) }
+        }
+      }
+      const shape = payload !== null && typeof payload === 'object' ? /** @type {{plugin?: unknown, schema?: unknown, entries?: unknown}} */ (payload) : undefined
+      const valid = shape !== undefined && shape.plugin === 'dsh-memento' && shape.schema === EXPORT_SCHEMA && Array.isArray(shape.entries)
+      if (!valid) return { kind: 'error', text: text.importBadSchema(EXPORT_SCHEMA) }
+      const rawEntries = /** @type {unknown[]} */ (shape.entries)
+      if (rawEntries.length === 0) return { kind: 'error', text: text.importNoEntries }
+      if (rawEntries.length > MAX_IMPORT_ENTRIES) return { kind: 'error', text: text.importTooMany(MAX_IMPORT_ENTRIES) }
+      const entries = []
+      for (const raw of rawEntries) {
+        if (raw === null || typeof raw !== 'object') return { kind: 'error', text: text.importBadEntry }
+        const entry = /** @type {{track?: unknown, scope?: unknown, text?: unknown, source?: unknown, workspaceKey?: unknown, agentKey?: unknown}} */ (raw)
+        if (typeof entry.track !== 'string' || typeof entry.scope !== 'string' || typeof entry.text !== 'string' || entry.text.length === 0) {
+          return { kind: 'error', text: text.importBadEntry }
+        }
+        entries.push({
+          track: entry.track,
+          scope: entry.scope,
+          text: entry.text,
+          ...(typeof entry.source === 'string' && entry.source.length > 0 ? { source: entry.source } : {}),
+          ...(typeof entry.workspaceKey === 'string' && entry.workspaceKey.length > 0 ? { workspaceKey: entry.workspaceKey } : {}),
+          ...(typeof entry.agentKey === 'string' && entry.agentKey.length > 0 ? { agentKey: entry.agentKey } : {}),
+        })
+      }
+      // seed 单次审批 + 全量预算预检 + 单事务原子落盘；条目重获新 id 与新时间戳，召回计数归零。
+      const result = await service.seed(entries, { agent: invocation?.agent, gate: makeCommandGate(ctx, invocation) })
+      return { kind: 'success', text: text.imported(result.added) }
+    }
     case 'add': {
       const parsed = parseCommandWrite(rest, true)
       if (parsed.kind === 'error') {
@@ -1549,9 +1676,11 @@ function parseCommandWrite(/** @type {string[]} */ args, /** @type {boolean} */
   return { kind: 'ok', track, scope, text }
 }
 
-/** 条目渲染行（命令/面板共用格式）。 */
-function renderEntryLine(/** @type {{track: string, scope: string, workspaceKey?: string, text: string}} */ entry) {
-  return `- [${entry.track}/${entry.scope}${entry.scope === 'workspace' ? ` @${entry.workspaceKey}` : ''}] ${entry.text}`
+/** 条目渲染行（命令/面板共用格式；workspace 条目带 @工作区键，非共享 agent 条目带 #agent 键）。 */
+function renderEntryLine(/** @type {{track: string, scope: string, workspaceKey?: string, agentKey?: string, text: string}} */ entry) {
+  const workspaceTag = entry.scope === 'workspace' ? ` @${entry.workspaceKey}` : ''
+  const agentTag = typeof entry.agentKey === 'string' && entry.agentKey.length > 0 ? ` #${entry.agentKey}` : ''
+  return `- [${entry.track}/${entry.scope}${workspaceTag}${agentTag}] ${entry.text}`
 }
 
 /**
@@ -1654,7 +1783,12 @@ export function makeMemoryRecallTool(service, ctx, recall, language = 'en') {
       exec.signal.throwIfAborted()
       const memory = service.query(
         { text: args.query, limit: args.memoryLimit ?? 10 },
-        { sessionId: exec.agent?.session?.id, session: exec.agent?.session },
+        {
+          sessionId: exec.agent?.session?.id,
+          session: exec.agent?.session,
+          // 与 memory 工具一致：会话内召回按可见集过滤（共享 + 本 agent）。
+          agentKey: agentKeyOf(/** @type {string | undefined} */ (exec.agent?.session?.header?.agentPreset)),
+        },
       )
       const history = await recallHistory(
         ctx,

package/lib/constants.mjs

@@ -1,58 +1,64 @@
-// lib/constants.mjs — dsh-memento 词汇表与协议常量（零 DSH 依赖）。
-//
-// 本文件只放协议级常量（词汇、错误码、存储格式版本）。部署可调参数一律走
-// index.mjs 的 Schemastery Config，绝不在此写死 tunable。
-
-/** 记忆轨道（双轨分家）：user=用户画像，agent=环境事实/约定/教训。 */
-export const TRACKS = /** @type {readonly ['user', 'agent']} */ (['user', 'agent'])
-
-/** 分层作用域：user-global 跨工作区，workspace 按会话 cwd。 */
-export const SCOPES = /** @type {readonly ['user-global', 'workspace']} */ (['user-global', 'workspace'])
-
-/** 写策略（Config.writePolicy）：ask=用户审批，auto=放行但记录审批来源，off=拒绝。 */
-export const WRITE_POLICIES = ['ask', 'auto', 'off']
-
-/** 审批请求里标识本插件记忆写动作的工具名（审批 answerer 据此认领请求）。 */
-export const TOOL_NAME = 'memory'
-
-/** 审批 reason 前缀（含方括号）：answerer 只认领带本前缀的 memory 写请求，防止误伤同工具名的其它请求。 */
-export const REQUEST_MARKER = '[dsh-memento]'
-
-/** 记忆库 schema 版本（单调递增；旧版逐级迁移，新版响亮拒绝）。v2 = proposals 提案表；v3 = agent_key + 召回排序列。 */
-export const SCHEMA_VERSION = 3
-
-/** 数据库文件名（位于 $DSH_HOME/dsh-memento/ 下）。 */
-export const DEFAULT_DB_NAME = 'memory.db'
-
-/** 条目默认来源标注（seed 写 source: 'claude' 时除外）。 */
-export const DEFAULT_SOURCE = 'dsh-memento'
-
-/** Provider 层查询返回硬上限：显式 limit 的钳制天花板（防模型/面板拉爆上下文）。 */
-export const MAX_QUERY_LIMIT = 1000
-
-/** 面板审计路由的返回上限：只读抽屉的审计尾展示天花板（协议常量，非部署 tunable）。 */
-export const PANEL_AUDIT_CEILING = 200
-
-/** 结构化错误码：工具与面板据此分支，模型据此决定"整合后重试"还是"放弃"。 */
-export const ERROR_CODES = {
-  DISABLED: 'MEMORY_DISABLED',
-  INVALID_INPUT: 'INVALID_INPUT',
-  NO_AGENT: 'WRITE_REQUIRES_AGENT',
-  BUDGET_EXCEEDED: 'BUDGET_EXCEEDED',
-  ENTRY_NOT_FOUND: 'ENTRY_NOT_FOUND',
-  AMBIGUOUS_MATCH: 'AMBIGUOUS_MATCH',
-  WRITE_DENIED: 'WRITE_DENIED',
-  PROPOSAL_NOT_FOUND: 'PROPOSAL_NOT_FOUND',
-  STORE_CORRUPT: 'STORE_CORRUPT',
-  STORE_UNSUPPORTED_VERSION: 'STORE_UNSUPPORTED_VERSION',
-  MISSING_DSH_HOME: 'MISSING_DSH_HOME',
-}
-
-/** 会话事件名（SessionEventMap 声明合并的词汇表；运行时按已知类型自适应派发）。 */
-export const SESSION_EVENTS = {
-  added: 'memory/added',
-  updated: 'memory/updated',
-  removed: 'memory/removed',
-  recalled: 'memory/recalled',
-  snapshot: 'memory/snapshot',
-}
+// lib/constants.mjs — dsh-memento 词汇表与协议常量（零 DSH 依赖）。
+//
+// 本文件只放协议级常量（词汇、错误码、存储格式版本）。部署可调参数一律走
+// index.mjs 的 Schemastery Config，绝不在此写死 tunable。
+
+/** 记忆轨道（双轨分家）：user=用户画像，agent=环境事实/约定/教训。 */
+export const TRACKS = /** @type {readonly ['user', 'agent']} */ (['user', 'agent'])
+
+/** 分层作用域：user-global 跨工作区，workspace 按会话 cwd。 */
+export const SCOPES = /** @type {readonly ['user-global', 'workspace']} */ (['user-global', 'workspace'])
+
+/** 写策略（Config.writePolicy）：ask=用户审批，auto=放行但记录审批来源，off=拒绝。 */
+export const WRITE_POLICIES = ['ask', 'auto', 'off']
+
+/** 审批请求里标识本插件记忆写动作的工具名（审批 answerer 据此认领请求）。 */
+export const TOOL_NAME = 'memory'
+
+/** 审批 reason 前缀（含方括号）：answerer 只认领带本前缀的 memory 写请求，防止误伤同工具名的其它请求。 */
+export const REQUEST_MARKER = '[dsh-memento]'
+
+/** 记忆库 schema 版本（单调递增；旧版逐级迁移，新版响亮拒绝）。v2 = proposals 提案表；v3 = agent_key + 召回排序列。 */
+export const SCHEMA_VERSION = 3
+
+/** 数据库文件名（位于 $DSH_HOME/dsh-memento/ 下）。 */
+export const DEFAULT_DB_NAME = 'memory.db'
+
+/** 条目默认来源标注（seed 写 source: 'claude' 时除外）。 */
+export const DEFAULT_SOURCE = 'dsh-memento'
+
+/** Provider 层查询返回硬上限：显式 limit 的钳制天花板（防模型/面板拉爆上下文）。 */
+export const MAX_QUERY_LIMIT = 1000
+
+/** 面板审计路由的返回上限：只读抽屉的审计尾展示天花板（协议常量，非部署 tunable）。 */
+export const PANEL_AUDIT_CEILING = 200
+
+/** /memory export 文档的 schema 标记（export 与 import 共用；import 只认本标记）。 */
+export const EXPORT_SCHEMA = 'memory-export-v1'
+
+/** /memory import 单次导入条目数上限：防一次性灌入海量条目把审批载荷撑爆（协议常量）。 */
+export const MAX_IMPORT_ENTRIES = 1000
+
+/** 结构化错误码：工具与面板据此分支，模型据此决定"整合后重试"还是"放弃"。 */
+export const ERROR_CODES = {
+  DISABLED: 'MEMORY_DISABLED',
+  INVALID_INPUT: 'INVALID_INPUT',
+  NO_AGENT: 'WRITE_REQUIRES_AGENT',
+  BUDGET_EXCEEDED: 'BUDGET_EXCEEDED',
+  ENTRY_NOT_FOUND: 'ENTRY_NOT_FOUND',
+  AMBIGUOUS_MATCH: 'AMBIGUOUS_MATCH',
+  WRITE_DENIED: 'WRITE_DENIED',
+  PROPOSAL_NOT_FOUND: 'PROPOSAL_NOT_FOUND',
+  STORE_CORRUPT: 'STORE_CORRUPT',
+  STORE_UNSUPPORTED_VERSION: 'STORE_UNSUPPORTED_VERSION',
+  MISSING_DSH_HOME: 'MISSING_DSH_HOME',
+}
+
+/** 会话事件名（SessionEventMap 声明合并的词汇表；运行时按已知类型自适应派发）。 */
+export const SESSION_EVENTS = {
+  added: 'memory/added',
+  updated: 'memory/updated',
+  removed: 'memory/removed',
+  recalled: 'memory/recalled',
+  snapshot: 'memory/snapshot',
+}