Knowledge Graph

The Knowledge Graph allows you to store, version, and govern the operational knowledge your agents need: firm rules, mappings, approval criteria, exception history, and process documentation. You organise documents in namespaces and folders, assign each agent the corpora they may search, and agents pull approved, versioned context on each turn instead of re-stating the same logic in every chat. Namespace boundaries keep regulated corpora segregated, so retrieval stays least-privilege and focused on the domain you intend.

KG and Skills share the same workspace filesystem explorer in Flow (upload, rename, move, download, drag-and-drop). Knowledge Graph uses an amber accent; Skills uses sky. File bytes live in one classified store; KG processing metadata overlays Knowledge Graph sources.

What is the Knowledge Graph?

A context store for operational knowledge: firm rules, mappings, approvals, exception history, and process documentation. Documents are namespace-scoped with version history; agents retrieve approved context instead of rediscovering logic on every run.

Knowledge Graph

Build a knowledge graph to model your firm's standards, rules, and decisions.

How agents get context

Before each chat or automation turn, Fontana automatically builds context from the Knowledge Graph. It runs vector search over the namespaces you assigned to that agent, ranks documents by similarity to the current message, and injects full text for the best matches above your configured threshold. You do not paste rules or procedures into every prompt; the agent starts each turn with approved, versioned knowledge already in place.

This pre-turn pass is fast, scoped to the corpora you permit, and bounded so only likely-relevant articles enter the thread before the model responds.

Agentic search

Automatic injection covers the strongest matches up front; agentic search lets agents improve results during the work itself. As the task develops, agents can explore the Knowledge Graph again: run semantic searches with vector similarity, inspect ranked summaries and scores, and pull full document text only for hits that support the current step. They can also retrieve exact articles with @slug references when a specific governed document applies.

Exploration stays inside the namespaces and permissions you configured, so agents can deepen context without loading your entire corpus into every conversation.

Storage and graph engine

Knowledge Graph data spans two stores in each workspace:

Layer	Store	Role
Source files	Convex unified filesystem (filesystem_files, scope knowledge-graph) + kg_file_meta	Blobs, processing status, layout, sidecars
Chunk text and provenance	Convex kg_chunks	Parsed text spans and evidence anchors for citations
Evidence mentions	Convex kg_entity_mentions	Quotes linking files to graph nodes (references Falkor entity ids)
Entity and relationship graph	Per-tenant FalkorDB (in-cluster StatefulSet, PVC at /var/lib/falkordb/data)	Open-typed entities, relationships, entity vectors, Cypher traversal
Jobs and registry	Convex kg_jobs, kg_namespace_registry, kg_extraction_runs	Pipeline queue, namespace stats, run history

Flow reads graph topology through Convex actions that query FalkorDB on the server. The browser never connects to Falkor directly.

In-cluster connection: Convex Node actions use the fixed Service DNS redis://falkordb:6379 (hardcoded in Convex; not a ConfigMap or deploy env var). Authentication uses Vault system/FALKORDB_PASSWORD, which convex-deploy sets as Convex env FALKORDB_PASSWORD. Only convex-backend may reach the Falkor Service (NetworkPolicy).

First cutover and restore

After you deploy Falkor-backed KG2, graph topology is not migrated from legacy Convex graph rows. You re-ingest from source files (folder sync or per-file processing). Set ingest mode to manual during cutover, then process namespaces deliberately. Platform snapshot rollback restores the Falkor PVC with other tenant volumes; if that PVC is missing, the graph is empty until you re-ingest.

Embeddings and retrieval

Knowledge Graph documents are embedded through the platform’s active embedding profile (Admin, AI, Embeddings). By default that is the in-cluster Text Embeddings Inference (TEI) service with nomic-ai/nomic-embed-text-v1.5 (768-dimensional vectors), so embedding runs air-gapped without external API calls. You pick provider and model from curated selects (TEI lists only the model shipped on the platform pod; dimension is fixed by that choice). TEI is platform infrastructure on the internal host-bridge; there is no Admin base URL field and no TEI URL env var. You can switch the profile to an external gateway (OpenAI, OpenRouter, LLM API), save, then run Create missing embeddings. That walks every source and enqueues work for gaps; rows whose content hash already matches the active model keep their vectors. The Embeddings panel shows coverage by source (agents, workflows, and knowledge chunks: total, embedded, failed, in progress, with a stacked progress bar and an overall status pill) plus grouped failure reasons when jobs fail.

• Chunk hybrid search (searchKg, automatic pre-turn injection) combines vector similarity on Convex shared per-dimension embedding tables with full-text keyword search on chunk text, fuses both rank lists with Reciprocal Rank Fusion (RRF), then expands results along weighted Falkor relationship edges (multi-hop, decay by hop and edge weight). Chunk vectors on FalkorDB are deferred.
• Entity graph search and traversal use FalkorDB vector indexes and OpenCypher where the pipeline has written entity nodes.

Both automatic pre-turn injection and agentic search use this pipeline. Injection uses the agent’s kbInjectionScoreThreshold (minimum similarity score; default 0.35). Workspace admins tune retrieval globally under Admin → Preferences (full-text toggle, graph expansion hops/decay/min-score/fan-out, RRF constant, and separate token budgets for auto-injection vs the searchKg tool). Chunks that rank well but exceed the token budget appear in the index as [below budget] rather than being injected silently.

What are embeddings?

Dense vector representations of text used for semantic search. Fontana stores Knowledge Graph and workflow-template vectors in shared per-dimension tables selected by the active embedding profile; only title, description, and vectorSource are sent to the embedding provider, not full document bodies.

When you upload or save documents, Fontana parses structured files (CSV, TSV, JSON) and prose (Markdown, text) into governed records, indexes them for search, and builds a relationship graph (entities and edges in FalkorDB) linking cross-references, semantically similar neighbours, and folder structure within each namespace.

Ingest mode

Knowledge Graph default ingest behaviour is automatic: file or folder changes enqueue processing when content hash differs. You can override at global, namespace, folder, or file scope with inherit, manual, or automatic:

Mode	Behaviour
inherit	Use the effective mode from the parent scope (folder → namespace → global)
automatic	Hash changes enqueue processing jobs
manual	Changes update metadata only until you explicitly start processing

In Flow, set ingest mode from the Knowledge Graph home panel, namespace graph header, folder panel, or file panel (Ingest mode picker), or from Knowledge Graph settings (cog) for that scope. Use manual during Falkor cutover so you control when each namespace repopulates the graph.

Platform sources

Beyond uploaded files, Knowledge Graph can index live platform configuration and your own chat history:

Namespace	Source
agents	Agent prompts, tools, skill patterns, and Knowledge Graph allow-lists
tools	Built-in tool catalog
mcp	MCP connection settings (credentials and secrets are never mirrored)
workflows	Workflow definition summaries
threads	Your root AI threads (owner-only in search and browse)
skills	Skills filesystem files via shared metadata (no duplicated blobs)

In Flow, open Knowledge Graph settings on the Knowledge Graph home surface and choose Sync platform sources. Write hooks also refresh mirrors when agents, MCP connections, Skills, or root-thread messages change. Thread mirrors stay private to the owning user; the other platform namespaces follow normal knowledge-graph:read access. Ingest mode (automatic vs manual) still controls whether mirrored files enqueue processing.

Knowledge Graph settings overrides

In Flow, open Knowledge Graph settings from the cog on the home, namespace, folder, or file surface. Ingest mode, chunking model, and extraction model inherit from parent scopes unless you override them. Overridden values appear in yellow, with Use inherited value to clear the local override (same pattern as Preferences).

Processing Status and Queue

In Flow at Knowledge Graph, the Status and Queue tabs show ingestion progress for uploads and folder sync. For each active file you can see pipeline phase (parsing, chunking, embedding, extraction), elapsed time, the approved chunking and extraction models in use, and file size. The explorer sidebar and document card also show a live processing pill (phase, elapsed time, and model) while a file is queued or running. When a worker stalls past the platform limit, the job fails closed with an error on that file so you can re-ingest or restart the queue; silent stuck Running counts without detail are not the intended state.

On Preferences (Global scope, Knowledge Graph section), you can raise or lower how many file jobs run at once (KG max concurrent jobs, default 5), and how many embedding or extraction calls run inside a job. Those controls spend workspace LLM budget, so they are Global-only.

Chunking and entity extraction each use an approved Agent model you configure for Knowledge Graph (global default, with optional namespace, folder, or file overrides per phase). You can set Chunking model and Extraction model independently in Knowledge Graph settings or the header pickers. Most models must advertise structured data output in Admin → Models; Amazon Nova on Bedrock is selectable without that catalog flag because Knowledge Graph uses prompt JSON for Nova (not tool-forced structured output). Model cards in those pickers show a star rating and a short suitability suggestion based on measured schema success, latency, and cost for that phase. Each modelId routes through the same Vault gateway resolution as chat, so Bedrock, Anthropic, OpenRouter, and other approved providers use the matching keys for the selected model.

Ingest cost

After a successful ingest, Flow shows the last-run structured LLM cost for that file (estimated USD and token totals from chunking and extraction calls). Folder, namespace, and full Knowledge Graph panels sum those per-file totals on the fly with paginated Convex reads, so large corpora stay within query limits. Re-ingest replaces the stored last-run cost for that file.

Knowledge Graph Document content types

Structured documents use CSV, TSV, PSV, or JSON. Unstructured prose and Markdown (YAML frontmatter) use text. In Flow on a Knowledge Graph document card, the Content section offers type-aware views: Monaco Raw (syntax highlighted by file type) on every text file, plus Preview for Markdown, Form and Table for JSON, and Table for CSV, TSV, and PSV.

Data type	Usage
Text / Markdown	Unstructured prose and Markdown articles with YAML frontmatter. Preview and Raw editors in the document card.
CSV	Comma-delimited tabular sources. Table and Raw views; parsed for structured agent retrieval.
TSV	Tab-delimited tabular sources. Table and Raw views; parsed for structured agent retrieval.
PSV	Pipe-delimited tabular sources. Table and Raw views; parsed for structured agent retrieval.
JSON	Structured JSON document bodies. Form, Table, and Raw views with schema-aware row editing when the body is tabular.

Manual entities

In Flow at Knowledge Graph, open a namespace and use the Entities list to create, edit, and delete operator-defined entities (name and type required; description optional). Manual entities share the same namespace Falkor graph as entities from extraction: creating an entity whose normalised name already exists merges onto that node and marks it manual. Deleting a manual entity removes the Falkor node and all of its mentions. Manual entities stay on the graph when you re-ingest files, and extraction prompts include a bounded catalog of known entities so the model can reuse them instead of minting duplicates.

Graph exploration in Flow

In Flow at Knowledge Graph, overview and namespace graphs show files as extension-labelled circles sized by file size, with blue namespace bubbles. Entity and relationship topology loads from FalkorDB when Convex signals processing or layout updates (reactive refetch, not a live Falkor subscription). While a large graph pages in, a corner progress bar shows load progress. Hovering a node highlights that node, its neighbours, and their connecting edges in yellow so you can read local structure without dimming the rest of the chart.

Knowledge Graph namespaces

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. In Flow at Knowledge Graph, you create, rename, and delete namespaces from the sidebar. The memory namespace and platform-source namespaces (agents, threads, tools, mcp, workflows, skills) are system-managed and cannot be renamed or deleted. Folders and files support rename and move within a namespace; each document carries version history.

Each agent searches only the namespaces you assign 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.