How-to

Cortex command guide

How Cortex commands support project memory, handoffs, verification, graph review, and operating evidence.

Public draft for dev reviewLast verified 2026-05-21

Derived from the canonical public Cortex command guide and the current command inventory verified on 2026-05-21.

What Cortex commands are for

Cortex commands make long-running AI work reviewable. They answer specific operating questions: what project and role is active, what work is assigned or blocked, what prior decisions exist, what code areas could be affected, and what evidence supports completion.

  • Use command output as project evidence, not decoration.
  • Prefer prior Cortex memory over guessing from chat history.
  • Escalate release, architecture, or data ambiguity through a consult handoff.

Start and orient

Boot and status commands prepare a worker or operator before work starts. `cortex boot <agent>` loads a compact role and handoff brief, `cortex bootstrap <agent>` loads a fuller project briefing, and `cortex state`, `cortex roster`, `cortex history`, and `cortex tail` help review current project activity.

  • Expected outcome: the operator can see the current lane, recent decisions, and whether there is an actionable handoff.
  • If no handoff is actionable, the correct result is to idle cleanly rather than inventing work.

Search memory

`cortex search`, `cortex graph-search`, and `cortex entities` retrieve durable project memory and knowledge-graph relationships. They help workers cite previous decisions, lessons, documents, and artifacts before changing direction.

  • Use memory search when a claim depends on prior project history.
  • Use graph search when the question is about entities, relationships, or architecture concepts.
  • Use entity browsing when the reviewer needs a named project concept and its related records.

Coordinate work

Handoffs are the normal unit of work. `cortex handoff --mine <agent>` lists lane work, `--show <id>` opens the full packet, `--claim` records ownership, `--create` opens a follow-up or consult, and `--complete` closes the packet after evidence exists.

  • Ownership should be visible before edits begin.
  • Handoff files and verification fields define the safe work boundary.
  • Completion should happen only after tests, screenshots, route checks, or other evidence supports it.

Verify before closing work

`cortex verify` checks claims against project facts. It can verify file existence, matching decisions, function presence, caller relationships, environment variables, and other structured claims where the current project exposes them.

  • A verified claim has supporting evidence.
  • A contradicted claim needs correction before review.
  • An unverifiable claim should not be treated as release-ready.

Review code blast radius

Graph commands help operators understand what a code or architecture change may touch. `cortex graph-blast --target <name>` checks blast radius, `cortex graph-callers` finds callers, `cortex graph-impact` reviews diff risk, and `cortex graph-large-fn` identifies oversized hotspots.

  • Run blast-radius checks before shared-code edits.
  • Treat graph output as a review signal, not as a replacement for reading code.
  • Pair graph evidence with focused tests when implementation changes are made.

Keep memory current

Ingestion and maintenance commands import sessions, artifacts, audio-derived text, markdown memory, embeddings, and knowledge-graph entities. These commands keep future work grounded in current project evidence rather than stale chat context.

  • Maintenance should have an explicit purpose.
  • Material memory or docs-state changes should leave a Cortex decision.
  • Retention, migration, history rebuilds, and workspace syncs are higher-impact operations that need clear authorization.

What good command evidence looks like

Good evidence is concise and repeatable: the command or product action used, the route or claim checked, the result and timestamp, residual risk, and the next action or review gate.

  • Reviewers should be able to trace what changed, why it changed, what was verified, and what still requires human judgment.
  • The command guide explains the evidence shape; the product should eventually surface the same evidence without requiring most users to open a terminal.

Website context

Connect this guide back to the product story

The technology docs map links this page to the public technology narrative and helps buyers move from a capability overview into the right operating guide.

Open technology docs map →