feat(memory): Stage E Phase 4.1 - typedNetwork config field + manager wiring

Adds optional typedNetwork config to CognitiveMemoryConfig with two variants:
- 'minimal': bank routing at encode (no graph traversal at retrieve)
- 'full': minimal + spreading activation per Hindsight Eq. 12 + 4-way RRF

Manager now exposes getTypedNetworkStore(), getTypedNetworkObserver(),
getTypedSpreadingActivation(). Returns null when typedNetwork is absent
(zero-cost no-op for non-Stage-E callers).

Phase 4.2 (encode integration) and 4.3 (retrieve integration) follow.

Author: jddunn

src/memory/CognitiveMemoryManager.ts

@@ -56,6 +56,11 @@ import {
   ConsolidationPipeline,
   type ConsolidationResult,
 } from './pipeline/consolidation/ConsolidationPipeline.js';
+import {
+  TypedNetworkStore,
+  TypedNetworkObserver,
+  TypedSpreadingActivation,
+} from './retrieval/typed-network/index.js';
 
 // Batch 3: Infinite Context
 import { ContextWindowManager } from './pipeline/context/ContextWindowManager.js';
@@ -289,6 +294,13 @@ export class CognitiveMemoryManager implements ICognitiveMemoryManager {
    */
   private hydeRetriever: HydeRetriever | null = null;
 
+  // Stage E: Hindsight 4-network typed observer wiring (optional)
+  private typedNetworkStore: TypedNetworkStore | null = null;
+  private typedNetworkObserver: TypedNetworkObserver | null = null;
+  private typedSpreadingActivation: TypedSpreadingActivation | null = null;
+  private typedNetworkVariant: 'minimal' | 'full' | null = null;
+  private typedNetworkWeight = 0.5;
+
   async initialize(config: CognitiveMemoryConfig): Promise<void> {
     this.config = config;
 
@@ -454,9 +466,45 @@ export class CognitiveMemoryManager implements ICognitiveMemoryManager {
       this.archive = config.archive;
     }
 
+    // --- Stage E: Hindsight 4-network typed observer (optional) ---
+    if (config.typedNetwork) {
+      this.typedNetworkVariant = config.typedNetwork.variant;
+      this.typedNetworkWeight = config.typedNetwork.weight ?? 0.5;
+      this.typedNetworkStore = new TypedNetworkStore();
+      this.typedNetworkObserver = new TypedNetworkObserver({
+        llm: config.typedNetwork.observerLLM,
+      });
+      // Spreading activation only for the 'full' variant. 'minimal' performs
+      // bank routing at encode but skips graph traversal at retrieve.
+      if (config.typedNetwork.variant === 'full') {
+        this.typedSpreadingActivation = new TypedSpreadingActivation({
+          decay: config.typedNetwork.decay ?? 0.5,
+        });
+      }
+    }
+
     this.initialized = true;
   }
 
+  // ---------------------------------------------------------------------------
+  // Stage E typed-network accessors
+  // ---------------------------------------------------------------------------
+
+  /** Stage E: typed-network store, or `null` when typed-network not configured. */
+  getTypedNetworkStore(): TypedNetworkStore | null {
+    return this.typedNetworkStore;
+  }
+
+  /** Stage E: typed-network observer (LLM extractor), or `null`. */
+  getTypedNetworkObserver(): TypedNetworkObserver | null {
+    return this.typedNetworkObserver;
+  }
+
+  /** Stage E: typed spreading activation, or `null` (only set for 'full' variant). */
+  getTypedSpreadingActivation(): TypedSpreadingActivation | null {
+    return this.typedSpreadingActivation;
+  }
+
   // =========================================================================
   // Encode
   // =========================================================================

src/memory/__tests__/CognitiveMemoryManager.typedNetwork.test.ts

@@ -0,0 +1,131 @@
+/**
+ * @fileoverview Stage E Phase 4.1: CognitiveMemoryManager `typedNetwork` config
+ * field + initialization wiring tests.
+ *
+ * Verifies the manager exposes a TypedNetworkStore + Observer + spreading
+ * activation when `config.typedNetwork` is provided, and exposes nulls when
+ * the field is absent (zero-cost no-op for non-Stage-E callers).
+ *
+ * @module memory/__tests__/CognitiveMemoryManager.typedNetwork.test
+ */
+
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { CognitiveMemoryManager } from '../CognitiveMemoryManager.js';
+import {
+  TypedNetworkStore,
+  TypedNetworkObserver,
+  TypedSpreadingActivation,
+  type ITypedExtractionLLM,
+} from '../retrieval/typed-network/index.js';
+
+function makeMinimalDeps() {
+  const mockKnowledgeGraph = {
+    initialize: vi.fn(),
+    upsertEntity: vi.fn(),
+    upsertRelation: vi.fn(),
+    queryEntities: vi.fn().mockResolvedValue([]),
+    getNeighborhood: vi.fn().mockResolvedValue({ entities: [], relations: [] }),
+    getRelations: vi.fn().mockResolvedValue([]),
+    deleteEntity: vi.fn(),
+    deleteRelation: vi.fn(),
+    traverse: vi.fn().mockResolvedValue({
+      root: { id: 'r', type: 'memory', label: 'r', properties: {}, confidence: 1, source: { type: 'system', timestamp: '', method: '' } } as any,
+      levels: [],
+      totalEntities: 0,
+      totalRelations: 0,
+    }),
+    recordMemory: vi.fn(),
+  };
+
+  const mockVectorStore = {
+    initialize: vi.fn(),
+    upsert: vi.fn(),
+    query: vi.fn().mockResolvedValue({ documents: [] }),
+    collectionExists: vi.fn().mockResolvedValue(true),
+    createCollection: vi.fn(),
+  };
+
+  const mockEmbeddingManager = {
+    generateEmbeddings: vi.fn().mockResolvedValue({
+      embeddings: [[0.1, 0.2, 0.3]],
+      modelId: 'test',
+      providerId: 'test',
+      usage: { totalTokens: 0 },
+    }),
+    getEmbeddingDimension: vi.fn().mockResolvedValue(3),
+    getEmbeddingModelInfo: vi.fn().mockResolvedValue({
+      dimension: 3,
+      modelId: 'test',
+      providerId: 'test',
+      maxInputTokens: 8192,
+    }),
+    initialize: vi.fn(),
+    checkHealth: vi.fn().mockResolvedValue({ isHealthy: true }),
+    shutdown: vi.fn(),
+  };
+
+  const mockWorkingMemory = {
+    capacity: 7,
+    store: vi.fn(),
+    retrieve: vi.fn().mockResolvedValue([]),
+    clear: vi.fn(),
+    getSlots: vi.fn().mockReturnValue([]),
+  };
+
+  return {
+    workingMemory: mockWorkingMemory as any,
+    knowledgeGraph: mockKnowledgeGraph as any,
+    vectorStore: mockVectorStore as any,
+    embeddingManager: mockEmbeddingManager as any,
+    agentId: 'stage-e-test',
+    traits: { emotionality: 0.5, conscientiousness: 0.5 },
+    moodProvider: () => ({ valence: 0, arousal: 0.3, dominance: 0 }),
+    featureDetectionStrategy: 'keyword' as const,
+  };
+}
+
+const stubLLM: ITypedExtractionLLM = {
+  invoke: async () => JSON.stringify({ facts: [] }),
+};
+
+describe('CognitiveMemoryManager: typedNetwork wiring', () => {
+  let manager: CognitiveMemoryManager;
+
+  beforeEach(() => {
+    manager = new CognitiveMemoryManager();
+  });
+
+  it('exposes null typed-network components when config.typedNetwork is absent', async () => {
+    await manager.initialize(makeMinimalDeps());
+    expect(manager.getTypedNetworkStore()).toBeNull();
+    expect(manager.getTypedNetworkObserver()).toBeNull();
+    expect(manager.getTypedSpreadingActivation()).toBeNull();
+  });
+
+  it('instantiates typed-network store/observer/activation when configured (full variant)', async () => {
+    await manager.initialize({
+      ...makeMinimalDeps(),
+      typedNetwork: {
+        variant: 'full',
+        observerLLM: stubLLM,
+      },
+    });
+    expect(manager.getTypedNetworkStore()).toBeInstanceOf(TypedNetworkStore);
+    expect(manager.getTypedNetworkObserver()).toBeInstanceOf(TypedNetworkObserver);
+    expect(manager.getTypedSpreadingActivation()).toBeInstanceOf(TypedSpreadingActivation);
+  });
+
+  it('instantiates only store + observer for minimal variant (no spreading activation)', async () => {
+    await manager.initialize({
+      ...makeMinimalDeps(),
+      typedNetwork: {
+        variant: 'minimal',
+        observerLLM: stubLLM,
+      },
+    });
+    expect(manager.getTypedNetworkStore()).toBeInstanceOf(TypedNetworkStore);
+    expect(manager.getTypedNetworkObserver()).toBeInstanceOf(TypedNetworkObserver);
+    // Minimal variant skips spreading activation: bank routing only.
+    expect(manager.getTypedSpreadingActivation()).toBeNull();
+  });
+});

src/memory/core/config.ts

@@ -320,10 +320,52 @@ export interface CognitiveMemoryConfig {
    * storage before overwriting with the gist. Enables on-demand rehydration
    * via `CognitiveMemoryManager.rehydrate()`.
    *
-   * @default undefined (no archive — gist is destructive)
+   * @default undefined (no archive, gist is destructive)
    * @see {@link IMemoryArchive} — the archive contract
    */
   archive?: import('../archive/IMemoryArchive.js').IMemoryArchive;
+
+  /**
+   * Stage E: optional Hindsight 4-network typed observer wiring.
+   *
+   * When provided, `encode()` additionally extracts typed facts (World /
+   * Experience / Opinion / Observation banks) via the configured LLM and
+   * persists them in an in-memory `TypedNetworkStore`. `retrieve()` runs
+   * typed-graph spreading activation (`'full'` variant only) and produces
+   * a 4-way RRF fused ranking that's merged into the existing scoring.
+   *
+   * Variants:
+   * - `'minimal'`: bank routing + observer only (no graph traversal at retrieve).
+   * - `'full'`: minimal + spreading activation per Hindsight Eq. 12 + 4-way RRF.
+   *
+   * @default undefined (Stage E disabled, zero-cost no-op)
+   * @see `packages/agentos-bench/docs/specs/2026-04-26-hindsight-4network-observer-design.md`
+   */
+  typedNetwork?: TypedNetworkRuntimeConfig;
+}
+
+/**
+ * Stage E runtime config for the typed-network observer + retrieval fusion.
+ */
+export interface TypedNetworkRuntimeConfig {
+  /**
+   * Variant selector.
+   * - `'minimal'`: 4-bank routing only at encode; no spreading activation.
+   * - `'full'`: minimal + spreading activation + 4-way RRF at retrieve.
+   */
+  variant: 'minimal' | 'full';
+  /** LLM adapter for the 6-step extraction call. */
+  observerLLM: import('../retrieval/typed-network/index.js').ITypedExtractionLLM;
+  /**
+   * Weight applied to the typed-network ranking when merging into the
+   * standard cognitive score. 0.0 ignores typed-network; 1.0 uses only
+   * typed-network. Default 0.5.
+   */
+  weight?: number;
+  /** Spreading-activation max depth. Default 3. */
+  maxDepth?: number;
+  /** Spreading-activation per-hop decay δ. Default 0.5. */
+  decay?: number;
 }
 
 // ---------------------------------------------------------------------------