feat(agent-workspace): add managed memory inspection capability

Author: Jacobinwwey

docs/diataxis/en/explanation/agent-conversation-focus-mode-plan.md

@@ -26,7 +26,7 @@ Implemented now:
 - the graph layout now reserves width for the docked workspace so the graph surface and agent surface can coexist.
 - graph-focus fullscreen now promotes the real graph workspace while keeping a restorable control card in front of it.
 - the new shell strings and runtime empty/fullscreen labels now have bilingual coverage, existing knowledge-card actions / localized system messages re-render on language switch, and conversation card rerender now flows through a centralized card-kind renderer registry in `workspace_panes` to reduce drift risk.
-- conversation knowledge points now carry an execution-capable typed descriptor surface: `focus` and `learning path` are joined by tutor-side `generate_quiz` / `recap` / `generate_transfer` / `generate_counterexample` / `follow_up`, query-side `compare_query_backends` / `inspect_query_backend_diagnostics` / `inspect_query_backend_comparison_history` / `inspect_query_backend_comparison_trend`, tutor diagnostics `inspect_tutor_adapter_telemetry` / `inspect_tutor_trace_diagnostics`, quality/session diagnostics (`inspect_learning_quality_trend` / `inspect_learning_quality_history` / `inspect_session_plan_quality_trend` / `inspect_session_plan_quality_history`), session-side `inspect_session_history` / `build_study_session`, and managed-memory operators (`inspect_memory_snapshot` / `inspect_unit_memory_snapshot` / `inspect_memory_retrain_plan` / `inspect_memory_read` / `write_memory_note` / `record_memory_correction` / `evict_memory_note`), while descriptors include execution, failure, and UI-hint metadata.
+- conversation knowledge points now carry an execution-capable typed descriptor surface: `focus` and `learning path` are joined by tutor-side `generate_quiz` / `recap` / `generate_transfer` / `generate_counterexample` / `follow_up`, query-side `compare_query_backends` / `inspect_query_backend_diagnostics` / `inspect_query_backend_comparison_history` / `inspect_query_backend_comparison_trend`, tutor diagnostics `inspect_tutor_adapter_telemetry` / `inspect_tutor_trace_diagnostics`, quality/session diagnostics (`inspect_learning_quality_trend` / `inspect_learning_quality_history` / `inspect_session_plan_quality_trend` / `inspect_session_plan_quality_history`), session-side `inspect_session_history` / `build_study_session`, and managed-memory operators (`inspect_memory_snapshot` / `inspect_unit_memory_snapshot` / `inspect_long_term_memory_snapshot` / `inspect_memory_retrain_plan` / `inspect_memory_read` / `inspect_long_term_memory_read` / `inspect_managed_memory_state` / `write_memory_note` / `record_memory_correction` / `evict_memory_note`), while descriptors include execution, failure, and UI-hint metadata.
 - browser smoke now exercises real `conversation/path/query-compare/query-compare-history/query-compare-trend/quality-trend/quality-history/session-plan-quality-trend/session-plan-quality-history/session-plan` backend flows, real graph runtime, and real path runtime with screenshot/console/network-summary evidence artifacts.
 
 Still open:
@@ -35,6 +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,
   - 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.

docs/diataxis/en/explanation/development-progress-dashboard.md

@@ -71,6 +71,25 @@ Execution anchor:
 - Changed the next bounded backend-governance slice:
   - keep repeated device-level measurement honest and move the next default budget into product/memory/operator work unless a measured trigger fires.
 
+## Latest Mainline Increment (2026-04-21 M8.20 Managed Memory Inspection Lane)
+
+- Added an explicit managed-memory inspection action without widening mutation scope:
+  - `inspect_managed_memory_state`.
+- Mainline capability emission now exposes deterministic per-atom managed-state lookup instead of forcing operators or users to infer it from broader session reads:
+  - `memoryLayer = session`,
+  - `memoryOperation = read`,
+  - `memoryLimit = 4`,
+  - `memoryMatchKeys = [conversation_note:{atomId}, conversation_correction:{atomId}]`.
+- Kept contract/runtime/backend behavior aligned for targeted read execution:
+  - frontend contract and runtime planners now forward `matchKeys` for read requests when present,
+  - learning-platform read execution now filters by `matchKeys` before applying query-token matching,
+  - no new write/delete semantics were introduced.
+- Expanded regression coverage for:
+  - conversation capability emission,
+  - frontend read payload shaping,
+  - runtime managed-memory execution payload forwarding,
+  - targeted backend read behavior.
+
 ## Latest Mainline Increment (2026-04-14 M1 Baseline)
 
 - Added first `AgentConversationAPI` contract surface:

docs/diataxis/en/explanation/local-backend-sufficiency-and-escalation-plan.md

@@ -26,6 +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,
 - 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.
 
@@ -70,7 +71,7 @@ The architecture baseline is no longer "pre-independence."
 That logic is also weak.
 The sharper gaps are currently:
 
-- explicit memory CRUD / correction surfaces,
+- broader explicit memory CRUD / correction/reporting surfaces beyond the current managed-key inspection/write/eviction scope,
 - conversation-product orchestration,
 - stable operator-facing reports,
 - clearer lane selection between product work and backend escalation.
@@ -242,7 +243,7 @@ If the backend sufficiency report remains green, backend escalation should pause
 Recommended next product order:
 
 1. conversation-product hardening:
-   - explicit conversation memory APIs,
+   - extend explicit conversation memory APIs beyond the current snapshot/read/managed-key inspection and note/correction/eviction surface,
    - correction / feedback flows,
    - stronger agent action surfaces around focus mode and learning path,
    - operator-facing visibility for those flows.

docs/diataxis/zh/explanation/agent-conversation-focus-mode-plan.md

@@ -24,7 +24,7 @@
 - 图谱布局已经为 docked workspace 预留宽度，graph surface 与 agent surface 可以并存。
 - graph focus 的 fullscreen 已可提升真实 graph workspace，同时保留一个可恢复的控制卡；
 - 新壳层静态文案与运行时按钮/空态标签已具备双语覆盖，且已有知识卡片动作按钮与本地化系统消息会在语言切换时重渲；conversation card 的重渲链路也已收敛为 `workspace_panes` 中的 card-kind 注册表驱动，降低后续漂移风险。
-- conversation knowledge point 现在已经具备可执行 typed descriptor：除 `focus` / `learning path` 外，已接入 tutor 侧 `generate_quiz` / `recap` / `generate_transfer` / `generate_counterexample` / `follow_up`、query 侧 `compare_query_backends` / `inspect_query_backend_diagnostics` / `inspect_query_backend_comparison_history` / `inspect_query_backend_comparison_trend`、导师诊断侧 `inspect_tutor_adapter_telemetry` / `inspect_tutor_trace_diagnostics`、质量/会话诊断侧 `inspect_learning_quality_trend` / `inspect_learning_quality_history` / `inspect_session_plan_quality_trend` / `inspect_session_plan_quality_history`、session 侧 `inspect_session_history` / `build_study_session`，以及托管记忆操作（`inspect_memory_snapshot` / `inspect_unit_memory_snapshot` / `inspect_memory_retrain_plan` / `inspect_memory_read` / `write_memory_note` / `record_memory_correction` / `evict_memory_note`），同时补齐 execution / failure / UI hint 元数据。
+- conversation knowledge point 现在已经具备可执行 typed descriptor：除 `focus` / `learning path` 外，已接入 tutor 侧 `generate_quiz` / `recap` / `generate_transfer` / `generate_counterexample` / `follow_up`、query 侧 `compare_query_backends` / `inspect_query_backend_diagnostics` / `inspect_query_backend_comparison_history` / `inspect_query_backend_comparison_trend`、导师诊断侧 `inspect_tutor_adapter_telemetry` / `inspect_tutor_trace_diagnostics`、质量/会话诊断侧 `inspect_learning_quality_trend` / `inspect_learning_quality_history` / `inspect_session_plan_quality_trend` / `inspect_session_plan_quality_history`、session 侧 `inspect_session_history` / `build_study_session`，以及托管记忆操作（`inspect_memory_snapshot` / `inspect_unit_memory_snapshot` / `inspect_long_term_memory_snapshot` / `inspect_memory_retrain_plan` / `inspect_memory_read` / `inspect_long_term_memory_read` / `inspect_managed_memory_state` / `write_memory_note` / `record_memory_correction` / `evict_memory_note`），同时补齐 execution / failure / UI hint 元数据。
 - browser smoke 已覆盖真实 `conversation/path/query-compare/query-compare-history/query-compare-trend/quality-trend/quality-history/session-plan-quality-trend/session-plan-quality-history/session-plan` 后端链路、真实 graph runtime、真实 path runtime，并会输出 screenshot / console / network-summary 证据产物。
 
 仍未完成：
@@ -33,6 +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 的确定性托管状态检查，
   - 写入仅落在 session 层托管 note/correction，
   - 清理仅移除当前 atom 对应的确定性托管 key，
   - 这是产品侧 memory operator surface，不是“完整记忆管理后台已完成”的宣称。

docs/diataxis/zh/explanation/development-progress-dashboard.md

@@ -71,6 +71,25 @@
 - 已更新下一段有界 backend governance 切片：
   - 保持设备级测量诚实，把默认预算转向 product / memory / operator 工作，除非 measured trigger 真实触发。
 
+## 主线最新增量（2026-04-21 M8.20 托管记忆定向检查链路）
+
+- 已新增一个显式托管记忆检查动作，但没有扩大 mutation scope：
+  - `inspect_managed_memory_state`。
+- 主线 capability 发射现在直接暴露按 atom 定位的确定性托管状态读取，不再要求用户或 operator 从更宽泛的 session read 结果里自行推断：
+  - `memoryLayer = session`，
+  - `memoryOperation = read`，
+  - `memoryLimit = 4`，
+  - `memoryMatchKeys = [conversation_note:{atomId}, conversation_correction:{atomId}]`。
+- contract/runtime/backend 三层对定向读取保持一致：
+  - 当前端 contract 与 runtime planner 遇到 read + `memoryMatchKeys` 时，会显式透传 `matchKeys`，
+  - learning-platform 的 read 执行会先按 `matchKeys` 过滤，再应用 query-token 匹配，
+  - 没有引入新的写入/删除语义。
+- 回归覆盖同步扩展到：
+  - conversation capability 发射，
+  - 前端 read payload 组装，
+  - runtime 托管记忆执行 payload 透传，
+  - backend 定向读取行为。
+
 ## 主线最新增量（2026-04-14 M1 基线）
 
 - 已新增第一版 `AgentConversationAPI` 合同面：

docs/diataxis/zh/explanation/local-backend-sufficiency-and-escalation-plan.md

@@ -26,6 +26,7 @@
 首个 post-checkpoint product-memory 增量已经落在 `main`：
 
 - agent workspace 已暴露只读 `long_term` memory snapshot/read 动作，
+- 对话 lane 现在也已暴露针对所选 atom 的只读确定性托管状态检查，
 - 托管写入/修正/清理仍然按设计限制在 session 层。
 - operator diagnostics 现在会按 layer / operation 汇总 memory-policy 执行情况，使这条 product-memory 主线可观测、不可黑箱化。
 
@@ -70,7 +71,7 @@
 这个逻辑当前也站不住。
 真正更尖锐的缺口是：
 
-- 显式 memory CRUD / correction surface，
+- 在当前托管 key 检查 / 写入 / 清理能力之外，更完整的显式 memory CRUD / correction / reporting surface，
 - conversation-product orchestration，
 - 稳定的 operator-facing report，
 - 在产品工作与 backend 升级之间更明确的 lane 选择。
@@ -241,7 +242,7 @@
 推荐的产品推进顺序：
 
 1. conversation-product 加固：
-   - 显式 conversation memory API，
+   - 在当前 snapshot/read/托管 key 检查与 note/correction/eviction 能力之上继续扩展显式 conversation memory API，
    - correction / feedback 流程，
    - 围绕 focus mode 与 learning path 的更强 agent action surface，
    - 与这些链路配套的 operator-facing visibility。

src/agent_workspace.frontend.test.ts

@@ -479,6 +479,36 @@ describe('agent_workspace frontend operation contract', () => {
         });
     });
 
+    test('apply_memory_policy builds read payload with targeted matchKeys passthrough', () => {
+        const requestPlan = buildKnowledgeOperationRequestPayload({
+            request: {
+                userId: 'learner-a',
+                atomId: 'atom-2',
+                memoryLayer: 'session',
+                memoryOperation: 'read',
+                memoryLimit: 4,
+                memoryMatchKeys: ['conversation_note:atom-2', 'conversation_correction:atom-2'],
+            },
+            execution: {
+                operationId: 'apply_memory_policy',
+            },
+        });
+
+        expect(requestPlan).toEqual({
+            operationId: 'apply_memory_policy',
+            endpoint: '/api/knowledge/memory/policy',
+            method: 'POST',
+            resultPresentation: 'memory_policy_card',
+            body: {
+                userId: 'learner-a',
+                layer: 'session',
+                operation: 'read',
+                limit: 4,
+                matchKeys: ['conversation_note:atom-2', 'conversation_correction:atom-2'],
+            },
+        });
+    });
+
     test('unsupported operation result presentation fails fast', () => {
         expect(() =>
             resolveOperationResultPresentation('build_learning_path', 'tutor_action_card')