Concepts

How XMemo works

Authoritative architecture and public boundary: server composition, execution lifecycle, subsystem nodes, and managed cloud boundary.

Architectural Invariants & Core Principles

XMemo enforces non-negotiable architectural invariants separating public client surfaces from internal subsystem execution. Operational capabilities are bound to real source evidence, while confidential topology, database credentials, and cluster keys remain strictly protected under zero plaintext secret exposure.

Zero Plaintext Secret Exposure: Client configuration files, logs, and public diagnostic responses never contain unencrypted bearer tokens, database connection strings, or master keys.
Verified Source Provenance: Every persisted memory, version revision, and retrieval citation carries immutable identity metadata and audit trails bound to source code contracts.
Deterministic Token & Byte Budgets: Recall context injection strictly respects caller-specified limits, preventing LLM context window overflow.
Plan & Feature-Gate Boundaries: Enterprise features (multi-tenant BYODB, distributed sync, background dream reflection) are gated behind explicit workspace configurations and plan boundaries.

Server Composition & Lifecycle Topology

Server initialization decouples deployment-time composition and tool registration from per-request runtime execution traces. External clients do not mount the host server; rather, the host server mounts the FastMCP ASGI application, adapts it via MemoryOSMcpMountAdapter, and registers authenticated tool handlers with FastMCP before any request is received.

Step 1 [HOST_COMPOSITION]: Host Starlette/FastAPI server mounts the FastMCP ASGI app at /mcp — Relation: SERVER_MOUNTS_APP — Evidence: src/memory_manager/server.py:111 — Status: [SOURCE_BACKED_PUBLIC_CONTRACT (VERIFIED)].
Step 2 [MOUNT_ADAPTER]: mount_streamable_mcp wraps streamable_http_app in MemoryOSMcpMountAdapter to handle CORS, SSE probes, and scope rewriting — Relation: ADAPTS_ASGI_APP — Evidence: src/memory_manager/services/mcp_mount.py:532 — Status: [SOURCE_BACKED_PUBLIC_CONTRACT (VERIFIED)].
Step 3 [AUTH_REGISTRATION]: install_mcp_tool_surface registers _call_tool_with_oauth_errors as the mcp._mcp_server.call_tool handler on the FastMCP low-level server — Relation: REGISTERS_TOOL_WRAPPER — Evidence: src/memory_manager/mcp/mcp_tool_surface.py:1600 — Status: [SOURCE_BACKED_PUBLIC_CONTRACT (VERIFIED)].

+---------------------------------------------------------------------------------------------------+
| [DEPLOYMENT-TIME SERVER COMPOSITION & TOPOLOGY: 2 INDEPENDENT BRANCHES]                           |
|                                                                                                   |
| [BRANCH 1: SERVER ASGI MOUNT BRANCH]                                                              |
|  +-------------------------------------------------------+                                        |
|  | Host ASGI Server (Starlette / FastAPI)                | [PUBLIC_BOUNDARY]                      |
|  | Location: src/memory_manager/server.py:111            | [SOURCE_BACKED_PUBLIC_CONTRACT]         |
|  +-------------------------------------------------------+                                        |
|                             |                                                                     |
|                             | Relation: SERVER_MOUNTS_APP                                         |
|                             | Status: [SOURCE_BACKED_PUBLIC_CONTRACT (VERIFIED)]                  |
|                             v                                                                     |
|  +-------------------------------------------------------+                                        |
|  | mount_streamable_mcp                                  | [INTERNAL_SUBSYSTEM]                   |
|  | Location: src/memory_manager/services/mcp_mount.py:532  | [SOURCE_BACKED_PUBLIC_CONTRACT]         |
|  +-------------------------------------------------------+                                        |
|                             |                                                                     |
|                             | Relation: ADAPTS_ASGI_APP                                           |
|                             | Status: [SOURCE_BACKED_PUBLIC_CONTRACT (VERIFIED)]                  |
|                             v                                                                     |
|  +-------------------------------------------------------+                                        |
|  | MemoryOSMcpMountAdapter                               | [PUBLIC_BOUNDARY]                      |
|  | Location: src/memory_manager/services/mcp_mount.py:217  | [SOURCE_BACKED_PUBLIC_CONTRACT]         |
|  +-------------------------------------------------------+                                        |
|                                                                                                   |
| [BRANCH 2: TOOL SURFACE REGISTRATION BRANCH]                                                      |
|  +-------------------------------------------------------+                                        |
|  | install_mcp_tool_surface                              | [INTERNAL_SUBSYSTEM]                   |
|  | Location: src/memory_manager/mcp/mcp_tool_surface.py:1600 [SOURCE_BACKED_PUBLIC_CONTRACT]        |
|  +-------------------------------------------------------+                                        |
|                             |                                                                     |
|                             | Relation: REGISTERS_TOOL_WRAPPER                                    |
|                             | Status: [SOURCE_BACKED_PUBLIC_CONTRACT (VERIFIED)]                  |
|                             v                                                                     |
|  +-------------------------------------------------------+                                        |
|  | FastMCP Tool Ingress Wrapper (_call_tool_with_oauth)  | [PUBLIC_BOUNDARY]                      |
|  | Location: src/memory_manager/mcp/mcp_tool_surface.py:1569 [SOURCE_BACKED_PUBLIC_CONTRACT]        |
|  +-------------------------------------------------------+                                        |
+---------------------------------------------------------------------------------------------------+

Runtime Execution Traces

At runtime, client requests execute across four isolated, deterministic operation flows. Every step is governed by strict caller-callee relations, source evidence locators, and explicit evidence status classifications:

OP_REMEMBER_WRITE [Remember / Write Trace: 13 steps]: External Client [PUBLIC_INGRESS] [CONCEPTUAL_DELEGATED] -> MemoryOSMcpMountAdapter [TRANSPORT_ADAPTER] [SOURCE_BACKED_PUBLIC_CONTRACT (VERIFIED)] -> FastMCP ASGI [FASTMCP_DISPATCH] [CONCEPTUAL_DELEGATED] -> _call_tool_with_oauth_errors [AUTH_GATEWAY] [SOURCE_BACKED_PUBLIC_CONTRACT (VERIFIED)] -> remember tool [AUTH_IDENTITY] [SOURCE_BACKED_PUBLIC_CONTRACT (VERIFIED)] -> _assert_setup_for_ctx [SETUP_GATE] [SOURCE_BACKED_PUBLIC_CONTRACT (VERIFIED)] -> sanitize_server_write [PII_REDACTION] [SOURCE_BACKED_PUBLIC_CONTRACT (VERIFIED)] -> enforce_memory_write_envelope [SECURITY_ENVELOPE] [SOURCE_BACKED_PUBLIC_CONTRACT (VERIFIED)] -> PersistenceEngine [PERSISTENCE_MUTATION] [SOURCE_BACKED_PUBLIC_CONTRACT (VERIFIED)]. Relations: 2 [CONCEPTUAL_DELEGATED], 11 [SOURCE_BACKED_PUBLIC_CONTRACT (VERIFIED)].
OP_RECALL_READ [Recall / Read Trace: 12 steps]: External Client [PUBLIC_INGRESS] [CONCEPTUAL_DELEGATED] -> MemoryOSMcpMountAdapter [TRANSPORT_ADAPTER] [SOURCE_BACKED_PUBLIC_CONTRACT (VERIFIED)] -> FastMCP ASGI [FASTMCP_DISPATCH] [CONCEPTUAL_DELEGATED] -> _call_tool_with_oauth_errors [AUTH_GATEWAY] [SOURCE_BACKED_PUBLIC_CONTRACT (VERIFIED)] -> recall tool [AUTH_IDENTITY] [SOURCE_BACKED_PUBLIC_CONTRACT (VERIFIED)] -> assert_requested_team_matches_bound_space [SCOPE_ISOLATION] [SOURCE_BACKED_PUBLIC_CONTRACT (VERIFIED)] -> SearchEngine.search [HYBRID_RETRIEVAL] [SOURCE_BACKED_PUBLIC_CONTRACT (VERIFIED)] -> SearchEngine.rerank_recall_results [CANDIDATE_RERANK] [SOURCE_BACKED_PUBLIC_CONTRACT (VERIFIED)] -> _apply_recall_response_budget [BUDGET_ASSEMBLY] [SOURCE_BACKED_PUBLIC_CONTRACT (VERIFIED)] -> _public_recall_meta [PUBLIC_CITATION] [SOURCE_BACKED_PUBLIC_CONTRACT (VERIFIED)]. Relations: 2 [CONCEPTUAL_DELEGATED], 10 [SOURCE_BACKED_PUBLIC_CONTRACT (VERIFIED)].
OP_UPDATE_VERSION [Update / Versioning Trace: 13 steps]: External Client [PUBLIC_INGRESS] [CONCEPTUAL_DELEGATED] -> MemoryOSMcpMountAdapter [TRANSPORT_ADAPTER] [SOURCE_BACKED_PUBLIC_CONTRACT (VERIFIED)] -> FastMCP ASGI [FASTMCP_DISPATCH] [CONCEPTUAL_DELEGATED] -> _call_tool_with_oauth_errors [AUTH_GATEWAY] [SOURCE_BACKED_PUBLIC_CONTRACT (VERIFIED)] -> update_memory tool [AUTH_IDENTITY] [SOURCE_BACKED_PUBLIC_CONTRACT (VERIFIED)] -> _assert_setup_for_ctx [SETUP_GATE] [SOURCE_BACKED_PUBLIC_CONTRACT (VERIFIED)] -> sanitize_server_write [PII_REDACTION] [SOURCE_BACKED_PUBLIC_CONTRACT (VERIFIED)] -> enforce_memory_write_envelope [SECURITY_ENVELOPE] [SOURCE_BACKED_PUBLIC_CONTRACT (VERIFIED)] -> PersistenceEngine [PERSISTENCE_MUTATION] [SOURCE_BACKED_PUBLIC_CONTRACT (VERIFIED)] -> VersionController.superseded_snapshot [VERSION_DAG] [SOURCE_BACKED_PUBLIC_CONTRACT (VERIFIED)]. Relations: 2 [CONCEPTUAL_DELEGATED], 11 [SOURCE_BACKED_PUBLIC_CONTRACT (VERIFIED)].
OP_FORGET_LIFECYCLE [Forget / Lifecycle Trace: 11 steps]: External Client [PUBLIC_INGRESS] [CONCEPTUAL_DELEGATED] -> MemoryOSMcpMountAdapter [TRANSPORT_ADAPTER] [SOURCE_BACKED_PUBLIC_CONTRACT (VERIFIED)] -> FastMCP ASGI [FASTMCP_DISPATCH] [CONCEPTUAL_DELEGATED] -> _call_tool_with_oauth_errors [AUTH_GATEWAY] [SOURCE_BACKED_PUBLIC_CONTRACT (VERIFIED)] -> forget tool [AUTH_IDENTITY] [SOURCE_BACKED_PUBLIC_CONTRACT (VERIFIED)] -> _assert_setup_for_ctx [SETUP_GATE] [SOURCE_BACKED_PUBLIC_CONTRACT (VERIFIED)] -> PersistenceEngine soft tombstone [TOMBSTONE_MARK] [SOURCE_BACKED_PUBLIC_CONTRACT (VERIFIED)] -> Background Lifecycle Daemon [BATCH_POLICY_EVALUATION] [CONCEPTUAL_DELEGATED] -> SearchEngine query exclusion [EXCLUDES_AT_QUERY] [SOURCE_BACKED_PUBLIC_CONTRACT (VERIFIED)]. Relations: 4 [CONCEPTUAL_DELEGATED], 7 [SOURCE_BACKED_PUBLIC_CONTRACT (VERIFIED)].

+------------------------------------------------------------------------------------------------------------------------+
| [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                                  |
|              Locator: src/memory_manager/services/mcp_mount.py:217 [CONCEPTUAL_DELEGATED]                              |
|     Step 2:   MemoryOSMcpMountAdapter --[DELEGATES_ASGI_REQUEST]--> FastMCP.streamable_http_app                        |
|              Locator: src/memory_manager/services/mcp_mount.py:426 [SOURCE_BACKED_PUBLIC_CONTRACT]                     |
|     Step 3:   FastMCP --[DISPATCHES_TOOL_INVOCATION]--> _call_tool_with_oauth_errors                                   |
|              Locator: src/memory_manager/mcp/mcp_tool_surface.py:1600 [CONCEPTUAL_DELEGATED]                           |
|     Step 4:   _call_tool_with_oauth_errors --[DISPATCHES_TOOL]--> tools.py::remember                                   |
|              Locator: src/memory_manager/mcp/mcp_tool_surface.py:1569 [SOURCE_BACKED_PUBLIC_CONTRACT]                  |
|     Step 5:   tools.py::remember --[CALLS]--> memory_helpers.py::_identity_context                                     |
|              Locator: src/memory_manager/mcp/tools.py:795 [SOURCE_BACKED_PUBLIC_CONTRACT]                              |
|     Step 6:   tools.py::remember --[CALLS]--> memory_helpers.py::_assert_setup_for_ctx                                 |
|              Locator: src/memory_manager/mcp/tools.py:866 [SOURCE_BACKED_PUBLIC_CONTRACT]                              |
|     Step 7:   memory_helpers.py::_assert_setup_for_ctx --[CALLS]--> gate.py::assert_setup_completed                    |
|              Locator: src/memory_manager/mcp/memory_helpers.py:792 [SOURCE_BACKED_PUBLIC_CONTRACT]                     |
|     Step 8:   tools.py::remember --[CALLS]--> memory_helpers.py::_prepare_mcp_memory_write                             |
|              Locator: src/memory_manager/mcp/tools.py:982 [SOURCE_BACKED_PUBLIC_CONTRACT]                              |
|     Step 9:   memory_helpers.py::_prepare_mcp_memory_write --[CALLS]--> redact.py::sanitize_server_write               |
|              Locator: src/memory_manager/mcp/memory_helpers.py:68 [SOURCE_BACKED_PUBLIC_CONTRACT]                      |
|     Step 10:  memory_helpers.py::_prepare_mcp_memory_write --[CALLS]--> security_envelope.py::enforce_memory_write_envelope |
|              Locator: src/memory_manager/mcp/memory_helpers.py:80 [SOURCE_BACKED_PUBLIC_CONTRACT]                      |
|     Step 11:  tools.py::remember --[CALLS]--> memory_helpers.py::_with_tenant_metadata                                 |
|              Locator: src/memory_manager/mcp/tools.py:998 [SOURCE_BACKED_PUBLIC_CONTRACT]                              |
|     Step 12:  tools.py::remember --[CALLS]--> core_manager.py::MemoryManager.remember                                  |
|              Locator: src/memory_manager/mcp/tools.py:1008 [SOURCE_BACKED_PUBLIC_CONTRACT]                             |
|     Step 13:  core_manager.py::MemoryManager.remember --[CALLS]--> persistence.py::PersistenceEngine.remember          |
|              Locator: src/memory_manager/core_manager.py:1162 [SOURCE_BACKED_PUBLIC_CONTRACT]                          |
|                                                                                                                        |
| 2. OP_RECALL_READ [READ RETRIEVAL FLOW: 12 STEPS]                                                                      |
|     Step 1:   External Client --[CLIENT_REQUESTS_ENDPOINT]--> MemoryOSMcpMountAdapter                                  |
|              Locator: src/memory_manager/services/mcp_mount.py:217 [CONCEPTUAL_DELEGATED]                              |
|     Step 2:   MemoryOSMcpMountAdapter --[DELEGATES_ASGI_REQUEST]--> FastMCP.streamable_http_app                        |
|              Locator: src/memory_manager/services/mcp_mount.py:426 [SOURCE_BACKED_PUBLIC_CONTRACT]                     |
|     Step 3:   FastMCP --[DISPATCHES_TOOL_INVOCATION]--> _call_tool_with_oauth_errors                                   |
|              Locator: src/memory_manager/mcp/mcp_tool_surface.py:1600 [CONCEPTUAL_DELEGATED]                           |
|     Step 4:   _call_tool_with_oauth_errors --[DISPATCHES_TOOL]--> tools.py::recall                                     |
|              Locator: src/memory_manager/mcp/mcp_tool_surface.py:1569 [SOURCE_BACKED_PUBLIC_CONTRACT]                  |
|     Step 5:   tools.py::recall --[CALLS]--> tools.py::_search_memory_impl                                              |
|              Locator: src/memory_manager/mcp/tools.py:6996 [SOURCE_BACKED_PUBLIC_CONTRACT]                             |
|     Step 6:   tools.py::_search_memory_impl --[CALLS]--> memory_helpers.py::_identity_context                          |
|              Locator: src/memory_manager/mcp/tools.py:1659 [SOURCE_BACKED_PUBLIC_CONTRACT]                             |
|     Step 7:   tools.py::_search_memory_impl --[CALLS]--> memory_space_binding.py::assert_requested_team_matches_bound_space |
|              Locator: src/memory_manager/mcp/tools.py:1689 [SOURCE_BACKED_PUBLIC_CONTRACT]                             |
|     Step 8:   tools.py::_search_memory_impl --[CALLS]--> core_manager.py::MemoryManager.search                         |
|              Locator: src/memory_manager/mcp/tools.py:1698 [SOURCE_BACKED_PUBLIC_CONTRACT]                             |
|     Step 9:   core_manager.py::MemoryManager.search --[CALLS]--> search.py::SearchEngine.search                        |
|              Locator: src/memory_manager/core_manager.py:2148 [SOURCE_BACKED_PUBLIC_CONTRACT]                          |
|     Step 10:  search.py::SearchEngine.search_impl --[CALLS]--> search.py::SearchEngine.rerank_recall_results           |
|              Locator: src/memory_manager/engines/search.py:6613 [SOURCE_BACKED_PUBLIC_CONTRACT]                        |
|     Step 11:  search.py::_assemble_recall_context_legacy --[CALLS]--> search.py::_apply_recall_response_budget         |
|              Locator: src/memory_manager/engines/search.py:3305 [SOURCE_BACKED_PUBLIC_CONTRACT]                        |
|     Step 12:  search.py::_apply_recall_response_budget --[CALLS]--> search.py::_public_recall_meta                     |
|              Locator: src/memory_manager/engines/search.py:3454 [SOURCE_BACKED_PUBLIC_CONTRACT]                        |
|                                                                                                                        |
| 3. OP_UPDATE_VERSION [VERSIONING & CORRECTION FLOW: 13 STEPS]                                                          |
|     Step 1:   External Client --[CLIENT_REQUESTS_ENDPOINT]--> MemoryOSMcpMountAdapter                                  |
|              Locator: src/memory_manager/services/mcp_mount.py:217 [CONCEPTUAL_DELEGATED]                              |
|     Step 2:   MemoryOSMcpMountAdapter --[DELEGATES_ASGI_REQUEST]--> FastMCP.streamable_http_app                        |
|              Locator: src/memory_manager/services/mcp_mount.py:426 [SOURCE_BACKED_PUBLIC_CONTRACT]                     |
|     Step 3:   FastMCP --[DISPATCHES_TOOL_INVOCATION]--> _call_tool_with_oauth_errors                                   |
|              Locator: src/memory_manager/mcp/mcp_tool_surface.py:1600 [CONCEPTUAL_DELEGATED]                           |
|     Step 4:   _call_tool_with_oauth_errors --[DISPATCHES_TOOL]--> tools.py::update_memory                              |
|              Locator: src/memory_manager/mcp/mcp_tool_surface.py:1569 [SOURCE_BACKED_PUBLIC_CONTRACT]                  |
|     Step 5:   tools.py::update_memory --[CALLS]--> memory_helpers.py::_identity_context                                |
|              Locator: src/memory_manager/mcp/tools.py:7045 [SOURCE_BACKED_PUBLIC_CONTRACT]                             |
|     Step 6:   tools.py::update_memory --[CALLS]--> memory_helpers.py::_assert_setup_for_ctx                            |
|              Locator: src/memory_manager/mcp/tools.py:7065 [SOURCE_BACKED_PUBLIC_CONTRACT]                             |
|     Step 7:   tools.py::update_memory --[CALLS]--> memory_helpers.py::_require_memory_in_mcp_scope                     |
|              Locator: src/memory_manager/mcp/tools.py:7066 [SOURCE_BACKED_PUBLIC_CONTRACT]                             |
|     Step 8:   tools.py::update_memory --[CALLS]--> memory_helpers.py::_prepare_mcp_memory_write                        |
|              Locator: src/memory_manager/mcp/tools.py:7114 [SOURCE_BACKED_PUBLIC_CONTRACT]                             |
|     Step 9:   memory_helpers.py::_prepare_mcp_memory_write --[CALLS]--> redact.py::sanitize_server_write               |
|              Locator: src/memory_manager/mcp/memory_helpers.py:68 [SOURCE_BACKED_PUBLIC_CONTRACT]                      |
|     Step 10:  tools.py::update_memory --[CALLS]--> memory_helpers.py::_with_tenant_metadata                            |
|              Locator: src/memory_manager/mcp/tools.py:7144 [SOURCE_BACKED_PUBLIC_CONTRACT]                             |
|     Step 11:  tools.py::update_memory --[CALLS]--> core_manager.py::MemoryManager.update_memory                        |
|              Locator: src/memory_manager/mcp/tools.py:7146 [SOURCE_BACKED_PUBLIC_CONTRACT]                             |
|     Step 12:  core_manager.py::MemoryManager.update_memory --[CALLS]--> persistence.py::PersistenceEngine.update_memory |
|              Locator: src/memory_manager/core_manager.py:1040 [SOURCE_BACKED_PUBLIC_CONTRACT]                          |
|     Step 13:  persistence.py::PersistenceEngine.update_memory --[CALLS]--> versioning.py::VersionController.superseded_snapshot |
|              Locator: src/memory_manager/engines/persistence.py:3939 [SOURCE_BACKED_PUBLIC_CONTRACT]                   |
|                                                                                                                        |
| 4. OP_FORGET_LIFECYCLE [RETENTION & LIFECYCLE FLOW: 11 STEPS]                                                          |
|     Step 1:   External Client --[CLIENT_REQUESTS_ENDPOINT]--> MemoryOSMcpMountAdapter                                  |
|              Locator: src/memory_manager/services/mcp_mount.py:217 [CONCEPTUAL_DELEGATED]                              |
|     Step 2:   MemoryOSMcpMountAdapter --[DELEGATES_ASGI_REQUEST]--> FastMCP.streamable_http_app                        |
|              Locator: src/memory_manager/services/mcp_mount.py:426 [SOURCE_BACKED_PUBLIC_CONTRACT]                     |
|     Step 3:   FastMCP --[DISPATCHES_TOOL_INVOCATION]--> _call_tool_with_oauth_errors                                   |
|              Locator: src/memory_manager/mcp/mcp_tool_surface.py:1600 [CONCEPTUAL_DELEGATED]                           |
|     Step 4:   _call_tool_with_oauth_errors --[DISPATCHES_TOOL]--> tools.py::forget                                     |
|              Locator: src/memory_manager/mcp/mcp_tool_surface.py:1569 [SOURCE_BACKED_PUBLIC_CONTRACT]                  |
|     Step 5:   tools.py::forget --[CALLS]--> memory_helpers.py::_identity_context                                       |
|              Locator: src/memory_manager/mcp/tools.py:7235 [SOURCE_BACKED_PUBLIC_CONTRACT]                             |
|     Step 6:   tools.py::forget --[CALLS]--> memory_helpers.py::_assert_setup_for_ctx                                   |
|              Locator: src/memory_manager/mcp/tools.py:7296 [SOURCE_BACKED_PUBLIC_CONTRACT]                             |
|     Step 7:   tools.py::forget --[CALLS]--> core_manager.py::MemoryManager.forget_memory                               |
|              Locator: src/memory_manager/mcp/tools.py:7345 [SOURCE_BACKED_PUBLIC_CONTRACT]                             |
|     Step 8:   core_manager.py::MemoryManager.forget_memory --[CALLS]--> persistence.py::PersistenceEngine.forget_memory |
|              Locator: src/memory_manager/core_manager.py:1091 [SOURCE_BACKED_PUBLIC_CONTRACT]                          |
|     Step 9:   Background Lifecycle Processor --[BATCH_POLICY_EVALUATION]--> lifecycle.py::should_archive               |
|              Locator: src/memory_manager/engines/lifecycle.py:345 [CONCEPTUAL_DELEGATED]                               |
|     Step 10:  Background Lifecycle Processor --[BATCH_POLICY_EVALUATION]--> lifecycle.py::should_decay_importance      |
|              Locator: src/memory_manager/engines/lifecycle.py:216 [CONCEPTUAL_DELEGATED]                               |
|     Step 11:  search.py::SearchEngine.search --[EXCLUDES_AT_QUERY]--> Database Storage Engine                          |
|              Locator: src/memory_manager/engines/search.py:5852 [SOURCE_BACKED_PUBLIC_CONTRACT]                        |
+------------------------------------------------------------------------------------------------------------------------+

Subsystem Decomposition & Boundary Classification

The system decomposes into ten verified subsystem nodes. Each node carries a strict boundary classification (PUBLIC_BOUNDARY or INTERNAL_SUBSYSTEM) and an empirical evidence status (SOURCE_BACKED_PUBLIC_CONTRACT / VERIFIED, CONCEPTUAL_DELEGATED, or NOT_VERIFIED):

NODE_1_CLIENT_AGENT_LAYER: Client & Agent Ecosystem (@xmemo/client, Claude Desktop, Cursor, Codex) — Classification: [PUBLIC_BOUNDARY] — Evidence Status: [SOURCE_BACKED_PUBLIC_CONTRACT (VERIFIED)] — Source: packages/memory-os-js/package.json.
NODE_2_TRANSPORT_ADAPTER: MCP Transport & Protocol Adapter (MemoryOSMcpMountAdapter, mount_streamable_mcp) — Classification: [PUBLIC_BOUNDARY] — Evidence Status: [SOURCE_BACKED_PUBLIC_CONTRACT (VERIFIED)] — Source: src/memory_manager/services/mcp_mount.py:532.
NODE_3_IDENTITY_AUTH_GATE: Identity & Authorization Gate (_call_tool_with_oauth_errors, install_mcp_tool_surface) — Classification: [PUBLIC_BOUNDARY] — Evidence Status: [SOURCE_BACKED_PUBLIC_CONTRACT (VERIFIED)] — Source: src/memory_manager/mcp/mcp_tool_surface.py:1600.
NODE_4_SANITIZATION_ENVELOPE: PII Sanitization & Vault Envelope (sanitize_server_write, enforce_memory_write_envelope) — Classification: [INTERNAL_SUBSYSTEM] — Evidence Status: [SOURCE_BACKED_PUBLIC_CONTRACT (VERIFIED)] — Source: src/memory_manager/security/redact.py:266.
NODE_5_SCOPE_ISOLATION_GUARD: Scope & Multi-Tenant Isolation Guard (BoundSpace, assert_requested_team_matches_bound_space) — Classification: [INTERNAL_SUBSYSTEM] — Evidence Status: [SOURCE_BACKED_PUBLIC_CONTRACT (VERIFIED)] — Source: src/memory_manager/auth/memory_space_binding.py:101.
NODE_6_SEARCH_TEMPORAL_PARSER: Search & Temporal Query Parser (TemporalQuerySpec, extract_temporal_context) — Classification: [INTERNAL_SUBSYSTEM] — Evidence Status: [SOURCE_BACKED_PUBLIC_CONTRACT (VERIFIED)] — Source: src/memory_manager/models/temporal_query_spec.py.
NODE_7_CANDIDATE_SCORER: Candidate Scorer & Reranker (SearchEngine.rerank_recall_results) — Classification: [INTERNAL_SUBSYSTEM] — Evidence Status: [SOURCE_BACKED_PUBLIC_CONTRACT (VERIFIED)] — Source: src/memory_manager/engines/search.py:2910.
NODE_8_VERSION_LIFECYCLE_ENGINE: Version & Lifecycle Controller (VersionController.superseded_snapshot) — Classification: [INTERNAL_SUBSYSTEM] — Evidence Status: [SOURCE_BACKED_PUBLIC_CONTRACT (VERIFIED)] — Source: src/memory_manager/engines/versioning.py:314.
NODE_9_CONTEXT_BUDGET_ASSEMBLER: Context Budget Assembler (_apply_recall_response_budget) — Classification: [INTERNAL_SUBSYSTEM] — Evidence Status: [SOURCE_BACKED_PUBLIC_CONTRACT (VERIFIED)] — Source: src/memory_manager/engines/search.py:5880.
NODE_10_PUBLIC_RECEIPT_CITATION: Public Receipt & Citation Formatter (_public_recall_meta) — Classification: [PUBLIC_BOUNDARY] — Evidence Status: [SOURCE_BACKED_PUBLIC_CONTRACT (VERIFIED)] — Source: src/memory_manager/engines/search.py:5960.

Open-Source vs Managed Cloud Service Boundary

Public architectural assertions and ecosystem claims are evaluated against the empirical code contract. Claims are strictly classified as VERIFIED (supported by executable tests and code symbols) or NOT_VERIFIED (refuted, unverified, or restricted to proprietary hosted environments):

STMT_01_PROVENANCE_ATTRIBUTION [VERIFIED]: XMemo provides cryptographic and tamper-evident provenance attribution for all stored memories. Grounding: src/memory_manager/security/security_envelope.py::enforce_memory_write_envelope.
STMT_02_CROSS_CLIENT_CONTINUITY [VERIFIED]: Memories captured across Claude Desktop, Cursor, or CLI are instantly accessible across any MCP-compliant client via standard JSON-RPC. Grounding: src/memory_manager/services/mcp_mount.py::mount_streamable_mcp.
STMT_03_REALTIME_CORRECTION [VERIFIED]: Fact updates maintain immutable version history while superseding prior conflicting memories via parent pointers. Grounding: src/memory_manager/engines/versioning.py::VersionController.superseded_snapshot.
STMT_04_TOKEN_BUDGET_GUARANTEE [VERIFIED]: Recall context injection strictly respects caller-specified token and byte budgets. Grounding: src/memory_manager/engines/search.py::_apply_recall_response_budget.
STMT_05_ZERO_TOKEN_EXPOSURE [VERIFIED]: Unauthenticated requests and unauthorized scopes are denied at the gateway without executing storage queries or exposing tokens. Grounding: src/memory_manager/mcp/mcp_tool_surface.py::_call_tool_with_oauth_errors.
STMT_06_BACKEND_OPEN_SOURCE_CLAIM [NOT_VERIFIED]: Claim of 100% open-source backend is REFUTED. Only client packages (@xmemo/client, MIT license) and local MCP server adapters are open source. Multi-tenant cloud infrastructure, billing, and fleet orchestration remain proprietary managed services.
STMT_07_AUTONOMOUS_CONSENSUS_CLAIM [NOT_VERIFIED]: Autonomous cross-organization consensus is REFUTED. Tenant isolation is strictly enforced by BoundSpace and tenant_id partitioning; cross-tenant automatic merging is not implemented.
STMT_08_ZERO_LATENCY_REPLICATION_CLAIM [NOT_VERIFIED]: Zero-latency global replication claim is REFUTED. Search uses embedded/local vector indices (Qdrant/SQLite); zero-latency global consistency is unverified and not claimed.

Reproducible Architecture Lifecycle Walkthrough (Synthetic A/B Example)

A step-by-step verifiable lifecycle walkthrough demonstrating cross-agent memory sharing, multi-tenant isolation, realtime user correction, and immutable provenance tracking using strictly synthetic demo data. Every step maps directly to verified system capabilities and approved claim IDs under the public contract:

Step 1 [AGENT_A_WRITE]: Agent A (ide-assistant-alpha) writes synthetic preference via tools.py::remember to scope 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) recalls preference within authorized scope project:synthetic-demo via tools.py::recall — 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]: Unauthorized Agent (rogue-guest-gamma) attempts cross-tenant access to project:synthetic-demo without valid credentials — Gate: assert_requested_team_matches_bound_space & _call_tool_with_oauth_errors — 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]: User corrects formatting standard via tools.py::update_memory — Payload: {'formatting': 'spaces', 'indent': 2}, reason: 'team style guide update' — Controller: VersionController.superseded_snapshot — 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]: Subsequent recall query selects updated version 2 while active candidate queries strictly exclude superseded version 1 via SearchEngine — 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]: Audit inspection of version history and tamper-evident DAG via VersionController — Chain: v1 (initial write by ide-assistant-alpha) -> v2 (superseded_by user correction) — Claim: [STMT_01_PROVENANCE_ATTRIBUTION] — Verification: Cryptographic hash chain and parent pointers fully inspectable — Status: [SOURCE_BACKED_PUBLIC_CONTRACT (VERIFIED)] — Boundary: [DEMO_DATA: SYNTHETIC].
Step 7 [STATE_RESET]: Resettable sandbox controls restore synthetic workspace scope project:synthetic-demo to clean baseline — 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]: Cloud multi-tenant billing pipelines [STMT_06_BACKEND_OPEN_SOURCE_CLAIM], autonomous cross-organization consensus [STMT_07_AUTONOMOUS_CONSENSUS_CLAIM], and zero-latency cross-region replication [STMT_08_ZERO_LATENCY_REPLICATION_CLAIM] are [NOT_VERIFIED] and excluded from this local open-source runtime walkthrough.

+------------------------------------------------------------------------------------------------------------------------+
| [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              |                              |                |
+------------------------------------------------------------------------------------------------------------------------+

Explore specific architectural domains through our deep-dive concept and security documentation:

Memory Data Model (/docs/concepts/memory-model): Entity structures, semantic categories, importance scores, and representation layers.
Provenance & Attribution (/docs/concepts/provenance-attribution): Audit trails, caller attribution, signature envelopes, and tamper evidence.
Project Memory Spaces (/docs/concepts/projects): Project boundary isolation, path routing conventions, and team sharing.
Dream & Memory Consolidation (/docs/concepts/dream-reflection): Background consolidation, graph linkage, association extraction, and dream jobs.
External Knowledge Bases (/docs/concepts/knowledge-bases): Document indexing, chunking strategies, and reference citations.
Data Boundary & Security (/docs/security/data-boundary): Comprehensive delineation between local self-hosted capabilities and cloud SaaS services.

Persona flows

ChatGPT user

Give ChatGPT durable access to your XMemo preferences, project facts, decisions, and TODOs without pasting bearer tokens into a chat.

Save a synthetic preference or project note, start a new chat, then ask ChatGPT to recall it through XMemo before continuing work.

Copilot / Codex developer

Carry repo decisions, coding conventions, bug-fix notes, and task history between IDE and CLI agents.

Record a codebase decision or bug fix, then ask the next IDE or CLI agent to recall the relevant XMemo context before editing.

Team / enterprise pilot owner

Evaluate shared memory with account controls, source attribution, export/delete workflows, and reviewer-safe setup evidence.

Have a pilot member save a synthetic team memory, confirm source attribution in XMemo, then review delete/export and support paths.

Source: How XMemo works