Skip to content

Memory and Learning Integrated Control Design

  • Author: Masahiro Aoki
  • Copyright: 2026 Moonlight Technologies Inc. All Rights Reserved.
  • Last updated: 2026-08-15

Overview

The main gap identified in the Sparse Evo-MemoryLM review is not missing subsystems, but the lack of a single production control flow connecting memory, inference, learning, and auditability. This document defines the integrated control layer that closes that gap.

This design is intentionally written as an extension-ready contract rather than a one-off minimal implementation. The current MemoryOrchestrator is the foundational layer; future integration with Meta-STDP, AEG, ForgettingController, LongTermMemoryModule, and multimodal LM variants should be added by following this specification.

The design connects the following existing assets under one request-scoped execution model.

  • evospikenet/episodic_memory.py memory storage, retrieval, and forgetting
  • evospikenet/memory_orchestrator.py minimal orchestration implementation
  • evospikenet/common.py AuditLogger and DataConverter
  • Learning and stabilization modules such as Meta-STDP, AEG, ForgettingController, and LongTermMemoryModule

Design goals

  1. Execute input handling, inference, learning updates, memory write-back, and audit emission in one control flow.
  2. Make every mandatory stage traceable through a shared request_id, session_id, and timestamp.
  3. Prohibit mock and fallback responses on the production path; fail fast on mandatory-stage errors.
  4. Normalize inference events and learning events into one memory-event contract.
  5. Define acceptance criteria that include Docker-based SDK/API validation and regression coverage.

Scope

In scope

  • Request normalization
  • Episodic and semantic memory retrieval
  • Pre-execution context fusion
  • Lightweight online learning control coupled to inference
  • Output, reward, and quality write-back into memory
  • Audit logs, operational metrics, and failure contracts

Out of scope

  • Replacing the underlying learning algorithms
  • Designing new modalities
  • Replacing the distributed substrate itself

Architecture

Core components

  1. InputNormalizer
  2. Converts raw input into a standard request envelope.

  3. Attaches source, session_id, actor, tenant, and trace_tags.

  4. MemoryRetrievalCoordinator

  5. Extracts semantic tags, selects retrieval strategy, and controls top-k.

  6. Collects episodic and semantic results in parallel and deduplicates them.

  7. ContextFusionEngine

  8. Merges retrieved memories, session state, and learning state into MemoryContextPayload.

  9. Trims noise and enforces model-context size limits.

  10. LearningControlCoordinator

  11. Governs Meta-STDP, AEG, ForgettingController, and long-term memory updates.

  12. Decides whether updates are allowed from reward, loss proxy, and quality signals.

  13. ExecutionPolicy

  14. Chooses between inference-only, inference-plus-learning, and learning-disabled modes.

  15. Evaluates safety, capacity, and convergence protection rules.

  16. AuditTrailEmitter

  17. Emits structured logs through AuditLogger.log_event() and DataConverter.convert_to_structured_event().
  18. Records successful inference, learning updates, and write-back failures in one event stream.

Standard data contracts

Required headers

Every event and internal payload must carry the following fields.

  • request_id
  • session_id
  • source
  • timestamp
  • pipeline_stage

Execution context

Use the existing MemoryContextPayload as the base type and elevate the following fields to operationally required status.

  • user_input
  • semantic_context
  • episodic_context
  • retrieved_memories
  • generated_output
  • metadata.learning_mode
  • metadata.reward_signal
  • metadata.quality_score

Memory events

Use MemoryEventRecord as the operation log with the following canonical event types.

  • retrieval_started
  • retrieval_completed
  • model_execution_started
  • model_execution_completed
  • learning_update_started
  • learning_update_completed
  • memory_writeback_started
  • memory_writeback_completed
  • pipeline_failed

Learning control signal

The implementation should introduce the following dataclass.

@dataclass
class LearningControlSignal:
    request_id: str
    session_id: str
    reward: float
    quality_score: float
    loss_proxy: float | None
    gradient_norm: float | None
    safe_to_update: bool
    update_reason: str

Execution sequence

flowchart TD
    A[Client Request] --> B[InputNormalizer]
    B --> C[MemoryRetrievalCoordinator]
    C --> D[Episodic Retrieval]
    C --> E[Semantic Retrieval]
    D --> F[ContextFusionEngine]
    E --> F
    F --> G[ExecutionPolicy]
    G --> H[Model Execution]
    H --> I[Quality / Reward Evaluation]
    I --> J[LearningControlCoordinator]
    J --> K[Memory Writeback]
    K --> L[AuditTrailEmitter]

Control modes

Mode A: inference only

  • Memory retrieval is mandatory.
  • No learning update is performed.
  • Only output and evaluation data are recorded.

Mode B: inference plus lightweight online update

  • Retrieval and inference are both mandatory.
  • Update Meta-STDP and AEG only when quality thresholds pass.
  • Use reward signals only after smoothing.

Mode C: batch consolidation and stabilization

  • Runs asynchronously from online requests.
  • Executes forgetting, compression, and long-term consolidation.
  • Links request-scoped events to scheduled job traces.

Fail-fast contract

This design forbids mock and fallback behavior on the production path. The fallback response still present in the minimal orchestrator implementation is a migration target, not a completion target.

Stop conditions

  1. Input normalization failure
  2. Mandatory memory retrieval failure
  3. Model execution failure
  4. Learning-control safety violation that cannot be absorbed by update suppression
  5. Memory write-back failure

Allowed continuation

  • Secondary audit-emission failures may be attached as auxiliary diagnostics to the primary exception.
  • Non-critical metric-export failures must not mutate the main transaction.

Implementation plan

Phase 1: contract unification

  • Refine MemoryContextPayload and MemoryEventRecord for fail-fast operation.
  • Repurpose FailureHandlingResult from fallback metadata into structured stop-reason metadata.
  • Route orchestration logs consistently through common.py.

Phase 2: orchestrator migration

  • Remove fallback branches from MemoryOrchestrator.process_request().
  • Emit start and completion events for retrieval, execution, learning, and write-back.
  • Add a request-scoped transaction context.

Phase 3: learning-control integration

  • Centralize Meta-STDP and AEG update gating in LearningControlCoordinator.
  • Record gradient norm, reward clip, and EMA alpha per request.
  • Make forgetting and long-term consolidation conditions explicit.

Phase 4: validation and production hardening

  • Validate the full retrieval-to-writeback path with live SDK/API Docker tests.
  • Convert no-degradation behavior into regression tests.
  • Verify that audit events can be reconstructed uniquely by request_id.

Acceptance criteria

  1. user_input -> retrieval -> context fusion -> model execution -> learning update -> memory writeback runs as one control flow.
  2. Mandatory-stage errors terminate explicitly instead of degrading into mock or fallback responses.
  3. A full request timeline can be reconstructed from AuditLogger output.
  4. Meta-STDP, AEG, and forgetting decisions are persisted as events.
  5. The same contract is verified by both automated tests and Docker-backed SDK validation.

API contract (updated 2026-08-14)

/api/memory/orchestrate is the unified API entrypoint for memory retrieval, generation, learning update, and write-back within one request-scoped pipeline.

Key request fields

  • user_input (required)
  • session_id (required)
  • source (optional, default api)
  • request_id (optional)
  • fail_fast (optional, default true)
  • runtime_model (optional): stub / api_loaded / evolm_backend
  • lm_architecture (optional): LM architecture for runtime_model=evolm_backend
  • model_device (optional): device override for runtime_model=evolm_backend
  • allow_stub_fallback (optional, default true)
  • max_new_tokens (optional, default 64)
  • temperature (optional, default 1.0)

Key response fields

  • status: completed or degraded
  • request_id
  • runtime_model: requested backend type
  • effective_runtime_model: actually used backend type
  • generated_output
  • metadata
  • memory_events[]: stage-level event stream
  • failure: structured failure payload when fail-fast is disabled

Error contract

  • When fail-fast is enabled, orchestration failures raise OrchestrationRuntimeError and are converted by API exception mapping into the standard error envelope.
  • Stage error codes:
  • MLI-REQ-001
  • MLI-RET-001
  • MLI-EXE-001
  • MLI-LRN-001
  • MLI-WRB-001

Audit-stream consistency requirements

  1. memory_events[].request_id must match response request_id.
  2. memory_events[].session_id must match input session_id.
  3. Event order must preserve start-to-end progression from retrieval_started through memory_writeback_completed.

Implementation reflection (2026-08-15)

This design is now reflected in the repository as follows:

  • evospikenet/memory_orchestrator.py generates a request-scoped transaction_id and emits transaction_started / transaction_committed / transaction_rolled_back audit events.
  • evospikenet/memory_orchestrator.py normalizes retrieval results for learning and propagates records, max_capacity, ltm_context, and spike_sequence into LearningControlCoordinator.
  • evospikenet/learning_control_coordinator.py wires Meta-STDP, AEG, ForgettingController, and LongTermMemoryModule through a shared request context.
  • evospikenet/memory_writeback_service.py preserves transaction_id in the write-back context.
  • evospikenet/execution_policy.py was corrected after integrated-path validation exposed a missing logging import that caused 500/NameError failures.
  • Tests and CI now include tests/unit/test_priority1_learning_control_unit.py, tests/integration/test_priority1_memory_orchestrator_integration.py, tests/e2e/test_priority1_memory_orchestrate_api_e2e.py, tests/performance/test_priority1_memory_orchestrator_performance.py, .github/workflows/priority1-memory-orchestrator.yml, and the Makefile target priority1-memory-orchestrator-test.
  • Validation: make priority1-memory-orchestrator-test passed under Product/venv with 5 tests.