Retrieval Methods in ai-memory: Full-Text, Graph, Entity, and Optional Vector Search

ai-memory retrieves information through a multi-stream engine that combines FTS5 full-text search, entity matching, graph traversal, and optional vector semantic search, fusing all scores with Reciprocal Rank Fusion (RRF) to produce ranked results.

The akitaonrails/ai-memory repository implements a hybrid retrieval architecture designed to surface relevant pages through complementary ranking signals. The system orchestrates independent retrieval streams in parallel, ensuring robust recall whether querying by exact keyword, structural relationships, or semantic meaning.

The Four Retrieval Streams

The core retrieval logic resides in crates/ai-memory-store/src/reader.rs, where the hybrid_search function coordinates four distinct ranking streams. When a query executes, all applicable streams run simultaneously and their results merge through RRF scoring.

FTS5 Full-Text Search

The FTS5 stream leverages SQLite's built-in full-text search engine to match keyword occurrences within page bodies. This stream tokenizes content and evaluates traditional lexical overlap, providing reliable keyword-based retrieval for exact term matches.

Entity Matching

The entity stream extracts and matches structured tokens including page names, tags, and linked identifiers. This enables lookup by exact page references even when the query contains no overlapping keywords with the page content. The engine identifies entities as discrete semantic units separate from the raw text body.

Graph Traversal

The graph stream traverses the link topology between pages, propagating relevance through connections. When a page matches a query, the engine boosts scores for pages linked from that matching node. This structural retrieval method surfaces related content that shares logical connections with explicitly matching pages.

Optional Vector Semantic Search

The vector stream performs semantic similarity search on unit-normalized embedding vectors produced by an embedder. Implemented in crates/ai-memory-llm/src/embedding.rs, this stream activates only when an embedding provider (such as OpenAI embeddings) is configured and a query vector is available. Without an embedder, the engine gracefully degrades to the three lexical streams (FTS5, entity, and graph).

Score Fusion Architecture

The retrieval engine combines raw scores from active streams using Reciprocal Rank Fusion (RRF), a robust algorithm that balances contributions across methods regardless of their score distributions. As implemented in crates/ai-memory-store/src/reader.rs, RRF ensures that no single stream dominates the final ranking while preserving the unique relevance signals each method provides.

When no embedder is present, the system executes the three lexical streams (FTS5 + entity + graph) and fuses their RRF scores. When vector support is enabled, the fourth stream runs in parallel and its scores integrate into the same RRF calculation.

Optional Post-Retrieval Reranker

Following initial retrieval, the pipeline supports an optional LLM-based reranker defined in crates/ai-memory-llm/src/reranker.rs. When attached to the query pipeline, this component re-evaluates and re-scores the candidate set for improved precision. When omitted, as noted in the source comments for memory_query in crates/ai-memory-mcp/src/server.rs, the system returns results ranked directly by the RRF-fused retrieval scores.

Using the Retrieval API

The public API exposes three primary methods for executing searches through the ReaderPool struct:

use ai_memory_store::ReaderPool;
use ai_memory_llm::EmbeddingProvider; // optional, for vector support

// Create a ReaderPool (normally obtained from the Store)
let pool: ReaderPool = /* … */;

// ----------- Plain lexical search (FTS5 + entity + graph) ----------
let fts_hits = pool
    .search("compile not retrieve", None) // No embedder → vector stream skipped
    .await?;

// ----------- Hybrid search with semantic vectors ----------
let embedder = EmbeddingProvider::new("openai", "text-embedding-ada-002")?;
let hybrid_hits = pool
    .hybrid_search("semantic similarity of memory", Some(embedder))
    .await?;

// ----------- Access individual streams (optional) ----------
let (fts, entity, graph, vector) = pool
    .search_explained("example query", Some(embedder))
    .await?;

• search executes the default lexical streams (FTS5, entity, graph) when no embedding provider is supplied.
• hybrid_search enables the optional vector stream when an embedder is provided.
• search_explained returns per-stream score breakdowns for debugging or custom ranking logic.

Summary

• Four parallel streams power the retrieval engine: FTS5 full-text, entity matching, graph traversal, and optional vector semantic search.
• RRF fusion combines scores from active streams into a unified ranking.
• Vector search requires configuration: The stream activates only when an embedder (e.g., OpenAI) is provided in crates/ai-memory-llm/src/embedding.rs.
• Graceful degradation: Without vector support, the system falls back to the three lexical retrieval methods.
• Optional reranking: An LLM-based reranker in crates/ai-memory-llm/src/reranker.rs can refine results post-retrieval.

Frequently Asked Questions

What retrieval methods does ai-memory use?

ai-memory uses four retrieval methods: FTS5 full-text search for keyword matching, entity extraction for structured token matching, graph traversal for link-based relevance propagation, and optional vector semantic search for embedding similarity. All methods run in parallel and fuse scores using Reciprocal Rank Fusion.

Is vector search enabled by default in ai-memory?

No. Vector search is an optional stream that requires explicit configuration of an embedding provider. When no embedder is passed to the query methods, the engine executes only the three lexical streams (FTS5, entity, and graph) and omits vector retrieval entirely.

How does ai-memory combine results from different retrieval streams?

The engine uses Reciprocal Rank Fusion (RRF) to merge rankings from all active streams. This algorithm inversely weights rank positions from each stream, creating a balanced score that prevents any single retrieval method from dominating the final result list.

Can ai-memory function without a vector database?

Yes. The system operates fully on SQLite with FTS5, entity matching, and graph traversal when no embedding provider is available. Vector search is an enhancement layer rather than a core requirement, making the system deployable with minimal dependencies.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}