Knowledge graph

This page is the operating reference for the knowledge graph. For the conceptual tour, start with The knowledge graph (Cortex). Here the mental model gets its full working detail: one graph, built to a depth, searched by two arms — and by default built with zero external AI calls.

One graph, workspaces as lenses

There is exactly one knowledge graph. A workspace is a named lens over it — a subgraph you build for a purpose. The same file is always one node in the graph, carrying a list of the workspaces it belongs to; adding a file to another workspace appends a membership, it never duplicates the node. That single mechanism is why a document can sit in the root mirror, a research workspace, and a context artifact's attached graph at once without three copies drifting apart.

Workspaces come in four kinds:

What is actually in the graph

Two node families and a small set of edge types:

• Folders and documents mirror your filesystem — every directory and file in scope is a node, linked by containment edges. Document nodes carry a description, a summary, an enrichment status, and size metadata.
• Entities are the concepts extracted from documents — people, organizations, technologies, concepts, events, places — linked by mentions edges from the documents that name them and by directed relationship edges between entities. Cross-document reference edges link documents that cite each other.

One entity exists once across the whole graph: if two workspaces extract the same concept, the second extraction adds a workspace membership to the existing entity rather than minting a duplicate.

The three depths — and what each costs

Every workspace is built to one of three depths. The depth you choose is a cost decision, and the platform is explicit about it:

Three operating facts about depth:

• Depth is derived, never declared. A workspace reads as full if vectors exist, as entities if entities exist, otherwise as structure. The badge always reflects what the graph actually holds.
• Structure is a complete state. The root workspace runs at structure depth by design, and agents locate documents remarkably well from names, folders, descriptions, and summaries alone.
• Full is a one-way upgrade. Once a workspace is promoted to full it cannot be quietly downgraded in place — reverting means deleting and recreating the workspace. Reserve full for corpora where meaning-based search genuinely earns its cost.

Ingest, enrichment, and the full pipeline

Three distinct operations put knowledge into the graph, and they are worth keeping separate in your head:

Registering (structure). Ingesting a file at the default depth registers it — creates its document node, links it into its folder, records metadata. No file content is sent anywhere; no model is called. This is instant and free, whether you ingest from the Cortex view, from an agent tool, or simply by letting the root mirror pick the file up.

Enriching (entities). Enrichment is a deliberate second step: an agent — the shipped kg-ingester, the Enrich action in Cortex, or the enrichment routine — reads the document in its own reasoning context and extracts entities (typically 5–30) and relationships (typically 3–40), plus a one-sentence description and a short summary for the document node. Those descriptions and summaries are what power topic search at this depth, so enrichment doubles as discovery indexing. Cost: your agent's attention, no external API.

Vectorizing (full). Promoting a workspace to full runs the embedding pipeline: documents are chunked, embedded with your Gemini key, and indexed for semantic retrieval. This is the only knowledge-graph operation that spends tokens, and it never happens implicitly.

When you build a context artifact's graph, the same three depths appear as the three named choices in the build dialog — structure only, structure + entities, full — and the artifact records which you picked.

Live root sync

The root workspace maintains itself. A sync engine watches your documents/ tree and applies deltas continuously — a new file appears in the graph about a second after it lands on disk, renames and deletions follow, and no model is ever consulted. The Cortex canvas animates these changes live.

You steer the mirror rather than maintain it:

• Root config (the gear in Cortex) controls what the mirror includes: root paths, included extensions, excluded folders, a per-file size cap. A prune action removes anything newly excluded.
• Sync now forces a full reconcile — useful after bulk file moves; the live engine handles the steady state on its own.
• Deleting a filesystem-backed node from the graph alone would be undone by the next sync pass, so the delete action in Cortex moves the underlying file to the OS trash instead — the graph follows the filesystem, never the other way around.

Searching — the two arms

The same graph is read two ways, and the split follows depth:

• Graph search works at every depth: the whole-tree skeleton (a compact overview agents read in a few hundred tokens), topic-based document finding over names, descriptions, and summaries, raw graph queries, neighbor traversal, and a natural-language subgraph answer. This is the default query path for agents and the source of everything the Cortex canvas shows.
• Semantic search works at full depth only, where vectors exist. Asked of a structure- or entities-depth workspace, it degrades to a ranked document search rather than erroring — honest, but not vector retrieval.

What an agent may change

Reading the graph and changing it are governed differently, on purpose.

Reads are open. Every graph query, traversal, skeleton, and document search answers normally — for you and for your agents — and nothing on this page changes that. A refusal you see while reading is not one of the mechanisms below.

A mutation by an agent crosses two gates, in this order. Both are checked before anything is written:

1. The control plane. Settings ▸ Terminals ▸ Agent control planes ▸ Knowledge-graph writes. While it is off, agent mutations are refused with a message naming the switch. It is hot, it defaults to on, and it fails open — if the configuration cannot be read, writes are allowed rather than silently blocked. It is checked first so that a plane you turned off says exactly that, instead of sending you to look at your subscription.
2. Your subscription. Graph curation is a Pro capability. Without it, the mutation is refused with the tier it found and where to upgrade — and the refusal says explicitly that reading is unaffected.

It covers the SQL, not only the write tools. The guard classifies every statement an agent issues rather than trusting which tool it arrived through: a statement is treated as a read only when it starts with a known read verb. Anything else — including a verb the guard has never seen — is treated as a mutation and governed. That direction is deliberate: an unrecognized statement being governed is the safe outcome; an unrecognized statement running ungoverned is not.

Every governed mutation is recorded, allowed or refused, one line each with a timestamp, the operation, the kind of statement, and a bounded excerpt, to:

documents/knowledge_graph/.control/audit.log

It is a plain append-only text file you can read with anything. This is also the plane most likely to be exercised while you are not watching, since scheduled enrichment runs through it.

Your own curation is not affected. Editing in Cortex reaches the graph through the knowledge-base service rather than the agent tool surface, so turning the plane off leaves the view working exactly as before. The general rule — a plane gates whatever shares its enforcement point — and the one plane where that rule cuts the other way are on Autonomy and controls.

Health — lint, report, and the activity log

Cortex carries three analytical surfaces beyond the canvas:

• Lint runs structural health checks: orphaned documents, isolated folders (both fixable directly from the pane), stale entries, singleton entities, and cross-workspace duplicates (flagged for review). Documents that simply have not been enriched yet are not treated as problems — they are a to-enrich queue, not orphans. The cortex-lint and kg-artifact-cleanup routines run the recurring portion on a schedule.
• Report generates a deterministic analysis of the graph — hub nodes, communities, reference cycles, gaps, suggested questions — with no model calls and no mutation.
• Activity is the chronological timeline of graph events: ingests, enrichments, deletions, lint actions. Clicking a subject jumps to the node on the canvas.

Export

Any workspace's graph exports to portable files — a JSON graph plus GraphML — into the kg_exports/ folder under your install root, from the Cortex header or the matching API. This is the hand-off format for outside tooling; inside the product, the graph lives in the database and renders on the canvas.

The engine underneath

The graph is stored in ArcadeDB, an Apache-2.0-licensed multi-model database that Command Center provisions and runs locally for you — no container runtime required, managed from Settings ▸ Database and Dashboard ▸ Platform Health. Vectors for full-depth workspaces live in the same engine.

You can also point the app at an external instance instead, which is the other backend mode. The two modes do not listen on the same graph-protocol port — the ports for each are in the daemon roster, and mixing them up is the usual cause of a connection refused from a database that is running fine. Connection details, backend modes, and the memory ceiling are configuration, not operations — see the configuration reference.

If the engine is unreachable, graph surfaces pause with honest offline states and every graph tool returns a clear error instead of failing silently; your documents themselves are never involved. The Doctor checks include the reachability probe.

Where to go next

• The knowledge graph (Cortex) — the concept page this reference deepens
• Context artifacts & grounding — attaching a purpose-built graph to an agent session
• Memory — where the graph sits among the memory layers