Retrieval

The current retrieval entry point is mandol.retrieval.MultiRetriever. Pre-refactor retrieval designs are retained only under docs/archive/.

Available methods

RetrievalMethod currently includes:

• BM25 / "bm25"

• COSINE_SIMILARITY / "cosine" or "cosine_similarity"

• SPLADE / "splade"

• GRAPH_TRAVERSAL / "graph"

• HYBRID / "hybrid"

• GRAPH_CONTEXT_EXPANSION / "graph_context_expansion"

Basic search

from mandol.retrieval import MultiRetriever

retriever = MultiRetriever(graph)
results = retriever.smart_search(
    "Where did Zhang San go?",
    methods=["bm25", "cosine"],
    top_k=5,
    fusion_method="rrf",
    rerank_method=None,
    space_names=["demo"],
)

smart_search returns list[tuple[MemoryUnit, float]] by default. Pass return_detailed=True to include the execution plan, method results and timing information.

Quantified search

payload = retriever.smart_search_with_quantification(
    "Where did Zhang San go?",
    methods=["bm25", "cosine"],
    top_k=5,
    rerank_method="baai",
    space_names=["demo"],
)

results = payload["results"]
metrics = payload["quantification"]

The quantification payload reports consistency between sparse and dense result sets, a confidence score and a simple diagnosis. The current implementation uses a reranker in this path; choose the backend and method deliberately because local rerankers can load large models.

Async reranking with vLLM

If RERANKER_BACKEND=vllm is set, local neural rerankers must use async retrieval paths:

results = await retriever.smart_search_async(
    "query",
    methods=["bm25", "cosine"],
    rerank_method="baai",
)

The sync APIs intentionally raise for this backend/method combination to avoid blocking a vLLM HTTP rerank path incorrectly.

Three-tower retrieval

mandol.triple_retrieval.TripleTowerRetriever orchestrates hierarchical, entity-relation and episodic retrieval over already-built memory spaces.

from mandol.triple_retrieval import TripleTowerConfig, TripleTowerRetriever

tower = TripleTowerRetriever(graph, config=TripleTowerConfig(final_top_k=10))
result = tower.search("What changed in the Q2 delivery plan?")

The three-tower package is retrieval-facing. Use mandol.auto_builder when memory spaces must be constructed before retrieval.