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.

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. 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