fix(memory): enforce typed and lifecycle-safe updates

[yuanqingz]

Summary

• Add an optional memory_type to MCP remember for explicit Preference or Experience extraction while preserving the existing untyped behavior.
• Require Agent Evolution for typed Experience writes at both request validation and the authoritative commit snapshot, avoiding silent coercion into another memory type.
• Harden memory updates around immutable identity, canonical memory-type ownership, page-ID namespaces, delete/replacement targets, and semantic no-op versioning.
• Hydrate Experience lifecycle metadata authoritatively during server-side context assembly and exclude deprecated, archived, unreadable, empty, or malformed entries.

Why

The generic remember path could accept an explicit Experience intent while Agent Evolution was disabled and silently update an unrelated Preference. LLM-generated update operations could also bind an existing page ID to the wrong schema or rewrite immutable identity fields. Separately, recalled Experience candidates were not checked against their authoritative lifecycle metadata.

This change makes those boundaries explicit and fail-closed while keeping existing untyped callers and legacy Experience documents without lifecycle metadata compatible.

User impact

• remember(messages=...) keeps its current behavior.
• remember(..., memory_type="preferences") constrains extraction to Preferences.
• remember(..., memory_type="experiences") queues the Case → Trajectory → Experience pipeline and returns an explicit precondition error when Agent Evolution is disabled.
• Semantic no-op updates no longer bump the primary memory version, but derived indexes and metadata are still retried.
• Deprecated and archived Experiences are no longer returned by server-assembled context or legacy recall.

Typed Experience writes accept caller-supplied transcripts and are documented as a trusted-author operation.

Validation

• 53 focused memory, MCP, session, URI, page-ID, and service tests passed.
• 18 context-assembler pipeline tests passed.
• git diff --check and Python compilation passed.
• Full HTTP fixture execution was not available locally because the isolated test environment lacks the native RAGFS binding; endpoint regressions are included for upstream CI.
• The upstream API and CLI integration workflow passed, including API tests, CLI compatibility, and CLI integration.

CI note

The Docs workflow currently reports an API-reference baseline failure: the route PATCH /api/v1/sessions/{session_id}/config is mounted on main, while the existing English and Chinese API reference still says runtime session-config updates are unavailable. This PR does not change that route or those API-reference pages; its MCP guide changes merely trigger the repository-wide API-reference check.

Related

The independent Codex memory-plugin reliability changes are in #3917. Neither PR contains the other's commit.

---

中文说明

改动概述

• 为 MCP remember 增加可选的 memory_type，支持显式提取 Preference 或 Experience，同时保持原有未指定类型时的行为不变。
• typed Experience 写入会在请求校验和最终 commit 快照两个阶段确认 Agent Evolution 已开启，避免内容被静默写成其他 memory 类型。
• 加固 memory 更新边界，包括 immutable identity、canonical memory type、page ID 命名空间、删除与替换目标，以及语义 no-op 的版本处理。
• 服务端组装检索上下文时会读取 Experience 的权威 lifecycle metadata，并排除 deprecated、archived、无法读取、空内容或 metadata 损坏的条目。

问题背景

此前，调用者即使明确希望保存 Experience，在 Agent Evolution 关闭时，通用 remember 路径仍可能接受请求并把内容更新到不相关的 Preference。LLM 生成的更新操作也可能将已有 page ID 绑定到错误的 schema，或者改写本应不可变的 identity 字段。此外，召回 Experience 时没有根据源文件中的权威 lifecycle metadata 做最终校验。

本 PR 将这些边界改为显式、fail-closed 的行为，同时兼容现有未指定 memory_type 的调用，以及没有 lifecycle metadata 的历史 Experience 文档。

用户影响

• remember(messages=...) 保持现有行为。
• remember(..., memory_type="preferences") 只允许提取 Preference。
• remember(..., memory_type="experiences") 会进入 Case → Trajectory → Experience 流水线；Agent Evolution 未开启时返回明确的前置条件错误。
• 语义没有变化的更新不再增加主 memory 版本，但仍会重试派生索引和 metadata 的同步。
• deprecated 和 archived Experience 不再出现在服务端组装的 context 或 legacy recall 结果中。

Typed Experience 接受调用者提供的 transcript，因此文档中明确将它定义为可信写入方接口；不可信应用应提交由服务端实际记录的 session。

验证结果

• 53 项 memory、MCP、session、URI、page ID 与 service 聚焦测试通过。
• 18 项 context assembler pipeline 测试通过。
• git diff --check 与 Python 编译检查通过。
• 本地隔离环境缺少原生 RAGFS binding，因此未执行完整 HTTP fixture；对应 endpoint 回归测试已经加入，交由上游 CI 执行。
• 上游 API 与 CLI 集成 workflow 已通过，包括 API tests、CLI compatibility 和 CLI integration。

CI 说明

Docs workflow 当前命中了上游 API reference 的既有缺口：main 已挂载 PATCH /api/v1/sessions/{session_id}/config，但现有中英文 API 文档仍声明运行时 session config 不可更新。本 PR 没有修改该路由或对应 API reference，只是 MCP guide 的改动触发了全仓 API reference 检查。

相关 PR

Codex memory plugin 的独立可靠性修复位于 #3917；两个 PR 均不包含对方的提交。

[yuanqingz]

@qin-ctx @heaoxiang-ai 麻烦有空帮忙 review 一下这个 PR，重点包括 typed MCP memory write、Agent Evolution 前置条件、memory identity/page ID 更新边界，以及 Experience lifecycle filtering。

本地 focused tests 和上游 API/CLI integration 均已通过。当前 Docs 红灯是 main 已存在的 session-config API reference 缺口，PR body 中已单独说明。谢谢！