How do I use ccontext?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@ccontext get the current context and show me what tasks are active" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

ccontext-mcp — Execution Context for AI Agents

English | 中文 | 日本語

Local-first MCP server that gives agents a shared, durable “execution context” across sessions: Vision (why) · Sketch (static blueprint) · Milestones (timeline) · Tasks (deliverables) · Notes/Refs (knowledge) · Presence (who’s doing what).

🧠 Persistent agent memory • 📋 Agent-native task tracking • 🧹 Built-in hygiene (diagnostics + lifecycle) • ⚡ Batch updates (one call) • 🔒 Local files, zero infra

PyPI Python License

🖼️ ccontext at a Glance

Files on disk (portable, git-friendly)

your-project/ └── context/ ├── context.yaml # vision, sketch, milestones, notes, references (+ embedded contract) ├── tasks/ │ ├── T001.yaml # deliverable tasks with steps │ └── T002.yaml ├── presence.yaml # runtime status (recommend gitignore) ├── .ccontext.lock # lock file (recommend gitignore) └── archive/ # auto-archived notes/refs/tasks (optional gitignore)

One call to “load the brain”

get_context() returns version + now + diagnostics so agents can quickly orient:

{ "version": "abc123def456", "now": { "active_milestone": { "id": "M2", "name": "Phase 2", "description": "...", "status": "active" }, "active_tasks": [{ "id": "T001", "name": "Implement auth", "milestone": "M2" }] }, "diagnostics": { "debt_score": 2, "top_issues": [{ "id": "NO_ACTIVE_MILESTONE", "severity": "info", "message": "No active milestone." }] }, "context": { "...": "vision/sketch/milestones/notes/references/tasks_summary" } }

Why ccontext? (Pain → Payoff)

The Pain

Agents forget what they were doing between sessions.
Multi-agent work becomes N² coordination noise without a shared “source of truth”.
Context grows unbounded; old notes become misleading; task state drifts.

The Payoff

Resume instantly: agents always start from the same structured context.
Coordinate cleanly: presence shows who’s doing what; tasks show what’s actually done.
Stay sane: diagnostics highlight context debt; ttl-based lifecycle prevents bloat.

✨ What Makes ccontext Different

🗂️ Local-first, Portable
Context is plain YAML in your repo. No DB, no cloud, no lock-in.

📋 Agent-native Structure
Designed around how agents actually work: vision, blueprint, milestones, tasks, notes.

⚡ Low-friction Updates
commit_updates() batches multiple changes in one call (status + task step + note).

🧹 Context Hygiene
get_context() emits diagnostics + top issues so agents know what to fix.

⏳ Lifecycle Built-in
Notes/refs decay by ttl and auto-archive, keeping context fresh.

👥 Presence That Stays Readable
Presence is normalized (single-line, de-duped) by design.

Core Model (The “Contract”)

Vision: one-sentence north star. Low frequency.
Sketch: static blueprint only (architecture, strategy, constraints, major decisions).
Do not put TODO/progress/task lists here.
Milestones: coarse phases (typically 2–6). Exactly one active at a time.
Tasks: deliverables with 3–7 steps. If work spans handoffs, it belongs in a task.
Notes/References: “things we must not forget” + “where to look”.
Presence: what each agent is doing/thinking right now (keep it short).

This contract is embedded into context.yaml under meta.contract for standalone use.

Installation

Claude Code

# Using uvx (recommended) claude mcp add ccontext -- uvx ccontext-mcp # Or using pipx claude mcp add ccontext -- pipx run ccontext-mcp

Claude Desktop

Add to claude_desktop_config.json:

{ "mcpServers": { "ccontext": { "command": "uvx", "args": ["ccontext-mcp"], "env": { "CCONTEXT_ROOT": "/path/to/your/project" } } } }

Other MCP clients / manual

pip install ccontext-mcp CCONTEXT_ROOT=/path/to/project ccontext-mcp

Root selection: ccontext uses CCONTEXT_ROOT when set; otherwise it uses the current working directory.

Agent Loop (Recommended)

Start every run

ctx = get_context() # call first

If missing, set the foundation

update_vision("Ship a reliable X that achieves Y.") update_sketch("## Architecture\n...\n## Strategy\n...\n## Risks\n...")

Keep one milestone active

create_milestone(name="Phase 1: Foundation", description="...", status="active")

Track real work as tasks

create_task( name="Implement auth", goal="Users can sign in and sessions are validated", steps=[ {"name":"Design", "acceptance":"Spec reviewed"}, {"name":"Implement", "acceptance":"Tests passing"}, {"name":"Rollout", "acceptance":"Docs updated"} ], milestone_id="M1", assignee="peer-a" )

Update with low friction (one call)

commit_updates(ops=[ {"op":"presence.set","agent_id":"peer-a","status":"Auth: implementing session validation; checking edge cases"}, {"op":"task.step","task_id":"T001","step_id":"S2","step_status":"done"}, {"op":"note.add","content":"Edge case: empty header triggers fallback path","ttl":50} ])

Tools

Category	Tool	Purpose
Context	`get_context()`	Call first. Returns `version`, `now`, `diagnostics`, and the full context.
	`commit_updates()`	Batch multiple updates (presence + task progress + notes/refs) in one call.
Vision / Sketch	`update_vision()`	Set the north star.
	`update_sketch()`	Update blueprint (static, no TODO/progress).
Presence	`get_presence()`	See what other agents are doing.
	`update_my_status()`	Update your status (1–2 sentences).
	`clear_status()`	Clear your status (remove stale/finished status).
Milestones	`create_milestone()` / `update_milestone()` / `complete_milestone()` / `remove_milestone()`	Manage coarse phases.
Tasks	`list_tasks()` / `create_task()` / `update_task()` / `delete_task()`	Track deliverables with steps.
Notes / Refs	`add_note()` / `update_note()` / `remove_note()`	Preserve lessons/decisions with ttl lifecycle.
	`add_reference()` / `update_reference()` / `remove_reference()`	Bookmark key files/URLs with ttl lifecycle.

Version Tracking (ETag-style)

Agents can detect change without guessing:

v = get_context()["version"] # ... later ... if get_context()["version"] != v: # someone changed context/tasks ctx = get_context()

Note: version is semantic. It intentionally ignores notes/refs ttl decay so frequent reads don’t churn the hash.

Diagnostics & Lifecycle (Context Hygiene)

Diagnostics: get_context() returns diagnostics (including debt_score and top_issues) so agents can keep the context clean.
TTL-based lifecycle: notes and references decay by 1 each get_context() call and auto-archive when stale, preventing “memory bloat”.
Presence normalization: agent IDs are canonicalized and de-duped; status is normalized to a single concise line for readability.

Git Recommendations

Most teams prefer:

context/presence.yaml context/.ccontext.lock context/archive/

Commit context/context.yaml and context/tasks/ so work survives sessions and can be reviewed.

Works With (and Without) Orchestrators

Standalone: any MCP-capable agent client can use ccontext directly.
Orchestrators: tools like CCCC can read/write the same context/ files for multi-agent runtime UX.
No MCP? You can still read/write the YAML files manually (you just won’t get MCP ergonomics like batch updates and diagnostics).

License

MIT

ccontext