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 the tree-walk retrieval lane and folder-level pruning. See Retrieval for how a router model walks this tree.

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. This overlay has two provenance methods:

  • 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.
  • llm: the EXTRACT stage reads chunks against your published schema and emits typed relationships (for example Owner -[:HAS]-> Pet), pruning anything off-schema.

Keyword-pass mentions are never promoted to typed relationships automatically: Peter and Mittens can exist as provisional entities from a keyword match long before EXTRACT ever 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. The Document Similarity Graph in KG Studio paints those file nodes and edges: stronger cosine scores become stronger springs. 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 platform snapshot of the namespace’s FalkorDB volume captures all four overlays together, so a restore never leaves lexical search ahead of the domain graph or vice versa.