Architecture

Knowledge Graph splits cleanly into a control plane and a data plane. Convex never executes Knowledge Graph processing: parsing, chunking, embedding, extraction, and graph writes are CPU and IO-heavy batch work that belongs in a dedicated service, so your workspace’s reactive UI stays responsive no matter how large a corpus you load.

Flow UI

↓

Control plane: Convex

• Source files (VFS)
• Jobs, prefs, budgets
• Ontology draft / publish
• ACL / namespace allow-lists

Data plane: kg-engine

• PARSE / INDEX / EMBED / EXTRACT
• Hybrid, tree-walk, navigate
• MCP server (`/mcp`) + S2S HTTP

↕

FalkorDB (derived KG SSOT, per tenant)

Convex never runs KG processing. It watches jobs and reports status; `kg-engine` owns every parse, chunk, embed, extract, and graph write against FalkorDB.

Why a dedicated engine?

Hot caches (compiled ontology matchers, embedding client pools, per-namespace query plans) are only useful when they stay warm across requests, which is not possible in stateless Convex actions. A dedicated pod also means one service owns every Cypher statement against Falkor, with one test suite, instead of Convex speaking Cypher directly.

Control plane (Convex)

Convex owns everything that is cheap, reactive, and does not require heavy compute:

Responsibility	What it holds
Source files	Your original document bytes on the unified workspace filesystem, plus processing stage metadata
Jobs and registry	The ingest queue, namespace statistics, ingest mode, retrieval preferences, and cost ledger
Ontology	Draft and published ontology JSON, with version hashes
Access control	Namespace allow-lists per agent, and the reactive Flow UI state

Data plane (kg-engine)

kg-engine is a per-tenant, in-cluster service (the same architectural family as workflow-engine) that owns the entire Knowledge Graph data plane: ingestion and retrieval, both. HTTP GET /health stays on the main thread. Lane jobs, service-to-service Falkor routes, finalize apply, and layout I/O run on an I/O worker thread; force-directed settle runs on a serialized layout worker so kubelet probes still get a response while a large graph is catching up. The workflow engine uses the same split: GET /healthz stays on the HTTP thread; Arrow decode for Flow grid pages and sample-data runs on a dedicated worker.

• Ingestion: every processing stage (PARSE, INDEX, EMBED, EXTRACT) runs as an independent, prioritized queue against the engine’s Falkor client. See Processing lanes.
• Retrieval: hybrid search, outline tree-walk, and entity navigation are served both as a Model Context Protocol server for agents and as a plain service-to-service HTTP API for KG Studio and Convex internals. See Retrieval and MCP.
• Watch and report: the engine subscribes to claimed jobs from Convex and reports status back in small, batched mutations, so Convex load from ingest scales with status changes, not with chunk volume.
• Scale: replicas scale on CPU and queue depth; parallelism is engine configuration per stage and per LLM provider rate limit, not a Convex preference cap.

FalkorDB: single source of truth for derived state

Every namespace has one Falkor property graph (kg:{namespace}) 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”: FalkorDB is the single source of truth for everything the pipeline derives from your source files. See Graph overlays for how one graph supports four different retrieval views.

Your original files stay on the workspace filesystem (the source of truth for bytes); FalkorDB holds only what the engine derives from them.

Per-tenant isolation and backup

Each workspace gets its own FalkorDB instance (an in-cluster StatefulSet with a persistent volume) and its own kg-engine deployment. Platform snapshot and restore cover the FalkorDB persistent volume alongside your other tenant volumes, so restoring a snapshot restores your derived graph, chunk text, and vectors together with the rest of your workspace state. If a restore omits that volume, the graph is empty until you re-ingest from your source files, which remain on the workspace filesystem regardless.

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.