Connected Is Not Proven: Building an Evidence Graph That Admits What It Doesn’t Know

Vivan — Sun, 18 Oct 2026 18:22:59 +0000

Graphynx is an evidence graph where every claim is anchored to a source quote and every answer lands in one of seven explicit verdict states.

A path in the graph is not a fact

Picture an on-call engineer at 2 a.m. asking an AI agent whether Checkout depends on the Redis cache. The agent finds a path (Checkout → Gateway → Order Service → Cache), answers yes, and the engineer starts a failover. But one of those links came from a war-room transcript where someone was only guessing, and another from a doc saying the dependency was removed last quarter. The agent saw nodes that were connected and reported a proven relationship.

That failure comes in three forms:

Hallucination. Language models produce believable relationships that no document actually supports, and nothing in the output tells you which ones are invented.
Edge-as-fact bias. Many graph pipelines treat every edge as ground truth, whether it is a documented fact, an assumption, or just two things mentioned together. Pairwise edges also flatten multi-party events, so two people who attended the same incident review look directly related.
Stale memory. Agents cache their conclusions and reuse them after the facts underneath have changed, so yesterday's answer gets served with today's confidence.

All three come down to the same flaw: the system cannot say what it can prove and what it is merely inferring. Graphynx is built around that gap. A connection in the graph is only a connection until a source quote, an explicit rule, or a fresh check says otherwise.

Why the usual approaches fall short

The three failures above set the requirements. Every claim has to trace to a source quote. "Stated," "derived," and "merely connected" have to be different answers. Multi-party events have to stay intact. Memory has to expire when its evidence changes.

Here is how common patterns measure up. This compares patterns, not specific products.

Common approach	What it does well	Where it breaks	Graphynx's answer
LLM summaries or plain RAG answers	Fast, readable, broad coverage	The answer reads equally fluent whether or not a source supports it, and claim-level provenance is usually missing	Every claim carries a verbatim quote with exact offsets, and claims without evidence default to `UNKNOWN`
LLM-extracted triples in a property graph	Structured and queryable	Binary `A → B` edges collapse multi-party events and invite false transitive links, and every edge looks equally "true"	`RelationEvent` hubs with role-labelled participants, plus a 7-state verdict on every answer
Merging duplicate entities in place	A clean, deduplicated graph	Overwrites IDs and discards history, so a wrong merge can't be cleanly undone	A reversible identity ledger where merges and splits are overlays on untouched claims
Agent memory as cached outputs or a vector store	Cheap reuse of earlier work	Nothing records which facts an answer depended on, so staleness goes unnoticed	Receipts with SHA-256 fingerprints of what was read, rechecked before reuse
A raw query tool for the agent (e.g., arbitrary Cypher)	Maximum flexibility	Open to injection and unintended destructive writes	Typed API endpoints and bounded MCP tools, with writes behind a dual gate

None of these tools is wrong. They are the wrong defaults when a wrong answer is expensive. Graphynx still lets a model help with extraction, but only as an opt-in hint, and a hint is accepted only if its quote matches the source text character for character.

What Graphynx is

Graphynx turns documents and data (CSV, JSON, JSONL, TXT, PDF) into an event-time graph where every claim is tied to the exact source text that supports it, then answers questions about that graph with an explicit verdict instead of a confident guess. It also keeps the audit trail an investigator or an agent needs: where each claim came from, what was inferred, and what has gone stale.

The core principle is that Graphynx is an inspectable evidence graph, not a general truth engine. If an uploaded document is wrong, Graphynx doesn't know that. It records that the document asserted the claim, and it shows you exactly where. Four design rules follow from that:

Evidence is mandatory. Every claim, relationship, and participant role links to a verbatim quote with exact start and end offsets in the source.
Connected is not proven. A path in the graph is a structural fact only, and it is never silently promoted to a source-backed one.
Uncertainty is a first-class state. Negations, conflicts, and hypotheses are stored as what they are, not flattened into generic edges.
Agents act behind a fence. Anything that writes state needs explicit authorization at both the request level and the environment level.

Core ideas

Six ideas carry the design. Each one answers a failure from the problem section.

1. Evidence anchoring: no quote, no claim

The problem: a language model can state a relationship with total confidence and no source.

The mechanism: every claim Graphynx stores is paired with an Evidence record. The record holds the verbatim quote, its character offsets within the source chunk, and a pointer to the chunk it came from. Two links tie them together: the evidence SUPPORTS the claim, and CITES the chunk.

Here is a trimmed, illustrative example. The source chunk reads: "The on-call notes say Checkout depends on the Redis cache."

{
  "kind": "Evidence",
  "quote": "Checkout depends on the Redis cache.",
  "start": 22,
  "end": 58,
  "source_id": "src_…",
  "chunk_id": "chunk_…"
}

{
  "kind": "Claim",
  "predicate": "DEPENDS_ON",
  "evidence_id": "ev_…",
  "verification_level": "source_assertion",
  "independently_verified": false
}

Slicing the chunk at [22:58] returns the quote exactly, so anyone can check a claim by reading the original text.

Three details keep this clear:

Model hints are verified, not trusted. When the optional Bedrock extraction is on, a proposed quote has to be an exact substring of the chunk. The only repair is recovering a unique exact slice when the text differs by whitespace alone. It never fixes typos, paraphrases, or changed punctuation.
A claim says what it is. Each claim is tagged source_assertion with independently_verified: false. Graphynx records that a document asserted something, and it doesn't claim the assertion is true.
No evidence means no answer. If nothing supported answers a question, the default verdict is UNKNOWN with the explanation "Insufficient supported evidence."

2. The seven-state verdict engine

The problem: in most graphs every edge looks equally true.

The mechanism: every relationship question returns one of seven states, never a bare yes/no and never a numeric probability.

State	Meaning
`SOURCE_ASSERTED`	A source states it directly
`SOURCE_NEGATED`	A source explicitly denies it
`CONTRADICTED`	Sources disagree over overlapping time periods
`RULE_DERIVED`	It follows from a declared rule over source-backed claims
`CONNECTED_ONLY`	A supported path exists, but the asked relationship isn't established
`HYPOTHESIS`	A stored, labelled lead; causation unproven
`UNKNOWN`	Nothing supported (the default)

The engine checks direct claims first, then declared rules, then bare paths. A hypothesis appears only if the caller asks for one, and UNKNOWN is the fallback. Three details matter:

A negation alone is not a conflict. CONTRADICTED needs opposing claims with overlapping validity, so a dependency that ended last quarter doesn't "contradict" an older one.
There are only two declared rules: dependency_reachability_v1 and shared_employer_temporal_overlap_v1. Everything else stops at CONNECTED_ONLY.
Path search is bounded by a hop limit and an expansion budget, and it skips claims whose time periods don't overlap.

A trimmed response when only a path exists:

{
  "status": "CONNECTED_ONLY",
  "explanation": "A supported graph connection exists; the requested predicate is not established",
  "confidence_note": "No numeric truth probability is claimed"
}

That is the 2 a.m. scenario done right: the agent can say "these are connected" without saying "this depends on that."

3. N-ary events: one hub, many roles

The problem: binary A → B edges flatten multi-party events and invite false links between people who merely attended the same incident.

The mechanism: a RelationEvent is a node of its own. Each participant attaches through a HAS_PARTICIPANT edge with an explicit role (lowercase names like responder, affected_system, context), and the event carries its own evidence record.

 (responder) on-call engineer ─┐
 (affected_system) Checkout ───┼── RelationEvent: incident
 (context) Redis cache ────────┘

Path search only walks claim edges, so sharing an event never creates a path between participants. If the source never said the engineer and the cache are related, Graphynx won't say so either.

4. A reversible identity ledger

The problem: merging duplicate entities in place overwrites IDs and throws away history, so a wrong merge can't be cleanly undone.

The mechanism: Graphynx never merges by editing records. Each source mention is stored immutably and grouped under a versioned entity card. Every change is a new appended revision (provisional_merge, split, or revert). Claims, sources, and events are never rewritten.

rev 1  initial_assignment   mention A and mention B sit on separate cards
rev 2  provisional_merge    both mentions move to one card
rev 3  revert (of rev 2)    back to separate cards; history keeps all three revisions

The guardrails are enforced in code:

A shared name alone never merges anything. It creates a review candidate with the reason "Shared name alone is insufficient identity evidence."
Cross-type merges are forbidden, and a merge needs at least two mentions.
You can't revert over a later identity decision, and initial source assignments can't be reverted at all (use a split).

Downstream work is protected too. A derived artifact records which revision of each mention it was built on. If any of those assignments change, including through a revert, the artifact is reported as stale instead of being silently reused.

5. Write fencing and a deliberately small MCP surface

The problem: give an agent raw query access and one bad prompt, or one injected instruction, can run arbitrary or destructive queries.

The mechanism: Graphynx exposes no Cypher at all. Agents get four typed tools over the Model Context Protocol (stdio, JSON-RPC 2.0, no network listener, meant for locally launched trusted clients):

Tool	What it does
`search_entities`	Resolves a name or alias; ambiguous identities stay separate
`evaluate_relationship`	Read-only; returns the verdict with evidence and paths, with no model calls and no hypotheses saved
`get_claim_evidence`	Returns one stored claim and its citation record by ID
`investigate_dependency_incident`	Previews a bounded multi-hop investigation by default

Each tool rejects any argument outside its schema. Writes sit behind two gates. The investigation tool stays in preview unless the request sets authorise_action: true and the server was started with UGI_MCP_ALLOW_WRITES=1. With only one of the two, the call fails with an explicit error. When both are set, the run persists the investigation and opens review tasks in a human queue.

The fence covers Graphynx's own state. Nothing in it triggers side effects on external systems.

6. Memory receipts: answers that expire

The problem: an agent caches a conclusion, the facts underneath change, and the stale answer gets reused with full confidence.

The mechanism: when a guided agent response is produced, Graphynx seals a receipt in a small SQLite sidecar. The receipt stores the output, plus a SHA-256 fingerprint of every fact the agent read to produce it. Before reusing it, the agent calls GET /api/agent/receipts/{id}/freshness, which re-reads those facts as they stand now:

A fingerprint changed: the receipt becomes STALE.
The facts now conflict: the receipt becomes UNKNOWN.
A parent receipt is no longer valid: the receipt becomes STALE, and the change cascades to everything built on it.
Nothing changed: the receipt is revalidated.

VALID ──(a fact it read changes)──► STALE ──(a conflict appears)──► UNKNOWN

Status only moves in this direction. A receipt can get less trusted, never more, and every downgrade is written to an invalidation log. Getting a VALID receipt again means a new, fully captured read. If freshness can't be verified at all, the API answers 503 with "do not reuse."

The check also runs inside the same SQLite transaction as the protected internal action, so nothing can change between the check and the act.

These are content fingerprints, not signatures or HMACs. They catch changed facts, not a tampered database.

Architecture at a glance

documents (CSV · JSON · JSONL · TXT · PDF)
        │  POST /api/uploads
        ▼
  parse + bounded extraction ◄── optional, opt-in model hints
        ▼
  evidence grounding
  Source · Chunk · Entity · Claim · Evidence · RelationEvent · identity ledger
        ▼
  graph store:  FalkorDB (persistent)  |  in-memory (tests)
        ▼
  FastAPI endpoints          MCP server (stdio, 4 typed tools)
        └──────────────┬──────────────┘
                       ▼
  verdict engine · fenced investigations · memory receipts (SQLite)
                       ▼
  browser workbench (2D evidence map, 3D orbit view, review queue)

Everything runs through five phases:

Ingest and bounded extraction. Documents arrive through POST /api/uploads and are split into bounded chunks. A deterministic clause grammar finds entities, predicates, and roles. If model extraction is enabled (AWS Bedrock, off by default), its output is only a hint, and a hint is kept only if its quote matches the source text.
Evidence grounding and storage. Each claim gets its Evidence record with the quote and offsets. Binary facts become Claim nodes and multi-party events become RelationEvent nodes. Records are committed in one transaction to FalkorDB or the in-memory store, chosen with UGI_BACKEND.
Epistemic reasoning. A question to POST /api/relationships walks direct claims, then declared rules, then bare paths, and returns one of the seven states with its evidence.
Controlled action. Investigations preview by default. Persisting one needs both write gates, and it opens review tasks that a human decides through POST /api/tasks/{id}/decision.
Verified memory. Guided agent responses (POST /api/agent/guided) seal receipts. Before an agent reuses one, it calls the freshness endpoint.

Walkthrough: from upload to verdict

This uses the repo's synthetic incident dataset (demo/incident.json: eight claims about Checkout, Gateway, and Cache) on the in-memory backend, so no database or model key is needed.

UGI_BACKEND=memory uvicorn ugi.api:app --port 8001

curl -F "file=@demo/incident.json" \
     -H "x-dataset: incident-demo" \
     http://localhost:8001/api/uploads

The upload response, trimmed:

{ "chunks": 8, "entities": 8, "claims": 8, "relation_events": 0,
  "provider": "offline", "usage": { "calls": 0, "estimated_usd": 0 } }

Now ask whether Checkout transitively depends on Cache:

curl -X POST http://localhost:8001/api/relationships \
  -H "x-dataset: incident-demo" -H "content-type: application/json" \
  -d '{"subject":"Checkout","object":"Cache","predicate":"TRANSITIVELY_DEPENDS_ON"}'

{
  "status": "RULE_DERIVED",
  "rules": ["dependency_reachability_v1"],
  "explanation": "A forward dependency chain entails dependency reachability; it does not prove a direct dependency or incident cause",
  "paths": [{ "claim_ids": ["a069db93…", "a7d60678…"], "directions": [true, true] }]
}

Two source-backed claims (Checkout → Gateway → Cache) are chained by a declared rule, and the response says exactly what that does and doesn't prove. Now ask the same pair for the stronger claim by changing the predicate to DEPENDS_ON:

{
  "status": "CONNECTED_ONLY",
  "explanation": "A supported graph connection exists; the requested predicate is not established"
}

It's the same path with a different answer, because nothing in the data states a direct dependency. Three more questions against the same dataset:

Question	Verdict	Why
Gateway `DEPENDS_ON` Cache	`SOURCE_ASSERTED`	One source row states it, and that row comes back as the evidence
Cache `USES` Redis	`CONTRADICTED`	The data holds both a positive and a negated row for the same relation
Cache `CAUSED` Incident 7	`UNKNOWN`	The only row marks the cause as "possible," which doesn't count as an assertion

Because this source is structured, the evidence for each claim is the source row itself. For prose, it is the exact quoted sentence.

Implementation choices

1. A fixed grammar first, a model second

ugi/clauses.py finds entities, predicates, and roles with a bounded clause grammar. Model extraction is off by default. Bedrock only runs when the provider is set to bedrock and paid calls are explicitly allowed, and a model hint is kept only if its quote is found in the source chunk.

Cost: a sentence form the grammar doesn't cover isn't extracted unless a model hint is enabled.

2. One store, two backends

ugi/store.py switches on UGI_BACKEND: falkordb (the default) or memory. The in-memory backend needs no database or key, which is how the Part 6 walkthrough runs.

Cost: two backends have to behave the same, and a run on the in-memory store says nothing about FalkorDB.

3. Typed access only

Graph access goes through FastAPI routes and an MCP server with four tools: search_entities, evaluate_relationship, get_claim_evidence, investigate_dependency_incident. Each tool rejects any argument it doesn't list. evaluate_relationship is read-only: it sets allow_hypothesis=False and use_ai=False.

Cost: you can only ask what the tools were built for.

4. Writes are opt-in, and MCP has a second lock

Investigations preview by default. Persisting one needs authorise_action=true on the request. On the MCP server there is a second requirement: the server process must be started with UGI_MCP_ALLOW_WRITES=1, which the caller can't set. Without it the call is rejected. The built-in agent bridge hard-codes writes off.

Cost: the HTTP API has only the request flag. The second lock exists on MCP, not on HTTP.

5. Receipts are a SQLite sidecar

Memory receipts are stored in SQLite (ugi/memory/core.py), separate from the graph. Every write runs in a BEGIN IMMEDIATE transaction, and the freshness gate for the protected internal action is held inside the same transaction.

6. A framework-free front end

The dashboard is plain HTML, CSS, and vanilla JavaScript (ugi/assets/), with a hand-written WebGL view alongside the SVG map.

Cost: you maintain the renderer yourself.

7. Hard input limits

Uploads are capped at 5 MB and 2,000 records by default, and text is split into 4,000-character chunks. Identity-ledger uploads are capped at 200 mentions.

The 2,000-record cap is a quota, not a throughput guarantee. Graph queries run under a 5,000 ms budget, and large uploads can exceed it. 1,000 and 2,000 rows timed out at baseline, and after the write-path fix (see Challenges) fresh 1,000- and 2,000-row uploads completed in one local run each. Large uploads that touch existing records still use the older, slower writer and keep the old capacity limit.

Challenges and dead ends

Every number below comes from the repo's own work log and milestone reports, and every sample is small.

1. The grammar alone found almost nothing on outside data

I ran the offline grammar on a fixed sample of 128 FewRel validation cases, with zero model calls. It emitted 1 claim and matched 0 of 128 target head/tail pairs. The check only screens directed pairs, so it measures coverage of an open-relation benchmark, not wrong answers. It still showed the grammar does not generalise beyond the text it was tuned on.

2. A small local model didn't fix it, and "fixing" it made things stricter

I pointed a local Qwen3 4B model (via Ollama) at the first four FewRel examples. The result was 4 model calls, 0 claims, and 0 of 4 target pairs. The log's diagnosis was that the full candidate schema exposed too many fields to a small model, so Ollama now gets a compact schema while Bedrock's is unchanged.

The next change replaced one review call per candidate with one batched call of up to 12 candidates per chunk. On the same four examples, model calls fell from 8 to 5, accepted claims fell from 4 to 1, and review tasks rose from 2 to 5. Target-pair hits stayed at 0 of 4. Batching made the system more conservative, not more accurate. Four examples is too few to say more.

3. The model reviewer rejected a correct claim

The reviewer rejected a claim built on "just south of" even though the source said it. The fix was to normalise directional predicates to base NORTH, SOUTH, EAST and WEST relations. The source quote is kept, and the claim still has to pass the standard semantic review.

4. A faster writer that failed real tests

Large uploads timed out at the 5,000 ms graph-query budget. At baseline, 1,000 and 2,000 rows timed out in both CSV and JSON. The bottleneck was not a missing index. Repeated endpoint lookups emitted about 60,200 pending records per call at 100 rows, which made the write quadratic.

Three attempts to speed up the write path:

Direct UNWIND MERGE: failed the real label and payload checks.
CREATE that still merged endpoints: correct, but large cases still timed out.
Combined new and existing node pool: passed fresh benchmarks, then caused two Invalid node id failures in the full regression run. It was not shipped.

What shipped is a writer for all-new records that links nodes by sorted ordinal. Any upload touching an existing endpoint falls back to the earlier writer, so large mixed or update documents keep the old capacity limit. The timeout was not raised and documents are not committed in partial batches.

Measured on one traced run per case on local Docker/Windows, ingest finished at:

Rows	CSV	JSON
1,000	4.1 s	4.1 s
2,000	8.1 s	10.2 s

These are single observations that overlapped an image rebuild. They are not throughput or p95 figures.

5. The model didn't beat the rules on a four-source probe

On four public dev sources with a local Ollama Qwen model, F1 was 16.67%. The rules alone scored 20% on the identical sources. The log keeps the latest run rather than the best one, notes that earlier reruns differed, and says not all raw intermediate traces were retained.

Challenges and dead ends

Every number below comes from the repo's own work log and milestone reports, and every sample is small.

1. The grammar alone found almost nothing on outside data

2. A small local model didn't fix it, and "fixing" it made things stricter

3. The model reviewer rejected a correct claim

4. A faster writer that failed real tests

Three attempts to speed up the write path:

Direct UNWIND MERGE: failed the real label and payload checks.
CREATE that still merged endpoints: correct, but large cases still timed out.
Combined new and existing node pool: passed fresh benchmarks, then caused two Invalid node id failures in the full regression run. It was not shipped.

Measured on one traced run per case on local Docker/Windows, ingest finished at:

Rows	CSV	JSON
1,000	4.1 s	4.1 s
2,000	8.1 s	10.2 s

These are single observations that overlapped an image rebuild. They are not throughput or p95 figures.

5. The model never beat the rules on the same texts

On the first four public development texts, an early run of a local Qwen model scored F1 16.67%, against 20% for the rules alone. After later extraction fixes, the model run scored 82.35% (7 correct out of 8 predictions, 9 targets) and the rules alone scored 87.5% on identical texts. The report states the model added no exact recall beyond the rules. The model's earlier first probe (77.78%) is kept in the repo rather than hidden. The labels are AI-provisional.

Results and evidence

Read this first: the extraction numbers use a development set with AI-provisional labels, and the extraction rules were tuned on that set. They are not independent accuracy. No human adjudication was added, and no paid calls were needed for the local runs. Counts are written as correct / predicted / targets.

Extraction on the development set

Same documents, rerun after the extraction fixes:

Measure	Before	After
Mixed binary claims (15 targets)	4 / 4 / 15	10 / 10 / 15
Mixed precision / recall / F1	100% / 26.67% / 42.11%	100% / 66.67% / 80%
Public-only complete binary (12 targets)	1 / 1 / 12	7 / 7 / 12
Public recall / F1	8.33% / 15.38%	58.33% / 73.68%
Exact emitted quotes	5 / 5	12 / 12

The one public research event (0 of 1, roles 0 of 4) is still missed. Two earlier synthetic sets are retained: a 20-case set at 22 / 24, F1 95.65%, and a 26-case AI-assisted challenge set at 17 / 18 / 25, F1 79.07%. Each is tiny, and the domain samples are too small to rank domains.

Outside benchmarks

FewRel: the offline grammar matched 0 of 128 directed pairs (1 claim emitted). A later frozen selection of 32 public examples gave 0 of 32 directed hits and 32 abstentions.
T2D (entity matching): 24 row pairs (12 gold matches, 12 non-matches), fixed seed. The resolver never sees gold URIs. The right candidate appeared in the pool 12 of 12 times, but 0 matches were approved, so recall is 0 and precision is undefined. It made 24 abstentions and 0 false merges. This is a derived pair probe, not the full T2D benchmark, and zero false merges here is not useful real-world recall.
Bedrock Qwen3 32B (shipped model): compared on 4 public Re-DocRED documents. It accepted 6 claims, answered 12 / 12 fixed-reference questions, and answered 7 / 12 questions from its own graph. Two of the four documents produced zero accepted relations for every model tried. This is not full Re-DocRED F1.

Ingestion scale

Fresh, ledger-off uploads of 100, 1,000 and 2,000 rows pass in both CSV and JSON. A 2,000-row upload produces 12,002 records and 8,000 edges. In the latest recorded run, 2,000-row ingest took 6,154.5 ms (CSV) and 6,048.4 ms (JSON), with write times of 1,637.8 ms and 1,562.6 ms. The 5,000 ms budget applies per query, so total ingest can run longer. This is not capacity for feature-on or large mixed-update uploads, and there are no p95 or server CPU figures.

Ledger overhead

Single traced run on 100 rows, ledger off versus on:

Measure	Off	On
Ingest	431 ms	661 ms
Write	94.9 ms	191.1 ms
Cypher queries	308	409
Exact records	602	1,305
Exact edges	400	400

This is a single observation. The report makes no p95 claim and no large-scale identity claim.

Restart persistence

Eight seeded datasets kept identical payload and edge fingerprints across a real API-and-graph container restart. The check compares fingerprints, not just counts. The report says this is not crash or backup certification.

Trade-offs and limitations

UGI is a working prototype, and its own README says it is not production-ready. Here is what it costs and where it stops.

What each design choice costs

Choice	What you get	What it costs
Conservative grammar and strict quote matching	Every claim points at an exact source span	Low recall on ordinary prose: 0 of 128 FewRel pairs, and ambiguous pronouns are deliberately left unassigned
Cautious entity linking	Few false merges (0 in the T2D probe)	True identities may stay fragmented unless a stable ID exists, and 0 of 24 T2D pairs were approved
Model review on top of extraction	A second check on model hints	The reviewer is fallible: it can accept under-specified claims and reject supported ones
Typed endpoints and a fixed tool set	No raw query access	You can only ask the questions the tools were built for
Deterministic guided agent	Predictable, auditable behaviour	It is not a free-form LLM planner

Limits worth knowing

The benchmarks are small, and most are tuned. The development set has AI-provisional labels and the extraction rules were tuned on it, so the F1 figures there are not independent accuracy. FewRel and T2D are diagnostics, not full benchmark runs. On the latest matched public subset, the local model's exact recall did not improve over the rules alone.
Grounded is not true. UGI checks that a claim is faithfully tied to the source text. If the source is wrong, UGI records that the source said it. The exact-quote check measures span correctness, not whether the sentence actually entails the claim.
Receipt fingerprints are not signatures. They are plain SHA-256 content hashes. They catch changed facts, not a tampered database. There are no signatures or HMACs.
The fence covers internal stores only. Writes to the graph, review tasks and receipt store are gated and run inside one transaction. There is deliberately no adapter for external side effects, because atomicity can't be promised outside SQLite. On the HTTP API the write gate is the request flag alone. The UGI_MCP_ALLOW_WRITES second lock applies to the MCP server.
Security is demo-grade. API keys are not a substitute for real IAM, TLS or tenant policy, and the README says not to expose the demo container publicly as-is. It also says there is no production authority RBAC.
Scale is proven only at small sizes. Fresh, ledger-off uploads of 1,000 and 2,000 rows complete in later runs, after timing out at baseline. Large uploads that touch existing records keep the old limit. The identity ledger rejects more than 200 mentions per upload, and nothing here is a million-record identity engine.
Durability was smoke-tested only. Restart persistence was checked by comparing fingerprints across a container restart. That is not crash or backup testing.
Input gaps. Scanned PDFs need OCR, which isn't bundled. Extraction is a rule system, not general language understanding.

Where it can be used

All of the examples below run on the repo's synthetic fixtures. The public datasets (FewRel, T2D, Re-DocRED) were used only as diagnostics, so none of this is evidence from real deployments.

Incident response. Upload demo/incident.json, investigate a service such as Cache, and inspect the saved review tasks. This serves an on-call engineer who needs to separate a source-backed dependency (SOURCE_ASSERTED) from a derived chain (RULE_DERIVED) and from a path that proves nothing about the predicate (CONNECTED_ONLY).
Supply chains. demo/supply_chain.csv and supply_network.json exercise the same code on a second domain. In the recorded run, a possible supply event stayed UNKNOWN instead of being promoted to a fact. This serves anyone auditing which statements a document actually makes.
Research and organisations. research_identity.json and shared_employer.json cover collaborations, shared employers and identity changes. The identity ledger lets an operator merge, split or undo entity records without rewriting the claims underneath. A deliberately wrong merge was recorded and reverted in the demo.
Agent builders. The MCP server exposes four typed tools, and receipts tell an agent whether a cached conclusion is still valid. This serves anyone building an agent that reuses earlier answers.

Try it out

Live demo: https://main.d6ybcxya0jl1.amplifyapp.com/

The demo turns source documents into an evidence graph. It answers questions about how things connect and tells you how well each answer is supported, instead of presenting every link as a fact. Nothing to install.

Load a dataset. "IT incident" is preselected under Dataset. Click Load evidence. The evidence map fills in, and the counters show entities, claims, events, saved cases and open reviews.
Inspect the evidence. Click any node or link. The Source inspector shows the exact source passage behind it. Use 3D Orbit to switch the view.
Ask a question. Under Evaluate a connection, the form is pre-filled with Checkout / TRANSITIVELY_DEPENDS_ON / Cache. Click Evaluate evidence. Expect RULE_DERIVED: two source-backed hops chained by a declared rule. Then change the predicate and ask again:
- Checkout DEPENDS_ON Cache gives CONNECTED_ONLY, because a path exists but no source states a direct dependency.
- Gateway DEPENDS_ON Cache gives SOURCE_ASSERTED, with the source row as evidence.
- Cache CAUSED Incident 7 gives UNKNOWN, because the only row calls the cause "possible".
Preview an investigation. Under Investigate and act, the target is Cache. Click Preview investigation. This is read-only. It shows what depends on Cache and which claims are uncertain or in conflict.
Save it (optional). Tick the authorize checkbox and click Execute authorized action. This creates a saved investigation and review tasks, which appear under Saved investigations and Review queue.
Record a decision. Decide on a review task. A decision records a human judgement. It never turns a model proposal into a source assertion.

To see other domains, choose "Supply chain" or "Research & identity" under Dataset and click Load evidence again.

Conclusion

The idea behind Graphynx is simple: a connection in a graph is not a fact until a source says so. Every claim points at an exact quote and offsets in the original document. Every answer comes back as one of seven states, so CONNECTED_ONLY and UNKNOWN stay visible in the cases where most systems would quietly draw a confident line. Agent writes need explicit authorisation, and a saved agent conclusion goes stale when any fact it read changes.

This is a prototype, and the limits are real. The benchmarks are small, the grammar misses a lot of ordinary prose, and the write fence covers internal stores only. Receipt fingerprints are plain SHA-256 hashes, not signatures. What the project does show is a design where an answer carries its evidence and its uncertainty with it, so a reader can tell what a system found in the sources, what it inferred by rule, and what it doesn't know.

DEV Community: Vivan

Connected Is Not Proven: Building an Evidence Graph That Admits What It Doesn’t Know

A path in the graph is not a fact

Why the usual approaches fall short

What Graphynx is

Core ideas

1. Evidence anchoring: no quote, no claim

2. The seven-state verdict engine

3. N-ary events: one hub, many roles

4. A reversible identity ledger

5. Write fencing and a deliberately small MCP surface

6. Memory receipts: answers that expire

Architecture at a glance

Walkthrough: from upload to verdict

Implementation choices

1. A fixed grammar first, a model second

2. One store, two backends

3. Typed access only

4. Writes are opt-in, and MCP has a second lock

5. Receipts are a SQLite sidecar

6. A framework-free front end

7. Hard input limits

Challenges and dead ends

1. The grammar alone found almost nothing on outside data

2. A small local model didn't fix it, and "fixing" it made things stricter

3. The model reviewer rejected a correct claim

4. A faster writer that failed real tests

5. The model didn't beat the rules on a four-source probe

Challenges and dead ends

1. The grammar alone found almost nothing on outside data

2. A small local model didn't fix it, and "fixing" it made things stricter

3. The model reviewer rejected a correct claim

4. A faster writer that failed real tests

5. The model never beat the rules on the same texts

Results and evidence

Extraction on the development set

Outside benchmarks

Ingestion scale

Ledger overhead

Restart persistence

Trade-offs and limitations

What each design choice costs

Limits worth knowing

Where it can be used

Try it out

Conclusion