How SemanticOS works
Six stages between a raw source and a grounded answer. Each one names the decision that was taken and the trade-off it carries. The rule the whole architecture follows is that a model may propose, and only deterministic code disposes.
- 01
Ingest
Airbyte OSS → Kafka → governed sink
A source is drained into an event-sourced log and then into a sink that knows what the graph is allowed to contain. Nothing is written straight through.
The decision
Transport is treated as orthogonal plumbing, validated once and then held still. The corpus can be fed directly when a spike does not need the pipe.
The trade-off
One connector is built and run end to end, for Notion. Each additional source is a connector still to write.
- 02
Extract
LLM extraction + contextual embeddings
Entities and the relationships between them are pulled from the text, each carrying a pointer back to the page it came from.
The decision
Entity embeddings carry name plus surrounding context rather than the bare name. A measurement forced that choice: bare names scored 0.650 against 0.865 with context.
The trade-off
A context window per entity costs tokens. The whole dogfood run came to 141 LLM calls.
- 03
Resolve
lexical-dominant scoring, 0.6 lexical / 0.4 semantic
The same thing said five ways collapses into one node. A candidate pair scores into one of three bands: merge, uncertain, or new.
The decision
An embedding can confirm or lift a merge, and never drives one alone. Conflicting types block a merge outright, and recall gaps land in the uncertain band for adjudication rather than in a silent auto-merge.
The trade-off
Precision over recall by construction. Some true matches sit in the uncertain band waiting for adjudication rather than merging themselves.
- 04
Govern
deterministic validator + skeptic reviewer
Types the corpus needs are proposed from the material, quarantined on arrival, and promoted only once they recur past a threshold. On promotion the LLM proposes a parent concept and a validator disposes of a bad one to the root.
The decision
The LLM proposes, a deterministic validator disposes. A model may propose a type; it never decides one. This is the rule the whole design follows.
The trade-off
A genuinely new type that appears once and never again stays quarantined. The schema is deliberately slower than the data.
- 05
Remember
bitemporal edges in Neo4j
Every fact edge carries four timestamps: valid-time (when it was true in the world) and transaction-time (when the system recorded it). On contradiction a fact is invalidated, not deleted, so the validity window closes and the history stays queryable.
The decision
Timestamps live on the relationship rather than in reified fact-nodes. That is Graphiti’s documented EntityEdge model, replicated in-graph rather than depended on as a service, which makes Graphiti a like-for-like benchmark instead of a runtime dependency.
The trade-off
Edge properties cannot express n-ary facts or a reason for change. Reified fact-nodes are the mechanism that would close that, and they are deferred.
- 06
Retrieve
graph traversal + vector search, grounded
Questions are answered by walking the graph and reporting the path taken. A temporal filter drops superseded edges so an answer reflects one coherent point in time.
The decision
When the graph does not hold an answer, the system abstains and says what it does hold instead.
The trade-off
Abstention has to be tuned. The threshold was swept against a mixed set of answerable and off-topic questions, because a value that never hallucinates but always abstains is equally useless.
Open questions
Four questions a technical reader arrives at quickly, with the current answer to each.
Why does a fact change?
Bitemporality records when a fact stopped being true, not the reason it changed. That gap runs across the field generally. Reified Event/Interval fact-nodes are the mechanism that would close it, and they are deferred.
Does it hold at enterprise scale?
The largest run so far is 9,430 pages into a 12,936-node graph, on a real corpus rather than a fixture. Enterprise volume is a larger claim and has not been tested.
How does it score on public benchmarks?
The evaluation harness exists and gates every retrieval change against a deterministic golden set, built in-house rather than relying on vendor numbers. LoCoMo and LongMemEval plug into it, and those runs are still to come.
How are permissions handled?
Access and provenance are carried as properties on the graph and evaluated for the requester at query time, so a retrieval is filtered by who is asking and every answer can name where it came from. That is the design as built and tested; it has not been through an external security audit.
Prior art, credited
The in-graph meta-model owes its shape to Jesús Barrasa’s Going Meta work on graph meta-modelling with neosemantics, alongside OMG MOF and W3C RDF/S. The bitemporal layer replicates Graphiti’s documented EntityEdge model. The deterministic validator vendors Neo4j’s MIT-licensed data-modelling core as a build-time library.
The comparison set (Graphiti, Cognee, WorldDB, Rippletide, Graphway’s Adaptive GraphRAG, UMass) was read directly and recorded with source URLs and verbatim excerpts. The contribution here is the combination and the implementation, not the idea of a meta-graph.
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.