Skip to content
Back to

Graph overlays

Fontana Knowledge Graph is one Falkor property graph per namespace (kg:{namespace}), not four separate stores stitched together. Every retrieval lane reads the overlay (or combination of overlays) it needs from that single graph.

Lexical overlay

Section titled “Lexical overlay”

The lexical overlay treats a document as text units in reading order: Chunk nodes connected by PART_OF (chunk to source file) and NEXT_CHUNK (chunk to chunk), each with full-text indexes. This overlay powers keyword and BM25-style search, citation hydration, and neighborhood expansion (pulling the chunk before or after a match for extra context). It becomes queryable at INDEX, with no LLM call.

Structural overlay (PageIndex)

Section titled “Structural overlay (PageIndex)”

The structural overlay treats a document as a hierarchy of sections: an OutlineNode tree connected by CHILD_OF, with each node covering one or more chunks. Fontana builds this outline directly from the parsed document’s typed heading blocks (not regex over markdown), so headings carry stable anchors that become citation targets. This overlay powers outline navigation and the section trail on every citation: an agent lists a file’s sections, opens one by its key, and hops to its parent, siblings, or children. See Retrieval for how agents move through it.

Domain overlay (semantic, typed)

Section titled “Domain overlay (semantic, typed)”

The domain overlay is an ontology-typed world model: Entity nodes connected by typed REL edges, evidenced by MENTIONS edges from the chunks that support them. Every mention records how it was found:

  • keyword: the INDEX stage’s ontology gazetteer matches published entity and alias surface forms in chunk text and creates provisional entities and mentions, with no LLM call. A keyword match always wins over NER for the same text.
  • ner: the NER stage runs named-entity recognition over the prose of each file (never over tables or code) and creates provisional typed entities, such as people, organisations, places, products, laws and events, with a mention in every chunk that names them. Low-confidence entities stay untyped with the proposed type as a hint.
  • module: tables yield entities from their headers and cells, and code yields definitions and imports from its syntax tree.
  • llm: the Ontology Agent reads chunks against your published schema and emits typed relationships (for example Owner -[:HAS]-> Pet), pruning anything off-schema.

The NER stage also links entities that often share a sentence in the same file with CO_OCCURS_WITH edges, weighted by pointwise mutual information and kept only for each entity’s strongest partners. Like a relationship, a co-occurrence edge records the file it came from, so it is only shown to someone who can read that file.

Keyword and NER mentions are never promoted to typed relationships automatically: Peter and Mittens can exist as provisional entities from a keyword match long before the Ontology Agent confirms Peter -[:HAS]-> Mittens. This overlay powers entity-seeded navigation and weighted relationship expansion.

Vector overlay (semantic, dense)

Section titled “Vector overlay (semantic, dense)”

The vector overlay adds embedding properties on Chunk, Entity, and FileRef nodes. Chunk and entity embeddings power hybrid search and entity merge candidates. During EMBED, Fontana also writes one whole-file embedding per FileRef (the concatenated document, windowed and pooled when it exceeds the model length) and SIMILAR_TO edges between files whose embeddings are close. In KG Studio, switch on Files and Similarity to draw those links between files, labelled with their score; in the force graph, stronger scores pull harder. Vector similarity never writes a typed REL directly: SIMILAR_TO is a similarity signal, not an ontology fact.

Why overlays, not separate databases

Section titled “Why overlays, not separate databases”

Every overlay lives on the same nodes and edges in the same Falkor graph, which gives you three properties that a split architecture cannot:

  • Consistent identity: an Entity node found through a keyword mention, an LLM-extracted relationship, and a vector similarity match is the same graph node, so you never reconcile three different identifiers for “ESMA.”
  • Cross-overlay fusion: hybrid search runs full-text, vector, and 1-hop relationship expansion against the same Falkor graph, then fuses ranked hits with Reciprocal Rank Fusion. You do not join across separate search services.
  • One backup, one restore: a volume snapshot of the workspace’s graph database captures all four overlays together, so a restore never leaves lexical search ahead of the domain graph or vice versa.