Alpha Agentic Search: a five-layer memory RAG stack behind a Route-Rewrite-Retrieve-Verify-Summary loop

The problem Alpha Agentic Search picks: layered recall with a latency ceiling

Most search-agent projects the README cites were built to climb a benchmark. Search-R1 and the web-search agents that followed it optimize answer quality in an unconstrained setting, where a run can take as long as it takes. Alpha Agentic Search takes the opposite constraint as its starting point. Its stated goal is stability, controllability and short wall-clock time, and the target reader is explicitly the engineer building a personal search assistant or the beginner learning how agentic retrieval is wired, not the researcher chasing a leaderboard.

The concrete problem it attacks is that a plain RAG loop has one retrieval path. If that path misses, the answer is wrong and there is nothing to fall back on; if it hits, you paid full latency anyway. AAS splits recall into five layers with different cost and coverage profiles, lets a router decide which layers to activate per question, runs the selected ones in parallel, and fuses the results. The second problem is memory: a session that answers the same question twice should not pay the same cost twice, which is what the L1 cache and the L3 history archive are for.

How the five layers and the RRF fusion actually fit together

The pipeline is fixed and named in the README: Route, Rewrite, Retrieve, Verify, Summary. src/core/agent.py is the orchestrator. Step 0 checks the L1 cache in src/cache/qa_cache.py, using both exact and fuzzy matching. Step 1 is routing in src/pipeline/tool_router.py, which also reaches into src/tools/ for time and weather. Step 2 rewrites the query in src/pipeline/query_rewriter.py, with a context provider supplying time and location, then hands off to src/rag/LayeredRetriever. Step 3 generates the answer through src/core/llm_client.py with configuration from src/configs/.

The five layers are L1 cache, L2 Wikipedia, L3 history, L4 live web, and L5 knowledge graph. The router decides which are active, they recall in parallel, and the results are merged with Reciprocal Rank Fusion. All five encode with FlagEmbedding BGE-M3, which is the design decision that makes fusion possible at all: a cosine score from the L2 FAISS index and a score from the L5 SQLite graph land in the same vector space, so they can be compared. The README also describes a cross-layer calibration step that maps each layer's raw score (cosine, rank-based, or mixed) onto a P(relevant) value, then aggregates those into an overall confidence with a noise-OR rule. That is a more honest approach than summing raw scores from incomparable sources, and it is the part of the design most worth reading the code for.

L5 has its own disambiguation problem. Entities that share a name collide, and the README gives the example of Beijing versus an American town of the same name. The fix is a combined score of weight times log1p(indegree), plus description overlap and a type-versus-intent match. The README reports disambiguation improving from 6/11 to 11/11 on that check. Treat that as the author's own figure on the author's own set, not an independent benchmark.

Installing Alpha Agentic Search and asking the first question

The README's quick start assumes a local Ollama instance for the router and rewriter stages. Pull the model and start the server first.

ollama pull qwen3:4b-instruct-2507-q8_0
ollama serve

Then create an isolated Python 3.11 environment and install the pinned dependency set. requirements.txt lists the third-party imports, including faiss-cpu, FlagEmbedding, transformers, torch, PyYAML and ddgs.

conda create -n search-agent python=3.11 && conda activate search-agent
pip install -r requirements.txt

The rewriter and summary stages default to a remote OpenAI-compatible model behind a gateway the README calls Tokenverse. Export the key, or switch to the DeepSeek path described in the stage configuration section.

export TOKENVERSE_API_KEY="xxx"

Live web search is optional. Layers L1, L2, L3 and L5 still work without it, but L4 returns empty. The chain is IQS, then Tavily, then Serper, then DuckDuckGo, then Bing; whichever key you set is the one used, and DuckDuckGo needs no key.

export IQS_API_KEY="xxx"
export TAVILY_API_KEY="tvly-xxx"
export SERPER_API_KEY="xxx"

Run the CLI or the Gradio interface. The web entry point takes a port argument, and the README uses 7860.

python main.py
python main_web.py --port 7860

On startup the program prints which model each stage is using. The README notes that the L2 Wikipedia index and the L5 knowledge graph only recall once their offline indexes exist, and that without them those two layers return empty while the system still works on L1, L3 and L4. Building from scratch means downloading Wikipedia and Wikidata truthy dumps and running for tens of hours, so the README publishes a prebuilt package instead.

pip install -U "huggingface_hub[cli]"
hf download benchen4395/alpha_agentic_search_ragdata \
    alpha_agentic_search_data.zip --repo-type dataset --local-dir .
unzip alpha_agentic_search_data.zip -d /path/to/alpha_agentic_search/

The zip contains a top-level data/ directory, so it must be extracted at the repository root. Extracting inside data/ produces data/data/rag_data/ and every layer fails to read. After extraction you should see data/rag_data/wikidata_zh_kg.db. The archive is 5.9 GB, expands to 14.4 GB, and peaks near 20 GB while both copies exist. The BGE-M3 weights are not in the package; FlagEmbedding downloads roughly 2.3 GB on first run. The bundled l3_history/ directory is the author's own test archive and can be deleted, since L3 rebuilds as you ask questions.

Where Alpha Agentic Search is the wrong tool

The licence is the first blocker. The README's table of contents lists section 11 as License, but the retrieved text does not name a licence, and the repository metadata does not carry one either. A company that needs a clear legal position before shipping code cannot get one from this repository as it stands.

The second constraint is the index. The README is direct that L2 and L5 return empty until their offline indexes are built or downloaded. If you cannot spare the disk for a 5.9 GB download and a 14.4 GB extraction, you are running three layers, not five, and the local-knowledge and structured-fact recall that distinguishes this project from a simpler web-search agent is gone. There is no middle path documented between a tens-of-hours build and the full package.

The third is the dependency weight. FlagEmbedding, transformers, tokenizers and torch are coupled tightly enough that requirements.txt recommends installing them as a group, and the README notes BGE-M3 runs on CPU but is slow on the first query. On a machine without a GPU, that first-query cost is real and the warmup call exists precisely because of it.

Finally, the retrieval stack is built around Chinese-language data. The shipped index files are wikidata_zh_kg.db, wiki_zh_emb_hnsw.faiss and wiki_zh_chunks.jsonl. A team whose corpus is English will find the prebuilt package of limited use and will be back to the offline build path.

How this differs from a single-index RAG service

The natural comparison is a hosted retrieval-augmented answer service, or a self-hosted stack such as a vector database plus an LLM API. Those systems give you one index and one similarity search, and the host manages the data. The difference here is not the model. It is that retrieval is treated as a routing problem with five candidate sources, and the router is a model call that can be inspected and reconfigured per stage.

The other real difference is the memory loop. A conventional RAG service re-embeds and re-searches every time. AAS archives each successful answer asynchronously into L1 and L3, so a repeated hot question can return from cache in milliseconds. That is the mechanism behind the README's claim that the system gets better the more you use it, and it is also the mechanism that makes a fresh install feel weaker than an established one. Anyone evaluating this on a clean checkout is evaluating it at its worst.

The honest counterpoint: the README states the project's core ideas also landed in Kuaishou's AI search product. That is a statement about the author's work, not evidence about this repository, and it should not be read as a deployment claim for the code you would be cloning.

Maintenance, upgrades and what the licence question costs you

The repository is not archived, and the last push was on 2026-09-15, two days before this writing. There are no retrieved releases, so upgrades are a git pull rather than a versioned artifact. The project declares version 0.1.0 in pyproject.toml and packages only the src tree; main.py and main_web.py are script entry points and are deliberately not distributed as a package, which means you cannot pip install this and import it as a library from PyPI. You vendor the repository.

That shapes the upgrade cost. requirements.txt pins minimum versions rather than exact ones, with comments warning that FlagEmbedding, transformers, tokenizers and torch are version-coupled and should be installed as a group. A dependency bump can move all four at once. The offline index format is another coupling point: the prebuilt package is tied to BGE-M3 and to the chunk alignment between wiki_zh_chunks.jsonl and the FAISS index, so changing the embedding model means rebuilding the index, not just the code.

The bundled l3_history/ is the author's test archive. Keeping it means inheriting someone else's cache state; deleting it costs nothing but the warm start. On licensing, the README does not state terms, so the practical step is to ask the author directly through the contact address given in the README before any commercial use. That is a fact about the repository, not legal advice.

Editorial conclusion

Adopt Alpha Agentic Search if you want a readable, single-repository implementation of a routed multi-layer retrieval pipeline and you are willing to run Ollama locally plus download a 5.9 GB index to get L2 and L5. Skip it if you need a published licence, a packaged API, or a system that works well with no local index at all, since the README states L2 and L5 return empty until you build or download one. Verify first that data/rag_data/wikidata_zh_kg.db exists after unzipping at the project root, that your disk can hold roughly 20 GB of peak usage during extraction, and that the repository's licence section actually names a licence, because the README table of contents lists section 11 as License but the retrieved text does not state which one.

Frequently asked questions

Official sources

1. benchen4395/alpha_agentic_search on GitHub
2. Issues
3. README