Architecture
Knowledge Graph splits cleanly into a control plane and a data plane. Fontana keeps heavy processing (parsing, chunking, embedding, extraction, and graph writes) in a dedicated data plane so your workspace UI stays responsive no matter how large a corpus you load.
- Source files (VFS)
- Jobs, prefs, budgets
- Ontology draft / publish
- ACL / namespace allow-lists
- PARSE / INDEX / EMBED / EXTRACT
- Hybrid search, outline, navigate
- MCP server (`/mcp`) + S2S HTTP
Convex never runs KG processing. It watches jobs and reports status; `kg-engine` owns every parse, chunk, embed, extract, and graph write against FalkorDB.
Control plane
Section titled “Control plane”The control plane owns everything that is reactive and operator-facing:
| Responsibility | What it holds |
|---|---|
| Source files | Your original document bytes on Fontana Files, with each processing step’s record beside them |
| Configuration | Ingest settings per namespace and folder, collections and retrieval preferences, kept under kg in the namespace’s .fontanaconfig.yaml, and the cost ledger |
| Ontology | Draft and published ontology, its evolution policy and review decisions, kept as a file in the namespace |
| Access control | Namespace allow-lists per agent, and the reactive Flow UI state |
Data plane
Section titled “Data plane”The per-workspace Knowledge Graph engine owns ingestion and retrieval:
- Ingestion: every processing step (PARSE, NER, EMBED, RESOLVE, INDEX) keeps its own record per file in the engine’s own store and runs again only when its input changed. There is no queue to lose: a restart picks up from those records. Where the workspace administrator has turned it on, each file’s processing results are also kept in its namespace, so an empty store loads them back instead of processing the files again; otherwise an empty store means one more pass over the files, not lost data. See Processing lanes.
- Retrieval: hybrid search, outline navigation, and entity navigation are available through MCP for agents and through KG Studio in the product UI. See Retrieval and MCP.
- Status: each step keeps one status file per namespace in the engine’s store. KG Studio reads status, parsed documents and extracted graphs from the engine under your read permissions, so status never passes through the control plane.
Derived graph store
Section titled “Derived graph store”Every namespace has one property graph that holds every derived artifact: chunks with provenance and embeddings, the document outline tree, typed entities and relationships, evidence mentions, and vector plus full-text indexes on the same nodes. There is no split between “chunks in one store and entities in another”. See Graph overlays for how one graph supports four different retrieval views.
Your original files stay in Fontana Files (the source of truth for bytes); the graph store holds only what Fontana derives from them.
The namespace keeps the graph’s state
Section titled “The namespace keeps the graph’s state”Once the workspace administrator has moved a namespace’s graph state into its Fontana Files (a one-time step after an upgrade), those files hold everything its graph needs, beside your documents. Until then, the ontology, the agent’s facts and the merges are kept in the graph database only.
| What | Where in the namespace |
|---|---|
| Settings for the namespace, its folders and its collections | kg in .fontanaconfig.yaml |
| Ontology: draft and published schema, evolution policy, accepted and rejected proposals | .fontana/kg/ontology.json |
| Facts, entity types and entity merges the Ontology Agent wrote | .fontana/kg/manual-triples.jsonl |
| Entity merge decisions | .fontana/kg/finalize-decisions.jsonl |
| Entity descriptions | .fontana/kg/entity-notes.jsonl |
| A file’s own settings: title, description, tags, disabled | .fontana/kg/files/<path>.yaml |
| Each file’s processing results: parsed text, entities, embeddings | .fontana/kg/derived/<path>/ |
Every change is written to its file first and to the graph after it: a setting you save in KG Studio, a review decision, a fact or merge an agent writes. When you rename a document, its settings file moves with it; when you delete one, its settings file and processing results go too. Where the workspace administrator has turned it on, processing results are written into the namespace once per processing pass and stay out of the namespace’s version history.
The graph is a copy built from these files. Rebuild graph, a restarted graph store, or a graph that was unloaded loads again from them without a model call: the ontology first, then each file’s processing results, then the agent’s facts and merges in the order they were written, then the merge decisions and the entity descriptions. A file, folder or namespace you disabled stays out of search after the reload.
Graphs load on demand
Section titled “Graphs load on demand”A namespace’s graph loads when something first needs it: a search, an agent’s Knowledge Graph tool, the Graph view in KG Studio, or new documents to process. The first search of a namespace that has not been used recently waits while its graph loads, and later searches answer straight away. A search over many namespaces answers from the graphs that are ready and reports the others as still loading, so an agent can search again a moment later. To keep a namespace’s graph loaded, set kg.resident in its namespace configuration.
Per-workspace isolation and backup
Section titled “Per-workspace isolation and backup”Each workspace has its own graph database and Knowledge Graph engine. Backups and volume snapshots include derived graph data alongside your other workspace volumes, so a restore brings back your graph, chunk text, and vectors together with the rest of your workspace state.
Once a namespace’s graph state has been moved into its Fontana Files and its processing results are kept there too, restoring the namespace’s Fontana Files also brings the graph back: its settings, ontology, the agent’s facts, the merge decisions and the processing results return with the files, and the graph loads from them the first time it is needed. What a restore does not bring back is work in progress, such as merge proposals still waiting to be applied; processing proposes them again. Keep the graph database volume in your backups until your administrator has turned on both.
Namespaces, folders, and documents
Section titled “Namespaces, folders, and documents”Knowledge Graph documents are organised in three levels: a namespace (top-level corpus boundary), a slash-path folder within that namespace, and individual documents addressed by path.
Each agent searches only the namespaces you assign it in Admin → Agents. Retrieval and relationship expansion stay inside those boundaries, which keeps regulated corpora segregated and agent answers focused on the domain you intend.