# 工作原理

权威架构与公开边界：服务端组装、执行生命周期、子系统节点与托管云边界。

- Canonical: https://docs.xmemo.dev/zh/docs/concepts/how-xmemo-works
- Locale: zh-CN
- Content-Locale: zh-CN
- Canonical-Content-Digest: 321f29a0f9c36406e495bc50c7110f64ee7680a5bf2706f6b5eef7ecfa09163d
- Edition-Digest: da636eaa7fb6519be05b565e0efb97006f44eb34a98c1e53aa6a47b02401a8b5
- Source-Revision: sha256:8310426b563698994f72fce9d60572391625bf1c49e90527246490ed5f7a65b5

## 简化架构：7 阶段记忆流水线

XMemo 通过 7 阶段流水线（Capture → Scope → Retrieve → Rerank → Assemble → Govern → Consolidate）处理智能体记忆。每个阶段履行专属职责，确保记忆操作保持高效、准确、边界隔离且完全可验证：

- Capture：通过标准模型上下文协议（MCP）或 REST API 接收来自 AI 客户端的写入与更新请求，并在持久化之前对敏感数据进行脱敏。这对您意味着：您的智能体可以通过标准工具自动保存笔记、决策与偏好，绝不泄漏密钥或个人数据。
- Scope：解析调用方身份上下文，并在用户、会话、智能体与工作区层级实施严格的多租户边界隔离。这对您意味着：每个智能体仅能访问其授权边界内的记忆，确保个人与团队数据安全隔离。
- Retrieve：通过结合向量语义嵌入与精确关键词匹配的混合检索引擎搜索已存记忆。这对您意味着：无论按主题含义搜索还是按精确词句或标识符查找，您的智能体都能精准召回正确事实。
- Rerank：综合权衡语义相关性、时间近度与重要性权重，对候选记忆进行评估与打分。这对您意味着：您的智能体将获得最相关且最新的上下文，避免陈旧或低优先级的对话碎片干扰。
- Assemble：将召回的记忆组装为即插即用的提示词上下文，同时严格执行调用方设定的 Token 与字节预算。这对您意味着：注入的记忆绝不会超出模型的上下文窗口，也不会产生意料之外的 Token 成本。
- Govern：记录操作审计日志，跟踪版本历史（memory_versions），并在启用密钥保护/保管库模式时应用加密信封。这对您意味着：每一次记忆更新均完全可追溯、可验证且可恢复，具备完整的审计责任制。
- Consolidate：预览记忆整理（Dream），将近期的情景交互提炼为结构化的候选洞察，在保存前需要人工确认。这对您意味着：为您准备有价值的洞察以供审阅，不会发生自动的意外变更，也不会拖慢交互式智能体对话。

## 架构内部机制 / 证据

基于 XMemo 代码库直接验证的权威架构实现细节、执行追踪与经验契约。以下各节详细阐述具体的运行时组合、隔离的子系统边界以及形式化验证矩阵。

## 架构不变量与核心原则

XMemo 围绕不可妥协的架构不变量进行设计，严格将公开客户端接口与内部子系统执行解耦。所有功能均受代码证据约束，私有拓扑与集群密钥在零明文凭据暴露原则下受到保护。

- 零明文凭据暴露：客户端配置文件、日志及公开诊断响应绝不包含未加密的 Bearer 令牌、数据库连接串或主密钥。
- 验证来源出处：每条持久化记忆、版本修订与检索引用均包含不可变的身份元数据与源代码契约审计追踪。
- 确定性 Token 与字节预算：回忆上下文注入严格遵守调用方指定的配额上限，杜绝 LLM 上下文窗口溢出。
- 方案与功能网关边界：多租户 BYODB、分布式同步与后台 Dream 调度受工作区配置、特性开关及服务方案边界显式门禁约束。

## 服务端组装与生命周期拓扑

服务端初始化严格将部署时组装与工具注册同每请求运行时执行链路解耦。外部客户端不挂载宿主服务器；相反，宿主服务器挂载 FastMCP ASGI 应用，通过 MemoryOSMcpMountAdapter 进行适配，并在收到任何请求前向 FastMCP 注册认证工具处理器。

- Step 1 [HOST_COMPOSITION]: Starlette/FastAPI 宿主应用在 /mcp 挂载 FastMCP ASGI 应用 — 关系: SERVER_MOUNTS_APP — 子系统: ASGI 宿主挂载 — 边界: 公共 HTTP 入口。
- Step 2 [MOUNT_ADAPTER]: mount_streamable_mcp 将 streamable_http_app 封装在 MemoryOSMcpMountAdapter 中处理 CORS 与作用域重写 — 关系: ADAPTS_ASGI_APP — 子系统: 流式协议适配器 — 边界: 协议桥接。
- Step 3 [AUTH_REGISTRATION]: install_mcp_tool_surface 将 _call_tool_with_oauth_errors 注册为 FastMCP 底层服务的 call_tool 处理器 — 关系: REGISTERS_TOOL_WRAPPER — 子系统: 身份与工具分发门禁 — 边界: 认证工具表面。

```text
+---------------------------------------------------------------------------------------------------+
| [DEPLOYMENT-TIME SERVER COMPOSITION & TOPOLOGY: 2 INDEPENDENT BRANCHES]                           |
|                                                                                                   |
| [BRANCH 1: SERVER ASGI MOUNT BRANCH]                                                              |
|  +-------------------------------------------------------+                                        |
|  | Host ASGI Server (Starlette / FastAPI)                | [PUBLIC_BOUNDARY]                      |
|  | Role: FastMCP Host Ingress Gateway                    | [PUBLIC_BOUNDARY]                      |
|  +-------------------------------------------------------+                                        |
|                             |                                                                     |
|                             | Relation: SERVER_MOUNTS_APP                                         |
|                             | Status: [PUBLIC_BOUNDARY (VERIFIED)]                                |
|                             v                                                                     |
|  +-------------------------------------------------------+                                        |
|  | mount_streamable_mcp                                  | [INTERNAL_SUBSYSTEM]                   |
|  | Role: Streamable HTTP Application Adapter             | [INTERNAL_SUBSYSTEM]                   |
|  +-------------------------------------------------------+                                        |
|                             |                                                                     |
|                             | Relation: ADAPTS_ASGI_APP                                           |
|                             | Status: [INTERNAL_SUBSYSTEM (VERIFIED)]                             |
|                             v                                                                     |
|  +-------------------------------------------------------+                                        |
|  | MemoryOSMcpMountAdapter                               | [PUBLIC_BOUNDARY]                      |
|  | Role: ASGI Protocol Bridge & Connection Handler       | [PUBLIC_BOUNDARY]                      |
|  +-------------------------------------------------------+                                        |
|                                                                                                   |
| [BRANCH 2: TOOL SURFACE REGISTRATION BRANCH]                                                      |
|  +-------------------------------------------------------+                                        |
|  | install_mcp_tool_surface                              | [INTERNAL_SUBSYSTEM]                   |
|  | Role: MCP Tool Surface Registration Pipeline          | [INTERNAL_SUBSYSTEM]                   |
|  +-------------------------------------------------------+                                        |
|                             |                                                                     |
|                             | Relation: REGISTERS_TOOL_WRAPPER                                    |
|                             | Status: [INTERNAL_SUBSYSTEM (VERIFIED)]                             |
|                             v                                                                     |
|  +-------------------------------------------------------+                                        |
|  | FastMCP Tool Ingress Wrapper (_call_tool_with_oauth)  | [PUBLIC_BOUNDARY]                      |
|  | Role: Authenticated Tool Invocation & Error Handler   | [PUBLIC_BOUNDARY]                      |
|  +-------------------------------------------------------+                                        |
+---------------------------------------------------------------------------------------------------+
```

## 运行时执行追踪

在运行时，客户端请求跨越四个隔离且确定性的操作流执行。每一步均遵循严格的调用方-被调用方关系及显式架构边界分类：

- OP_REMEMBER_WRITE [记住 / 写入追踪: 13 步]: 外部客户端 [PUBLIC_INGRESS] -> MemoryOSMcpMountAdapter [TRANSPORT_ADAPTER] -> FastMCP ASGI 分发 -> 认证门禁 -> remember 工具表面 -> 初始化校验门禁 -> 隐私脱敏封套 -> 安全封套（启用密钥保护/保管库模式时加密） -> 持久化存储引擎。跨公共入口、认证、脱敏与持久化的完整 13 步执行链路。
- OP_RECALL_READ [回忆 / 读取追踪: 12 步]: 外部客户端 [PUBLIC_INGRESS] -> MemoryOSMcpMountAdapter [TRANSPORT_ADAPTER] -> FastMCP ASGI 分发 -> 认证门禁 -> recall 工具表面 -> BoundSpace 多租户隔离 -> 混合检索引擎 -> 语义候选重排器 -> 上下文预算装配器 -> 公开凭据格式化器。跨检索、隔离、重排与预算控制的完整 12 步执行链路。
- OP_UPDATE_VERSION [更新 / 版本追踪: 13 步]: 外部客户端 [PUBLIC_INGRESS] -> MemoryOSMcpMountAdapter [TRANSPORT_ADAPTER] -> FastMCP ASGI 分发 -> 认证门禁 -> update_memory 工具表面 -> 初始化校验门禁 -> 隐私脱敏封套 -> 安全封套（启用密钥保护/保管库模式时加密） -> 持久化存储引擎 -> 不可变版本历史 DAG 控制器。跨校验、更新与 DAG 替代的完整 13 步执行链路。
- OP_FORGET_LIFECYCLE [遗忘 / 生命周期追踪: 11 步]: 外部客户端 [PUBLIC_INGRESS] -> MemoryOSMcpMountAdapter [TRANSPORT_ADAPTER] -> FastMCP ASGI 分发 -> 认证门禁 -> forget 工具表面 -> 初始化校验门禁 -> 软标记持久化 -> 后台保留策略守护进程 -> 搜索排除过滤器。跨删除、墓碑标记与数据保留的完整 11 步执行链路。

```text
+------------------------------------------------------------------------------------------------------------------------+
| [RUNTIME EXECUTION TRACES: 4 CANONICAL OPERATION FLOW DIAGRAMS]                                                        |
|                                                                                                                        |
| 1. OP_REMEMBER_WRITE [WRITE INGRESS FLOW: 13 STEPS]                                                                    |
|     Step 1:   External Client --[CLIENT_REQUESTS_ENDPOINT]--> MemoryOSMcpMountAdapter                                  |
|              Boundary: Public Ingress Gateway [PUBLIC_BOUNDARY]                                                        |
|     Step 2:   MemoryOSMcpMountAdapter --[DELEGATES_ASGI_REQUEST]--> FastMCP.streamable_http_app                        |
|              Boundary: ASGI Streamable Mount Adapter [INTERNAL_SUBSYSTEM]                                              |
|     Step 3:   FastMCP --[DISPATCHES_TOOL_INVOCATION]--> _call_tool_with_oauth_errors                                   |
|              Boundary: Tool Surface Ingress Gate [INTERNAL_SUBSYSTEM]                                                  |
|     Step 4:   _call_tool_with_oauth_errors --[DISPATCHES_TOOL]--> remember tool                                        |
|              Boundary: MCP Tool Dispatch Handler [PUBLIC_BOUNDARY]                                                     |
|     Step 5:   remember tool --[CALLS]--> Identity Context Resolver                                                     |
|              Boundary: Identity & Authentication Context [INTERNAL_SUBSYSTEM]                                          |
|     Step 6:   remember tool --[CALLS]--> Workspace Setup Gate                                                          |
|              Boundary: Workspace Initialization Gate [INTERNAL_SUBSYSTEM]                                              |
|     Step 7:   Workspace Setup Gate --[CALLS]--> Initialization Validator                                               |
|              Boundary: Setup Verification Gate [INTERNAL_SUBSYSTEM]                                                    |
|     Step 8:   remember tool --[CALLS]--> Write Preparation Pipeline                                                    |
|              Boundary: Memory Write Preparation [INTERNAL_SUBSYSTEM]                                                   |
|     Step 9:   Write Preparation Pipeline --[CALLS]--> PII Sanitization Envelope                                        |
|              Boundary: Sensitive Data Redaction [INTERNAL_SUBSYSTEM]                                                   |
|     Step 10:  Write Preparation Pipeline --[CALLS]--> Security Envelope (encryption when keyguard/vault mode is active)|
|              Boundary: Cryptographic Security Envelope [INTERNAL_SUBSYSTEM]                                            |
|     Step 11:  remember tool --[CALLS]--> Tenant Isolation Envelope                                                     |
|              Boundary: Multi-Tenant Workspace Binding [INTERNAL_SUBSYSTEM]                                             |
|     Step 12:  remember tool --[CALLS]--> Memory Manager Core Engine                                                    |
|              Boundary: Core Memory Management [INTERNAL_SUBSYSTEM]                                                     |
|     Step 13:  Memory Manager Core Engine --[CALLS]--> Persistence Storage Engine                                       |
|              Boundary: Persistent Storage Engine [INTERNAL_SUBSYSTEM]                                                  |
|                                                                                                                        |
| 2. OP_RECALL_READ [READ RETRIEVAL FLOW: 12 STEPS]                                                                      |
|     Step 1:   External Client --[CLIENT_REQUESTS_ENDPOINT]--> MemoryOSMcpMountAdapter                                  |
|              Boundary: Public Ingress Gateway [PUBLIC_BOUNDARY]                                                        |
|     Step 2:   MemoryOSMcpMountAdapter --[DELEGATES_ASGI_REQUEST]--> FastMCP.streamable_http_app                        |
|              Boundary: ASGI Streamable Mount Adapter [INTERNAL_SUBSYSTEM]                                              |
|     Step 3:   FastMCP --[DISPATCHES_TOOL_INVOCATION]--> _call_tool_with_oauth_errors                                   |
|              Boundary: Tool Surface Ingress Gate [INTERNAL_SUBSYSTEM]                                                  |
|     Step 4:   _call_tool_with_oauth_errors --[DISPATCHES_TOOL]--> recall tool                                          |
|              Boundary: MCP Tool Dispatch Handler [PUBLIC_BOUNDARY]                                                     |
|     Step 5:   recall tool --[CALLS]--> Search Memory Implementation                                                    |
|              Boundary: Search Query Coordinator [INTERNAL_SUBSYSTEM]                                                   |
|     Step 6:   Search Memory Implementation --[CALLS]--> Identity Context Resolver                                      |
|              Boundary: Identity & Authentication Context [INTERNAL_SUBSYSTEM]                                          |
|     Step 7:   Search Memory Implementation --[CALLS]--> BoundSpace Multi-Tenant Isolation                              |
|              Boundary: Scope Isolation Boundary [INTERNAL_SUBSYSTEM]                                                   |
|     Step 8:   Search Memory Implementation --[CALLS]--> Memory Manager Search Service                                  |
|              Boundary: Core Search Controller [INTERNAL_SUBSYSTEM]                                                     |
|     Step 9:   Memory Manager Search Service --[CALLS]--> Hybrid Retrieval Engine                                       |
|              Boundary: Hybrid Vector & Text Retrieval [INTERNAL_SUBSYSTEM]                                             |
|     Step 10:  Hybrid Retrieval Engine --[CALLS]--> Semantic Relevance Reranker                                         |
|              Boundary: Candidate Scorer & Reranker [INTERNAL_SUBSYSTEM]                                                |
|     Step 11:  Hybrid Retrieval Engine --[CALLS]--> Response Budget Assembler                                           |
|              Boundary: Token & Byte Budget Manager [INTERNAL_SUBSYSTEM]                                                |
|     Step 12:  Response Budget Assembler --[CALLS]--> Public Citation & Receipt Formatter                               |
|              Boundary: Provenance Citation Formatter [PUBLIC_BOUNDARY]                                                 |
|                                                                                                                        |
| 3. OP_UPDATE_VERSION [VERSIONING & CORRECTION FLOW: 13 STEPS]                                                          |
|     Step 1:   External Client --[CLIENT_REQUESTS_ENDPOINT]--> MemoryOSMcpMountAdapter                                  |
|              Boundary: Public Ingress Gateway [PUBLIC_BOUNDARY]                                                        |
|     Step 2:   MemoryOSMcpMountAdapter --[DELEGATES_ASGI_REQUEST]--> FastMCP.streamable_http_app                        |
|              Boundary: ASGI Streamable Mount Adapter [INTERNAL_SUBSYSTEM]                                              |
|     Step 3:   FastMCP --[DISPATCHES_TOOL_INVOCATION]--> _call_tool_with_oauth_errors                                   |
|              Boundary: Tool Surface Ingress Gate [INTERNAL_SUBSYSTEM]                                                  |
|     Step 4:   _call_tool_with_oauth_errors --[DISPATCHES_TOOL]--> update_memory tool                                   |
|              Boundary: MCP Tool Dispatch Handler [PUBLIC_BOUNDARY]                                                     |
|     Step 5:   update_memory tool --[CALLS]--> Identity Context Resolver                                                |
|              Boundary: Identity & Authentication Context [INTERNAL_SUBSYSTEM]                                          |
|     Step 6:   update_memory tool --[CALLS]--> Workspace Setup Gate                                                     |
|              Boundary: Workspace Initialization Gate [INTERNAL_SUBSYSTEM]                                              |
|     Step 7:   update_memory tool --[CALLS]--> Scope Validation Gate                                                    |
|              Boundary: Workspace Scope Boundary [INTERNAL_SUBSYSTEM]                                                   |
|     Step 8:   update_memory tool --[CALLS]--> Write Preparation Pipeline                                               |
|              Boundary: Memory Write Preparation [INTERNAL_SUBSYSTEM]                                                   |
|     Step 9:   Write Preparation Pipeline --[CALLS]--> PII Sanitization Envelope                                        |
|              Boundary: Sensitive Data Redaction [INTERNAL_SUBSYSTEM]                                                   |
|     Step 10:  update_memory tool --[CALLS]--> Tenant Isolation Envelope                                                |
|              Boundary: Multi-Tenant Workspace Binding [INTERNAL_SUBSYSTEM]                                             |
|     Step 11:  update_memory tool --[CALLS]--> Memory Manager Core Engine                                               |
|              Boundary: Core Memory Management [INTERNAL_SUBSYSTEM]                                                     |
|     Step 12:  Memory Manager Core Engine --[CALLS]--> Persistence Storage Engine                                       |
|              Boundary: Persistent Storage Engine [INTERNAL_SUBSYSTEM]                                                  |
|     Step 13:  Persistence Storage Engine --[CALLS]--> Immutable Version DAG Controller                                 |
|              Boundary: Version DAG Supersession Engine [INTERNAL_SUBSYSTEM]                                            |
|                                                                                                                        |
| 4. OP_FORGET_LIFECYCLE [RETENTION & LIFECYCLE FLOW: 11 STEPS]                                                          |
|     Step 1:   External Client --[CLIENT_REQUESTS_ENDPOINT]--> MemoryOSMcpMountAdapter                                  |
|              Boundary: Public Ingress Gateway [PUBLIC_BOUNDARY]                                                        |
|     Step 2:   MemoryOSMcpMountAdapter --[DELEGATES_ASGI_REQUEST]--> FastMCP.streamable_http_app                        |
|              Boundary: ASGI Streamable Mount Adapter [INTERNAL_SUBSYSTEM]                                              |
|     Step 3:   FastMCP --[DISPATCHES_TOOL_INVOCATION]--> _call_tool_with_oauth_errors                                   |
|              Boundary: Tool Surface Ingress Gate [INTERNAL_SUBSYSTEM]                                                  |
|     Step 4:   _call_tool_with_oauth_errors --[DISPATCHES_TOOL]--> forget tool                                          |
|              Boundary: MCP Tool Dispatch Handler [PUBLIC_BOUNDARY]                                                     |
|     Step 5:   forget tool --[CALLS]--> Identity Context Resolver                                                       |
|              Boundary: Identity & Authentication Context [INTERNAL_SUBSYSTEM]                                          |
|     Step 6:   forget tool --[CALLS]--> Workspace Setup Gate                                                            |
|              Boundary: Workspace Initialization Gate [INTERNAL_SUBSYSTEM]                                              |
|     Step 7:   forget tool --[CALLS]--> Memory Manager Core Engine                                                      |
|              Boundary: Core Memory Management [INTERNAL_SUBSYSTEM]                                                     |
|     Step 8:   Memory Manager Core Engine --[CALLS]--> Persistence Storage Engine                                       |
|              Boundary: Persistence Tombstone Engine [INTERNAL_SUBSYSTEM]                                               |
|     Step 9:   Background Lifecycle Daemon --[BATCH_POLICY_EVALUATION]--> Retention Policy Evaluator                    |
|              Boundary: Archive Policy Evaluation [INTERNAL_SUBSYSTEM]                                                  |
|     Step 10:  Background Lifecycle Daemon --[BATCH_POLICY_EVALUATION]--> Importance Decay Evaluator                    |
|              Boundary: Importance Decay Engine [INTERNAL_SUBSYSTEM]                                                    |
|     Step 11:  Hybrid Retrieval Engine --[EXCLUDES_AT_QUERY]--> Database Storage Engine                                 |
|              Boundary: Query-Time Tombstone Filter [INTERNAL_SUBSYSTEM]                                                |
+------------------------------------------------------------------------------------------------------------------------+
```

## 子系统分解与边界分类

系统分解为十个已验证子系统节点。每个节点均具备严格的边界分类（PUBLIC_BOUNDARY 或 INTERNAL_SUBSYSTEM）及实证证据状态（SOURCE_BACKED_PUBLIC_CONTRACT / VERIFIED、CONCEPTUAL_DELEGATED 或 NOT_VERIFIED）：

- NODE_1_CLIENT_AGENT_LAYER: 客户端与 Agent 生态 (@xmemo/client, Claude Desktop, Cursor, Codex) — 分类: [PUBLIC_BOUNDARY] — 证据状态: [SOURCE_BACKED_PUBLIC_CONTRACT (VERIFIED)].
- NODE_2_TRANSPORT_ADAPTER: MCP 传输与协议适配器 (MemoryOSMcpMountAdapter, mount_streamable_mcp) — 分类: [PUBLIC_BOUNDARY] — 证据状态: [SOURCE_BACKED_PUBLIC_CONTRACT (VERIFIED)].
- NODE_3_IDENTITY_AUTH_GATE: 身份与授权门禁 (_call_tool_with_oauth_errors, install_mcp_tool_surface) — 分类: [PUBLIC_BOUNDARY] — 证据状态: [SOURCE_BACKED_PUBLIC_CONTRACT (VERIFIED)].
- NODE_4_SANITIZATION_ENVELOPE: 隐私脱敏与保险库封套 (sanitize_server_write, enforce_memory_write_envelope) — 分类: [INTERNAL_SUBSYSTEM] — 证据状态: [SOURCE_BACKED_PUBLIC_CONTRACT (VERIFIED)].
- NODE_5_SCOPE_ISOLATION_GUARD: 范围与多租户隔离防护 (BoundSpace, assert_requested_team_matches_bound_space) — 分类: [INTERNAL_SUBSYSTEM] — 证据状态: [SOURCE_BACKED_PUBLIC_CONTRACT (VERIFIED)].
- NODE_6_SEARCH_TEMPORAL_PARSER: 搜索与时态查询解析器 (TemporalQuerySpec, extract_temporal_context) — 分类: [INTERNAL_SUBSYSTEM] — 证据状态: [SOURCE_BACKED_PUBLIC_CONTRACT (VERIFIED)].
- NODE_7_CANDIDATE_SCORER: 候选评分与重排器 (SearchEngine.rerank_recall_results) — 分类: [INTERNAL_SUBSYSTEM] — 证据状态: [SOURCE_BACKED_PUBLIC_CONTRACT (VERIFIED)].
- NODE_8_VERSION_LIFECYCLE_ENGINE: 版本与生命周期控制器 (VersionController.superseded_snapshot) — 分类: [INTERNAL_SUBSYSTEM] — 证据状态: [SOURCE_BACKED_PUBLIC_CONTRACT (VERIFIED)].
- NODE_9_CONTEXT_BUDGET_ASSEMBLER: 上下文预算装配器 (_apply_recall_response_budget) — 分类: [INTERNAL_SUBSYSTEM] — 证据状态: [SOURCE_BACKED_PUBLIC_CONTRACT (VERIFIED)].
- NODE_10_PUBLIC_RECEIPT_CITATION: 公开凭据与引用格式化器 (_public_recall_meta) — 分类: [PUBLIC_BOUNDARY] — 证据状态: [SOURCE_BACKED_PUBLIC_CONTRACT (VERIFIED)].

## 开源与托管云服务边界

公开架构主张与生态系统声明经由实证代码契约评估。声明严格分类为 VERIFIED（受可执行测试与源码符号支持）或 NOT_VERIFIED（已被驳回、未经验证或局限于专有托管环境）：

- STMT_01_PROVENANCE_ATTRIBUTION [VERIFIED]: XMemo 记录操作审计日志，保留版本历史（memory_versions），并在启用密钥保护/保管库模式时应用加密信封。 架构保障: 密码学安全写入封套机制。
- STMT_02_CROSS_CLIENT_CONTINUITY [VERIFIED]: 在 Claude Desktop、Cursor 或 CLI 中捕获的记忆可通过标准 JSON-RPC 在任何兼容 MCP 的客户端中立即可用。 架构保障: 流式 FastMCP ASGI 协议适配器。
- STMT_03_REALTIME_CORRECTION [VERIFIED]: 事实更新保持不可变版本历史，同时通过父级指针取代先前冲突的记忆。 架构保障: 不可变版本 DAG 控制器。
- STMT_04_TOKEN_BUDGET_GUARANTEE [VERIFIED]: 回忆上下文注入严格遵守调用方指定的 Token 与字节预算。 架构保障: 确定性 Token 预算装配器。
- STMT_05_ZERO_TOKEN_EXPOSURE [VERIFIED]: 未认证请求与未授权作用域在网关处被直接拒绝，不执行存储查询亦不泄露令牌。 架构保障: 入口身份认证与作用域隔离门禁。
- STMT_06_BACKEND_OPEN_SOURCE_CLAIM [NOT_VERIFIED]: 宣称 100% 后端开源已被驳回。仅客户端代码包（@xmemo/client，MIT 许可）和本地 MCP 适配器开源。多租户云端基础设施、计费及集群编排仍为专有托管服务。
- STMT_07_AUTONOMOUS_CONSENSUS_CLAIM [NOT_VERIFIED]: 跨组织自主共识已被驳回。租户隔离受 BoundSpace 及 tenant_id 分区严格执行；系统未实现跨租户自动合并。
- STMT_08_ZERO_LATENCY_REPLICATION_CLAIM [NOT_VERIFIED]: 零延迟全局复制主张已被驳回。检索使用本地/嵌入式向量索引（Qdrant/SQLite）；零延迟全球强一致性未经验证且未做保证。

## 可复现架构生命周期走查（合成 A/B 示例）

通过完全确定性的合成演示数据，逐步验证跨 Agent 记忆共享、多租户范围隔离、实时用户纠偏与不可变来源追踪的完整生命周期。每一步骤均严格对应公开契约中经过代码验证的系统能力与已批准的主张 ID：

- Step 1 [AGENT_A_WRITE]: Agent A (ide-assistant-alpha) 通过 remember tool 向范围 project:synthetic-demo 写入合成偏好 — Payload: {'formatting': 'tabs', 'indent': 4} — Claim: [STMT_01_PROVENANCE_ATTRIBUTION] & [STMT_02_CROSS_CLIENT_CONTINUITY] — Receipt: mem-synth-pref-001@v1, digest sha256:7f83b165 — Status: [SOURCE_BACKED_PUBLIC_CONTRACT (VERIFIED)] — Boundary: [DEMO_DATA: SYNTHETIC].
- Step 2 [AGENT_B_RECALL]: Agent B (terminal-assistant-beta) 在同一授权范围 project:synthetic-demo 内通过 recall tool 召回偏好 — Query: 'code formatting indent' — Claim: [STMT_02_CROSS_CLIENT_CONTINUITY] & [STMT_04_TOKEN_BUDGET_GUARANTEE] — Receipt: mem-synth-pref-001@v1 cited, score 0.94, bounded budget — Status: [SOURCE_BACKED_PUBLIC_CONTRACT (VERIFIED)] — Boundary: [DEMO_DATA: SYNTHETIC].
- Step 3 [UNAUTHORIZED_DENIAL]: 未授权 Agent (rogue-guest-gamma) 尝试在无凭证情况下跨租户访问 project:synthetic-demo — Gate: Scope Isolation & Auth Gateway — Claim: [STMT_05_ZERO_TOKEN_EXPOSURE] — Outcome: AUTH_SCOPE_DENIED (HTTP 403), zero data leakage, zero storage mutation verified by database snapshot byte equality — Status: [SOURCE_BACKED_PUBLIC_CONTRACT (VERIFIED)] — Boundary: [DEMO_DATA: SYNTHETIC].
- Step 4 [USER_CORRECTION]: 用户通过 update_memory tool 纠正代码格式标准 — Payload: {'formatting': 'spaces', 'indent': 2}, reason: 'team style guide update' — Controller: Version DAG Controller — Claim: [STMT_03_REALTIME_CORRECTION] — Receipt: mem-synth-pref-001@v2, supersedes v1, parent_digest sha256:7f83b165 — Status: [SOURCE_BACKED_PUBLIC_CONTRACT (VERIFIED)] — Boundary: [DEMO_DATA: SYNTHETIC].
- Step 5 [LATER_RECALL_V2]: 后续召回查询自动选择最新版本 2，同时 SearchEngine 在候选过滤阶段严格排除已被替代的版本 1 — Query: 'indentation preference' — Claim: [STMT_03_REALTIME_CORRECTION] & [STMT_04_TOKEN_BUDGET_GUARANTEE] — Outcome: Active recall context injects only v2 (spaces, 2) — Status: [SOURCE_BACKED_PUBLIC_CONTRACT (VERIFIED)] — Boundary: [DEMO_DATA: SYNTHETIC].
- Step 6 [PROVENANCE_DAG]: 通过 Version Controller 审计并检查版本历史 — Chain: v1 (initial write by ide-assistant-alpha) -> v2 (superseded_by user correction) — Claim: [STMT_01_PROVENANCE_ATTRIBUTION] — Verification: 版本历史与父指针完全可检查 — Status: [SOURCE_BACKED_PUBLIC_CONTRACT (VERIFIED)] — Boundary: [DEMO_DATA: SYNTHETIC].
- Step 7 [STATE_RESET]: 可重置沙箱机制将合成工作区 project:synthetic-demo 恢复为干净初始状态 — Action: Deterministic teardown and state purge — Claim: [STMT_05_ZERO_TOKEN_EXPOSURE] — Receipt: reset_status CLEARED, 0 residual rows, zero persistent side effects — Status: [SOURCE_BACKED_PUBLIC_CONTRACT (VERIFIED)] — Boundary: [DEMO_DATA: SYNTHETIC].
- Boundary Notice [NOT_VERIFIED]: 云端多租户计费系统 [STMT_06_BACKEND_OPEN_SOURCE_CLAIM]、跨组织自主共识机制 [STMT_07_AUTONOMOUS_CONSENSUS_CLAIM] 与零延迟跨区域复制 [STMT_08_ZERO_LATENCY_REPLICATION_CLAIM] 均属于 [NOT_VERIFIED]，不包含在本地开源运行时走查范围内。

```text
+------------------------------------------------------------------------------------------------------------------------+
| [REPRODUCIBLE ARCHITECTURE LIFECYCLE WALKTHROUGH: SYNTHETIC A/B PREFERENCE SHARING & CORRECTION]                       |
|                                                                                                                        |
|  Agent A (IDE)               XMemo Gateway & Engines            Agent B (CLI)              Unauthorized Agent (Guest)  |
|  [ide-assistant-alpha]       [FastMCP / Storage / Scope]        [terminal-assistant-beta]  [rogue-guest-gamma]         |
|         |                               |                              |                              |                |
|  (1) remember(pref: tabs, 4)            |                              |                              |                |
|  -------------------------------------> |                              |                              |                |
|         |                          [Write v1, Hash: 7f83b1]            |                              |                |
|  <------------------------------------- |                              |                              |                |
|    Receipt: mem-001@v1                  |                              |                              |                |
|         |                               |      (2) recall(pref)        |                              |                |
|         |                               | <--------------------------- |                              |                |
|         |                               |  [Scope Match: synth-demo]   |                              |                |
|         |                               | ---------------------------> |                              |                |
|         |                               |   Citation: mem-001@v1       |                              |                |
|         |                               |                              |   (3) recall(foreign tenant) |                |
|         |                               | <---------------------------------------------------------- |                |
|         |                               |                          [BoundSpace Check: MISMATCH]       |                |
|         |                               | ----------------------------------------------------------> |                |
|         |                               |                          DENIED: AUTH_SCOPE_DENIED (Zero Mutation)           |
|         |                               |                              |                              |                |
|  (4) update_memory(pref: spaces, 2)     |                              |                              |                |
|  -------------------------------------> |                              |                              |                |
|         |                          [Write v2, parent: v1]              |                              |                |
|  <------------------------------------- |                              |                              |                |
|    Receipt: mem-001@v2 (supersedes v1)  |                              |                              |                |
|         |                               |      (5) recall(pref)        |                              |                |
|         |                               | <--------------------------- |                              |                |
|         |                               |  [Exclude v1, Select v2]     |                              |                |
|         |                               | ---------------------------> |                              |                |
|         |                               |   Citation: mem-001@v2       |                              |                |
|         |                               |                              |                              |                |
|  (6) inspect_provenance(mem-001)        |                              |                              |                |
|  -------------------------------------> |                              |                              |                |
|  <------------------------------------- |                              |                              |                |
|    DAG: v1 (Hash: 7f83) -> v2 (Hash: 4d82)                             |                              |                |
|         |                               |                              |                              |                |
|  (7) reset_synthetic_state()            |                              |                              |                |
|  -------------------------------------> | [Purge demo scope]           |                              |                |
|  <------------------------------------- | 0 residual rows              |                              |                |
+------------------------------------------------------------------------------------------------------------------------+
```

## 深入概念与安全导航

通过深入的概念与安全文档探索特定架构领域：

- 记忆数据模型 (/docs/concepts/memory-model): 实体结构、语义分类、重要性评分与表示层。
- 出处与归属 (/docs/concepts/provenance-attribution): 审计追踪与调用方归属。
- 项目记忆空间 (/docs/concepts/projects): 通过工作区路径路由和个人项目边界隔离实现的经过验证的项目关联。
- 梦境与记忆整理 (/docs/concepts/dream-reflection): 候选预览整理、明确的目标位置审阅与维护策略。
- 外部知识库 (/docs/concepts/knowledge-bases): 文档索引、分块策略与参考引用。
- 数据边界与安全 (/docs/security/data-boundary): 本地自托管能力与云端 SaaS 服务之间的全面界定。

## ChatGPT 用户

让 ChatGPT 持久访问你的 XMemo 偏好、项目事实、决策和 TODO，同时不把 bearer token 粘贴到聊天里。

通过 ChatGPT/OpenAI app 的 OAuth 流程连接托管 XMemo MCP server，然后为你的 XMemo 账户批准 memory:read 与 memory:write 授权。

保存一条合成偏好或项目笔记，开启新聊天，再让 ChatGPT 在继续工作前通过 XMemo 召回它。

如果 OAuth 失败或工具未出现，先在宿主应用里退出该 MCP server，重新连接 XMemo server URL 并重试，再考虑创建 direct token。

## Copilot / Codex 开发者

在 IDE 与 CLI agent 之间携带仓库决策、编码规范、bug 修复说明和任务历史。

在可用时对 VS Code / GitHub Copilot 和 Gemini CLI 使用 OAuth。对于 Copilot CLI、Codex、Cursor 或其他直连 MCP 客户端，请在本地环境或密钥存储中保留 XMEMO_KEY，并设置稳定的 XMEMO_AGENT_INSTANCE_ID。

记录一条代码库决策或 bug 修复，然后让下一个 IDE 或 CLI agent 在编辑前召回相关 XMemo 上下文。

如果召回为空，检查所选 MCP 配置路径、direct client 的 XMEMO_KEY 环境变量，以及宿主应用中是否存在过期 OAuth 凭据。

## 团队 / 企业 pilot owner

用账户控制、来源归因、导出/删除流程和 reviewer-safe 设置证据来评估共享记忆。

创建或进入受保护的 XMemo workspace，邀请已批准用户，然后根据 readiness badges 通过 OAuth 或 scoped direct credential 连接各客户端。

让一名 pilot 成员保存一条合成团队记忆，在 XMemo 中确认来源归因，然后审阅删除/导出和支持路径。

如果成员无法连接，先检查角色权限、OAuth 批准、客户端 readiness 状态和支持指引，再签发新 token。

## 自主 agent operator

让 headless 或定时 agent 记录进度、取回历史决策，并保持稳定的非秘密实例身份。

获取 /api/v1/mcp/config/autonomous-agent。当 runner 支持 OAuth + 自定义 headers 时优先使用 auth_modes.oauth；只有完全 headless 的 runner 才使用 auth_modes.xmemo_key，并从密钥库读取 XMEMO_KEY。

运行一个会向 XMemo 写入进度的合成任务，重启 runner，并确认它使用同一个 XMEMO_AGENT_INSTANCE_ID 召回该进度。

如果归因变化或召回分散到多个实例，请把 XMEMO_AGENT_INSTANCE_ID 持久化到 git 之外，并确认 runner 不会每次启动都重新生成它。