# 작동 원리 신뢰할 수 있는 아키텍처 및 공용 경계: 서버 구성, 수명 주기, 서브시스템 노드 및 클라우드 경계. - Canonical: https://docs.xmemo.dev/ko/docs/concepts/how-xmemo-works - Locale: ko-KR - Content-Locale: ko-KR - Canonical-Content-Digest: 321f29a0f9c36406e495bc50c7110f64ee7680a5bf2706f6b5eef7ecfa09163d - Edition-Digest: 4febc33321c77097d685d6301733a8cf578a94380bb24de9b5622e6d95d0eb61 - Source-Revision: sha256:8310426b563698994f72fce9d60572391625bf1c49e90527246490ed5f7a65b5 ## 간소화된 아키텍처: 7단계 메모리 파이프라인 XMemo는 7단계 파이프라인(Capture → Scope → Retrieve → Rerank → Assemble → Govern → Consolidate)을 통해 에이전트 메모리를 처리합니다. 각 단계는 메모리 작업의 신속성, 정확성, 경계 격리, 검증 가능성을 보장하기 위해 전용 책임을 수행합니다: - Capture: 표준 Model Context Protocol(MCP) 또는 REST API를 통해 AI 클라이언트의 메모리 작성 및 업데이트 요청을 수신하고, 저장 전에 민감한 데이터를 정제합니다. 사용자에게 미치는 영향: 에이전트는 비밀이나 개인정보를 노출하지 않고 표준 도구를 통해 메모, 결정 사항, 선호도를 자동으로 저장할 수 있습니다. - Scope: 호출자의 ID 컨텍스트를 확인하고 사용자, 세션, 에이전트, 워크스페이스 계층에 걸쳐 엄격한 멀티테넌트 경계를 적용합니다. 사용자에게 미치는 영향: 각 에이전트는 승인된 경계 내의 메모리에만 접근하므로 개인 데이터와 팀 데이터가 안전하게 격리됩니다. - Retrieve: 벡터 의미 임베딩과 정확한 키워드 매칭을 결합한 하이브리드 검색 엔진을 사용하여 저장된 메모리를 검색합니다. 사용자에게 미치는 영향: 에이전트는 주제의 의미로 검색하든 정확한 문구나 식별자로 검색하든 올바른 팩트를 정확히 회상합니다. - Rerank: 의미론적 관련성, 최신성, 중요도 가중치를 종합적으로 평가하여 후보 메모리를 채점합니다. 사용자에게 미치는 영향: 에이전트는 오래되거나 우선순위가 낮은 대화 조각 대신 가장 관련성 높고 최신의 컨텍스트를 제공받습니다. - Assemble: 호출자가 지정한 토큰 및 바이트 예산을 엄격히 준수하면서 회상된 메모리를 프롬프트 준비 컨텍스트로 패키징합니다. 사용자에게 미치는 영향: 주입된 메모리가 모델의 컨텍스트 창을 초과하거나 예상치 못한 토큰 비용을 유발하지 않습니다. - Govern: 운영 감사 로그를 기록하고, 버전 기록(memory_versions)을 추적하며, 키가드/볼트 모드가 활성화된 경우 암호화 봉투를 적용합니다. 사용자에게 미치는 영향: 모든 메모리 업데이트는 완전한 감사 책임을 바탕으로 추적, 검증 및 복구할 수 있습니다. - Consolidate: 최근 에피소드 상호작용을 구조화된 후보 인사이트로 합성하기 위해 메모리 통합(Dream)을 미리 보여주며, 저장하기 전에 사람의 확인이 필요합니다. 사용자에게 미치는 영향: 자동적이고 예기치 않은 변경 없이, 대화형 에이전트 채팅을 지연시키지도 않으면서 검토를 위한 유용한 인사이트가 준비됩니다. ## 아키텍처 내부 구조 / 근거 XMemo 코드베이스에 대해 직접 검증된 신뢰할 수 있는 아키텍처 구현 세부사항, 실행 추적 및 실증적 계약입니다. 다음 섹션에서는 구체적인 런타임 구성, 격리된 하위 시스템 경계 및 공식 검증 매트릭스를 문서화합니다. ## 아키텍처 불변조건 및 핵심 원칙 XMemo는 공용 클라이언트 표면과 내부 서브시스템 실행을 엄격히 분리하는 불변 원칙을 따릅니다. 모든 기능은 코드 근거에 귀속되며, 비공개 토폴로지 및 클러스터 키는 평문 비밀 유출 제로 원칙 하에 보호됩니다. - 평문 비밀 유출 제로: 클라이언트 설정 파일, 로그 및 진단 응답에 암호화되지 않은 Bearer 토큰이나 DB 연결 문자열이 포함되지 않습니다. - 검증된 출처 증명: 저장된 모든 기억, 버전 및 인용은 불변의 메타데이터와 감사 추적을 유지합니다. - 결정론적 토큰 및 바이트 예산: 호출자가 지정한 제한을 엄격히 준수하여 LLM 컨텍스트 초과를 방지합니다. - 플랜 및 기능 게이트 경계: 멀티 테넌트 BYODB, 분산 동기화 및 백그라운드 Dream 스케줄링은 명시적 워크스페이스 설정, 기능 플래그 및 플랜 경계로 통제됩니다. ## 서버 구성 및 수명 주기 토폴로지 서버 초기화는 배포 시 구성 및 도구 등록을 요청별 실행 경로와 엄격히 분리합니다. 클라이언트는 서버를 직접 마운트하지 않으며, 호스트 서버가 FastMCP ASGI 앱을 마운트하고 어댑터를 통해 연결합니다. - 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를 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] | | +-------------------------------------------------------+ | +---------------------------------------------------------------------------------------------------+ ``` ## 런타임 실행 추적 런타임 시 클라이언트 요청은 4개의 독립적이고 결정론적인 작업 흐름에 따라 실행됩니다. 모든 단계는 엄격한 호출 관계와 명시적 아키텍처 경계 분류를 따릅니다: - OP_REMEMBER_WRITE [기억 / 쓰기 추적: 13단계]: 외부 클라이언트 [PUBLIC_INGRESS] -> MemoryOSMcpMountAdapter [TRANSPORT_ADAPTER] -> FastMCP ASGI 디스패치 -> 툴 인증 게이트 -> remember 툴 -> 설정 검증 게이트 -> 개인정보 보호 봉투 -> 보안 봉투(Keyguard/Vault 모드 활성화 시 암호화) -> 영속성 엔진. 프로토콜 수신, 인증, 마스킹 및 영속성에 이르는 검증된 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 툴 -> 설정 검증 게이트 -> 개인정보 보호 봉투 -> 보안 봉투(Keyguard/Vault 모드 활성화 시 암호화) -> 영속성 엔진 -> 불변 버전 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] | +------------------------------------------------------------------------------------------------------------------------+ ``` ## 서브시스템 분해 및 경계 분류 시스템은 10개의 검증된 서브시스템 노드로 구성되며, 각 노드는 엄격한 경계 분류(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]: 캡처된 기억은 표준 JSON-RPC를 통해 모든 MCP 호환 클라이언트에서 즉시 액세스할 수 있습니다. 아키텍처: 스트리밍 FastMCP ASGI 어댑터. - STMT_03_REALTIME_CORRECTION [VERIFIED]: 사실 업데이트는 불변 버전 기록을 유지하면서 이전 충돌 기억을 대체합니다. 아키텍처: 불변 버전 DAG 컨트롤러. - STMT_04_TOKEN_BUDGET_GUARANTEE [VERIFIED]: 회상 컨텍스트 주입은 지정된 토큰 및 바이트 예산을 엄격히 준수합니다. 아키텍처: 결정론적 토큰 예산 어셈블러. - STMT_05_ZERO_TOKEN_EXPOSURE [VERIFIED]: 인증되지 않은 요청은 게이트웨이에서 즉시 거부되며 토큰 노출이 발생하지 않습니다. 아키텍처: 수신 인증 및 스코프 격리 게이트. - STMT_06_BACKEND_OPEN_SOURCE_CLAIM [NOT_VERIFIED]: 백엔드 전체 오픈 소스 주장은 기각되었습니다. 클라이언트 패키지(@xmemo/client)와 로컬 MCP 어댑터만 오픈 소스이며, 멀티테넌트 클라우드 인프라는 독점 관리형 서비스입니다. - STMT_07_AUTONOMOUS_CONSENSUS_CLAIM [NOT_VERIFIED]: 조직 간 자율 합의 주장은 기각되었습니다. 테넌트 격리는 엄격히 유지되며 교차 테넌트 자동 병합 기능은 제공되지 않습니다. - STMT_08_ZERO_LATENCY_REPLICATION_CLAIM [NOT_VERIFIED]: 지연 시간 제로 글로벌 복제 주장은 기각되었습니다. 검색은 임베디드 벡터 색인을 사용하며 지연 시간 제로 보장은 없습니다. ## 재현 가능한 아키텍처 라이프사이클 워크스루 (합성 A/B 예시) 완전히 결정론적인 합성 데모 데이터를 사용하여 에이전트 간 메모리 공유, 멀티테넌트 격리, 실시간 사용자 교정 및 불변 출처 추적을 단계별로 검증합니다. 모든 단계는 공개 계약에 따른 검증된 시스템 기능 및 승인된 클레임 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: 결정론적 분해 및 상태 제거 — 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 사용자 채팅에 전달자 토큰을 붙여넣지 않고도 XMemo 기본 설정, 프로젝트 사실, 결정 및 TODO에 대한 지속 가능한 액세스를 ChatGPT에 부여하세요. ChatGPT/OpenAI 앱 OAuth 흐름을 통해 호스팅된 XMemo MCP 서버를 연결한 다음 XMemo 계정에 대한 메모리:읽기 및 메모리:쓰기 권한을 승인합니다. 종합 기본 설정이나 프로젝트 노트를 저장하고 새 채팅을 시작한 다음 작업을 계속하기 전에 XMemo를 통해 ChatGPT에 이를 불러오도록 요청하세요. OAuth가 실패하거나 도구가 표시되지 않으면 호스트 앱의 MCP 서버에서 로그아웃하고 XMemo 서버 URL을 다시 연결한 후 직접 토큰을 생성하기 전에 다시 시도하세요. ## 부조종사/Codex 개발자 IDE와 CLI 에이전트 간에 리포지토리 결정, 코딩 규칙, 버그 수정 메모, 작업 기록을 전달합니다. 가능한 경우 VS Code / GitHub Copilot 및 Gemini CLI에 OAuth를 사용하세요. Copilot CLI, Codex, Cursor 또는 기타 직접 MCP 클라이언트의 경우 로컬 환경 또는 보안 저장소에 XMEMO_KEY를 유지하고 안정적인 XMEMO_AGENT_INSTANCE_ID를 설정하세요. 코드베이스 결정이나 버그 수정을 기록한 후 편집하기 전에 다음 IDE 또는 CLI 에이전트에게 관련 XMemo 컨텍스트를 기억하도록 요청하세요. 회수가 비어 있는 경우 선택한 MCP 구성 경로, 직접 클라이언트용 XMEMO_KEY 환경 변수 및 호스트 앱의 오래된 OAuth 자격 증명을 확인하세요. ## 팀/엔터프라이즈 파일럿 소유자 계정 제어, 소스 속성, 내보내기/삭제 워크플로, 검토자에게 안전한 설정 증거를 통해 공유 메모리를 평가합니다. 보호된 XMemo 작업 공간을 생성하거나 입력하고 승인된 사용자를 초대한 다음 준비 배지에 따라 OAuth 또는 범위가 지정된 직접 자격 증명을 통해 각 클라이언트를 연결합니다. 파일럿 멤버에게 가상 팀 메모리를 저장하고 XMemo에서 소스 속성을 확인한 다음 삭제/내보내기 및 지원 경로를 검토하도록 합니다. 구성원이 연결할 수 없는 경우 새 토큰을 발급하기 전에 역할 권한, OAuth 승인, 클라이언트 준비 상태 및 지원 지침을 확인하세요. ## 자율 에이전트 운영자 헤드리스 또는 예약 에이전트가 진행 상황을 기록하고, 이전 결정을 검색하고, 안정적이고 비밀이 아닌 인스턴스 ID를 유지하도록 합니다. /api/v1/mcp/config/autonomous-agent를 가져옵니다. 실행기가 OAuth + 사용자 정의 헤더를 지원하는 경우 auth_modes.oauth를 선호합니다. 완전 헤드리스 러너에 대해서만 비밀 저장소의 XMEMO_KEY와 함께 auth_modes.xmemo_key를 사용하십시오. XMemo에 진행 상황을 기록하는 하나의 합성 작업을 실행하고 실행기를 다시 시작한 다음 동일한 XMEMO_AGENT_INSTANCE_ID를 사용하여 해당 진행 상황을 호출하는지 확인합니다. 속성이 변경되거나 인스턴스 간에 분할된 경우 git 외부에서 XMEMO_AGENT_INSTANCE_ID를 유지하고 실행기가 시작할 때마다 이를 다시 생성하지 않는지 확인하세요.