FLAMEHAVEN FileSearch: Why This RAG Engine Feels Different from the Usual Stack

RAG is no longer an exotic idea.

At this point, most developers have seen the familiar stack:

• parser
• chunker
• embeddings
• vector store
• LLM
• framework wrapper
• demo query

That is not the interesting part anymore.

The interesting part is what happens after the diagram:
how much infrastructure the stack quietly demands, how much of the retrieval path is actually auditable, how much of the system is still mechanical rather than opaque, and how much operational tax the user is forced to absorb just to get a search engine running.

That is where FLAMEHAVEN FileSearch gets more interesting than the usual "another RAG repo" framing.

This is not a feature announcement. It is a technical look at what the project is actually doing differently.

The real problem with many RAG stacks

A lot of RAG systems are not products. They are assembly instructions.

They give you flexibility, but they also leave you responsible for stitching together:

• file parsing
• chunking strategy
• embeddings
• lexical retrieval
• semantic retrieval
• answer generation
• attribution
• storage
• auth
• monitoring
• caching
• deployment

That is fine if you want a blank canvas.

It is less fine if what you actually want is a document search engine that can be deployed without turning the setup itself into a second project.

That is the first reason this repo feels different: it is trying to compress more of that surface area into one codebase.

What is technically different here

1) Hybrid retrieval is treated as the baseline, not the upgrade path

A lot of RAG repos still behave as if semantic retrieval is the main event and lexical matching is an optional add-on.

That is backwards for real document systems.

FLAMEHAVEN FileSearch builds around three explicit modes:

• keyword
• semantic
• hybrid

The interesting part is the hybrid path itself.

The retrieval stack combines:

• BM25
• Reciprocal Rank Fusion (RRF)
• a Korean + English tokenizer
• a lazy per-store BM25 rebuild path

That last point matters more than it sounds. The BM25 index is not eagerly rebuilt on every upload. It is marked dirty (_bm25_dirty) and rebuilt on first hybrid search after mutation. That is a very practical decision. It keeps ingestion cheaper without pretending indexing is free.

This is one of the deeper differences from many vector-first RAG demos: the system does not assume semantic retrieval should dominate exact-match behavior. It assumes production search needs both.

2) The indexing model is not just "document in, chunks out"

The second meaningful difference is the indexing granularity.

This repo introduces a KnowledgeAtom layer: a two-level indexing model with

• file-level documents
• chunk-level atoms

Those chunk atoms are not anonymous fragments. They carry stable fragment URIs of the form:

local://store/encoded_path#c0001

`

That design solves two very common problems at once:

• precision retrieval
• stable attribution

The file-level object remains available, but the system can also retrieve chunk-level units directly. That reduces the usual gap between "the document matched" and "the relevant passage was actually isolated."

The URI choice matters too. A lot of local-first search code still uses basename-style references that collide the moment two files share a name. This repo moves to a reversible, quoted absolute-path-based URI namespace (urllib.parse.quote(abs_path, safe='')), which is much less fragile.

That is not marketing polish. That is retrieval hygiene.

3) The chunking path is internal, structured, and mechanical

Another place where this codebase differs is that it does not outsource the core text pipeline by default.

Instead of treating chunking as a thin wrapper around an external library, it implements an internal text chunker with:

• heading-boundary splitting
• paragraph splitting
• sentence fallback for oversized blocks
• undersized chunk merging (default minimum: 64 tokens)
• token-aware chunk sizing

The chunking system is actually two-pass under the hood. The structure-aware TextChunker handles the document splits above. On top of that, KnowledgeAtom applies a second windowing pass when generating chunk embeddings — 800-character windows, 120-character overlap, and an 80-character minimum before a fragment is dropped. These two paths are separate by design: TextChunker is responsible for semantic structure, KnowledgeAtom for granular embedding units.

The engine also ships a ContextExtractor — a sliding-window utility that can enrich each chunk with text from its neighboring chunks before retrieval. It is fully tested, but it is not yet wired into the default ingestion path. It is available for downstream pipeline extension.

So the pipeline architecture is:

text
document
→ structure-aware split (TextChunker)
→ chunk atom embedding (KnowledgeAtom, 800-char windows)
→ multi-level indexing
→ retrieval


That is a better-shaped pipeline for document search than a naive chunk list.

4) The vector path is trying to remove operational weight, not add it

This is probably the most unusual architectural choice in the repo.

Instead of anchoring everything around a heavyweight embedding model stack, the project uses Gravitas Vectorizer v2.0, a deterministic vectorization path built on:

• hybrid feature extraction (word tokens + character n-grams)
• signed feature hashing for collision mitigation
• SHA-256 based deterministic output
• no torch, no transformers, no model download

The trade-off is obvious: this is not trying to win a leaderboard as a giant foundation-model embedding backend.

That is not the point.

The point is that it makes the semantic path much cheaper to deploy, easier to reason about, and viable in environments where "just load another model" is operationally the wrong answer.

Technically, that shows up in several ways:

• deterministic vector generation
• cold start under 1ms
• no ML framework dependency in the core vector path
• optional NumPy acceleration with pure-Python fallback

In other words, the semantic layer is being treated as infrastructure, not as a permanent excuse to expand infrastructure.

That is rare.

5) The repo is explicit about local-first and multi-provider execution

A lot of document search systems quietly assume one provider path.

This repo does not.

The provider layer supports:

• Gemini
• OpenAI
• Anthropic
• Ollama
• OpenAI-compatible endpoints

That matters for two reasons.

First, it keeps the system from being hardwired to one hosted model assumption.

Second, it means the retrieval stack and the answer stack are not collapsed into the same dependency decision.

That is an important architectural separation.

For non-Gemini providers, the code takes a provider-RAG route: local semantic retrieval first, then prompt construction, then model answer generation. That is a much more honest design than pretending all providers support the same retrieval semantics natively.

The local Ollama path is especially relevant. Not because "local" is fashionable, but because self-hosted document search is often most attractive precisely when data boundary control matters more than marginal model quality gains.

6) The codebase has been refactored toward narrower responsibilities

One of the easiest ways to tell whether a repo is becoming more operationally serious is to look at whether the core orchestrator is shrinking or swelling.

Here, the architecture moved in the right direction.

The central core.py was split into focused mixins:

• IngestMixin
• LocalSearchMixin
• CloudSearchMixin

That is not just aesthetic cleanup.

It clarifies the system boundary between:

• ingestion
• local retrieval/orchestration
• provider-backed answer generation

The same pattern appears elsewhere:

• BackendRegistry maps file extensions to parser classes via register() — new formats plug in without modifying existing dispatch logic
• duplicate helper blocks were pulled out of cloud search paths
• file parsing was reduced to dispatch instead of a single giant extractor module

These changes do not make a flashy screenshot.

They do make the code easier to maintain without quietly reintroducing the same complexity elsewhere.

That is a real engineering improvement.

Benchmark snapshot

System profile

• Gravitas Vectorizer v2.0 (deterministic DSP, zero ML deps)
• ChronosGrid vector backend with quantized storage (int8)
• BM25 + RRF hybrid retrieval
• Local / pgvector backends
• Redis cache optional

Documented performance figures (Docker, Apple M1, 500 PDFs ~2GB)

• Vector generation: <1ms
• Search, cache hit: 9ms
• Search, cache miss (includes Gemini API round-trip): 1,250ms
• Batch search (10 queries, parallel): 2,500ms
• Upload, 50MB file with indexing: 3,200ms

What matters more than the numbers

The cache-hit figure reflects the full path when semantic and lexical retrieval are served from warm indexes.

The cache-miss figure is dominated by the Gemini API round-trip, not local retrieval.

The performance story here is not just raw speed. It is that the repo achieves low-latency local retrieval by reducing dependency weight and simplifying the vector path, rather than by hiding heavy infrastructure behind abstraction.

A comparison that is actually worth making

The wrong comparison is:

"Is this the best RAG framework?"

That is too vague to be useful.

The better comparison is architectural.

That is the actual niche.

Not "RAG but louder."

More like:

RAG with a lower operational tax.

Why this matters now

The RAG field has cooled compared to its peak hype cycle.

That is not a bad thing.

It means the novelty premium is lower, and the real questions are clearer:

• Can it be deployed?
• Can it run without a side quest in infrastructure?
• Can it keep data local?
• Can it support both lexical precision and semantic recall?
• Can its retrieval behavior be inspected rather than mythologized?

That is why a repo like this becomes more interesting now than it would have been in the most hype-saturated phase of the RAG wave.

When everything is new, wrappers are enough.

When the field matures, the differentiator becomes whether the system removes real engineering burden.

This one is at least trying to solve that problem directly.

What is special about the code, specifically

If I had to reduce the repo's technical distinctiveness to a short list, it would be this:

• BM25 + RRF is built in, not bolted on later
• KnowledgeAtom indexing gives the system a more precise retrieval unit than document-only search
• Stable chunk URIs (local://store/enc_path#c0001) make attribution less fragile
• Two-pass chunking — structure-aware TextChunker + char-window KnowledgeAtom embedding pass — keeps the text pipeline mechanical and inspectable
• Gravitas Vectorizer v2.0 reduces startup cost and dependency sprawl (zero torch/transformers)
• Provider abstraction separates retrieval architecture from model vendor choice
• Mixin segmentation and BackendRegistry pattern show a codebase moving away from monolithic orchestration

That is why this repo feels different from the usual RAG stack.

Not because it claims magic.

Because it makes several practical decisions that many RAG repos defer, externalize, or ignore.

The honest boundary

This is not a claim that the repo solves everything.

It does not.

And the codebase itself shows that.

Static inspection still flags complexity hotspots in:

• api.py
• admin_routes.py
• eval_self.py
• chronos_grid.py

There are also components that exist in the engine but are not yet connected to the default pipeline — ContextExtractor being the clearest example. The architecture is there; the wiring is not yet complete everywhere.

That is actually a good thing for a write-up like this, because it keeps the claim honest.

The interesting story here is not "perfect codebase."

It is:

a repo with a real architectural point of view, a recognizably lower dependency burden, and code decisions that are meaningfully different from the usual vector-wrapper pattern.

That is a much stronger claim than vague "enterprise-grade RAG" language.

Final take

FLAMEHAVEN FileSearch is interesting because it is not merely trying to make retrieval work.

It is trying to make retrieval:

• more mechanical
• more local
• more attributable
• less dependency-heavy
• and less painful to deploy

That is a better differentiator than "supports RAG."

Most repositories do.

The more important question now is whether they reduce the actual engineering burden around RAG, or just rearrange it.

This repo is interesting because it appears to reduce some of it in code.

And in a field where many projects now converge into the same parser + vector store + model + wrapper pattern, that is a difference worth paying attention to.

Repository

GitHub: https://github.com/flamehaven01/Flamehaven-Filesearch