Class UnifiedRetriever

Unified retrieval orchestrator that executes a RetrievalPlan across ALL available sources in parallel, merges results via RRF, reranks, and feeds back into cognitive memory.

This is the single entry point for ALL retrieval in AgentOS. It replaces the need to call RetrievalAugmentor, QueryDispatcher, CognitiveMemoryManager, and MultimodalIndexer separately.

All source queries are executed with Promise.allSettled so partial failures degrade gracefully — a failed GraphRAG query does not prevent vector results from being returned.

Example

import { UnifiedRetriever } from '@framers/agentos/rag/unified';
import { buildDefaultPlan } from '@framers/agentos/rag/unified/types';

const retriever = new UnifiedRetriever({
  hybridSearcher,
  raptorTree,
  graphEngine,
  memoryManager,
  hydeRetriever,
  rerank: async (q, chunks, n) => reranker.rerank(q, chunks, n),
});

const plan = buildDefaultPlan('moderate');
const result = await retriever.retrieve('How does authentication work?', plan);
console.log(`Found ${result.chunks.length} chunks from ${Object.keys(result.sourceDiagnostics).length} sources`);

See

  • RetrievalPlan for plan specification
  • buildDefaultPlan for creating default plans
  • UnifiedRetrieverDeps for dependency injection

Hierarchy

  • EventEmitter
    • UnifiedRetriever

Constructors

constructor

Methods

retrieve

Constructors

constructor

  • new UnifiedRetriever(deps): UnifiedRetriever

  • Creates a new UnifiedRetriever.

    Parameters

    • deps: UnifiedRetrieverDeps

      Dependency injection container. All dependencies are optional; the retriever gracefully skips sources whose deps are not provided.

    Returns UnifiedRetriever

    Example

    const retriever = new UnifiedRetriever({
      hybridSearcher: myHybridSearcher,
      raptorTree: myRaptorTree,
      graphEngine: myGraphEngine,
      memoryManager: myMemoryManager,
      rerank: myReranker,
    });

Methods

retrieve

  • retrieve(query, plan, topK?): Promise<UnifiedRetrievalResult>

  • Execute a retrieval plan across all enabled sources.

    Flow:

    1. Check memory first — if episodic memory has a cached answer, fast-return
    2. Execute all enabled sources in parallel (Promise.allSettled)
    3. Merge results via Reciprocal Rank Fusion (RRF)
    4. Apply temporal boosting if configured
    5. Rerank merged results
    6. For complex plans: decompose and recurse
    7. Store retrieval event as episodic memory (feedback loop)

    Parameters

    • query: string

      The user's natural-language query.

    • plan: RetrievalPlan

      The retrieval plan specifying which sources to query.

    • Optional topK: number

      Maximum number of final results. Defaults to deps.defaultTopK (10).

    Returns Promise<UnifiedRetrievalResult>

    Unified retrieval result with merged, reranked chunks and diagnostics.

    Throws

    Never — all source failures are caught and reported in diagnostics. The retriever always returns a result, even if empty.

    Example

    const plan = buildDefaultPlan('moderate');
    const result = await retriever.retrieve('How does auth work?', plan);
    for (const chunk of result.chunks) {
      console.log(`[${chunk.matchType}] ${chunk.relevanceScore.toFixed(3)}: ${chunk.content.slice(0, 80)}`);
    }

Settings

Member Visibility

Theme

On This Page

constructorretrieve