Collect the receipts
Markdown, text, structured config, PDFs, DOCX files, and optional Git provenance enter a local workspace.
Why agents love it
It turns "trust me" into "show your work."
EvidEngine gives agents a grounded working memory over a project: queryable facts, source-backed chunks, graph neighborhoods, Git lineage, and machine-readable errors instead of brittle chat context.
Citations are first-class
Answers can point back to source paths, chunks, pages, paragraphs, commits, run IDs, and config snapshots.
Graph context is navigable
Agents can ask for a node, walk neighbors, explain why two things connect, and export subgraphs for deeper reasoning.
Runs are reproducible
Stable ordering, deterministic IDs, audit logs, and replay support make tool output reviewable by humans and agents.
$ evidengine query --q "architecture" --limit 5 { "query": "architecture", "results": [ { "id": "ent_...", "score": 1.0, "explanation": { "matched_terms": ["architecture"], "tie_break": ["ent_..."] } } ] }
ag_query -> find grounded evidence ag_neighbors -> expand local context ag_why_connected -> explain graph paths ag_diff -> compare runs git_file_history -> recover provenance ag_validate_store -> audit for redaction misses
The value proposition
A pipeline from local evidence to agent-ready answers.
The README hero shows the promise: ingest the material that matters, skip the noise intentionally, materialize deterministic graph artifacts, then let agents query the evidence instead of guessing.
Make evidence typed
Sections, references, technologies, config keys, chunks, commits, authors, and file lineage become stable records.
Connect what matters
Explainable links, chunk citations, co-occurrence edges, and Git relationships make context traversable.
Answer with provenance
CLI and MCP tools return deterministic JSON that agents can inspect, cite, replay, export, and defend.
Built for engineering reality
Less vibes. More audit trail.
EvidEngine is especially useful when a project has long-lived decisions, scattered notes, mysterious config, and Git history that contains the "why" behind the current state.
Decision recall
Find ADRs, architectural notes, references, and the neighboring evidence that explains how a choice came to be.
Config comprehension
Structured configs become queryable notes and key trees, with links to technologies and referenced documents.
Provenance recovery
Ask who changed a file, when it was introduced, which commits touched it, and how its lineage evolved.
Run diffing
Compare graph runs to understand what was added, removed, or changed after the source material moved.
Neo4j path
Export or sync graph artifacts to Neo4j when local CLI workflows need richer visual exploration or integration.
Safety posture
Read-only MCP mode, redaction checks, export path constraints, and normalized errors keep agents inside clear rails.
Agent contract
Small, composable tools. Predictable output.
The LLM integration is not an afterthought. EvidEngine ships an MCP server, generated skill documentation, OpenAI function adapter artifacts, read-only mode, and a manifest-driven tool surface.
ag_query ag_list ag_node ag_neighbors ag_why_connected ag_diff ag_export ag_jobs_list git_who_changed git_commits_for_file git_file_introduced git_file_historyGrounding Results carry IDs, explanations, source paths, citation metadata, and graph context.
Determinism Stable ordering, tie-breaks, manifests, config snapshots, and replay make answers inspectable.
Boundaries Read-only mode blocks write-classified tools; exports stay under workspace export paths.
Failure model Tools normalize failures with codes like INVALID_INPUT, NOT_FOUND, FORBIDDEN, TIMEOUT, and INTERNAL_ERROR.
Honest by design
Clear scope beats magical claims.
EvidEngine is early-stage CLI software, and the project is explicit about what it does today. That transparency is part of why agents can use it responsibly.
Git provenance still creates file nodes from commit history, but code structure navigation belongs to language-aware tools.
They produce deterministic document, segment, and chunk artifacts with citation metadata, not full concept graphs by default.
The implemented surface focuses on deterministic keyword/entity/chunk retrieval, graph traversal, export, and provenance.
First run
Clone, install, query.
Start with the sample corpus, then point EvidEngine at your own workspace when you are ready to give your agents a local evidence base.
- Status: early-stage CLI project, currently focused on local developer workflows.
- Primary audience: solo engineers and small teams that need deterministic, inspectable project memory.
- License: MIT.
$ git clone https://github.com/socratesone/evidengine $ cd evidengine $ python -m venv .venv $ source .venv/bin/activate $ pip install -e . $ evidengine run examples/sample_docs/ $ evidengine query --root examples/sample_docs/ --q "architecture" --limit 5 $ evidengine 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" is not good enough and the next answer needs a trail of real evidence.