🎯 Codex ↔ Memory 跨项目运行可观测性计划（2026-11-03）

📌 结论摘要

本专题是 AgentMeshOS 与 Memory Server 的跨项目协作计划，不切换 AgentMeshOS 当前 P21 阶段，也不占用既有 P22 网络职责分离计划。Memory Server 先提供统一的只读诊断契约；AgentMeshOS 再消费该契约，把 Codex ↔ Memory 运行状态放入“Agent 运行态势”。

AgentMeshOS 只负责跨节点汇总和展示，不读取 Memory 数据库、不复制 Memory 内部诊断逻辑，也不根据配置存在推断运行正常。

🗂️ 目录

两个项目的职责
统一契约
推进顺序
不改变的边界
AgentMeshOS 验收门槛
回退与依赖
风险与未决项

🧩 两个项目的职责

项目	负责内容	发布位置
`agentmeshos/mcp-memory-server`	Memory 内部诊断 API、系统页 Codex 运行链路、证据脱敏	已发布 release `824e64b0`，102 生产健康
`agentmeshos/AgentMeshOS`	API Gateway 只读消费、Agent 运行态势 Memory 运行链路表、跨节点问题归一化	已发布；最新 main `3a23220d`，生产 API/Console 已回读

两个项目分别提交、分别推送、分别执行 Actions；当前对话只负责协调和统一验收。

📊 统一契约

契约标识：agentmeshos.codex-memory-observability/v1

AgentMeshOS 依赖以下只读对象：

对象	展示目标
`server`	Memory 服务健康、release、存储和模型摘要
`clients[]`	Codex 节点、Agent、协议、最近心跳和总体状态
`clients[].channels[]`	Hook 写入、Hook 召回、MCP 工具调用等通道
`clients[].evidence`	Bootstrap、MCP、Hook 的最近成功/失败与证据新鲜度
`freshness`	证据年龄、TTL 和过期状态
`issues[]`	问题、影响、下一步和来源

状态只接受 healthy、degraded、blocked、unknown、offline、not_applicable。

🔁 推进顺序

Memory Server 完成 MCO-1 至 MCO-5，发布并回读 API。
AgentMeshOS 增加 Memory 专项 API 读取和脱敏归一化。
AgentMeshOS 在现有 Agent 运行态势“Agent 客户端”域增加 Memory 运行链路视图，不新增第五个状态域。
两边分别做端到端回读：Memory 系统页、Memory API、AgentMeshOS API、Console 页面。

当前 AgentMeshOS 实现已加入：API Gateway 拉取 Memory /api/system/codex-observability，按 client_id 映射到现有 Codex 客户端，并在 Agent 运行态势新增“Memory 运行链路”只读表。定向验证：.venv/bin/python tools/api-gateway/tests/test_agent_runtime.py 返回 agent_runtime=passed；Console 静态契约返回 PASS console workspace static contract；生产 API 返回 memory_observability，生产页面静态资源包含“Memory 运行链路”。

🛡️ 不改变的边界

不修改 AgentMeshOS docs/plans/state.json 的 current_phase。
不把该专题写入 P22 网络职责分离的工作包。
不恢复 Memory 已退役的旧治理、observer 或 Agent 安装更新链。
不新增独立调度器、数据库或第二套客户端状态采集器。
不把“配置已存在”显示成“运行正常”。

🧪 AgentMeshOS 验收门槛

API Gateway 能读取并校验契约版本。
Memory API 不可达时只影响 Memory 子视图，不污染其他状态域。
每个 Codex 客户端的 Memory 状态与 clients[].channels[] 可追溯。
Home、Summer、OfficeSummer 的离线/未知状态不被硬编码为正常。
页面展示证据年龄、失败原因和下一步，且不泄露敏感值。
生产 API 与 Console 页面回读通过后，才关闭本专题。

🔁 回退与依赖

Memory 侧失败时，AgentMeshOS 回退为“Memory 诊断不可达/未验证”，不回退到旧治理页面。AgentMeshOS 侧失败时，Memory API 和 Memory 系统页保持独立可用。两个项目均保留各自的 last-known-good 发布版本。

⚠️ 风险与未决项

服务端通道活动不一定等于模型回合实际选择了工具；缺少真实调用元数据时必须显示 unknown。
Memory API 版本已冻结为 agentmeshos.codex-memory-observability/v1；后续字段演进必须新增版本或保持向后兼容。
本专题不处理当前运行态势里的 Home WebBridge、规则扩散和 CPA 版本上报，它们保留为独立待办。

📌 未决项 / 需要用户决策

无。按 Memory → AgentMeshOS 串行顺序执行。