> ## Documentation Index
> Fetch the complete documentation index at: https://docs.evermind.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Retrieval

> How EverOS OSS selects the right memory at the right granularity — retrieval methods, hierarchical search, and multi-granularity coexistence.

EverOS OSS stores memories at multiple granularities — episodes, atomic facts, user profiles, foresight, agent skills — and selects the right type at query time, not write time. All retrieval methods work across multimodal memories (text, image, audio, doc, PDF). See [Multimodal Memory](/open-source/multimodal) for details.

## Retrieval Methods

EverOS OSS supports four retrieval methods with different performance and dependency trade-offs:

| Method     | Mechanism                                        | Requires                   | Best for                                          |
| ---------- | ------------------------------------------------ | -------------------------- | ------------------------------------------------- |
| `keyword`  | BM25 full-text (jieba + tantivy)                 | Nothing                    | Exact terms, low latency, no model setup          |
| `vector`   | ANN embedding similarity                         | Embedding model            | Semantic queries, paraphrased language            |
| `hybrid` ⭐ | BM25 + vector + hierarchical fusion + LLM rerank | Embedding + LLM            | **Recommended** — best recall and precision       |
| `agentic`  | Multi-round adaptive with LLM sufficiency check  | Embedding + LLM + reranker | Complex queries needing multiple retrieval rounds |

<Tip>
  Use `hybrid` as your default. It delivers the best results across most query types by combining keyword recall, semantic similarity, and hierarchical granularity selection. Fall back to `keyword` when you need zero-dependency fast lookup, or `agentic` for complex multi-part queries.
</Tip>

`keyword` is the only method that requires no external model — it runs entirely on the embedded LanceDB engine with local jieba tokenization. All other methods require the corresponding model providers to be configured in `.env`.

## HYBRID: Hierarchical Retrieval

`hybrid` is more than a simple BM25 + vector blend. It runs a **hierarchical fusion** over episodes and their atomic facts:

1. **BM25 and vector recall run concurrently** — each returns a candidate pool
2. **RRF fusion** scores each candidate episode
3. **Atomic facts are fetched** for every candidate episode
4. **Granularity competition** — if a fact's relevance score exceeds the lowest-scoring episode in the top-N, the fact replaces its parent episode in the results. The parent is evicted; orphaned facts find their parent from the pre-fusion pool
5. **LLM rerank** rescores the mixed episode + atomic\_fact list by relevance to the query

The result is a ranked mix of episodes and atomic facts — the system automatically returns the right granularity for each query without any configuration.

<Note>
  For case and skill memory (agent track), `hybrid` uses LR fusion instead of hierarchical fusion, since cases and skills have no child memory types.
</Note>

## AGENTIC: Multi-Round Adaptive Retrieval

`agentic` handles queries where a single retrieval pass is insufficient:

1. **Round 1** — initial query → cross-encoder rerank → top 10 candidates
2. **LLM sufficiency check** — is this enough to answer the query?
   * If yes: return immediately
   * If no: LLM generates N supplementary queries based on what is missing
3. **Round 2** — supplementary queries run in parallel (BM25 + vector + RRF), results merged, deduped, and cross-encoder reranked

Use `agentic` for complex or underspecified queries where the initial recall is likely incomplete.

## Multi-Granularity Coexistence

All memory types compete in the same retrieval pool. Different queries surface different granularities from the same user's memory:

| Query                                    | Winning type   | Why                                              |
| ---------------------------------------- | -------------- | ------------------------------------------------ |
| "When is Jason's birthday?"              | `atomic_fact`  | A specific fact — direct and precise             |
| "What has Jason been working on lately?" | `episode`      | Needs narrative context, not a single data point |
| "What kind of person is Jason?"          | `user_profile` | Requires an aggregated portrait                  |
| "What is Jason planning this week?"      | `foresight`    | Forward-looking — only foresight holds this      |

No configuration is required. Write memory as you normally would — granularity selection happens at retrieval time.

## Cross-Track Retrieval

A single search call spans all memory tracks — `users/`, `agents/`, and `knowledge/` all participate. The retrieval pool assembles candidates from all relevant tracks before ranking.

This means an agent answering a user's question can surface in one call:

* what this specific user has said or planned (`user_profile`, `episode`, `foresight`)
* what the agent itself knows how to do (`agent_skill`)
* what the system knows about the world (`knowledge_entry`)

## Search Consistency

Search results reflect the index state, which may lag slightly behind recent writes while the Cascade Daemon processes the queue. For time-critical reads immediately after a write, call `everos flush` to force index sync before searching.

See [How Memory Works](/open-source/how-memory-works) for the full consistency model.