Context — agent guide

server contextupdated 2026-09-06beta main@0c1777fRaw .mdSource

How an agent connects to the Context MCP, reads the work model, runs the plan → review → done loop, and reports truthfully.

Context — agent guide

1. What it is

Context is the shared workspace for a person's goals and how agents execute them, across every host they use. Work lives as Epics and Issues with human review gates; approvals are decided by the person, never by an agent. The Shared Space works with Google sign-in alone; Private Spaces and the Personal domains (memories, logs, people, health, calendar, skills) exist only after the person pairs their iPhone.

2. Connect

3. First call

Call start_context before anything else (or when the user says "Nomi, get me started"). Read-only. It returns:

4. Vocabulary

Account → Space → Epic → Issue → Artifact. (Graph is a view, not a primitive.)

5. The loop

  1. Plan — interview the user, then create_epic {space, title, goal, issues?}; add work with create_issues {parent_id, issues[]} (title, description, acceptance_criteria[], labels, due_at, blocked_by). Do not assign or pin models at chart time.
  2. Pick up — list_issues {parent_id} (direct children only; pass ready: true for the unblocked frontier), get_issue {issue_id} for criteria, delivery.version and comments. Move it with update_issues {issues: [{issue_id, state: "in_progress", assignee: <your caller label>, expected_version}]}.
  3. Work — narrate with post_comment {target: {kind: "issue", id}, body}. Everything the reviewer must see goes on the Issue: attach_artifact {target, title, mime, content} for text; for binaries pass filename, size, sha256 and follow the returned upload plan.
  4. Hand to the human — update_issues {…state: "in_review"} then request_review {target: {kind: "issue", id}, reason, blocking: true}. The reason is a real summary (≤ 500 chars). Never raise a second request for the same decision.
  5. Wait — get_changes {cursor, waitMs: 25000} is the only event channel. A changes_requested decision puts the Issue back in your hands; read the comment, fix, request review again.
  6. Close — after acceptance, complete_issues {issue_ids, work_stats}. The server refuses the batch without a truthful trace:
{"schemaVersion": 2, "unitId": "<uuid>", "wallDurationSec": 5400,
 "contributors": [
   {"role": "primary", "model": "claude-fable-5-1", "tokensIn": 120000, "tokensOut": 9000,
    "activeDurationSec": 3600, "costUsd": 0.8,
    "skills": [{"name": "rules", "count": 1}], "tools": [{"name": "update_issues", "count": 4}]},
   {"role": "subagent", "agentLabel": "research fork", "model": "claude-sonnet-5",
    "tokensIn": 40000, "tokensOut": 3000, "activeDurationSec": 600, "skills": [], "tools": []}
 ]}

Exactly one primary; every subagent needs agentLabel; activeDurationSec, skills[] and tools[] must be present on every contributor (empty arrays are fine); skills/tools entries are {name, count}; model ids lower-case. Any other contributor field is rejected. Estimate honestly when you lack exact numbers.

6. Rules that bite

7. Skills to load

Skill Role Raw
context how to talk to Context: primitives, vocabulary, which tool when https://agents.onecontext.me/skills/context.md
rules execution discipline: plan → verify → handoff, work_stats https://agents.onecontext.me/skills/rules.md
setup-context chart a job as an Epic with gates (uses wayfinder, grill-me) https://agents.onecontext.me/skills/setup-context.md
daily-brief recurring digest of what changed https://agents.onecontext.me/skills/daily-brief.md

Channel rule: resolve latest (tagged) at session start — https://agents.onecontext.me/channels.json; opt into beta (/skills/<key>@beta.md) only when told to. If the versions you hold differ from the channel, refresh (coding hosts) or finish the work, comment on the Issue, and tell the user to re-download (chat hosts). Record the versions you ran with.

8. Tool map

Links: https://agents.onecontext.me/mcp/context#<tool>.

Stage Tools Notes
Start start_context read-only; call first
Discovery search_context, list_spaces bounded search by words; Spaces you can reach
Epic list_epics, get_epic, create_epic, update_epic, delete_epic delete_epic is destructive
Issue list_issues, get_issue, create_issues, update_issues, complete_issues, delete_issues complete_issues needs work_stats
Conversation post_comment narration, answers, anchored notes on Artifacts
Review request_review, claim_issue, verify_issue the human gate and its evidence
Artifact list_artifacts, get_artifact, attach_artifact, revise_artifact, update_artifact, delete_artifacts, get_artifact_transfer revise_artifact needs expected_revision_id
Changes get_changes, list_mutation_receipts long-poll decisions; audit queued writes
Space (paired) create_space, delete_space private Spaces only
Memories (paired) list_memories, get_memory, save_memories, delete_memories the person's own notes
Logs (paired) list_logs, log_meal, log_workout, delete_logs atomic events; you compute totals
People (paired) list_people, get_person, create_people, update_people, delete_people, merge_people
Health (paired) query_health_samples, summarize_health HealthKit-mirrored
Calendar (paired) list_calendar_events, get_calendar_event
Skills (paired) list_skills, get_skill, save_skill the person's own playbooks — not the catalog above
Content (paired) request_content, get_content_request ask the phone for a resource

Paired groups answer PAIRING_REQUIRED and are omitted from tools/list until the iPhone is paired.

9. Errors and limits