The knowledge graph (Cortex)

Cortex is Command Center's knowledge layer: a private graph of your documents and the concepts inside them, stored locally on your machine. It is what turns a folder of Markdown files into something agents can navigate — find the right document by topic, walk from a document to the entities it mentions, and answer "how do these things connect" without reading everything.

The headline is the cost model: by default, the graph is built with zero external AI calls. The base layers cost nothing to build and nothing to maintain. Paid semantic search is an opt-in upgrade, not a dependency.

One graph, many workspaces

There is one knowledge graph. A workspace is a lens over it — a named subgraph you build for a purpose: a research corpus, a project's documentation, the knowledge attached to a context artifact. The same file can belong to several workspaces at once without being duplicated; the graph stores one node per file and records its memberships.

One workspace is special: the root workspace, which mirrors your entire documents/ tree automatically. A background sync watches the filesystem and updates the graph as files land — you write a report, and moments later it exists as a node in the graph. You never maintain the mirror by hand.

The three depths

Every workspace is built to one of three depths, and the depth you choose is a cost decision:

Depth is not a label you have to manage — the platform derives it from what the workspace actually contains. A workspace with extracted entities reads as entities; one with vectors reads as full. What you see always reflects reality.

What "ingest" means

Ingesting a document means registering it in the graph — creating its node, linking it into its folder, recording its description. At structure depth that is the whole story, and it is instant and free.

Entity enrichment is a separate, deliberate step. When you choose to enrich a document (or a whole workspace), an agent reads the material and extracts the concepts and relationships in its own reasoning — no external extraction service, no per-token bill. You decide what is worth enriching; the platform never burns budget on it silently. The same rule holds for the background sync that keeps a workspace following its source folder: it mirrors structure and never extracts on its own.

Upgrading a workspace to full depth runs the embedding pipeline over it, which is when the Gemini key comes into play.

When to use which depth

• Stay at structure for most of your workspace. Agents locate documents by name, folder, description, and summary remarkably well — the root workspace runs at structure depth by design.
• Add entities where the connections matter: a research corpus you will ask conceptual questions of, a domain you want mapped, a context artifact's attached graph.
• Go full only for a corpus where phrasing varies enough that meaning-based search genuinely beats graph search — dense technical references, jargon-heavy research. Full is the exception, not the default.

Searching respects the same split: graph search works at every depth, and semantic search works at full depth. Ask a semantic question of a structure-depth workspace and you get a ranked document search instead of an error.

The Cortex view

The Cortex view is where you see and steer all of this: an interactive graph canvas for browsing workspaces, folders, documents, and entities; workspace creation and ingest actions; an entities toggle to reveal a workspace's concept layer; a lint surface that flags structural issues (orphans, stale nodes) for cleanup; and an activity log of what changed in the graph and when. Your agents reach the same graph through their own tools — same graph, two doors — with one deliberate asymmetry, below.

One practical note: the graph runs on a local database engine that the platform provisions and manages for you. If the Doctor view ever reports it unreachable, the graph surfaces pause until it is back — your documents themselves are never affected.

What an agent may do to the graph

Reading is open, by policy. At every depth, in every workspace, an agent can search documents, walk entities, and answer questions from the graph without asking anyone. That is the whole point of building it: the graph describes documents the agent can already open, so gating reads would buy nothing and cost the capability.

Changing it is governed, on two axes. Building and curating the graph is a subscribed capability, and separately, whether agents may mutate it unattended is a switch you hold: Knowledge-graph writes, in Settings ▸ Terminals ▸ Agent control planes. With it off, an agent's mutations are refused while its reads keep answering — so a fleet can still reason over a graph it can no longer edit.

Two details worth carrying, because they are easy to guess wrong:

• What is governed is the write, not a short list of write tools. The general-purpose query tool your agents use is not a read-only surface — a query language expresses deletions as readily as questions — so the platform judges what a statement would do rather than which tool sent it, and treats anything ambiguous as a change.
• Every mutation an agent attempts is written to an audit log, in plain text under documents/knowledge_graph/, whether it was allowed or refused. This matters most for scheduled work: a cleanup routine that removes an abandoned workspace runs while nobody is watching, and the log is how you find out what it removed.

Your own actions in Cortex are not affected by that switch. They reach the graph through a different service than the agent tool does, so curating your own graph never depends on the state of an agent control plane. The wider model — every plane, why they all fail open, and how this differs from a subscription refusal — is on Autonomy and controls.

Where to go next

• Memory layers — where the knowledge graph sits in the wider memory system
• Context artifacts & grounding — attaching a purpose-built graph to an agent session
• Autonomy and controls — the control planes, including knowledge-graph writes
• Knowledge graph infrastructure — the deeper technical reference