How it works
Not search. Navigation.
What the front page showed, opened up: what the agent does, what the code guarantees, and how to check it yourself.
§0 · The problem
Three ways to give an agent documents, and what each one loses
Chunk retrieval
Everything, cut into fixed-size pieces and ranked by resemblance to the question.
The boundaries. A table split across chunks loses its header row; an equation lands away from its label. It can find the answer and still read the wrong number.
An agent searching chunks
An agent that searches again, reads more, and checks itself.
The pieces are still the same pieces. Reading more fragments of a broken table does not put the table back together.
The whole document in context
Everything, at once.
Until the corpus outgrows the window. And when it fits, nothing in the answer says which row it came from.
Agents got active; the documents stayed passive. Hunter-RAG changes what the agent reads, not how hard it searches. Chunking becomes compiling; embedding, top-k and reranking leave the loop; the agent navigates the document itself.
Fig. 1 Units. A document is compiled once into typed units, each kept whole and given an address.
§1
A document becomes units
- What happens
- Each document is compiled once into Coherent Document Units: sections, tables, equations, figures, code blocks. Each unit gets an address made of the document, its type and its id, like medical_PMC8104425:table:tab_005. Compiling replaces chunking: there is no fixed window to cut by, no embedding step, nothing to rerank.
- What is guaranteed
- A table stays a table: it is never cut into fixed-size fragments. An equation stays LaTeX; a figure keeps its caption. An address names the unit, not a position in a file, so it survives edits elsewhere in the document.
- Check it yourself
hunterrag ingest paper.pdfcompile a document and keep its unitshunterrag inspect <doc_id>how many units of each type, and the headings
§2
Units become a corpus you can query
- What happens
- Units are kept in a local store. A folder or an Obsidian vault is indexed the same way, one document at a time. The store answers SQL over units, over their tables' cells, and over the metadata your documents carry in their frontmatter.
- What is guaranteed
- Queries are read-only: nothing a query does can change the store. Results are limited and time-boxed, so an agent can be handed the query surface directly.
- Check it yourself
hunterrag index ./docsindex a folderhunterrag sql "SELECT element_type, count(*) FROM cdus GROUP BY 1"the corpus, by unit type
§3
The agent hunts
- What happens
- The agent works the corpus with about twenty primitives: orient (open_document), locate (find_units, grep_units), inspect (peek_unit), read (expand_unit, read_table), relate (get_neighbors, trace_source, compare_units), compute (calculate). It decides what to open next from what it has seen, and follows a document's own references ("shown in Table 6") to the unit they name.
- What is guaranteed
- No vector database and no similarity threshold sits between the question and what the agent gets to read. The agent sees the structure and chooses.
- Check it yourself
hunterrag paper.pdf -p "Which finding had the highest specificity?"one question, answered and exitedhunterrag paper.pdfor ask in the interactive session
§4
Evidence is committed, then cited
- What happens
- Search returns candidates. The agent peeks to inspect; a unit that does not answer the question is dropped and the hunt moves on. A unit that does is opened whole and committed. A number it computes is committed together with the units it was computed from. The answer cites unit addresses.
- What is guaranteed
- The answer's evidence list is exactly the units the agent read in full, and every address in it resolves to the unit itself. A unit it only glanced at, or dropped, stays in the trajectory and is never listed as evidence. The agent is asked to cite as it writes; that every sentence carries a citation is the model's discipline, not a check.
- Check it yourself
/citein a session: the units behind the last answer
§5
Every step is on the record
- What happens
- Each primitive call and its result is recorded as the trajectory of the answer. Sessions can be saved and resumed.
- What is guaranteed
- The full trajectory is kept. When an answer is wrong, you can see the step where it went wrong: a unit not opened, a reference not followed, the wrong table kept.
- Check it yourself
/tracein a session: the last answer's trajectoryhunterrag --resume mysessionpick a saved session back up
§6
When parsing misses something, the agent reads the page
- What happens
- Parsing is imperfect: a figure's image may not come through, a table may be mangled. The unit still exists, with its caption, its type and its place in the document. When the agent finds it empty, it locates the page the unit sits on and reads the whole page, rendered as an image, with the model.
- What is guaranteed
- A parsing gap does not remove anything from the corpus: the unit stays addressable, and the original page stays reachable from it.
- Check it yourself
/tracea recovered answer shows the empty unit, then the page read
§7
Your agent, or ours
- What happens
- Hunter-RAG ships its own agent (the interactive session and the one-shot command). Any other agent that can run a shell command can use the same corpus: the one-shot form prints the answer and exits; a skill teaches the agent to hunt and to cite unit addresses rather than line numbers.
- What is guaranteed
- Read-only commands write nothing outside the store, so they also run inside an agent sandbox that forbids writes. You choose the model: OpenAI, a gateway, or a model on your own machine.
- Check it yourself
cdu report.pdf -p "List the material risk factors, with citations."from any agent's shellskills/hunterrag-corpusthe skill, in the repository
§8
Your notes become a knowledge base
- What happens
- Point it at a folder of notes or an Obsidian vault. Frontmatter becomes fields you can query; [[wikilinks]] become links the agent can follow. Notes your agents write after a task join the same corpus. The corpus is compiled into short cards; at the start of a task, the matching card is handed to the agent (wire it to your agent's prompt hook). Judgments such as "this note replaces that one" are kept as links between units. Arc's own knowledge base runs on this.
- What is guaranteed
- No embeddings, no vector database, no server. A card cites units that exist, or it is not written. Matching a task to a card calls no model. A replaced note is marked, never hidden: it stays searchable.
- Check it yourself
hunterrag index ./vaulta vault: frontmatter and wikilinks includedhunterrag prior buildcompile the corpus into cardshunterrag prior match "draft the imaging criteria"which card a task would receive
What it does not claim
- It does not guarantee a correct answer.
- It guarantees that the answer's evidence is the set of units the agent actually read, each one an address you can open. Whether the reading was right is still a judgment you can check.
- It is not better on every question.
- In some cases, on prose or on code, chunk retrieval can do as well or better. The advantage is largest where the answer is an object: a table, an equation, a figure.
- It does not spend fewer tokens.
- Opening a unit returns the whole table, derivation or function. That is the price of reading it intact.
- It does not escape the parser.
- When extraction fails, the agent can read the page instead. But a table parsed into the wrong place, or text extracted wrongly, still shapes what the agent sees.
- It is not model-free.
- Navigation and answers use the model you choose. What is deterministic is the rest: the gates, the queries, matching a task to a card.
- It is not offline.
- Your documents and the store stay on your machine; the agent's questions and the units it opens go to the model endpoint you configure.
Where it stands
In daily use across Arc. Core mechanisms patent pending: Arc's patents.
Terms
Source-available. Free for personal, research and education use; commercial use needs a licence. Licensing.
Go further