@modusensus/dsh-mneme 0.7.32 → 0.8.1

package/lib/store.js

@@ -148,6 +148,25 @@ CREATE TABLE IF NOT EXISTS conflict_pending (
 );
 CREATE INDEX IF NOT EXISTS idx_conflict_pending_unresolved ON conflict_pending(resolved_at);
 
+-- scope_changes: v0.8.1 底座（issue #170）scope 归属的人工修正审计。显式声明
+-- （memory_save/memory_update 的 scope 参数、面板编辑）每次改变某条记忆的
+-- agent/workspace 归属都落一行：改动前后值 + 来源 + actor（tool=模型侧 /
+-- panel=人工侧）。与 conflict_pending 同款的 bookkeeping 表：只做审计，
+-- 不触发 write hooks。放宽可见性（label→global）的候选筛选与回放都靠它。
+CREATE TABLE IF NOT EXISTS scope_changes (
+  id                    TEXT PRIMARY KEY,
+  memory_id             TEXT NOT NULL,
+  actor                 TEXT NOT NULL,
+  prev_agent_scope      TEXT,
+  prev_workspace_scope  TEXT,
+  next_agent_scope      TEXT,
+  next_workspace_scope  TEXT,
+  agent_scope_source    TEXT,
+  workspace_scope_source TEXT,
+  decided_at            TEXT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_scope_changes_memory ON scope_changes(memory_id);
+
 -- llm_audit_logs: every background LLM call (autoDream consolidation + summary,
 -- autoSummarize compression) is recorded here — tokens in/out, duration, status
 -- and the trigger that caused it (Bug8). Failures are captured as status='error'
@@ -310,7 +329,9 @@ function escapeLike(q) {
 // 法值一律返回 undefined → 不进 WHERE（忽略而非报错：面板传坏参数时宁可放宽
 // 过滤也不要白屏）。updated_at 列是 toISOString 产生的 UTC "Z" 字符串，字典
 // 序与时间序一致，SQL 里可直接比较。
-function updatedAtBounds(updatedFrom, updatedTo) {
+// v0.8.0 A2：导出复用——occurred_at 时间过滤（service 的搜索后置过滤）与
+// updated_at 过滤共用同一套边界归一化，坏参数口径一致。
+export function updatedAtBounds(updatedFrom, updatedTo) {
   const norm = (raw, endOfDay) => {
     if (typeof raw !== "string" || !raw.trim()) return undefined;
     const s = raw.trim();
@@ -332,6 +353,33 @@ function parseTags(raw) {
   }
 }
 
+// scope 列（agent_scope/workspace_scope/sensitivity）写入归一化：非空 trim 字符串
+// 原样收下，其余（undefined/null/空串/非字符串）一律 NULL。存储层不做枚举校验——
+// scope 值是宿主身份标签（agentPreset id / 目录路径 / 自由 sensitivity 标签），
+// 语义由调用方负责；这里只保证「脏输入落 NULL，绝不阻塞写入」。
+function normalizeScopeText(raw) {
+  if (typeof raw !== "string") return null;
+  const s = raw.trim();
+  return s ? s : null;
+}
+
+// scope 来源列（issue #170 底座）：'auto'=载体自动标注，'explicit'=显式声明。
+// 只认这两个枚举值，其余（含 NULL）落 NULL——NULL 语义是「未标注，或 0.8.1
+// 之前落库的存量标注（视为 auto 的软效力，第 3 步语义收窄时按此口径读）」。
+function normalizeScopeSource(raw) {
+  return raw === "auto" || raw === "explicit" ? raw : null;
+}
+
+// occurred_at：事件发生时间（区别于 created_at 的入库时间）。可解析的时间戳
+// 统一归一到 UTC ISO（A2 的时间过滤要按字典序直接比较）；解析失败落 NULL，
+// 同样不阻塞写入。
+function normalizeOccurredAt(raw) {
+  if (typeof raw !== "string" || !raw.trim()) return null;
+  const ms = Date.parse(raw.trim());
+  if (Number.isNaN(ms)) return null;
+  return new Date(ms).toISOString();
+}
+
 function toRow(row) {
   if (!row) return undefined;
   return {
@@ -347,6 +395,13 @@ function toRow(row) {
     content_history: parseJsonArray(row.content_history),
     quality_score: row.quality_score !== null && row.quality_score !== undefined ? Number(row.quality_score) : undefined,
     epistemic_status: row.epistemic_status ?? "subjective",
+    agent_scope: row.agent_scope ?? undefined,
+    workspace_scope: row.workspace_scope ?? undefined,
+    agent_scope_source: row.agent_scope_source ?? undefined,
+    workspace_scope_source: row.workspace_scope_source ?? undefined,
+    scope_decided_at: row.scope_decided_at ?? undefined,
+    sensitivity: row.sensitivity ?? undefined,
+    occurred_at: row.occurred_at ?? undefined,
     created_at: row.created_at,
     updated_at: row.updated_at,
     last_accessed_at: row.last_accessed_at ?? undefined,
@@ -412,6 +467,22 @@ function toConflictPending(row) {
   };
 }
 
+function toScopeChange(row) {
+  if (!row) return undefined;
+  return {
+    id: row.id,
+    memory_id: row.memory_id,
+    actor: row.actor,
+    prev_agent_scope: row.prev_agent_scope ?? undefined,
+    prev_workspace_scope: row.prev_workspace_scope ?? undefined,
+    next_agent_scope: row.next_agent_scope ?? undefined,
+    next_workspace_scope: row.next_workspace_scope ?? undefined,
+    agent_scope_source: row.agent_scope_source ?? undefined,
+    workspace_scope_source: row.workspace_scope_source ?? undefined,
+    decided_at: row.decided_at
+  };
+}
+
 function toRecallRun(row) {
   if (!row) return undefined;
   return {
@@ -597,6 +668,24 @@ export function createStore(path) {
   addColumn("memories", "content_history", "ALTER TABLE memories ADD COLUMN content_history TEXT");
   addColumn("memories", "quality_score", "ALTER TABLE memories ADD COLUMN quality_score REAL");
 
+  // v0.8.0 A1（issue #17）scope 隔离存储层：四列全部可空、不带 DEFAULT——存量行
+  // 零重写，读侧把 NULL 视为未标注（= 全局可见）。是否落值由 scopeEnabled 门控
+  // （service/tools 层），存储层只负责归一化（normalizeScopeText/normalizeOccurredAt）。
+  addColumn("memories", "agent_scope", "ALTER TABLE memories ADD COLUMN agent_scope TEXT");
+  addColumn("memories", "workspace_scope", "ALTER TABLE memories ADD COLUMN workspace_scope TEXT");
+  addColumn("memories", "sensitivity", "ALTER TABLE memories ADD COLUMN sensitivity TEXT");
+  addColumn("memories", "occurred_at", "ALTER TABLE memories ADD COLUMN occurred_at TEXT");
+
+  // v0.8.1 底座（issue #170）：scope 标注的来源与决策时间。三列全部可空不带
+  // DEFAULT（与 A1 同款零重写迁移）。来源拆成 agent/workspace 各一列而非单列
+  // scope_source：混合来源（agent 维显式 + workspace 维自动）必须可表达——否则
+  // 「提升回全局」之后遗留的自动 workspace 标签会在效力收窄时被一并当成显式，
+  // 恰好复活 issue #170 抱怨的「自动标签吃硬过滤」问题。存量标注行三列皆 NULL，
+  // 读侧按 auto（软效力）口径解释。
+  addColumn("memories", "agent_scope_source", "ALTER TABLE memories ADD COLUMN agent_scope_source TEXT");
+  addColumn("memories", "workspace_scope_source", "ALTER TABLE memories ADD COLUMN workspace_scope_source TEXT");
+  addColumn("memories", "scope_decided_at", "ALTER TABLE memories ADD COLUMN scope_decided_at TEXT");
+
   // Legacy dream_runs without policy_epoch → backfill with the default epoch.
   addColumn("dream_runs", "policy_epoch", "ALTER TABLE dream_runs ADD COLUMN policy_epoch INTEGER NOT NULL DEFAULT 0");
   addColumn("dream_runs", "run_type", "ALTER TABLE dream_runs ADD COLUMN run_type TEXT NOT NULL DEFAULT 'auto'");
@@ -643,7 +732,7 @@ export function createStore(path) {
     return ts;
   }
 
-  function count(type, { minImportance = null, source = null, includeForgotten = false, includeArchived = false, onlyArchived = false, depositedOnly = false, updatedFrom = null, updatedTo = null } = {}) {
+  function count(type, { minImportance = null, source = null, includeForgotten = false, includeArchived = false, onlyArchived = false, depositedOnly = false, updatedFrom = null, updatedTo = null, occurredFrom = null, occurredTo = null, visibility = null } = {}) {
     const clauses = [];
     const params = [];
     if (type !== undefined) {
@@ -670,6 +759,36 @@ export function createStore(path) {
       clauses.push("updated_at <= ?");
       params.push(bounds.to);
     }
+    // occurred_at 闭区间：与 list() 同口径（COALESCE 回退 created_at），
+    // memory_list 的 total 才能和过滤后的行保持一致。
+    const occurred = updatedAtBounds(occurredFrom, occurredTo);
+    if (occurred.from) {
+      clauses.push("COALESCE(occurred_at, created_at) >= ?");
+      params.push(occurred.from);
+    }
+    if (occurred.to) {
+      clauses.push("COALESCE(occurred_at, created_at) <= ?");
+      params.push(occurred.to);
+    }
+    // occurred_at 闭区间：与 list() 同过滤（visibility 同口径），memory_list
+    // 的 total 才能和过滤后的行保持一致。
+    if (visibility) {
+      // v0.8.1 第 3 步（issue #170 4.3）：硬过滤只认显式声明——与
+      // service.isVisibleInScope 同口径。IS NOT 是 NULL 安全比较：来源为
+      // auto/NULL（v0.8.0 存量自动标注）的行不吃硬墙，只走 A2 软加权。
+      if (visibility.agentScope != null) {
+        clauses.push("(agent_scope IS NULL OR agent_scope_source IS NOT 'explicit' OR agent_scope = ?)");
+        params.push(visibility.agentScope);
+      } else {
+        clauses.push("(agent_scope IS NULL OR agent_scope_source IS NOT 'explicit')");
+      }
+      if (visibility.workspaceScope != null) {
+        clauses.push("(workspace_scope IS NULL OR workspace_scope_source IS NOT 'explicit' OR workspace_scope = ?)");
+        params.push(visibility.workspaceScope);
+      } else {
+        clauses.push("(workspace_scope IS NULL OR workspace_scope_source IS NOT 'explicit')");
+      }
+    }
     if (!includeForgotten) {
       clauses.push("forgotten = 0");
     }
@@ -714,8 +833,8 @@ export function createStore(path) {
       : inferEpistemicStatus(memory);
     runAtomically(() => {
       db.prepare(
-        `INSERT INTO memories (id, type, title, content, tags, importance, forgotten, archived, source, content_history, quality_score, embedding, epistemic_status, created_at, updated_at)
-         VALUES (?, ?, ?, ?, ?, ?, 0, ?, ?, ?, ?, ?, ?, ?, ?)`
+        `INSERT INTO memories (id, type, title, content, tags, importance, forgotten, archived, source, content_history, quality_score, embedding, epistemic_status, agent_scope, workspace_scope, agent_scope_source, workspace_scope_source, scope_decided_at, sensitivity, occurred_at, created_at, updated_at)
+         VALUES (?, ?, ?, ?, ?, ?, 0, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`
       ).run(
         id,
         type,
@@ -729,6 +848,13 @@ export function createStore(path) {
         Number.isFinite(memory.quality_score) ? memory.quality_score : null,
         embedding,
         epistemicStatus,
+        normalizeScopeText(memory.agent_scope),
+        normalizeScopeText(memory.workspace_scope),
+        normalizeScopeSource(memory.agent_scope_source),
+        normalizeScopeSource(memory.workspace_scope_source),
+        normalizeOccurredAt(memory.scope_decided_at),
+        normalizeScopeText(memory.sensitivity),
+        normalizeOccurredAt(memory.occurred_at),
         now,
         now
       );
@@ -760,9 +886,26 @@ export function createStore(path) {
     const qualityScore = patch.quality_score !== undefined && Number.isFinite(patch.quality_score)
       ? patch.quality_score
       : (existing.quality_score ?? null);
+    // v0.8.1 底座（issue #170）：scope 列只在本 patch 显式携带该键时才改写
+    // （undefined=不动；null=清空为未标注/global）。来源列只认 auto|explicit。
+    const nextAgentScope = patch.agent_scope !== undefined
+      ? normalizeScopeText(patch.agent_scope)
+      : (existing.agent_scope ?? null);
+    const nextWorkspaceScope = patch.workspace_scope !== undefined
+      ? normalizeScopeText(patch.workspace_scope)
+      : (existing.workspace_scope ?? null);
+    const nextAgentSource = patch.agent_scope_source !== undefined
+      ? normalizeScopeSource(patch.agent_scope_source)
+      : (existing.agent_scope_source ?? null);
+    const nextWorkspaceSource = patch.workspace_scope_source !== undefined
+      ? normalizeScopeSource(patch.workspace_scope_source)
+      : (existing.workspace_scope_source ?? null);
+    const nextDecidedAt = patch.scope_decided_at !== undefined
+      ? normalizeOccurredAt(patch.scope_decided_at)
+      : (existing.scope_decided_at ?? null);
     runAtomically(() => {
       db.prepare(
-        `UPDATE memories SET type=?, title=?, content=?, tags=?, importance=?, source=?, content_history=?, quality_score=?, embedding=?, epistemic_status=?, updated_at=? WHERE id=?`
+        `UPDATE memories SET type=?, title=?, content=?, tags=?, importance=?, source=?, content_history=?, quality_score=?, embedding=?, epistemic_status=?, agent_scope=?, workspace_scope=?, agent_scope_source=?, workspace_scope_source=?, scope_decided_at=?, updated_at=? WHERE id=?`
       ).run(
         type,
         patch.title ?? existing.title,
@@ -774,6 +917,11 @@ export function createStore(path) {
         qualityScore,
         embedding,
         epistemicStatus,
+        nextAgentScope,
+        nextWorkspaceScope,
+        nextAgentSource,
+        nextWorkspaceSource,
+        nextDecidedAt,
         now,
         id
       );
@@ -936,7 +1084,7 @@ export function createStore(path) {
     return rows.map(toRow);
   }
 
-  function list({ type, limit = 50, offset = 0, order = "importance", includeForgotten = false, includeArchived = false, onlyArchived = false, depositedOnly = false, minImportance = null, source = null, updatedFrom = null, updatedTo = null } = {}) {
+  function list({ type, limit = 50, offset = 0, order = "importance", includeForgotten = false, includeArchived = false, onlyArchived = false, depositedOnly = false, minImportance = null, source = null, updatedFrom = null, updatedTo = null, occurredFrom = null, occurredTo = null, visibility = null } = {}) {
     const clauses = [];
     const params = [];
     if (type) {
@@ -964,6 +1112,40 @@ export function createStore(path) {
       clauses.push("updated_at <= ?");
       params.push(bounds.to);
     }
+    // v0.8.0 A2（issue #17）：occurred_at 闭区间过滤——按「事件发生时间」检索。
+    // 未标注 occurred_at 的行（含全部存量）回退 created_at 比较（COALESCE），
+    // 否则过滤器对旧库近乎不可用；边界归一化与 updated_at 共用 updatedAtBounds。
+    const occurred = updatedAtBounds(occurredFrom, occurredTo);
+    if (occurred.from) {
+      clauses.push("COALESCE(occurred_at, created_at) >= ?");
+      params.push(occurred.from);
+    }
+    if (occurred.to) {
+      clauses.push("COALESCE(occurred_at, created_at) <= ?");
+      params.push(occurred.to);
+    }
+    // v0.8.0 A3（issue #17）：strictScope 硬过滤（memory_list 分页路径）。
+    // SQL 与 service.isVisibleInScope 同口径：未标注(NULL)恒可见；v0.8.1 起
+    // 硬墙只认 explicit 来源（4.3），当前维度解析不到时该维度只放行未标注/
+    // 非显式行（fail-closed 收窄）。只有显式传 visibility 的用户面调用才
+    // 过滤——dream/质量过滤等内部 store.list 调用不受影响。
+    if (visibility) {
+      // v0.8.1 第 3 步（issue #170 4.3）：硬过滤只认显式声明——与
+      // service.isVisibleInScope 同口径。IS NOT 是 NULL 安全比较：来源为
+      // auto/NULL（v0.8.0 存量自动标注）的行不吃硬墙，只走 A2 软加权。
+      if (visibility.agentScope != null) {
+        clauses.push("(agent_scope IS NULL OR agent_scope_source IS NOT 'explicit' OR agent_scope = ?)");
+        params.push(visibility.agentScope);
+      } else {
+        clauses.push("(agent_scope IS NULL OR agent_scope_source IS NOT 'explicit')");
+      }
+      if (visibility.workspaceScope != null) {
+        clauses.push("(workspace_scope IS NULL OR workspace_scope_source IS NOT 'explicit' OR workspace_scope = ?)");
+        params.push(visibility.workspaceScope);
+      } else {
+        clauses.push("(workspace_scope IS NULL OR workspace_scope_source IS NOT 'explicit')");
+      }
+    }
     if (!includeForgotten) {
       clauses.push("forgotten = 0");
     }
@@ -1520,7 +1702,14 @@ export function createStore(path) {
    * order is normalized (sorted by id) so the same two memories are only ever
    * pending once — a re-detection in a later dream run is a no-op, never a
    * duplicate queue entry. Returns the pending row (freshly inserted, or the
-   * existing unresolved row when the pair is already pending).
+   * existing unresolved row when the pair is already pending), or undefined
+   * when the re-detection is suppressed.
+   *
+   * v0.8.1（issue #170 复核项 4）：人工已裁决过的对（resolved_at 非空）不再
+   * 反复入队——除非任一侧在裁决之后又被改过（updated_at 晚于 resolved_at）。
+   * 否则跨 scope 对每轮 sleep 都原样回来，把「保留双方」的决定变成噪声。
+   * updated_at 是宽松代理（任何字段更新都会触发重新评审）——宁可多看一眼，
+   * 不静音真冲突。
    */
   function saveConflictPending({ run_id, memory_a, memory_b, reason }) {
     const [a, b] = [memory_a, memory_b].sort();
@@ -1528,6 +1717,15 @@ export function createStore(path) {
       "SELECT * FROM conflict_pending WHERE memory_a = ? AND memory_b = ? AND resolved_at IS NULL LIMIT 1"
     ).get(a, b);
     if (existing) return toConflictPending(existing);
+    const reviewed = db.prepare(
+      "SELECT * FROM conflict_pending WHERE memory_a = ? AND memory_b = ? AND resolved_at IS NOT NULL ORDER BY resolved_at DESC, rowid DESC LIMIT 1"
+    ).get(a, b);
+    if (reviewed) {
+      const touched = db.prepare(
+        "SELECT count(*) AS c FROM memories WHERE id IN (?, ?) AND updated_at > ?"
+      ).get(a, b, reviewed.resolved_at).c;
+      if (touched === 0) return undefined;
+    }
     const id = randomUUID();
     const now = nowIso();
     db.prepare(
@@ -1573,6 +1771,44 @@ export function createStore(path) {
     ).get().c;
   }
 
+  /**
+   * v0.8.1 底座（issue #170）：scope 归属人工修正的审计行。record 描述「一次
+   * 决策后的完整状态」（prev_* 为改前、next_* 为改后，NULL=global/未标注），
+   * 由调用方（service.updateMemory）在 store.update 成功后写入；本函数不做
+   * 业务校验，只保证审计落库失败不反噬主写入（异常上抛由调用方吞掉记 warn）。
+   */
+  function saveScopeChange({ memory_id, actor, prev_agent_scope, prev_workspace_scope, next_agent_scope, next_workspace_scope, agent_scope_source, workspace_scope_source, decided_at }) {
+    const id = randomUUID();
+    db.prepare(
+      `INSERT INTO scope_changes (id, memory_id, actor, prev_agent_scope, prev_workspace_scope, next_agent_scope, next_workspace_scope, agent_scope_source, workspace_scope_source, decided_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`
+    ).run(
+      id,
+      memory_id,
+      actor === "panel" ? "panel" : "tool",
+      normalizeScopeText(prev_agent_scope),
+      normalizeScopeText(prev_workspace_scope),
+      normalizeScopeText(next_agent_scope),
+      normalizeScopeText(next_workspace_scope),
+      normalizeScopeSource(agent_scope_source),
+      normalizeScopeSource(workspace_scope_source),
+      normalizeOccurredAt(decided_at) ?? nowIso()
+    );
+    return toScopeChange(db.prepare("SELECT * FROM scope_changes WHERE id = ?").get(id));
+  }
+
+  /** Scope 修正审计（单条记忆，新→旧）。审计回放与候选复核用。 */
+  function listScopeChanges(memoryId, { limit = 50 } = {}) {
+    const lim = Number.isInteger(limit) && limit > 0 ? Math.min(limit, 200) : 50;
+    // tiebreaker 用 rowid（追加写入的单调序）而非 id：decided_at 只有毫秒精度，
+    // 连续两次修正落在同一毫秒时 UUID 排序是随机的（CI windows/node24 抓到的
+    // 真实 flake）——审计回放要求「最新一条」确定。
+    const rows = db.prepare(
+      "SELECT * FROM scope_changes WHERE memory_id = ? ORDER BY decided_at DESC, rowid DESC LIMIT ?"
+    ).all(memoryId, lim);
+    return rows.map(toScopeChange);
+  }
+
   function getFailureStats({ since } = {}) {
     const clause = since ? "WHERE created_at >= ?" : "";
     const params = since ? [since] : [];
@@ -2038,6 +2274,8 @@ export function createStore(path) {
     listConflictPending,
     resolveConflictPending,
     countConflictPending,
+    saveScopeChange,
+    listScopeChanges,
     createEntity,
     findEntityByName,
     findEntityById,

package/lib/tools.js

@@ -1,4 +1,5 @@
 import { defineTool } from "@deepseek-ai/dsh-tools";
+import { createScopeResolver, normalizeExplicitScope } from "./scope.js";
 import { describeLocalRuntime, resolveRuntimeEntry } from "./runtime/loader.js";
 import { defaultRuntimeDir } from "./runtime/layout.js";
 import { hostModulesDir, loadRuntimeManifest, provisionRuntime } from "./runtime/provision.js";
@@ -25,11 +26,48 @@ const MEMORY_ITEM_SCHEMA = {
     tags: { type: "array", items: { type: "string" } },
     importance: { type: "integer", required: true },
     source: { type: "string" },
+    // v0.8.0 A2：scope 标注与事件发生时间随行透出（未标注时缺省，可选属性）。
+    // v0.8.1 底座：scope 来源（auto/explicit）与决策时间随行透出（同样可选）。
+    agent_scope: { type: "string" },
+    workspace_scope: { type: "string" },
+    agent_scope_source: { type: "string" },
+    workspace_scope_source: { type: "string" },
+    scope_decided_at: { type: "string" },
+    sensitivity: { type: "string" },
+    occurred_at: { type: "string" },
     created_at: { type: "string", required: true },
     updated_at: { type: "string", required: true }
   }
 };
 
+// v0.8.0 A2：occurred 时间窗参数 → store 过滤选项（list/count 同口径）；
+// 未传参返回空对象，既有调用方不受影响。（A3 复核：此处入参仅含 occurred 边界。）
+function occurredWindow(args) {
+  const from = args?.occurred_from ?? null;
+  const to = args?.occurred_to ?? null;
+  return from !== null || to !== null ? { occurredFrom: from, occurredTo: to } : {};
+}
+
+// v0.8.0 A3：strictScope 硬过滤的 visibility 选项（store.list/count 同口径）。
+// flag 关或会话 scope 未解析出（flag 关时解析器返回 null）→ 空对象不过滤；
+// scope 为 {null,null}（匿名会话）时照传——store 侧 fail-closed 只放行未标注行。
+function strictVisibility(config, scope) {
+  if (config?.strictScope !== true || !scope) return {};
+  return { visibility: { agentScope: scope.agent_scope, workspaceScope: scope.workspace_scope } };
+}
+
+// v0.8.0 A2：检索结果的 provenance 附加段——只在有标注时出现，未标注行渲染
+// 与 A2 前逐字节一致。
+const MEMORY_PROVENANCE = (m) => {
+  const parts = [];
+  if (m.occurred_at) parts.push(`occurred: ${m.occurred_at}`);
+  if (m.agent_scope || m.workspace_scope) {
+    parts.push(`scope: ${m.agent_scope ?? "global"} / ${m.workspace_scope ?? "global"}`);
+  }
+  if (m.sensitivity) parts.push(`sensitivity: ${m.sensitivity}`);
+  return parts.length ? ` | ${parts.join(" | ")}` : "";
+};
+
 export function createTools(ctx, service, config, embedder) {
   const toolsRegistry = ctx.tools;
   let registeredTools = REGISTERED_TOOLS.get(toolsRegistry);
@@ -37,6 +75,30 @@ export function createTools(ctx, service, config, embedder) {
     registeredTools = new Set();
     REGISTERED_TOOLS.set(toolsRegistry, registeredTools);
   }
+  // v0.8.0 A1/A2（issue #17）：会话 scope 解析（agentPreset + workspace 反查）。
+  // flag 关闭时恒返回 null——写入不标注，检索不加权，行为与 A1 前完全一致。
+  // logger 透传：registry 反查失败时 warnOnce 才有出口（否则静默降级无观测）。
+  const resolveSessionScope = createScopeResolver({ ctx, config, logger: ctx.logger });
+
+  // 复核项 4（issue #170）：strictScope 下他 scope（explicit）的行对工具侧按
+  // 「不存在」处理——update/delete 与 memory_get 同款无存在性泄漏。strictScope
+  // 关、或会话身份取不到（scope 为 null）时恒可见（与 get 的短路语义一致）。
+  const visibleUnderStrictScope = (memory, exec) => {
+    if (config?.strictScope !== true) return true;
+    const scope = resolveSessionScope(exec);
+    return !scope || service.isVisibleInScope(memory, scope);
+  };
+  // 在调用点以「展开恒为 undefined」的形态前置校验（抛错即中止写入）。
+  const assertVisibleForTool = (id, exec) => {
+    const memory = id ? service.getById(id) : undefined;
+    if (!visibleUnderStrictScope(memory, exec)) throw new Error("memory not found");
+    return undefined;
+  };
+  // delete 侧需要目标行本身判断存在性（不可见 = 视作不存在，不抛错）。
+  const visibleForTool = (id, exec) => {
+    const memory = id ? service.getById(id) : undefined;
+    return visibleUnderStrictScope(memory, exec) ? memory : undefined;
+  };
   const tools = [
     defineTool({
       name: "memory_save",
@@ -50,7 +112,11 @@ export function createTools(ctx, service, config, embedder) {
         content: { type: "string", required: true, description: "Memory body" },
         tags: { type: "array", items: { type: "string" }, description: "Optional tags" },
         importance: { type: "integer", description: "1-5; >= threshold auto-injects into future sessions" },
-        source: { type: "string", description: "Optional provenance" }
+        source: { type: "string", description: "Optional provenance" },
+        sensitivity: { type: "string", description: "Optional sensitivity label (free-form, e.g. personal). Same-title entries with different sensitivity stay separate instead of merging." },
+        occurred_at: { type: "string", description: "Optional ISO-8601 instant the remembered event happened (differs from write time). Invalid values are ignored." },
+        agent_scope: { type: "string", description: "Optional explicit agent-scope declaration (issue #170): 'global' or '*' makes this memory visible to every agent; any other value narrows it to that label. Overrides the automatic carrier label for this write; honored even when automatic scope labeling is disabled." },
+        workspace_scope: { type: "string", description: "Optional explicit workspace-scope declaration: 'global' or '*' makes this memory visible in every workspace; any other value narrows it to that label. Overrides the automatic carrier label for this write; honored even when automatic scope labeling is disabled." }
       },
       output: {
         schema: {
@@ -63,14 +129,34 @@ export function createTools(ctx, service, config, embedder) {
         },
         render: (_args, value) => TEXT_OUTPUT(`memory ${value.action}: ${value.id}`)
       },
-      async execute(args) {
+      async execute(args, exec) {
+        // scope 标注（v0.8.1 底座，issue #170）：默认由会话身份解析（载体自动
+        // 标注，盖 auto 章）；显式 agent_scope/workspace_scope 参数逐维覆盖并盖
+        // explicit 章。解析绝不抛错、取不到落 NULL。
+        // 复核项 2（#170）：scopeEnabled 只门控「自动标注」分支——显式声明与
+        // 读取身份（search/list/get/注入经同一解析器）不受 flag 限制，否则
+        // strictScope 硬墙会被 flag 静默拆掉（fail-open）。
+        // （存储 NULL，由 source 列与「从未标注」区分）。非字符串参数在工具
+        // 入参 schema 层即被拒（type: "string"）——脏值到不了归一化，无静默放宽。
+        const scope = resolveSessionScope(exec);
+        const autoStamping = config?.scopeEnabled === true;
+        const agentLabel = args.agent_scope !== undefined
+          ? { value: normalizeExplicitScope(args.agent_scope), source: "explicit" }
+          : autoStamping && scope ? { value: scope.agent_scope, source: "auto" } : null;
+        const workspaceLabel = args.workspace_scope !== undefined
+          ? { value: normalizeExplicitScope(args.workspace_scope), source: "explicit" }
+          : autoStamping && scope ? { value: scope.workspace_scope, source: "auto" } : null;
         const { action, memory } = service.saveWithDedupe({
           type: args.type,
           title: args.title,
           content: args.content,
           tags: args.tags ?? [],
           importance: args.importance ?? 3,
-          source: args.source ?? "tool"
+          source: args.source ?? "tool",
+          ...(agentLabel ? { agent_scope: agentLabel.value, agent_scope_source: agentLabel.source } : {}),
+          ...(workspaceLabel ? { workspace_scope: workspaceLabel.value, workspace_scope_source: workspaceLabel.source } : {}),
+          ...(args.sensitivity !== undefined ? { sensitivity: args.sensitivity } : {}),
+          ...(args.occurred_at !== undefined ? { occurred_at: args.occurred_at } : {})
         });
         return { action, id: memory.id };
       }
@@ -79,12 +165,15 @@ export function createTools(ctx, service, config, embedder) {
     defineTool({
       name: "memory_search",
       description: "Search the cross-session memory store. Use when you need past context: how a problem was solved, user preferences, project decisions. Substring-matches title/content/tags, and augments results with semantic (vector) recall + optional rerank when an embeddings provider is configured. Returns matching entries with source and timestamps.",
+      // A2 检索接线：occurred 时间窗 + 会话 scope 加成（见 execute）。
       parameters: {
         query: { type: "string", required: true, description: "Search text; substring match over title/content/tags" },
         limit: { type: "integer", description: "Max results (default 20)" },
         mode: { type: "string", enum: ["auto", "keyword", "vector", "hybrid"], description: "auto (default) = keyword hits first + vector fill when enabled; keyword = text only; vector = semantic recall first (falls back to keyword); hybrid = vector leads, keyword fills remaining slots" },
         semantic: { type: "boolean", description: "Shorthand: enable semantic (vector) recall (same as mode=vector when true)" },
-        rerank: { type: "boolean", description: "Run cross-encoder rerank over candidates when a local reranker is configured (default true)" }
+        rerank: { type: "boolean", description: "Run cross-encoder rerank over candidates when a local reranker is configured (default true)" },
+        occurred_from: { type: "string", description: "Optional ISO date/timestamp lower bound on when the remembered event happened (occurred_at, falling back to created_at). Date-only values are inclusive from that day's 00:00Z." },
+        occurred_to: { type: "string", description: "Optional ISO date/timestamp upper bound on occurred_at. Date-only values are inclusive through that day's 23:59:59.999Z." }
       },
       output: {
         schema: {
@@ -104,19 +193,26 @@ export function createTools(ctx, service, config, embedder) {
             .map((m, i) => {
               const preview = (m.content ?? "").replace(/\s+/g, " ").trim();
               const cut = preview.length > 200 ? `${preview.slice(0, 200)}…` : preview;
-              return `[${i + 1}] ${m.title}\n    ID: ${m.id} | type: ${m.type} | importance: ${m.importance} | updated: ${m.updated_at}\n    ${cut}`;
+              return `[${i + 1}] ${m.title}\n    ID: ${m.id} | type: ${m.type} | importance: ${m.importance} | updated: ${m.updated_at}${MEMORY_PROVENANCE(m)}\n    ${cut}`;
             })
             .join("\n\n");
           return TEXT_OUTPUT(`Found ${items.length} memory entr${items.length === 1 ? "y" : "ies"}:\n\n${body}`);
         }
       },
-      async execute(args) {
+      async execute(args, exec) {
         const limit = args.limit ?? 20;
         const mode = args.semantic === true && !args.mode ? "vector" : args.mode ?? "auto";
+        // v0.8.0 A2（issue #17）：scope 检索加权 + occurred 时间窗的检索接线。
+        // flag 关闭或解析不出 scope 时为 null，检索行为与 A2 前一致。
+        const scope = resolveSessionScope(exec);
+        const occurredFrom = args.occurred_from ?? null;
+        const occurredTo = args.occurred_to ?? null;
         const rows = await service.searchMemories(args.query, {
           mode,
           topK: limit,
-          useRerank: args.rerank !== false
+          useRerank: args.rerank !== false,
+          ...(scope ? { scope } : {}),
+          ...(occurredFrom !== null || occurredTo !== null ? { occurredFrom, occurredTo } : {})
         });
         return { items: service.toApiList(rows) };
       }
@@ -129,7 +225,9 @@ export function createTools(ctx, service, config, embedder) {
         type: { type: "string", enum: ["preference", "project", "decision", "history", "rejected_solution", "pitfall", "constraint"], description: "Filter by type; omit for all" },
         limit: { type: "integer", description: "Page size (default 50)" },
         offset: { type: "integer", description: "Page offset (default 0)" },
-        include_archived: { type: "boolean", description: "Include archived (hidden) entries so they can be found and restored (default false)" }
+        include_archived: { type: "boolean", description: "Include archived (hidden) entries so they can be found and restored (default false)" },
+        occurred_from: { type: "string", description: "Optional ISO date/timestamp lower bound on when the remembered event happened (occurred_at, falling back to created_at). Date-only values are inclusive from that day's 00:00Z." },
+        occurred_to: { type: "string", description: "Optional ISO date/timestamp upper bound on occurred_at. Date-only values are inclusive through that day's 23:59:59.999Z." }
       },
       output: {
         schema: {
@@ -147,7 +245,7 @@ export function createTools(ctx, service, config, embedder) {
           const items = value.items ?? [];
           if (items.length === 0) return TEXT_OUTPUT(`0 memory entries (of ${value.total}).`);
           const body = items
-            .map((m, i) => `[${i + 1}] ${m.title} (type=${m.type}, importance=${m.importance})\n    ID: ${m.id} | updated: ${m.updated_at}`)
+            .map((m, i) => `[${i + 1}] ${m.title} (type=${m.type}, importance=${m.importance})\n    ID: ${m.id} | updated: ${m.updated_at}${MEMORY_PROVENANCE(m)}`)
             .join("\n\n");
           return TEXT_OUTPUT(`${items.length} memory entries (of ${value.total}):\n\n${body}`);
         }
@@ -158,9 +256,13 @@ export function createTools(ctx, service, config, embedder) {
           type: args.type,
           limit: args.limit ?? 50,
           offset: args.offset ?? 0,
-          includeArchived
+          includeArchived,
+          ...occurredWindow(args),
+          // A3：strict 开启时按会话 scope 硬过滤（宿主按 (args, runContext) 调用，
+          // 从 arguments 取第二参）。
+          ...strictVisibility(config, resolveSessionScope(arguments[1]))
         }));
-        return { items: rows, total: service.count(args.type, { includeArchived }) };
+        return { items: rows, total: service.count(args.type, { includeArchived, ...occurredWindow(args), ...strictVisibility(config, resolveSessionScope(arguments[1])) }) };
       }
     }),
 
@@ -186,6 +288,10 @@ export function createTools(ctx, service, config, embedder) {
                 tags: { type: "array", items: { type: "string" } },
                 content: { type: "string", required: true },
                 source: { type: "string" },
+                agent_scope: { type: "string" },
+                workspace_scope: { type: "string" },
+                sensitivity: { type: "string" },
+                occurred_at: { type: "string" },
                 created_at: { type: "string" },
                 updated_at: { type: "string" }
               }
@@ -194,12 +300,19 @@ export function createTools(ctx, service, config, embedder) {
         },
         render: (_args, value) => {
           const m = value.memory;
-          return TEXT_OUTPUT(`${m.title}\nID: ${m.id} | type: ${m.type} | importance: ${m.importance}\n\n${m.content}`);
+          return TEXT_OUTPUT(`${m.title}\nID: ${m.id} | type: ${m.type} | importance: ${m.importance}${MEMORY_PROVENANCE(m)}\n\n${m.content}`);
         }
       },
       async execute(args) {
         const memory = service.getById(args.id);
         if (memory === undefined) throw new Error("memory not found");
+        // v0.8.0 A3：strictScope 下他 scope 的行按不存在处理（无存在性泄漏）。
+        // 宿主注册表按 (args, runContext) 两参调用处理器，从 arguments 取第二参。
+        const runContext = arguments[1];
+        const scope = resolveSessionScope(runContext);
+        if (config.strictScope === true && scope && !service.isVisibleInScope(memory, scope)) {
+          throw new Error("memory not found");
+        }
         return { memory: service.toApiList([memory])[0] };
       }
     }),
@@ -214,7 +327,9 @@ export function createTools(ctx, service, config, embedder) {
         type: { type: "string", enum: ["preference", "project", "decision", "history", "rejected_solution", "pitfall", "constraint"] },
         tags: { type: "array", items: { type: "string" } },
         importance: { type: "integer", description: "1-5" },
-        reason: { type: "string", description: "Optional context for the correction (what the user actually said/wanted), recorded for reflection" }
+        reason: { type: "string", description: "Optional context for the correction (what the user actually said/wanted), recorded for reflection" },
+        agent_scope: { type: "string", description: "Optional explicit agent-scope correction (issue #170): 'global' or '*' widens visibility to every agent; any other value narrows it to that label. Omit to keep the current agent scope. Recorded as an explicit scope decision (audited)." },
+        workspace_scope: { type: "string", description: "Optional explicit workspace-scope correction: 'global' or '*' widens visibility to every workspace; any other value narrows it to that label. Omit to keep the current workspace scope. Recorded as an explicit scope decision (audited)." }
       },
       output: {
         schema: {
@@ -240,7 +355,12 @@ export function createTools(ctx, service, config, embedder) {
           content: args.content,
           type: args.type,
           tags: args.tags,
-          importance: args.importance
+          importance: args.importance,
+          // 复核项 4（#170）：strictScope 下他 scope 的行按「不存在」处理（与 get 对齐），
+          // 展开恒为 undefined，仅承担写入前校验。
+          ...(assertVisibleForTool(args.id, arguments[1])),
+          ...(args.agent_scope !== undefined ? { agent_scope: args.agent_scope } : {}),
+          ...(args.workspace_scope !== undefined ? { workspace_scope: args.workspace_scope } : {})
         }, { query: args.reason });
         return { memory: { id: memory.id, title: memory.title, content: memory.content } };
       }
@@ -261,9 +381,10 @@ export function createTools(ctx, service, config, embedder) {
         render: (_args, value) => TEXT_OUTPUT(value.deleted ? "Memory deleted." : "Memory not found.")
       },
       async execute(args) {
-        const existed = service.getById(args.id) !== undefined;
-        if (existed) service.remove(args.id);
-        return { deleted: existed };
+        // 复核项 4（#170）：不可见（explicit 他 scope）= 视作不存在，无存在性泄漏。
+        const target = visibleForTool(args.id, arguments[1]);
+        if (target) service.remove(args.id);
+        return { deleted: !!target };
       }
     }),