Knowledge Graphs

A knowledge graph is a data structure where entities are nodes, relationships are edges, and both carry typed properties. Unlike a flat table or a document store, a knowledge graph encodes meaning in its structure -- the connections between things are as important as the things themselves.

Tables vs knowledge graphs

The key difference is structure. In a table, the relationship between a person and a company is a foreign key integer. In a graph, it is a typed WorksAt edge that you can traverse, filter, and project over directly.

The compounding effect

Knowledge graphs become more valuable as they grow. Every new entity and relationship creates new traversal paths that didn't exist before. A single Paper node connected to its Author, Concept, and CitedBy edges makes every future query about that author, concept, or citation chain richer without any extra indexing work.

This is the opposite of a document store, where adding more documents makes retrieval noisier unless you rebuild your index strategy.

What agents get from a knowledge graph

• Typed structure -- Agents know what kinds of entities exist and what properties they carry. No guessing field names or data shapes.
• Traversal -- Instead of "find me the row where ID = 42", agents ask "find me everyone who works at the same company as this person." The graph encodes the path.
• Constrained vocabulary -- Enums, types, and annotations prevent agents from writing garbage. A status field that only accepts pending | active | closed catches mistakes at write time.
• Connected context -- A single query can pull a person, their company, their team, and their recent activity. No client-side joins.

Building a knowledge graph incrementally

You don't need to model your entire domain upfront. A practical path:

1. Start with one entity type. Model the thing your agents read most. Give it a @key property and the fields agents need.
2. Add one relationship. Connect that entity to the next most important thing. This edge is your first traversal path.
3. Load real data. Use omnigraph load to bring in existing data. See what breaks, what's missing.
4. Write your first query. A simple one-hop traversal that answers a question you care about.
5. Expand from the edges. Every time you need to answer a new question, check whether you need a new node type, a new edge type, or just a new query over existing structure.

Common query patterns

Context window

Pull everything relevant to an entity in a single query -- the entity itself plus its immediate neighborhood.

query person_context($name: String) {
    match {
        $p: Person { name: $name }
        $p worksAt $c: Company
        $p knows $friend: Person
    }
    return { $p.name, $p.age, $c.name, $friend.name }
}

Gap finder

Find entities that are missing expected relationships.

query people_without_company() {
    match {
        $p: Person
        not { $p worksAt $c }
    }
    return { $p.name }
}

Impact analyzer

Trace multi-hop paths to understand blast radius or influence.

query second_degree_connections($name: String) {
    match {
        $p: Person { name: $name }
        $p knows $f1
        $f1 knows $f2
        $f2 != $p
    }
    return { $f2.name }
}

Comparison with other stores