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
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)
get_context() returns version + now + diagnostics so agents can quickly orient:
- 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.
- 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.
|
🗂️ Local-first, Portable 📋 Agent-native Structure ⚡ Low-friction Updates |
🧹 Context Hygiene ⏳ Lifecycle Built-in 👥 Presence That Stays Readable |
- 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.
# Using uvx (recommended)
claude mcp add ccontext -- uvx ccontext-mcp
# Or using pipx
claude mcp add ccontext -- pipx run ccontext-mcpAdd to claude_desktop_config.json:
{
"mcpServers": {
"ccontext": {
"command": "uvx",
"args": ["ccontext-mcp"],
"env": { "CCONTEXT_ROOT": "/path/to/your/project" }
}
}
}pip install ccontext-mcp
CCONTEXT_ROOT=/path/to/project ccontext-mcpRoot selection: ccontext uses CCONTEXT_ROOT when set; otherwise it uses the current working directory.
- 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}
])| 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. |
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:
get_context()returnsdiagnostics(includingdebt_scoreandtop_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.
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.
- 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).
MIT
{ "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" } }