メモリと学習の統合制御設計

Author: Masahiro Aoki
Copyright: 2026 Moonlight Technologies Inc. All Rights Reserved.
最終更新日: 2026年8月15日

概要

Sparse Evo-MemoryLM のレビューで特定された主要ギャップは、記憶、推論、学習、監査が別々に存在し、単一の実運用フローとして接続されていない点にある。本設計書は、そのギャップを埋めるための統合制御レイヤーを定義する。

この設計は「最小実装」で終わらせず、今後の拡張に耐える統合契約として定義する。したがって、現在の MemoryOrchestrator 実装は基礎であり、新しい Meta-STDP / AEG / ForgettingController / LongTermMemoryModule との接続や、マルチモーダル LM との統合は、この文書の仕様に沿って追加する。

本設計の対象は、以下の既存資産を単一の request 単位で接続することである。

evospikenet/episodic_memory.py の記憶保存・検索・忘却
evospikenet/memory_orchestrator.py の最小オーケストレーション実装
evospikenet/common.py の AuditLogger と DataConverter
Meta-STDP、AEG、ForgettingController、LongTermMemoryModule などの学習・安定化モジュール

設計目標

入力から推論、学習更新、記憶書き戻し、監査までを単一制御フローで実行する。
すべての必須段階を共通の request_id、session_id、timestamp で追跡可能にする。
本番経路では mock や fallback 応答を使わず、必須段階の失敗時は fail-fast で停止する。
推論系イベントと学習系イベントを共通のメモリイベント契約に正規化する。
Docker 上の SDK/API 検証と回帰テストまで含めて受入条件を定義する。

スコープ

対象

ユーザー入力または API リクエストの正規化
エピソード記憶・セマンティック記憶の検索
モデル実行前コンテキストの融合
オンライン推論に連動した軽量学習制御
出力結果・報酬・品質評価の記憶書き戻し
監査ログ、運用メトリクス、失敗契約

非対象

学習アルゴリズム自体の再発明
新規モダリティの追加設計
分散基盤そのものの置き換え

アーキテクチャ

中核コンポーネント

InputNormalizer
生入力を request_id 付きの標準入力へ変換する。
source、session_id、actor、tenant、trace_tags を付与する。
MemoryRetrievalCoordinator
セマンティックタグ抽出、検索戦略選択、top-k 制御を行う。
エピソード記憶とセマンティック記憶を並列収集し、重複統合する。
ContextFusionEngine
取得記憶、セッション状態、学習状態を MemoryContextPayload に統合する。
推論に不要なノイズを落とし、モデル投入サイズを制限する。
LearningControlCoordinator
Meta-STDP、AEG、ForgettingController、長期記憶更新を制御する。
推論後の reward、loss proxy、quality score を使って更新可否を判断する。
ExecutionPolicy
推論専用、推論+学習、学習停止の各モードを判定する。
安全制約、容量制約、収束保護ルールを評価する。
AuditTrailEmitter
AuditLogger.log_event() と DataConverter.convert_to_structured_event() を通して構造化ログを出力する。
推論成功、学習更新、書き戻し失敗などを同一イベント系列で記録する。

モジュール構成（実装単位）

以下は evospikenet/memory_orchestrator.py を中核として分割する実装単位である。

モジュール	主責務	入力	出力	依存
`request_normalizer.py`	リクエスト正規化、ID採番、トレースタグ整形	Raw request	`NormalizedRequest`	`uuid`, `datetime`, `DataConverter`
`memory_retrieval_coordinator.py`	エピソード/セマンティック検索、重複排除、ranking	`NormalizedRequest`	`RetrievalBundle`	`EpisodicMemory`, semantic index
`context_fusion_engine.py`	コンテキスト圧縮、優先度選別、token budget 制御	`RetrievalBundle` + session state	`MemoryContextPayload`	tokenizer, prompt budget policy
`execution_policy.py`	モード判定、安全制約判定、更新可否判定	payload + runtime stats	`ExecutionDecision`	safety rules, capacity policy
`learning_control_coordinator.py`	Meta-STDP/AEG/忘却/長期固定化の更新制御	`LearningControlSignal`	`LearningUpdateResult`	`MetaSTDP`, `AEG`, `ForgettingController`, `LongTermMemoryModule`
`memory_writeback_service.py`	出力・評価・更新結果の記憶書き戻し	output + learning result	`WritebackResult`	episodic/semantic stores
`audit_trail_emitter.py`	全ステージの監査イベント出力	stage event	structured audit log	`AuditLogger`

コンテキストサイズ制御ポリシー

ContextFusionEngine はモデル投入前に次の制約を満たす。

max_retrieved_items: 既定 32。
max_context_tokens: 既定 2048。
max_event_age_hours: 既定 72。
dedup_key: memory_id 優先、欠落時は (source, hash(content))。
priority_score: recency * 0.35 + relevance * 0.45 + quality * 0.20。

閾値超過時は priority_score 降順で剪定し、剪定件数を metadata.pruned_count に記録する。

標準データ契約

必須ヘッダー

全イベントと全内部ペイロードは以下を必須とする。

request_id
session_id
source
timestamp
pipeline_stage

実行コンテキスト

既存の MemoryContextPayload を基底とし、以下の項目を運用上の必須フィールドへ昇格する。

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

メモリイベント

MemoryEventRecord を operation log として使い、イベント種別を以下で固定する。

retrieval_started
retrieval_completed
model_execution_started
model_execution_completed
learning_update_started
learning_update_completed
memory_writeback_started
memory_writeback_completed
pipeline_failed

学習制御信号

実装では新規 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

内部データ型（最小契約）

@dataclass
class NormalizedRequest:
   request_id: str
   session_id: str
   source: str
   actor: str | None
   tenant: str | None
   user_input: str
   trace_tags: list[str]
   timestamp: str


@dataclass
class ExecutionDecision:
   mode: str  # inference_only | inference_plus_update | consolidation
   safe_to_execute: bool
   safe_to_update: bool
   reason: str
   max_new_tokens: int


@dataclass
class LearningUpdateResult:
   updated: bool
   skipped_reason: str | None
   gradient_norm: float | None
   reward_ema: float | None
   forgetting_actions: int

実行シーケンス

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]

シーケンス詳細（同期リクエスト）

sequenceDiagram
   participant C as Client
   participant O as MemoryOrchestrator
   participant R as RetrievalCoordinator
   participant F as ContextFusionEngine
   participant P as ExecutionPolicy
   participant M as LM Runtime
   participant L as LearningCoordinator
   participant W as WritebackService
   participant A as AuditTrailEmitter

   C->>O: process_request(raw_input)
   O->>A: retrieval_started
   O->>R: retrieve(normalized_request)
   R-->>O: retrieval_bundle
   O->>A: retrieval_completed
   O->>F: fuse(retrieval_bundle, session_state)
   F-->>O: memory_context_payload
   O->>P: decide(payload, runtime_stats)
   P-->>O: execution_decision
   O->>A: model_execution_started
   O->>M: generate(payload, max_new_tokens)
   M-->>O: generated_output
   O->>A: model_execution_completed
   O->>L: evaluate_and_update(signal)
   L-->>O: learning_update_result
   O->>W: writeback(payload, output, learning_result)
   W-->>O: writeback_result
   O->>A: memory_writeback_completed
   O-->>C: structured response

ワークフロー（運用ジョブ）

Workflow 1: Online Inference Loop

API/SDK が process_request を呼び出す。
retrieval と context fusion を実行する。
実行ポリシーで mode を決定する。
推論を実行する。
更新可の場合のみ学習制御を実行する。
出力と評価を記憶へ書き戻す。
全段階の監査イベントを確定する。

Workflow 2: Consolidation Batch

オンラインイベントログから対象 request 群を収集する。
ForgettingController の閾値で短期記憶を整理する。
長期固定化候補を抽出し LongTermMemoryModule に反映する。
圧縮統計と削除統計を監査へ書き込む。

Workflow 3: Failure Escalation

必須ステージで例外発生時に pipeline_failed を発行する。
例外は error_code, failed_stage, request_id を保持する。
fallback 応答は返さず、呼び出し元に fail-fast 例外を返す。

制御モード

モード A: 推論のみ

記憶検索は必須
学習更新は行わない
出力と評価だけを記録する

モード B: 推論 + 軽量オンライン更新

記憶検索と推論を必須とする
品質閾値を満たした場合のみ Meta-STDP / AEG を更新する
reward smoothing 後の信号のみ書き戻しに使う

モード C: バッチ統合・固定化

オンライン要求とは非同期に走る
ForgettingController、圧縮、長期固定化を実行する
request 単位のイベント系列と日次ジョブ系列を関連付ける

フェイルファスト契約

本設計では、本番経路における mock / fallback を禁止する。最小実装に存在する fallback 応答は、設計上は移行対象であり、本番完了条件には含めない。

停止条件

入力正規化失敗
必須メモリ検索失敗
モデル実行失敗
学習制御で安全制約違反が発生し、更新抑止では吸収できない場合
記憶書き戻し失敗

許容される継続

監査ログ出力の副次的失敗は、主処理の例外に付随情報として束ねて返す
非必須メトリクス送信の失敗は、主トランザクションを汚染しない

ステートマシン

stateDiagram-v2
   [*] --> RECEIVED
   RECEIVED --> RETRIEVING
   RETRIEVING --> FUSING
   FUSING --> POLICY_EVAL
   POLICY_EVAL --> EXECUTING
   EXECUTING --> LEARNING
   LEARNING --> WRITEBACK
   WRITEBACK --> AUDITED
   AUDITED --> COMPLETED

   RETRIEVING --> FAILED
   FUSING --> FAILED
   POLICY_EVAL --> FAILED
   EXECUTING --> FAILED
   LEARNING --> FAILED
   WRITEBACK --> FAILED
   FAILED --> AUDITED

FAILED 遷移時は pipeline_failed を必須発行し、COMPLETED へは遷移しない。

監査・可観測性仕様

監査イベント最小フィールド

request_id
session_id
pipeline_stage
event_type
status (started, completed, failed)
latency_ms
error_code (失敗時のみ)

主要メトリクス

memory_retrieval_latency_ms
context_tokens_after_prune
inference_latency_ms
learning_update_applied_total
memory_writeback_failure_total

エラーコード規約

MLI-REQ-001: 入力正規化失敗
MLI-RET-001: 必須検索失敗
MLI-EXE-001: モデル実行失敗
MLI-LRN-001: 学習更新安全制約違反
MLI-WRB-001: 記憶書き戻し失敗

実装方針

Phase 1: 契約統一

MemoryContextPayload と MemoryEventRecord を fail-fast 前提で再定義する
FailureHandlingResult は fallback 用ではなく、停止理由の構造化表現へ役割変更する
common.py の監査ログ関数をオーケストレーション経路へ統一適用する

Phase 2: オーケストレータ本体の移行

MemoryOrchestrator.process_request() から fallback 分岐を除去する
retrieval / execution / learning / writeback ごとに開始・完了イベントを記録する
request 単位の transaction context を追加する

Phase 3: 学習制御統合

Meta-STDP と AEG の更新ゲートを LearningControlCoordinator に集約する
gradient norm、reward clip、EMA alpha を request 単位で記録する
ForgettingController と長期固定化条件を明示する

Phase 4: 検証と運用化

Docker 上の live SDK/API テストで、記憶検索から書き戻しまでを実測検証する
失敗時に縮退応答ではなく明示例外になることを回帰テスト化する
監査イベントが request_id 単位で一意に追跡できることを検証する

受入基準

user_input -> retrieval -> context fusion -> model execution -> learning update -> memory writeback が単一制御フローで実行される。
必須段階の失敗時に mock / fallback 応答へ逃げず、明示エラーで停止する。
AuditLogger 出力から 1 リクエスト分の全ステージを再構築できる。
Meta-STDP / AEG / 忘却制御の更新判断がイベントとして残る。
Docker 上の SDK 検証と自動テストの両方で同一契約を満たす。

API 契約（2026-08-14 更新）

/api/memory/orchestrate は、メモリ検索・推論・学習更新・書き戻しを単一 API 呼び出しで実行する統合経路である。

リクエスト主要項目

user_input (必須)
session_id (必須)
source (任意、既定 api)
request_id (任意)
fail_fast (任意、既定 true)
runtime_model (任意): stub / api_loaded / evolm_backend
lm_architecture (任意): runtime_model=evolm_backend 時の LM アーキテクチャ名
model_device (任意): runtime_model=evolm_backend 時のデバイス指定
allow_stub_fallback (任意、既定 true)
max_new_tokens (任意、既定 64)
temperature (任意、既定 1.0)

レスポンス主要項目

status: completed または degraded
request_id
runtime_model: 要求されたモデル種別
effective_runtime_model: 実際に使われたモデル種別
generated_output
metadata
memory_events[]: stage イベント系列
failure: fail-fast 無効時の構造化失敗情報

エラー契約

fail-fast 有効時は OrchestrationRuntimeError を送出し、API 例外変換で標準エラー envelope に変換する。
ステージ別エラーコード:
MLI-REQ-001
MLI-RET-001
MLI-EXE-001
MLI-LRN-001
MLI-WRB-001

監査系列の整合要件

memory_events[].request_id はレスポンス request_id と一致する。
memory_events[].session_id は入力 session_id と一致する。
retrieval_started から memory_writeback_completed までの開始/完了イベントが順序を保つ。

実装反映（2026-08-15）

本設計は、2026-08-15 時点で以下の実装へ反映済みである。

evospikenet/memory_orchestrator.py
request 単位の transaction_id を生成し、transaction_started / transaction_committed / transaction_rolled_back を監査イベント系列へ追加。
retrieval 結果を学習制御向けレコードへ正規化し、records、max_capacity、ltm_context、spike_sequence を LearningControlCoordinator へ伝播。
evospikenet/learning_control_coordinator.py
Meta-STDP、AEG、ForgettingController、LongTermMemoryModule を共通 request 文脈で束ねる構成を反映。
evospikenet/memory_writeback_service.py
transaction_id を含む writeback context を保持可能にした。
evospikenet/execution_policy.py
統合経路の検証時に露出した logging import 欠落を修正し、500 / NameError を解消。
テスト/CI
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
Makefile の priority1-memory-orchestrator-test

検証結果:

Product/venv で make priority1-memory-orchestrator-test を実行し、5 passed を確認済み。
request 単位の統合フローと transaction 境界は、回帰テストで追跡できる状態になっている。