feat(rag): wire HyDE retrieval into RetrievalAugmentor, multimodal search, and memory recall

HyDE (Hypothetical Document Embedding) was fully implemented as a standalone
HydeRetriever class but never called in any actual retrieval pipeline.

Wire it into three pipelines:

1. RetrievalAugmentor.retrieveContext() — main RAG pipeline
   - Add setHydeLlmCaller() for LLM registration
   - When options.hyde.enabled, generate hypothesis and embed it instead
     of the raw query
   - Support pre-supplied hypotheses (skip LLM call)
   - Graceful fallback to direct embedding on any failure
   - HyDE diagnostics in RagRetrievalDiagnostics
   - Audit trail integration (operation type 'hyde')

2. MultimodalIndexer.search() — cross-modal search
   - Add setHydeRetriever() to attach a HyDE retriever
   - When opts.hyde.enabled, delegate to HydeRetriever.retrieve()
     with adaptive thresholding
   - Support pre-supplied hypotheses and modality filtering

3. CognitiveMemoryManager.retrieve() — memory recall
   - Add setHydeRetriever() / getHydeRetriever()
   - When options.hyde is true, generate a hypothetical memory trace
     and search using that instead of the raw query
   - Non-critical: failures fall back silently to raw query

Also:
- Add 'hyde' to RAGOperationEntry.operationType union
- Add hydeDetails to RAGOperationEntry for audit transparency
- Add setHydeDetails() to RAGOperationHandle
- Add hyde diagnostics to RagRetrievalDiagnostics
- Add hyde option to CognitiveRetrievalOptions
- Add hyde option to MultimodalSearchOptions
- 10 new tests covering all HyDE integration paths

Author: jddunn

src/memory/CognitiveMemoryManager.ts

@@ -61,6 +61,9 @@ import { ContextWindowManager } from './context/ContextWindowManager.js';
 import type { ContextMessage, CompactionEntry } from './context/types.js';
 import type { ContextWindowStats } from './context/ContextWindowManager.js';
 
+// HyDE (Hypothetical Document Embedding) for improved memory retrieval
+import type { HydeRetriever } from '../rag/HydeRetriever.js';
+
 // ---------------------------------------------------------------------------
 // Interface
 // ---------------------------------------------------------------------------
@@ -151,6 +154,15 @@ export interface ICognitiveMemoryManager {
   /** Get prospective-memory manager when enabled. */
   getProspective(): ProspectiveMemoryManager | null;
 
+  /**
+   * Attach a HyDE retriever for hypothesis-driven memory recall.
+   * Pass `null` to disable.
+   */
+  setHydeRetriever?(retriever: HydeRetriever | null): void;
+
+  /** Get the HyDE retriever if configured, or `null`. */
+  getHydeRetriever?(): HydeRetriever | null;
+
   /** Get infinite-context runtime stats when enabled. */
   getContextWindowStats(): ContextWindowStats | null;
 
@@ -191,6 +203,16 @@ export class CognitiveMemoryManager implements ICognitiveMemoryManager {
   // Batch 3: Infinite Context (optional)
   private contextWindow: ContextWindowManager | null = null;
 
+  /**
+   * Optional HyDE retriever for hypothesis-driven memory recall.
+   *
+   * When set and `options.hyde` is `true` on a `retrieve()` call, the manager
+   * generates a hypothetical memory trace via LLM and uses that text for the
+   * embedding-based memory search. This improves recall for vague or abstract
+   * queries (e.g. "that deployment discussion last week").
+   */
+  private hydeRetriever: HydeRetriever | null = null;
+
   async initialize(config: CognitiveMemoryConfig): Promise<void> {
     this.config = config;
 
@@ -405,7 +427,26 @@ export class CognitiveMemoryManager implements ICognitiveMemoryManager {
 
     const startTime = Date.now();
 
-    const { scored, partial } = await this.store.query(query, mood, options);
+    // When HyDE is enabled and a retriever is available, generate a
+    // hypothetical memory trace and use it as the search query. The
+    // hypothesis is a plausible memory that the agent *would* have stored,
+    // producing an embedding that's semantically closer to actual stored
+    // traces than the raw recall query.
+    let effectiveQuery = query;
+    if (options.hyde && this.hydeRetriever) {
+      try {
+        const hypoResult = await this.hydeRetriever.generateHypothesis(
+          `Recall a memory about: ${query}`,
+        );
+        if (hypoResult.hypothesis) {
+          effectiveQuery = hypoResult.hypothesis;
+        }
+      } catch {
+        // HyDE generation is non-critical — fall through to raw query.
+      }
+    }
+
+    const { scored, partial } = await this.store.query(effectiveQuery, mood, options);
 
     // --- Batch 2: Spreading activation ---
     if (this.graph && scored.length > 0) {
@@ -805,6 +846,35 @@ export class CognitiveMemoryManager implements ICognitiveMemoryManager {
     return this.prospective;
   }
 
+  /**
+   * Attach a HyDE retriever to enable hypothesis-driven memory recall.
+   *
+   * When set, the `retrieve()` and `assembleForPrompt()` methods can accept
+   * `options.hyde = true` to generate a hypothetical memory trace before
+   * searching. This improves recall for vague or abstract queries by
+   * producing embeddings that are semantically closer to stored traces.
+   *
+   * @param retriever - A pre-configured HydeRetriever instance, or `null`
+   *   to disable HyDE.
+   *
+   * @example
+   * ```typescript
+   * memoryManager.setHydeRetriever(new HydeRetriever({
+   *   llmCaller: myLlmCaller,
+   *   embeddingManager: myEmbeddingManager,
+   *   config: { enabled: true },
+   * }));
+   * ```
+   */
+  setHydeRetriever(retriever: HydeRetriever | null): void {
+    this.hydeRetriever = retriever;
+  }
+
+  /** Get the HyDE retriever if configured, or `null`. */
+  getHydeRetriever(): HydeRetriever | null {
+    return this.hydeRetriever;
+  }
+
   // =========================================================================
   // Internal
   // =========================================================================

src/memory/types.ts

@@ -188,6 +188,21 @@ export interface CognitiveRetrievalOptions {
   timeRange?: { after?: number; before?: number };
   /** If true, skip emotional congruence bias (useful for factual lookups). */
   neutralMood?: boolean;
+  /**
+   * Enable HyDE (Hypothetical Document Embedding) for memory retrieval.
+   *
+   * When `true` and a HyDE retriever is configured on the memory manager,
+   * the system generates a hypothetical memory trace matching the query
+   * before embedding. This produces embeddings that are closer to actual
+   * stored memories, improving recall — especially for vague or abstract
+   * recall prompts (e.g. "that thing we discussed about deployment").
+   *
+   * Adds one LLM call per retrieval. Use for important lookups where
+   * recall quality matters more than latency.
+   *
+   * @default false
+   */
+  hyde?: boolean;
 }
 
 export interface ScoredMemoryTrace extends MemoryTrace {

src/rag/IRetrievalAugmentor.ts

@@ -134,6 +134,21 @@ export interface RagRetrievalDiagnostics {
   dataSourceHits?: Record<string, number>;
   effectiveDataSourceIds?: string[];
   messages?: string[];
+  /**
+   * HyDE-specific diagnostics, populated when HyDE retrieval is active.
+   *
+   * - `hypothesis`: The generated (or pre-supplied) hypothetical answer.
+   * - `hypothesisLatencyMs`: Time spent generating the hypothesis via LLM.
+   * - `effectiveThreshold`: Final similarity threshold after adaptive stepping.
+   * - `thresholdSteps`: Number of times the threshold was lowered before results
+   *   were found (0 means the initial threshold succeeded).
+   */
+  hyde?: {
+    hypothesis: string;
+    hypothesisLatencyMs: number;
+    effectiveThreshold: number;
+    thresholdSteps: number;
+  };
 }
 
 /**