How it works

From files on disk to answers with receipts.

One command scans a folder and builds a graph you can question. Every step is deterministic — run it twice, get the same thing twice.

01 collect

Point it at your files

Markdown, notes, configs (.yaml, .toml, .json…), PDFs, DOCX, source code, and Git history — the material that already explains your project.

02 extract

Turn them into typed evidence

Sections, passages, entities, config keys, code anchors, commits — each with a stable ID and an honest locator: page, paragraph, heading, line range.

03 link

Connect what’s related

Explainable edges tie claims to sources, configs to the technologies they configure, and files to the commits that shaped them.

04 answer

Ask, and get receipts

Deterministic search and graph tools return JSON your agent can cite, diff, and replay — with the trail back to the source.

An answer is only as good as its receipts — EvidEngine keeps them attached.

Why agents need it

It turns “trust me” into “show your work.”

Agents are confident by default. EvidEngine gives them memory they can prove: queryable facts, source-backed passages, graph neighborhoods, and Git lineage — instead of vibes recalled from a long chat or wasted time and tokens grepping through your work space.

Citations are first-class
Every result carries IDs, source paths, and citation metadata — pages, paragraphs, commits, run IDs.
The graph is navigable
Agents can inspect a node, walk its neighbors, ask why two things are connected, and export a subgraph for deeper reasoning.
Runs are reproducible
Stable ordering, deterministic IDs, manifests, and run diffs make every answer inspectable after the fact.

$ evid query --root examples/sample_docs/ --q "architecture" --limit 5
{
  "query": "architecture",
  "results": [
    {
      "id": "ent_9f4c…",
      "score": 1.0,
      "explanation": {
        "matched_terms": ["architecture"],
        "tie_break": ["ent_9f4c…"]
      }
    }
  ]
}

ag_query          → find grounded evidence
ag_node           → inspect one artifact
ag_neighbors      → expand local context
ag_why_connected  → explain graph paths
ag_diff           → compare two runs
git_who_changed   → recover provenance
… 24 tools · read-only mode available

Built for engineering reality

Less vibes. More audit trail.

Most useful on projects with long-lived decisions, scattered notes, mysterious configs, and a Git history that holds the real “why.”

Decision recall

Find the ADR, the note beside it, and the evidence around it — how a choice actually came to be.

Config comprehension

Structured configs become queryable keys and notes, linked to the technologies and docs that reference them.

Code anchors

Python, TypeScript, JavaScript, and Rust files become navigable anchors — real names and locations, never invented claims about what the code does.

Provenance recovery

Ask who changed a file, when it first appeared, and which commits shaped it into what it is today.

Run diffing

Compare two builds of the graph to see exactly what changed after the source material moved.

Neo4j export

Optional export to Neo4j when you want visual exploration on top of the local artifacts.

Agent contract

Small, composable tools. Predictable output.

The MCP server isn’t an afterthought — it’s how agents are meant to use EvidEngine. 24 tools with a manifest, generated docs, and a read-only mode for cautious setups.

ag_queryag_listag_nodeag_neighborsag_why_connectedag_diffag_exportag_doctorag_validate_storeag_jobs_rungit_who_changedgit_commits_for_filegit_file_introducedgit_file_history

GroundingResults carry IDs, explanations, source paths, and citation metadata an agent can hand straight back to you.

DeterminismStable ordering and tie-breaks, manifests, config snapshots, and run diffs make every answer inspectable.

BoundariesRead-only mode blocks every write tool with a clean FORBIDDEN — agents stay on rails, exports stay inside the workspace.

Failure modelErrors are normalized codes agents can actually handle: INVALID_INPUT, NOT_FOUND, FORBIDDEN, TIMEOUT, INTERNAL_ERROR…

Honest by design

Clear scope beats magical claims.

EvidEngine is early-stage software, and the docs say so plainly. Knowing exactly what it does — and doesn’t — is part of why you can trust what it returns.

It’s a CLI, not a SaaS.

No hosted service, no chatbot, no accounts. A local tool (evid) writing plain artifacts to a .pkg/ folder you own. Early-stage, v0.1.0.

Search today is deterministic.

Keyword search (BM25) plus exact lookups — same query, same results, with an explanation of why. Semantic search exists behind a flag, off by default, still experimental.

Citations never bluff.

PDF and DOCX evidence carries page, paragraph, and heading locators where they’re known. Unknown coordinates are null — never guessed.

Code becomes anchors, not opinions.

Source files yield real names and locations for navigation. EvidEngine doesn’t pretend to understand what your code does.

First run

What using it looks like.

One command builds the graph. The next ones question it. This is the whole loop — early access gets you the repo and a working setup.

Status: early-stage CLI, v0.1.0 — installs from source, Python 3.10+. Not on PyPI yet.
Everything lives in a local .pkg/ directory — plain files you can inspect, back up, or delete.
MCP server included for Claude Code, VS Code, and other agent tools.

Get early access

# build the evidence graph from a folder
$ evid run examples/sample_docs/

# ask it a question — scored, explained results
$ evid query --root examples/sample_docs/ --q "architecture" --limit 5

# browse what it extracted
$ evid list --root examples/sample_docs/ --type ag:section --limit 5

Give your agents the ability to keep the receipts.

EvidEngine is for the moments when “the AI said so” isn’t good enough. Join the list and be first in line when early access opens.