Skip to content

Memory Orchestration End-to-End Specification

Last updated: 2026-08-23

1. Objective

This specification defines the end-to-end execution contract of MemoryOrchestrator in Sparse Evo-MemoryLM. It covers request normalization, retrieval, context fusion, model execution, learning update, writeback, and resilience behavior.

2. Execution flow

  1. Accept input and normalize it with InputNormalizer.
  2. Emit transaction_started and retrieval_started.
  3. Extract semantic context and run memory retrieval.
  4. Prune/fuse retrieval outputs and build MemoryContextPayload.
  5. Extract explicit causal evidence into causal_context.
  6. Evaluate policy with ExecutionPolicy.
  7. Execute model inference, applying fallback if needed.
  8. Run learning update and writeback unless in consolidation mode.
  9. Commit on success, or rollback/degrade on failure.

3. Identity isolation contract (tenant/user/client)

  • Propagate tenant_id, user_id, and client_id into MemoryOrchestrator.process_request(...).
  • Compatibility mode (default): if tenant_id is omitted, it is normalized to public; user_id and client_id remain optional.
  • Strict mode: when EVOSPIKENET_IDENTITY_STRICT=true, the API rejects missing tenant_id/user_id/client_id with 400.
  • Retrieval and writeback enforce tenant boundaries as required keys to prevent cross-tenant blending.
  • Persistent fallback snapshots are written under tenant subdirectories (<persistent_fallback_dir>/<tenant_id>/).

4. Failure contract

  • In fail-fast mode (fail_fast=true), raise OrchestrationRuntimeError.
  • In degraded mode (fail_fast=false), return structured FailureHandlingResult.
  • Error codes:
  • MLI-REQ-001 request normalization
  • MLI-RET-001 memory retrieval
  • MLI-EXE-001 model execution
  • MLI-LRN-001 learning update
  • MLI-WRB-001 memory writeback

5. Persistent fallback

When persistent_fallback_dir is configured, degraded failures are persisted as JSON snapshots.

Stored fields include:

  • request/session/source/status
  • failure_type/failed_stage/error_code/message
  • nested structured failure object
  • memory event trail

6. Schemas

  • MemoryContextPayload
  • semantic_context, retrieved_memories, causal_context, generated_output
  • FailureHandlingResult
  • failure_type, failed_stage, error_code, retryable, safe_mode
  • OrchestrationResponse
  • status, failure, metadata, causal_context
  • EvoSpikeNet-Core/specs/system_orchestration_spec.md
  • EvoSpikeNet-Core/specs/system_orchestration_spec.ja.md
  • SPARSE_EVO_MEMORYLM_SYSTEM_REVIEW.en.md