Every Fact Cited, Dated and Disputed: Building Nodus on FalkorDB

The question of who owns ledger-service may seem simple, but in most companies, determining the answer can take an entire afternoon. The service catalog may label it as Platform, a design document from last spring may suggest Payments, and a Slack thread from Tuesday may claim Infra now owns Ledger. However, the person who would know left during a recent reorganization, leaving each source partially correct and none providing clear information on when the answer was accurate.

For questions surrounding ownership, accountability, and decision-making, a confident incorrect answer is worse than no answer at all. To address this, a company brain was developed that tracks its sources, leading to the creation of Nodus. Nodus is an organizational knowledge graph built entirely on FalkorDB, enabling it to answer questions such as "who owns this?", "who knows about this?", and "why was this decided?", while providing an exact quote from its source.

Nodus functions using a bi-temporal graph that incorporates people, teams, systems, projects, tickets, documents, chats, and architecture decisions (ADRs). Each fact is represented as a versioned claim with evidence, which becomes an Assertion node pointing to the precise character range of the Span the claim originated from. Each Assertion node contains the following information:

* Valid time: When the claim was true in the real world (valid_from, valid_to)

* Transaction time: When the Nodus learned or retracted the claim (recorded_at, retracted_at)

* Authority: The level of trust in the claim (4 = structured data, 2 = human confirmation, 1 = chat, 0 = drafts)

This structure allows Nodus to answer two distinct historical questions:

1. Who owned Ledger before the reorg? This question pertains to reality.

2. What did we believe about Ledger last month? This question concerns the brain's own state.

Unlike most systems, Nodus can distinguish between these two types of queries. Past events are never deleted, and FalkorDB is the sole datastore utilized for storage, vector search, full-text search, graph algorithms, temporal reasoning, and permission checks.

To address the complexities of the design, Nodus incorporates four key solutions:

1. Full history without slow queries: Nodus maintains complete provenance for each fact through an immutable assertion ledger. This layer is append-only and lists every assertion linked to current edges with their respective validity and authority data. These fast edges allow for quick queries, while the full history remains intact. Operational queries run on the fast layer, fetching citations from the ledger only when necessary.

2. Handling source disagreements: Nodus treats contradiction handling as a first-class rule, rather than an edge case. When a new claim enters the system, it only replaces an old one if its authority is equal to or higher than the existing one. In cases where the authority is lower, the new assertion is recorded as a DISPUTE, and the old one is kept in the ledger as evidence. This allows for visibility into conflicts and facilitates resolution.

3. Graph algorithms at any point in time: Some questions require understanding the overall organization structure, such as identifying the most critical systems or potential single points of failure. FalkorDB offers native GraphBLAS implementations of these algorithms, which can be filtered by node label and relationship types, rather than property predicates evaluated per hop. This enables faster processing of queries related to the organization's shape.

4. Stale-doc detection: Nodus can identify outdated documentation by querying the latest version of each wiki page that still asserts a superseded fact. This is achieved through a single query that checks for any remaining superseded facts and flags outdated documentation accordingly.

By providing an organized, verifiable, and traceable knowledge graph, Nodus offers a reliable solution to the challenges surrounding ownership, accountability, and decision-making within an organization.