Why an agent needs a graph, not a better index
An agent is only as reliable as what it can retrieve, and the thing it most needs to retrieve is structure: who owns this, what it blocks, which deal depends on it. Similarity search cannot return a relationship it never stored. This page is the design argument behind SemanticOS — what was measured, and what is still only a design.
Four ways retrieval breaks on real data
A plain RAG pipeline demos beautifully on a clean corpus. These are the failure modes it hits once the corpus is somebody’s actual workspace, and they are what the architecture below is answering.
Hallucinated answers
Without a structured ground truth, LLM agents invent plausible owners, dates, and decisions, and confidently cite documents that don't exist.
Stale context
Nightly vector re-indexing means an agent answering at 2pm is reasoning on yesterday's state. Decisions get made on data that has already changed.
Permission leaks
Embedding-only RAG flattens access control. An agent surfaces a snippet from a doc the requester was never supposed to see.
No traceability
When an agent answers wrong, security and compliance teams can't reconstruct which sources, joins, and filters produced the output.
The four properties, and how far each one got
Each of these is labelled with what has actually been shown. Two were measured on real data, one runs for a single source, and one is a design property that no external party has audited.
Structure survives retrieval
DemonstratedAgents traverse a typed graph of people, projects, documents and events rather than a bag of nearest chunks, so an answer can report the path it took. On a controlled evaluation over edge-only facts, graph retrieval scored 1.000 where flat RAG scored 0.000, on a narrow mechanism test rather than a broad benchmark.
One node per real thing
DemonstratedEntity resolution collapses the same person, project or account across sources into one node. On a labelled spike set: precision and recall of 1.0 with no incorrect merges, and on the real corpus, 46% of the first pass turned out to be duplicates of something already present.
Permissions and provenance as graph properties
Designed, not auditedAccess and origin are carried on the graph itself, so a retrieval can be filtered by who is asking and every answer can name where it came from. This is a property of the system as built and tested. It has not been through an external security audit.
Continuous ingest, not a nightly re-index
Runs for one sourceIngestion is event-sourced through Kafka so the graph can track a corpus as it changes rather than snapshot it overnight. Notion is the source that has been run end to end. Every other connector is unwritten, and an unwritten connector is not a feature.
From a document to an answer, in five stages
Every figure below comes from a recorded run on a real corpus. Where a stage has only been run for one source, it says which.
- 01
Ingest
A source is drained into an event-sourced log through Airbyte and Kafka, then into a sink that knows what the graph is allowed to contain. Nothing is written straight through. Notion is the source this has been run on: ~14.4k page records down to 9,430 unique pages.
- 02
Resolve
Entity resolution stitches the same person, project or account into a single node, and relationships become first-class typed edges. An embedding may lift a candidate pair to review; it may never drive a merge on its own.
- 03
Govern
The LLM proposes, a deterministic validator disposes, so hallucination is contained at extraction and removed from schema decisions entirely. Unknown types wait in quarantine and are promoted only by recurring past a threshold; a skeptic agent judges the band below it, and rejected 6 of the proposals on the real corpus as noise.
- 04
Index
Nodes carry semantic embeddings alongside their structured fields, so retrieval can combine traversal with vector search. Measured on a 20,000-node spike: recall@10 of 0.992, with a p95 latency that missed its target because of a cross-region network floor.
- 05
Retrieve
Questions are answered by walking the graph and reporting the path. When the path does not exist, the answer says so. That abstention held against questions about content never ingested, with zero fabrication.
What the model was designed to serve
Not deployments. Nobody runs an agent on this today. These are the retrieval shapes the graph model was built for, and the reason it is shaped the way it is.
Autonomous knowledge retrieval
A support agent surfaces the runbook, the last related incidents and the on-call owner in one grounded answer, because those are edges rather than three separate searches.
Account intelligence on demand
An account brief assembled by traversing from the customer to its deals, its open issues and the conversations that touched them, rather than by ranking chunks that mention its name.
Onboarding companion
"How do we ship a feature here?" answered from the artifacts a team actually produced, with the path visible, instead of from a wiki page nobody has updated.
Compliance review
Every claim traced back to the node and the source it came from, which is why provenance is a property on the graph rather than a citation string appended by a model.
Common questions
Why do AI agents need a graph at all?
Embeddings collapse structure. Nearest-neighbour retrieval can find text that mentions a project and still cannot tell you who owns it, what it blocks, or which deal depends on it, because those are relationships and not similarity. A typed graph keeps them, which is what lets an answer report a path instead of a vibe.
How does this compare to standard RAG?
Standard RAG retrieves chunks from a vector store. Here, retrieval is graph traversal with vector search alongside it for the natural-language half. The measurable difference showed up on edge-only facts, questions whose answer lives in a relationship rather than in any single chunk, where graph retrieval scored 1.000 and flat RAG scored 0.000. That is a small, deliberately narrow evaluation validating a mechanism, not a claim about general retrieval quality.
Can agents take actions, not just answer questions?
Not today. The system reads: it ingests, resolves, governs and answers. Write-back through the same connectors is a coherent extension of the design and it has not been built, so it is not offered here as a capability.
How is permission enforcement handled?
Access is carried as properties on the graph and evaluated for the requester at query time rather than baked into a shared index. That is the design as built and tested. It has not been through an external security audit or any compliance certification, and mirroring real source-system ACLs at production scale has not been demonstrated.
If you are building something like this
SemanticOS is an independent project, paused between phases while I look for the resources and the people to carry it further. The problem it addresses does not pause with it: an organisation’s knowledge has to be modelled before anything built on top of it can be trusted. If your team is working on that, for retrieval or for agents, I would like to hear about it.
Goes to info@semanticos.io, which I read myself. Happy to give a live walkthrough of the system and the reports behind it.