foragekit

foragekit

Your agent can already search. foragekit makes it forage: hunt sources by expected information gain, pin every claim to a verified quote, and ship briefs that know how sure they are.

Literature review is quietly becoming agent work — and agents are fast, tireless, and unaccountable. They cite from memory and present every claim with the same unearned confidence. The fix isn't a smarter model; it's giving the model the discipline we ask of a good PhD student: receipts, stances, and an honest "I'm not sure yet." — the maintainers, July 2026

News · 2026-07 foragekit 0.0.1 on PyPI — uvx foragekit serve --mcp · 2026-07 working core + MCP server: 21 tools, zero runtime dependencies · 2026-07 head-to-head agent evaluation published (docs/EVAL.md) · 2026-07 spec and plan hardened by a four-critic adversarial review

Spec · Plan · Agent skill · Example brief · Eval results · What is epistemic foraging?

Get your agent foraging in 60 seconds

Zero runtime dependencies — Python stdlib only. On PyPI, so one line:

$ claude mcp add forage -- uvx foragekit serve --mcp     # Claude Code, zero install
$ uvx foragekit serve --mcp                              # any other MCP client

Or open a clone in Claude Code or Cursor — the repo ships .mcp.json and the server is auto-detected. Either way the workspace initializes itself on the first tool call. Prefer pip? pip install foragekit gives you the forage CLI too.

Then paste any of these at your agent:

• "Register the question 'does creatine improve cognition?' and forage: search, snowball the best hits, read in frontier order, pin evidence, and compile a brief with confidence levels."
• "What should I read next, and is the current patch exhausted?"
• "Audit the workspace — which claims are single-source or contested?"
• "Replay the ledger: show me exactly what you did and verify the chain."

For agents that follow written skills, drop in agents/SKILL.md. For humans, the same loop is the forage CLI.

Why foragekit?

• Agents hallucinate citations. foragekit makes "no pin, no claim" mechanical: a claim without a verbatim, canonical-match-verified quote is flagged unsupported by a machine audit, not by hoping someone notices.
• Search is not foraging. Relevance ranking reads what looks similar; the frontier ranks unread sources by expected information gain (relevance + novelty + citation centrality − reading cost, per-component explainable) and tells you when a patch is exhausted — foraging theory's marginal-value rule, applied to reading.
• Confidence is usually decoration. Here every claim carries author-stated confidence plus derived status — supported / contested / unsupported / stale — and contested claims render both sides instead of the convenient one.
• Agent work is unauditable. Every mutation lands in a hash-chained, append-only ledger attributed to the actor (agent:claude, human:you). forage log --verify proves nothing was rewritten after the fact.

Quick tour (real output)

$ forage ask "Do retrieval-augmented LLMs hallucinate less than closed-book LLMs?"
question q1 registered (uncertainty: high)

$ forage search "retrieval augmented generation hallucination" --limit 10
10 sources added (0 duplicates merged)

$ forage snowball src_99b22d --budget 20
20 sources added from citation graph

$ forage frontier --question q1 --top 3 --explain
 1. 0.575  src_ffe035  (2024) A Survey on RAG Meeting LLMs: Towards Retrieval-Augmented...
      highly relevant to the question
 2. 0.529  src_99b22d  (2024) Reducing hallucination in structured outputs via RAG
      central in the citation neighborhood
 3. 0.474  src_680255  (2026) A Review on Retrieval-Augmented Generation: Architectures...
      highly relevant to the question
patch signal: patch still yielding

$ forage pin src_1a03ce --find "RAG emerged as a promising solution" --loc "abstract ¶1"
evidence ev2 pinned (verified-abstract)
"Augmented Generation (RAG) has emerged as a promising solution by incorporating
 knowledge from external databases."

$ forage claim add "RAG mitigates LLM hallucination but does not eliminate it" \
    --evidence ev2:supports --confidence 0.7 --question q1
claim c1 added (status: supported)

$ forage audit
[single-source-claim] c1: RAG mitigates LLM hallucination but does not eliminate it
[unsupported-claim]  c2: RAG fully eliminates hallucination

$ forage log --verify | tail -1
chain: VERIFIED - ledger intact

And forage brief q1 compiles the artifact — see a real one, generated end-to-end by an agent, in examples/brief-rag-hallucination.md.

Or use it as a library (no MCP, no CLI, no network)

Building your own RAG pipeline? The evidence discipline is importable as two deterministic primitives — a batch relevance scorer and a quote-verification gate — so your reviewer agent can score retrieved chunks without expanding any context window:

from foragekit import score_passages, verify_quote

scores = score_passages(question, retrieved_texts)   # BM25, [0,1] per chunk
span = verify_quote(claim, chunk)                    # exact supporting span, or None

None is a binary "fail as evidence"; a Span is a pass with the receipt (exact text + char offsets) attached. Runnable writer/reviewer loop in examples/rag_reviewer.py; the exact scoring math is documented in docs/SCORING.md.

The MCP surface

21 tools over stdio; every write is ledger-attributed to the calling agent. Grouped by loop stage:

stage	tools
questions	forage_ask · forage_list_questions · forage_update_question
discovery	forage_search · forage_snowball · forage_list_sources · forage_get_source
reading	forage_fetch_text · forage_get_source_text (windowed) · forage_find_text (quote-snap) · forage_mark_read · forage_frontier · forage_status
evidence	forage_pin_evidence · forage_add_claim · forage_link_evidence · forage_get_claim · forage_get_evidence
synthesis	forage_brief · forage_audit · forage_log

Nothing returns a whole paper in one call — text is windowed, lists paginate, briefs can write to disk and return a summary. And the server teaches the agent: the MCP handshake injects the foraging loop as server instructions, and every tool response ends with a one-line next hint — so a cold agent with zero prompting still forages instead of flailing. Full contracts in SPEC §5.1.

The idea's lineage

"Epistemic foraging" isn't our coinage — it's an established concept: an agent's active search for information to reduce uncertainty about its environment, rather than pursuing immediate reward. foragekit is a deliberately practical implementation of three research threads:

• Active inference / epistemic value (Karl Friston et al.) — behavior decomposes into pragmatic (reward-seeking) and epistemic (uncertainty-reducing) action; the frontier score is a working approximation of epistemic value for reading.
• Information foraging theory (Pirolli & Card) — humans hunt information the way animals hunt food, following "scent"; the frontier's why strings are scent made explicit.
• Optimal foraging / the marginal value theorem (Charnov) — leave a patch when its marginal yield drops below what's available elsewhere; that is literally the patch_exhausted signal.

Design choices

• Local-first, nothing else. One workspace directory: SQLite + Markdown + JSONL. Delete it and nothing remains. No cloud, no telemetry, no account.
• Zero runtime dependencies. Stdlib only — the MCP server is 300 lines of hand-rolled JSON-RPC. pip install cannot fail on a transitive pin.
• One explainable score, not a learned ranker. Frontier weights are visible, configurable, and logged per ranking. You can argue with it, which is the point.
• Connectors are an allowlist, not a framework. OpenAlex, arXiv, and Crossref today (Semantic Scholar specced); static hosts, polite rate limits, honest User-Agent, zero API keys. There is no generic-URL fetcher, by design — full text comes only from arXiv's own HTML renders.
• MCP over stdio only. No network listener until an authenticated HTTP design earns its way in (SPEC §5.3).

Status — honest edition: young but real. Evidence pins reach verified-full-text for papers with arXiv HTML renders (most post-2023 arXiv papers; 136K-char fetches work today) and verified-abstract elsewhere — PDF extraction is still open. The eval harness is live with first benchmark numbers (docs/EVAL.md): foraging found 25.0% of a survey's hidden references vs 0.9% for keyword search at equal budget. Semantic Scholar and confidence calibration remain unbuilt. The plan says what lands when.

What it will never do

Literature review and knowledge work only. Enforced by design: no generic or covert collection (curated host allowlist, no crawler, no credentialed scraping) and no person-centric data model (works and citations only — no author-entity endpoints, no dossier primitives). Enforced by policy: no offensive-security/OSINT features, no biosafety workflows, no persuasion systems. Full text and the honest design-vs-policy split in SPEC §8.

Names we considered

Generated through three lenses (foraging metaphor, descriptive dev-tool, epistemics brand), web-checked for collisions: foragekit (chosen — says what it does, no exact collision), trailcairn (great provenance metaphor, misses discovery), credence (best epistemics word, crowded namespace), tekmerion (Aristotle's "sure sign", unspellable), notesynth (clear, generic).

Wanted: connectors & adapters

The extension surface is deliberately small and these slots are open — each is a good first issue: Crossref connector · Semantic Scholar connector · Zotero / CSL-JSON export adapter · brief output formats · README translations. See CONTRIBUTING.md for the conformance rules (and the scope rules PRs are checked against).

License

Apache-2.0 (see LICENSE).