feat(agent-workspace): surface managed memory state visibility

Jacobinwwey · Jacobinwwey · commit 3a1926a31dd5 · 2026-04-21T04:06:54.000-05:00
diff --git a/docs/diataxis/en/explanation/agent-conversation-focus-mode-plan.md b/docs/diataxis/en/explanation/agent-conversation-focus-mode-plan.md
@@ -35,7 +35,7 @@ Still open:
 - long-lived dynamic conversation cards beyond the current `study_session_card` / `tutor_action_card` / `session_history_card` / `query_backend_comparison_card` / `query_backend_diagnostics_card` / `query_backend_comparison_history_card` / `query_backend_comparison_trend_card` / `tutor_adapter_telemetry_card` / `tutor_trace_diagnostics_card` / `learning_quality_trend_card` / `learning_quality_history_card` / `session_plan_quality_trend_card` / `session_plan_quality_history_card` paths now share registry-driven rerender wiring, and a source-level guard test now enforces append-kind/registry parity (`src/agent_workspace.frontend.test.ts`); follow-up work is to keep each new card kind wired through that gate by default.
 - the execution-capable contract is now present and no longer limited to quiz/recap, but it still has room to absorb broader tutor/query/session operations beyond the currently shipped action band.
 - managed memory mutation is now present in the conversation lane, but it remains intentionally scoped:
-  - read-side inspection now includes deterministic managed-state lookup for the selected atom,
+  - read-side inspection now includes deterministic managed-state lookup plus explicit present/missing managed-key visibility for the selected atom,
   - writes are limited to session-layer managed notes/corrections,
   - eviction only removes the deterministic managed keys for the selected atom,
   - this is a product-side memory operator surface, not a claim of full memory-admin tooling.
diff --git a/docs/diataxis/en/explanation/development-progress-dashboard.md b/docs/diataxis/en/explanation/development-progress-dashboard.md
@@ -90,6 +90,21 @@ Execution anchor:
   - runtime managed-memory execution payload forwarding,
   - targeted backend read behavior.
 
+## Latest Mainline Increment (2026-04-21 M8.21 Managed Memory State Visibility Lane)
+
+- Upgraded managed-memory inspection from count-only output to actionable state visibility:
+  - targeted `read` responses now expose filter metadata for `matchKeys`,
+  - backend now returns `matchedKeys`, `missingKeys`, and `returnedEntries` for targeted reads.
+- Kept scope intentionally narrow:
+  - this is still a read-only visibility improvement,
+  - no new memory mutation semantics or persistence model were introduced.
+- Runtime assistant summaries now surface actual managed-state presence instead of generic snapshot counts:
+  - targeted reads report which managed key classes are present,
+  - missing managed keys are surfaced explicitly for correction-follow-up work.
+- Expanded regression coverage for:
+  - backend targeted-read filter metadata,
+  - runtime managed-memory state messaging for present vs missing managed keys.
+
 ## Latest Mainline Increment (2026-04-14 M1 Baseline)
 
 - Added first `AgentConversationAPI` contract surface:
diff --git a/docs/diataxis/en/explanation/local-backend-sufficiency-and-escalation-plan.md b/docs/diataxis/en/explanation/local-backend-sufficiency-and-escalation-plan.md
@@ -26,7 +26,7 @@ Current default posture:
 First post-checkpoint product-memory slice now landed on `main`:
 
 - agent workspace exposes read-only `long_term` memory snapshot/read actions,
-- the conversation lane now exposes read-only deterministic managed-state inspection for the selected atom,
+- the conversation lane now exposes read-only deterministic managed-state inspection with explicit present/missing key visibility for the selected atom,
 - managed mutation remains session-scoped by design.
 - operator diagnostics now summarize memory-policy execution by layer and operation, so the new product-memory lane is inspectable instead of opaque.
 
diff --git a/docs/diataxis/zh/explanation/agent-conversation-focus-mode-plan.md b/docs/diataxis/zh/explanation/agent-conversation-focus-mode-plan.md
@@ -33,7 +33,7 @@
 - 当前 `study_session_card` / `tutor_action_card` / `session_history_card` / `query_backend_comparison_card` / `query_backend_diagnostics_card` / `query_backend_comparison_history_card` / `query_backend_comparison_trend_card` / `tutor_adapter_telemetry_card` / `tutor_trace_diagnostics_card` / `learning_quality_trend_card` / `learning_quality_history_card` / `session_plan_quality_trend_card` / `session_plan_quality_history_card` 已支持语言切换后重渲，且已统一走注册表驱动；同时已新增源码级门禁测试校验 append-kind 与注册表键集合一致（`src/agent_workspace.frontend.test.ts`）。后续新增 card kind 时，需要默认通过该门禁。
 - 可执行 contract 已具备，且不再只停留在 quiz/recap，但仍需继续吸收更广的 tutor/query/session 动作。
 - 对话 lane 现在已具备受控记忆写入/修正/清理动作，但范围被刻意收窄：
-  - 读取侧现在也支持针对所选 atom 的确定性托管状态检查，
+  - 读取侧现在也支持针对所选 atom 的确定性托管状态检查，并显式返回“已存在/缺失”的托管 key 状态，
   - 写入仅落在 session 层托管 note/correction，
   - 清理仅移除当前 atom 对应的确定性托管 key，
   - 这是产品侧 memory operator surface，不是“完整记忆管理后台已完成”的宣称。
diff --git a/docs/diataxis/zh/explanation/development-progress-dashboard.md b/docs/diataxis/zh/explanation/development-progress-dashboard.md
@@ -90,6 +90,21 @@
   - runtime 托管记忆执行 payload 透传，
   - backend 定向读取行为。
 
+## 主线最新增量（2026-04-21 M8.21 托管记忆状态可见性链路）
+
+- 托管记忆检查已从“只返回数量”升级为“返回可行动状态”：
+  - 定向 `read` 响应现在会显式暴露 `matchKeys` 过滤元数据，
+  - backend 现在返回 `matchedKeys`、`missingKeys` 与 `returnedEntries`。
+- 范围仍然刻意保持收敛：
+  - 这仍然只是只读可见性增强，
+  - 没有引入新的记忆 mutation 语义，也没有引入新的持久化模型。
+- runtime assistant 摘要现在会暴露真实托管状态，而不是继续使用泛化 snapshot 计数：
+  - 定向读取会报告哪些托管 key 类别已存在，
+  - 缺失的托管 key 也会被显式指出，便于后续 correction 跟进。
+- 回归覆盖同步扩展到：
+  - backend 定向读取过滤元数据，
+  - runtime 托管记忆状态消息对“已存在/缺失”键的断言。
+
 ## 主线最新增量（2026-04-14 M1 基线）
 
 - 已新增第一版 `AgentConversationAPI` 合同面：
diff --git a/docs/diataxis/zh/explanation/local-backend-sufficiency-and-escalation-plan.md b/docs/diataxis/zh/explanation/local-backend-sufficiency-and-escalation-plan.md
@@ -26,7 +26,7 @@
 首个 post-checkpoint product-memory 增量已经落在 `main`：
 
 - agent workspace 已暴露只读 `long_term` memory snapshot/read 动作，
-- 对话 lane 现在也已暴露针对所选 atom 的只读确定性托管状态检查，
+- 对话 lane 现在也已暴露针对所选 atom 的只读确定性托管状态检查，并能显式区分已存在/缺失的托管 key，
 - 托管写入/修正/清理仍然按设计限制在 session 层。
 - operator diagnostics 现在会按 layer / operation 汇总 memory-policy 执行情况，使这条 product-memory 主线可观测、不可黑箱化。
 
diff --git a/src/agent_workspace.runtime.behavior.test.ts b/src/agent_workspace.runtime.behavior.test.ts
@@ -1807,8 +1807,16 @@ describe('agent workspace runtime behavior', () => {
                         operation: 'read',
                         entries: [
                             { key: 'conversation_note:atom-memory-managed-1', value: 'managed note' },
-                            { key: 'conversation_correction:atom-memory-managed-1', value: 'managed correction' },
                         ],
+                        filter: {
+                            matchKeys: [
+                                'conversation_note:atom-memory-managed-1',
+                                'conversation_correction:atom-memory-managed-1',
+                            ],
+                            matchedKeys: ['conversation_note:atom-memory-managed-1'],
+                            missingKeys: ['conversation_correction:atom-memory-managed-1'],
+                            returnedEntries: 1,
+                        },
                         evictedCount: 0,
                         stats: {
                             session: 4,
@@ -1855,6 +1863,8 @@ describe('agent workspace runtime behavior', () => {
 
         const messages = document.getElementById('agent-workspace-messages') as HTMLElement;
         expect(messages.textContent || '').toContain('session/read');
+        expect(messages.textContent || '').toContain('present note');
+        expect(messages.textContent || '').toContain('missing correction');
     });
 
     test('executes memory write capability, prompts for note text, and persists deterministic key', async () => {
diff --git a/src/frontend/agent_workspace_runtime.js b/src/frontend/agent_workspace_runtime.js
@@ -175,6 +175,28 @@
             return Math.max(1, Math.min(100, Math.floor(base)));
         }
 
+        function formatMemoryKeyLabel(rawKey) {
+            const key = trimString(rawKey);
+            if (!key) {
+                return '';
+            }
+            if (key.startsWith('conversation_note:')) {
+                return 'note';
+            }
+            if (key.startsWith('conversation_correction:')) {
+                return 'correction';
+            }
+            const segments = key.split(':').map((segment) => trimString(segment)).filter((segment) => segment.length > 0);
+            return segments.length > 1 ? segments[segments.length - 1] : key;
+        }
+
+        function summarizeMemoryKeyLabels(keys) {
+            const labels = resolveStringArray(keys)
+                .map((key) => formatMemoryKeyLabel(key))
+                .filter((label) => label.length > 0);
+            return labels.length ? labels.join(', ') : 'none';
+        }
+
         function resolveMisconceptionTopK(rawTopK, fallback) {
             const numericTopK = Number(rawTopK);
             const numericFallback = Number(fallback);
@@ -1459,6 +1481,9 @@
                     const stats = result && result.stats && typeof result.stats === 'object'
                         ? result.stats
                         : {};
+                    const filter = result && result.filter && typeof result.filter === 'object'
+                        ? result.filter
+                        : {};
                     const entriesCount = Array.isArray(result && result.entries) ? result.entries.length : 0;
                     const recommendedActionsCount = Array.isArray(result && result.recommendedActions)
                         ? result.recommendedActions.length
@@ -1473,6 +1498,9 @@
                     const longTermCount = Number(stats.longTerm);
                     const layer = trimString(result && result.layer) || 'session';
                     const operation = trimString(result && result.operation) || 'snapshot';
+                    const targetedMatchKeys = resolveStringArray(filter && filter.matchKeys);
+                    const matchedKeys = resolveStringArray(filter && filter.matchedKeys);
+                    const missingKeys = resolveStringArray(filter && filter.missingKeys);
                     if (operation === 'write') {
                         appendMessage(
                             'assistant',
@@ -1510,6 +1538,25 @@
                         );
                         return;
                     }
+                    if (operation === 'read' && targetedMatchKeys.length > 0) {
+                        appendMessage(
+                            'assistant',
+                            getI18nText(
+                                'agentWorkspace.messages.memoryTargetedReadLoaded',
+                                `Memory targeted read loaded (${layer}/${operation}): present ${summarizeMemoryKeyLabels(matchedKeys)}, missing ${summarizeMemoryKeyLabels(missingKeys)}, totals session ${Number.isFinite(sessionCount) ? sessionCount : 0}, unit ${Number.isFinite(unitCount) ? unitCount : 0}, long-term ${Number.isFinite(longTermCount) ? longTermCount : 0}.`,
+                                {
+                                    layer,
+                                    operation,
+                                    matchedKeysSummary: summarizeMemoryKeyLabels(matchedKeys),
+                                    missingKeysSummary: summarizeMemoryKeyLabels(missingKeys),
+                                    sessionCount: Number.isFinite(sessionCount) ? sessionCount : 0,
+                                    unitCount: Number.isFinite(unitCount) ? unitCount : 0,
+                                    longTermCount: Number.isFinite(longTermCount) ? longTermCount : 0,
+                                }
+                            )
+                        );
+                        return;
+                    }
                     appendMessage(
                         'assistant',
                         getI18nText(
diff --git a/src/frontend/locales/en.json b/src/frontend/locales/en.json
@@ -294,7 +294,8 @@
       "memoryPolicyFailed": "Memory snapshot request failed.",
       "memoryWriteLoaded": "Memory updated ({layer}/{operation}): wrote {mutatedCount} entry, totals session {sessionCount}, unit {unitCount}, long-term {longTermCount}.",
       "memoryEvictLoaded": "Memory eviction completed ({layer}/{operation}): removed {evictedCount} entries, targeted keys {removedKeysCount}, totals session {sessionCount}, unit {unitCount}, long-term {longTermCount}.",
-      "memoryPolicyLoaded": "Memory snapshot loaded ({layer}/{operation}): {entriesCount} entries, evicted {evictedCount}, totals session {sessionCount}, unit {unitCount}, long-term {longTermCount}, recommended {recommendedActionsCount} actions."
+      "memoryPolicyLoaded": "Memory snapshot loaded ({layer}/{operation}): {entriesCount} entries, evicted {evictedCount}, totals session {sessionCount}, unit {unitCount}, long-term {longTermCount}, recommended {recommendedActionsCount} actions.",
+      "memoryTargetedReadLoaded": "Memory targeted read loaded ({layer}/{operation}): present {matchedKeysSummary}, missing {missingKeysSummary}, totals session {sessionCount}, unit {unitCount}, long-term {longTermCount}."
     }
   },
   "manual": {
diff --git a/src/frontend/locales/zh.json b/src/frontend/locales/zh.json
@@ -294,7 +294,8 @@
       "memoryPolicyFailed": "记忆快照请求失败。",
       "memoryWriteLoaded": "记忆已更新（{layer}/{operation}）：写入 {mutatedCount} 条，总量 session {sessionCount}、unit {unitCount}、long-term {longTermCount}。",
       "memoryEvictLoaded": "记忆清理已完成（{layer}/{operation}）：移除 {evictedCount} 条，命中键 {removedKeysCount} 个，总量 session {sessionCount}、unit {unitCount}、long-term {longTermCount}。",
-      "memoryPolicyLoaded": "记忆快照已加载（{layer}/{operation}）：{entriesCount} 条，清理 {evictedCount} 条，总量 session {sessionCount}、unit {unitCount}、long-term {longTermCount}，推荐动作 {recommendedActionsCount} 个。"
+      "memoryPolicyLoaded": "记忆快照已加载（{layer}/{operation}）：{entriesCount} 条，清理 {evictedCount} 条，总量 session {sessionCount}、unit {unitCount}、long-term {longTermCount}，推荐动作 {recommendedActionsCount} 个。",
+      "memoryTargetedReadLoaded": "定向记忆读取已加载（{layer}/{operation}）：已命中 {matchedKeysSummary}，缺失 {missingKeysSummary}，总量 session {sessionCount}、unit {unitCount}、long-term {longTermCount}。"
     }
   },
   "nodes": "节点",
diff --git a/src/learning/KnowledgeLearningPlatform.test.ts b/src/learning/KnowledgeLearningPlatform.test.ts
@@ -1185,6 +1185,15 @@ describe('KnowledgeLearningPlatform', () => {
                 'conversation_correction:target',
             ])
         );
+        expect(targetedReadResult.filter).toEqual({
+            matchKeys: ['conversation_note:target', 'conversation_correction:target'],
+            matchedKeys: expect.arrayContaining([
+                'conversation_note:target',
+                'conversation_correction:target',
+            ]),
+            missingKeys: [],
+            returnedEntries: 2,
+        });
 
         const retrainResult = await platform.applyMemoryPolicy({
             userId: 'user_tutor',
diff --git a/src/learning/KnowledgeLearningPlatform.ts b/src/learning/KnowledgeLearningPlatform.ts
@@ -2414,7 +2414,8 @@ export class KnowledgeLearningPlatform implements KnowledgeLearningPlatformAPI {
         if (operation === 'read') {
             const limit = clamp(Math.floor(Number(request.limit) || 20), 1, 100);
             const queryTokens = tokenize(String(request.query || ''));
-            const matchKeys = new Set(normalizeStringList(request.matchKeys));
+            const normalizedMatchKeys = normalizeStringList(request.matchKeys);
+            const matchKeys = new Set(normalizedMatchKeys);
             const selectedEntries = bank[layer]
                 .filter((entry) => {
                     if (matchKeys.size > 0 && !matchKeys.has(entry.key)) {
@@ -2428,11 +2429,22 @@ export class KnowledgeLearningPlatform implements KnowledgeLearningPlatformAPI {
                 })
                 .sort((left, right) => right.updatedAt.localeCompare(left.updatedAt))
                 .slice(0, limit);
+            const matchedKeys = selectedEntries.map((entry) => entry.key);
+            const matchedKeySet = new Set(matchedKeys);
             return {
                 layer,
                 operation,
                 entries: selectedEntries,
                 evictedCount: 0,
+                filter: {
+                    ...(queryTokens.length ? { query: String(request.query || '') } : {}),
+                    ...(normalizedMatchKeys.length ? { matchKeys: normalizedMatchKeys } : {}),
+                    ...(normalizedMatchKeys.length ? { matchedKeys } : {}),
+                    ...(normalizedMatchKeys.length
+                        ? { missingKeys: normalizedMatchKeys.filter((key) => !matchedKeySet.has(key)) }
+                        : {}),
+                    returnedEntries: selectedEntries.length,
+                },
                 stats: this.collectMemoryStats(),
             };
         }
diff --git a/src/learning/types.ts b/src/learning/types.ts
@@ -704,6 +704,13 @@ export interface MemoryPolicyResponse {
     evictedCount: number;
     mutatedCount?: number;
     removedKeys?: string[];
+    filter?: {
+        query?: string;
+        matchKeys?: string[];
+        matchedKeys?: string[];
+        missingKeys?: string[];
+        returnedEntries: number;
+    };
     recommendedActions?: LearningAction[];
     stats: {
         session: number;
