Stop embedding what you can just address.

A vector database bills you before it's answered a single question

Chunk the corpus, embed every chunk, store every vector, re-embed on every edit — that's the fixed cost of a conventional pipeline before "hello world" runs once. treehash's structural resolver never embeds anything at ingest; the optional semantic tier only computes vectors per-query, on demand, and throws them away.

Three moves instead of one similarity search

A conventional RAG pipeline chunks every document, embeds every chunk, and pays a similarity search over every vector for every query. treehash resolves structure first.

treehash vs. a typical chunk-and-embed pipeline

Every "typical pipeline" column below is the honest, unglamorous default — a standard chunker, a standard embedding call, a standard vector store — not a strawman. See benchmarks/ingest_cost/ and BENCHMARKS.md to run the comparison yourself.

Install it and it runs

No model downloads, no API key needed to use the core engine, no sklearn/torch/numpy to even get started. Published on PyPI — this is a real, working install, not a "coming soon."

from treehash import KnowledgeBase

kb = KnowledgeBase(domain="finance")   # or "medical", "education", or None
kb.add_document("10k_2025", filing_text)

result = kb.query("What was revenue in Q2 2025?")
print(result.method)              # "structural" — resolved by address, not search
print(result.hits[0]["content"])   # "6.1M"

ctx = kb.context_for_llm("What was revenue in Q2 2025?")
print(ctx["estimated_tokens"])     # a handful of tokens, not a whole page

Feed context_for_llm()'s output to your own LLM call, or let kb.ask(query, api_key=..., provider="anthropic") do it and hand back the provider-reported token counts — so any reduction shows up as a real number on your bill, not an estimate.

What each module actually does

We publish our own bugs. Most projects don't.

Every claim on this page is backed by a script anyone can re-run — that's this project's own disclosure standard's whole job. The clearest proof isn't a number — it's watching the number get worked on in public. Three consecutive rounds: find the highest-leverage real gap, fix exactly that, verify zero regression at the individual-case level before keeping it.

Blended accuracy across all 1,108 cases moved 84.4% → 92.1% over the three rounds above, plus a new multi_hop_computed category (4/4), on a bank where every generated case's expected answer traces back to a fact a human already verified — never invented. Full methodology and numbers in accuracy_cases/ITERATION_LOG.md.

An address, a method, a confidence — not a similarity score

A cosine-similarity hit names a nearest neighbor. This names an address — inspectable, hash-chained, exportable as evidence.

answer = kb.ask("What was revenue in Q2 2025?", api_key="sk-...")  # recorded automatically

ok, bad_index = kb.audit_log.verify()          # hash-chain integrity check
kb.audit_log.export_csv("audit-trail.csv")         # for a human reviewer
report = kb.cost_savings_report(input_cost_per_1k=0.15)  # real, provider-billed tokens

• Every ask() call is recorded with its literal source addresses, resolution method, confidence, answer, and real provider-billed token usage.
• Hash-chained — the same content-addressing idea this project already applies to tree nodes, applied to log entries: each record's hash covers its own fields plus the previous record's, so editing or reordering an earlier record is detectable, not just trusted.
• Cost savings, verified not asserted — the actual-cost half of cost_savings_report() comes from real provider-billed tokens; the baseline-cost half is honestly labeled as an estimate, since that path is never actually run against a real API.
• A runnable starter kit for the vertical this project is strongest in — finance 10-K/10-Q analysis — end to end, no API key required: examples/tenk_analysis_audit_trail.py.

An agent already knows what it wants — give it an address, not a guess

Deterministic address resolution fits a tool-calling agent better than a human typing a question. treehash exposes that directly as MCP tools.

# pip install treehash[mcp]
python3 -m treehash.mcp_server   # stdio transport — plug into Claude, LangGraph, any MCP host

• Structured tools first — get_section, get_table_cell, get_by_address bypass the natural-language resolver entirely, calling the tree/hash index directly. Deterministic by construction, not by a query happening to match a regex.
• query (natural language) stays available as a fallback for exploratory use with no known address — but it isn't the primary surface here the way it is for a human chatting.
• ask() is deliberately not exposed as a tool — the calling agent already is the LLM; it doesn't need this to call another one, and a tool that accepts an API key is a credential smell for no benefit.
• Same TREEHASH_DATA_DIR/sharding/audit-log config as the HTTP server — an MCP client and Server mode can point at the same data.

What real documents and real traffic actually broke

• Memory — pdfplumber's per-page cache, never released, cost 1.5GB to parse one 13MB report. Fixed with page.close(): 69MB, 22× smaller.
• Concurrency — 5 real OS processes writing to the same SQLite file lost writes under the default journal mode. Fixed with WAL, busy_timeout, and BEGIN IMMEDIATE; verified with a real subprocess-based test.
• Crash recovery — a process SIGKILLed mid-write, an open gap this project named itself. A real subprocess is killed partway through an uncommitted transaction; the test confirms the database still opens and that none of the killed write is partially visible.
• Multi-tenant auth — per-KB bearer keys (TREEHASH_API_KEYS), so one tenant's key can't read another tenant's kb; a single shared token remains a fallback for kbs with no per-kb keys configured.
• Enterprise-shaped scale — thousands of SEPARATE documents (not one giant document) found two real O(n_documents) bugs in the structural resolver, both fixed; confirmed flat lookup latency from 100 to 20,000 documents afterward.
• A table-lookup that quietly stopped being O(1) — a repeated label word in a table's row key made candidate generation cost O(corpus size); fixed by checking a token's selectivity before paying to fetch its match set. 18.9ms → 0.013ms at 100,000 elements.
• A single-document ingest that quietly became O(n²) — every section in one giant document shared one parent, and adding a child rebuilt that parent's whole list every time. Fixed with an O(1) membership check. 121s → 7.34s at 1,000,000 elements.
• Postgres — a StorageBackend reachable from multiple machines, not just one SQLite file. Found and fixed a real concurrency bug (schema creation races under concurrent first-open) and two round-trip-reduction fixes; its own latency numbers are reported as directional, not a tight bound — see BENCHMARKS.md.
• Server — a per-IP rate limit (60/min default, in-memory by default, Redis-backed across worker processes when configured), a request-size ceiling (150MB), and structured request logging.
• Tables and figures — PDF and DOCX extract embedded images and attach nearby "Figure N"/"Table N" captions; a text-position table-detection strategy was tested and rejected after it shredded ordinary prose on most real documents it was tried against.
• Domain aliases — a section alias ("item", "chapter") resolved the ordinal query form ("the second chapter") but silently not the bare-number form ("chapter 2"), for every domain pack, until a new generic contract test — written so any future domain pack gets the same coverage automatically — caught it.

Every phase, found through testing — not assumed and patched in the abstract

In order. The most recent phases are a self-directed loop: expand the test bank, measure, fix the single highest-leverage gap, verify zero regression, repeat.

1. 1

   Productized rewrite 9b4033c

   Zero-dependency core, persistent SQLite backend, three domain packs, multi-format parsing, LangChain/LlamaIndex adapters, an HTTP server.

2. 2

   Real-world benchmark harness 34449e6

   Added FinanceBench: real SEC 10-K/10-Q filings, real GPT-4o-mini calls, provider-reported token usage — not estimated.

3. 3

   PDF headings, concurrency, hardening 41ffe9c

   Font-size-only heading detection found 1 section in a real 121-page 10-K; rewritten to combine size, boldness, and SEC pattern matching → 9 sections, 497 subsections. Fixed real multi-process SQLite write loss. Server hardened.

4. 4

   Memory and capacity 2b69aad

   A real 13MB/248-page report used 1.5GB peak RSS to parse. Fixed: 69MB, a 22× reduction. Validated against ten real documents and a 110MB combined-PDF stress test.

5. 5

   Accuracy investigation 2fc93b7

   Bare table-cell values ("21.6") were losing context-ranking to verbose but useless text — labeled with row/header context. Added lightweight stemming.

6. 6

   Images, tables, and a rejected idea 5c68dfb

   Added image + caption extraction to both parsers. A hybrid table-detection strategy looked promising on one document, failed on several others, and was documented as not shipped.

7. 7

   Three real retrieval bugs c580b0e

   Built a free, offline recall checker (no LLM call) and found: a domain alias word matching entire documents' worth of tables; a thin stopword list; a redundant ancestor/descendant ranking bug.

8. 8

   Paid confirmation 6885a3b

   Re-ran the real, billed FinanceBench suite to confirm the free checker's finding wasn't an artifact of its own grading logic. It wasn't.

9. 9

   Cost gap, adversarial set, a real O(n) bug d053abc

   Investigated a claimed FinanceBench cost regression — the premise was stale; treehash already used fewer tokens. Built a 48-case hand-verified adversarial set (paraphrase/typo/multihop/vague) and found a real accuracy gap. Found and fixed a table-lookup that had quietly stopped being O(1) at scale.

10. 10

    Published to PyPI 07e53a6

    pip install treehash-rag went from "reserved but never published" to actually working — verified in a brand-new virtualenv against the real PyPI index, not local source.

11. 11

    Ingest cost, and a real O(n²) bug 4b4af68

    Set out to measure treehash's $0 ingest cost against a chunk-and-embed baseline; building the 1M-element test case exposed a quadratic-scaling bug in MemoryBackend. Fixed: 121s → 7.34s.

12. 12

    1,104-case accuracy bank, iteration 1 21396d8

    Mechanically expanded the 48 hand-verified facts into a >=1,000-case tagged bank. Found and fixed a multi-section resolver gap it surfaced.

13. 13

    Two more fixes, v1.0.1 published 4a5e4ee

    Typo-tolerance for anchor words, then a multi-hop connector split — each verified with zero case-level regressions before keeping it. Version bumped and republished to PyPI the same day.

14. 14

    Multi-hop computed-metric resolution

    Instrumented real misses directly and found 67% of numeric FinanceBench questions have no verbatim answer at all — they're computed metrics. Built a new resolver that finds raw values by address and computes the answer deterministically; real-filing recall 7.9% → 9.2%, verified against a real example matching FinanceBench's own published answer.

15. 15

    Fixed a real dedup-ranking bug; one algorithmic experiment tried and reverted

    Found and fixed a genuine logic bug: candidate ranking dropped a high-scoring section any time a near-zero-score descendant was also present, with no regard for relative scores — now score-aware. Zero regression, reported plainly even though this specific test set showed no measured movement. Separately, tried swapping piece-selection to full BM25 reasoning it would help — it measured worse on real filings (9.2% → 5.6%) and was reverted the same day, not shipped on theory.

What we're improving next

Real numbers, tracked in the open — see benchmarks/financebench/README.md for the full trace behind each one.

• Real-filing numeric recall: 9.2%, up from 7.9% — the dominant real cause turned out to be that 67% of numeric questions have no verbatim answer in the document at all (computed metrics, not retrieval misses). A new multi-hop computed-metric resolver now handles year-over-year change and N-year averages, verified against a real example matching FinanceBench's own published answer.
• Vague/underspecified queries: 58.3% (n=12, smallest category) — next step is growing this into a generated category like the other five.
• Medical-corpus token reduction runs slightly negative against the blended 11.0% figure — a disclosed, known exception.
• Computed-metric coverage is still narrow — year-over-year change and N-year averages of a single line item, not compound ratios (margins, turnover) needing two line items divided together.
• A real parser bug (repeated document letterhead text misdetected as a heading, separating a statement from its own table) is worked around locally in one resolver, not fixed at the root.
• The resolver is curated patterns, not a trained model — a query log now surfaces real fallthrough traffic to prioritize the next pattern.
• No OCR; single-column PDF layout only; vector-drawn charts aren't captured.