cargo-ai context

• runtime — browse, read, write, edit, and execute against the workspace's runtime sandbox (a checked-out copy of the context repo).

  write

  /

  edit

  are pushed to the default branch;

  execute

  runs are not pushed.
• graph — build/load the knowledge graph derived from every markdown/MDX file in the context repo.

The canonical example of a context repository is

getcargohq/cargo-workspaces

. Read its

README.md

to understand the domain layout and file conventions before writing new entries. For uploading runtime-independent files (CSVs, PDFs) used in batch runs, use

cargo-workspace-management

(

cargo-ai workspaceManagement file upload

) instead. For RAG file attachments to agents, use

cargo-ai

(

cargo-ai content file upload

).

See

references/conventions.md

for the full context repo structure and per-domain templates. See

references/response-shapes.md

for the JSON shapes returned by each

cargo-ai context

command. See

references/troubleshooting.md

for common errors and how to fix them. See

references/examples/authoring.md

for end-to-end add / edit / delete recipes. See

references/examples/lifecycle.md

for the bootstrap + refresh-from-calls playbook. See

references/examples/graph-queries.md

for inspecting the knowledge graph.

• write

  and

  edit

  push to the default branch of the context repo. They are not local-only.

• execute

  does not push. Changes made to files by a shell command run via

  execute

  stay in the sandbox and are discarded — use

  execute

  for builds, tests, or inspection, not for committing edits.

.files/

content file

cargo-content

.files/

execute

read

browse

cargo-ai context runtime execute --command ls --args '["-1",".files"]'

.files/

cargo-ai content file …

write

edit

cargo-ai whoami   # → workspace.uuid, workspace.name

workspace.name

workspace.name

example.com

cargo-ai login --oauth --workspace-uuid <uuid>

--token <workspace-scoped-token>

references/examples/lifecycle.md

• Title: VP of Sales
• Seniority: Executive
• Function: Revenue
• Reports to: CRO or CEO

• New ARR, win rate, pipeline coverage, rep ramp time

• Pipeline gaps, slow ramp, low rep activity, forecasting drift

• Hit the number, build a repeatable motion, get visibility

• medium/linkedin-outbound
• medium/exec-warm-intro

• objection/we-already-have-an-ai-sdr

• Filename:

  kebab-case.md

  (e.g.

  vp-sales-mid-market.md

  ).
• Frontmatter: start every

  .md

  /

  .mdx

  file with YAML frontmatter setting

  title

  and

  description

  . This is a strong convention, not enforced — a write with missing, empty, or malformed frontmatter is still created and committed; it just indexes poorly. The graph reads

  title

  (fallback: filename) and

  summary

  (fallback: the file's first paragraph); it does not read

  description

  , so add a

  summary:

  if you want to control the node summary. See Source references and graph edges.
• Cross-references: use the

  domain/slug

  form, no

  .md

  extension (e.g.

  persona/vp-sales-mid-market

  ). To register as a graph edge a reference must use one of the three link forms below — a bare

  domain/slug

  (or file path) in plain prose creates no edge.
• Templates: each domain ships an

  _template.md

  . Read it (

  cargo-ai context runtime read --path persona/_template.md

  ) before authoring a new entry.

  _template.*

  files are excluded from the graph — never reference them.

.md

.mdx

.yaml

.yml

.git/

1. Frontmatter

   references:

   list (preferred for source citations — keeps prose clean):
   yaml

   ---
   title: AgoraPulse expansion thesis
   description: Why AgoraPulse is ready for a multi-thread expansion play.
   references:
     - outputs/sales-notes/2026-06-05-agorapulse-build-session-1-outcomes.md
   ---

2. A Markdown link in the body — standard

   [label]

   followed immediately by

   (path)

   syntax, where the target is the file path, e.g. an anchor linking to

   outputs/sales-notes/2026-06-05-agorapulse-build-session-1-outcomes.md

   .
3. Wikilinks in the body (extension optional):

   [[outputs/sales-notes/2026-06-05-agorapulse-build-session-1-outcomes]]

   .

• Never cite a source as a bare path in prose (e.g. a

  Source:

  line that just mentions

  outputs/sales-notes/foo.md

  as text) — it is not parsed and creates no edge.
• Prefer root-relative paths (resolved from the repo root first, then relative to the citing file) so links work regardless of where the document lives.
• Extensions are optional — the resolver auto-tries

  .md

  ,

  .mdx

  ,

  .yaml

  ,

  .yml

  in that order. Including the extension is fine.
• The target must exist or the edge is broken (a dead link in the graph UI). Verify with

  runtime browse

  before citing.
• For docs with a Source/Evidence section, cite the files in frontmatter

  references:

  ; use inline markdown links when the citation needs surrounding prose. Full rules:

  references/conventions.md

  .

1. Confirm the target domain and copy its template:
   bash

   cargo-ai context runtime read --path persona/_template.md

2. write

   a new file at

   <domain>/<slug>.md

   with

   title

   +

   description

   and the body sections filled in.
3. Add cross-refs (

   domain/slug

   ) where useful — keep them bidirectional when it makes sense.
4. Rebuild the knowledge graph to verify the new entry and its links:
   bash

   cargo-ai context graph get

references/conventions.md

references/examples/authoring.md

references/examples/lifecycle.md

1. Bootstrap (one-time): seed

   global/

   ,

   persona/

   ,

   client/

   ,

   proof/

   ,

   objection/

   ,

   signal/

   from public sources, then open a fresh agent session against the seeded repo. For the prescriptive, automatable version (domain in → files out, idempotent, with credit budget), use

   references/examples/bootstrap-from-domain.md

   .
2. Refresh (every 2–4 weeks): pull the last ~3 months of sales-call transcripts → analyze one at a time, human-in-the-loop → apply a repetition threshold before promoting any claim to context → validate by generating sequence permutations → diff the graph before/after and retire stale entries.

references/conventions.md

context graph get

• Audit cross-references between domains (e.g. find personas that link to plays with no proof attached).
• Discover what already exists before writing a new entry (avoid duplicates).
• Power downstream agents that need the typed structure of the workspace's context.

cargo-ai context graph get

domain/slug

jq

references/examples/graph-queries.md