Skip to main content
Glama
Sign In
ccontext

ccontext

by ChesterRa
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

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" }
}

Related MCP server: @vemdev/mcp-server

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)

  1. Start every run

ctx = get_context()  # call first

  1. If missing, set the foundation

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

  1. Keep one milestone active

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

  1. 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"
)

  1. 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

Available Tools

21 tools
add_noteA

Preserve important knowledge for future sessions - lessons, warnings, decisions. TTL decays and auto-archives over time. Recommended tiers: 10=short-term, 30=normal, 100=long-term. Example: 'API rate limit is 100/min - batch requests to avoid throttling'

Inputs: content (required), ttl.

add_referenceA

Bookmark important file paths or URLs for quick navigation. TTL decays over time. Recommended tiers: 10=short-term, 30=normal, 100=long-term. Use for: key source files, API docs, configs. Example: 'src/core/auth.py - OAuth implementation'

Inputs: url (required), note (required), ttl.

clear_statusA

Clear your presence status (remove stale/finished status). Use this when you’re done or after a handoff so old statuses don’t linger and mislead.

Inputs: agent_id (required).

commit_updatesA

Apply multiple updates in ONE call (reduces friction; keeps context current). Input: ops=[{op: ...}, ...] and optional dry_run=true. Supported ops:

  • context.set: vision?, sketch?

  • presence.set: agent_id, status

  • milestone.update: milestone_id, name?, description?, status?, outcomes?

  • milestone.complete: milestone_id, outcomes

  • task.update: task_id, status?, name?, goal?, assignee?, milestone_id?, steps?

  • task.step: task_id, step_id, step_status

  • note.add: content, ttl? (10/30/100 recommended)

  • note.update: note_id, content?, ttl?

  • note.remove: note_id

  • reference.add: url, note, ttl? (10/30/100 recommended)

  • reference.update: reference_id, url?, note?, ttl?

  • reference.remove: reference_id Example ops: [{op:'presence.set',agent_id:'peer-a',status:'Implementing X'},{op:'task.step',task_id:'T001',step_id:'S2',step_status:'done'},{op:'note.add',content:'Found edge case in parser',ttl:50}]

Inputs: ops (required), dry_run.

complete_milestoneA

Close a milestone and record what was accomplished. Outcomes become permanent project history visible to future sessions.

Inputs: outcomes (required), milestone_id (required).

create_milestoneA

Start a new coarse project phase (timeline). Use for 2–6 big stages (e.g., 'Phase 1: Core Implementation'). Exactly one milestone should be active at a time.

Inputs: name (required), description (required), status.

create_taskA

Create a deliverable work item with 3–7 steps. Use for concrete outcomes that span handoffs or need tracking. Prefer linking it to a milestone via milestone_id.

Inputs: goal (required), name (required), steps (required), task_id, +2 more.

delete_taskA

Remove a cancelled or mistaken task. Completed tasks auto-archive after 7 days - no need to delete them.

Inputs: task_id (required).

get_contextA

Read this first or risk repeating work and missing critical decisions. Your execution memory that persists across sessions. Contains: vision (goal), sketch (static blueprint), milestones (phases), tasks (deliverables), notes (lessons), and references (key files). Other agents update this too - check regularly. Returns 'version' for change detection, 'now' for active status, 'diagnostics' (debt score + top issues), and may include 'warnings'/'hints' for suggested actions.

Inputs: no named parameters.

get_presenceA

Get all agents' current status - what they're doing/thinking. Essential for multi-agent coordination. Each agent has: ID, status (natural language), last update time.

Inputs: no named parameters.

list_tasksA

Find tasks by status (planned/active/done) or assignee. Use to see what work exists and check progress across sessions.

Inputs: status, task_id, assignee, include_archived.

remove_milestoneA

Delete a cancelled or mistaken milestone. Completed milestones should be kept as project history.

Inputs: milestone_id (required).

remove_noteA

Delete an obsolete note immediately. Prefer letting low-value notes decay naturally via ttl lifecycle.

Inputs: note_id (required).

remove_referenceA

Delete an obsolete reference immediately. Prefer letting outdated references decay naturally via ttl lifecycle.

Inputs: reference_id (required).

update_milestoneA

Modify milestone details or advance status (pending→active→done). Use to mark phase transitions or adjust phase scope/outcomes.

Inputs: milestone_id (required), name, status, description.

update_my_statusA

Tell other agents what you're doing - they can't see your work otherwise. 1-2 sentences describing your current focus, intent, or blockers. Example: 'Debugging JWT edge case, found timezone issue' or 'Blocked on schema confirmation'.

Inputs: status (required), agent_id (required).

update_noteA

Refresh a note's ttl to prevent decay, or update its content. Use when a note is still valuable but its ttl is getting low.

Inputs: note_id (required), ttl, content.

update_referenceA

Refresh a reference's ttl to prevent decay, or update its details. Use when a reference is still valuable but its ttl is getting low.

Inputs: reference_id (required), ttl, url, note.

update_sketchA

Update the execution blueprint (markdown). Sketch is static: architecture, strategy, constraints, major decisions. Do NOT put TODOs, daily progress, task lists, or milestone status here (use tasks/milestones instead). Recommended sections: ## Architecture, ## Strategy, ## Risks, ## Decisions. Update on: architecture/strategy shifts or major risk changes.

Inputs: sketch (required).

update_taskB

Update task execution state - status/steps/details (and optional milestone link). Keeps progress accurate for handoffs and resumption.

Inputs: task_id (required), goal, name, status, +4 more.

update_visionA

Set or update the project vision - what we're building. This is a short, fixed statement that captures the project goal. Example: 'Build secure SaaS platform for 10K users'

Inputs: vision (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    Claude Code, inside the Godot 4 editorFlockbay puts an AI agent in the real Godot 4 editor: it writes GDScript, runs your game and fixes what breaks. Free, or bring your own Claude Code or Codex.flockbay.comAd

    TDQS

    A4/5.0

    Scored across 21 tools

    Disambiguation5/5

    Each tool targets a distinct entity and action: tasks, milestones, notes, references, presence, and context. The batch tool commit_updates is clearly distinguished as a multi-op alternative to the single-purpose tools, reducing ambiguity.

    Naming Consistency5/5

    All tools follow a consistent verb_noun pattern in snake_case (e.g., list_tasks, create_milestone, add_note, remove_reference). Minor verb variations (add vs create, remove vs delete) correspond to natural language for each entity but maintain the same structure.

    Tool Count4/5

    21 tools is on the higher end but appropriate for the broad scope of project context management (context, tasks, milestones, presence, notes, references). Each tool serves a distinct purpose, though some could theoretically be folded into commit_updates.

    Completeness5/5

    The tool surface covers the full lifecycle of each core domain entity: CRUD for tasks, milestones, notes, and references; presence management; and vision/sketch updates. The batch commit_updates fills any gaps for atomic multi-entity updates, and get_context provides a comprehensive view for resuming work.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Resources

    Related MCP Connectors

    Related MCP Servers

    Appeared in Searches