common-context-mcp
A shared, file-backed context store that lets many AI agents hand off work, avoid each other's collisions, and recover from crashes — all over MCP.
Start a session with
load_context(brief by default, orfullfor the entire store) to pick up other agents' work, recent sessions and known failures.Checkpoint progress with
save_context— store a fact/decision/config under a key, with tags; overwrites preserve history.Close out work with
save_summary— title, what was accomplished, learned, decisions and next steps; marks the session complete.Learn from mistakes via
save_failure(what was tried, why it failed) andrecord_success(approaches to prefer).Search everything —
search_contextdoes case-insensitive keyword search across contexts, sessions, failures and broadcasts, returning excerpts with IDs.Avoid edit collisions —
claim_areaa file/area before editing (auto-expires),release_areawhen done,list_claimsto see active claims.Coordinate across agents —
broadcasta decision/message to all agents, orhandoffwork to another agent with a summary and full context.Inspect learned behavior with
get_patterns(what works vs. fails, with counts) andget_audit_trail(recent sessions, failures, claims).Recover interrupted work —
resume_sessiontakes over a stale session (refusing completed or live ones), andsession_statusreports store size, counts, interrupted sessions and estimated token cost.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@common-context-mcp checkpoint my progress and hand off the auth refactor to the next agent"
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.
common-context-mcp
🧠 common-context-mcp
Shared, append-only context store for AI agents — over the Model Context Protocol (MCP).
Agents checkpoint their work, record failures, claim files, hand off tasks, and recover after crashes — so the next agent starts exactly where the last one stopped.
common context MCP (also published as common-context-mcp) gives every agent on your machine one shared memory file — one common context that Claude Code, Codex, Cursor, Gemini, OpenCode, Kilo Code, Cline, Goose, Freebuff, Hermes Agent, Muse, Qwen Code, Zed, Windsurf and Kiro all read and write.
📦 npm: npm install -g common-context-mcp · 💻 GitHub: Gokulanand-art/common-context-mcp
Built by Gokulanand · Agent Orchestration · Knowledge & Memory · Developer Tools
🎬 See it in action
Add your own demo GIF below — record a terminal session with
asciinemaorttygif, save it asdocs/demo.gif, and uncomment the line:
Related MCP server: Casefile
🚀 Quick start
1. Install
npm install -g common-context-mcp
ccmccm is the one command: it opens the Google login page first (required — the cloud stores your context), then back in the terminal it sets up every AI tool it finds (Claude Code, Codex, Cursor, Gemini, OpenCode, Kilo Code, Cline, Goose, Freebuff, Hermes Agent, Muse, Qwen Code, Zed, Windsurf, Kiro) and finishes. To remove everything again later: common-context-mcp-setup --uninstall (backups are kept).
Note:
ccmis also the name of Cassandra Cluster Manager. If you have that installed, whicheverccmcomes first on your PATH wins — runwhich ccmto check, and use the fullcommon-context-mcpcommand (same options, except bare invocation starts the server) if they collide.
2. Use it in any project
Your agents talk to the store through MCP tools (the protocol below keeps them honest). You only need the CLI for health and sync:
ccm login # sign in with Google for Drive sync (opens the browser)
ccm logout # sign out (revokes and removes stored tokens)
ccm doctor # environment and store health
ccm status # Google Drive login/sync state
ccm sync # pull remote changes, then push
ccm --upgrade # upgrade the package, then re-run setupWhat an agent does in a session:
load_contextfirst — loads what the team already knowssave_contextafter each meaningful step — the checkpointsave_failure, thensearch_context— the moment something breaksclaim_area/release_area— around edits to shared filessave_context, thensave_summary— before the final answerOn a greeting with no task — brief what's in progress and next, ask what's on their mind
⚡ The protocol (mandatory, every message)
The server sends these instructions to every connected agent. Follow them in order:
# | Step | Tool | Why |
1 | Load first |
| Before any other tool or reply — starts your session |
2 | Checkpoint |
| After every meaningful step — this is your save point |
3 | Record failures |
| Immediately on error, then search before any alternative |
4 | Claim files |
| Before/after editing a shared file — avoids collisions |
5 | Summarize |
| Before your final answer — marks the session complete |
6 | Greet |
| On a greeting with no task — brief in-progress work and next steps, ask what's on their mind |
🛠️ Tools reference
Tool | Purpose | Read-only |
| Start a session; load shared state, recent sessions, failures, interrupted work | |
| Save a fact/decision/config under a key ( | |
| Close session with title, accomplished, learned, decisions, next steps (title auto-derived when omitted) | |
| Record a failed approach and why, so future agents see it | |
| Record an approach that worked, so it's preferred next time | |
| Case-insensitive search across contexts, sessions, failures, broadcasts | ✓ |
| Claim a file/area so others avoid it (auto-expires) | |
| Release a claimed area | |
| List all currently active (unexpired) area claims | ✓ |
| Send a decision or message to all agents | |
| Transfer work to another agent with full context | |
| Learned patterns: what works and what fails, with counts | ✓ |
| Recent sessions, failures, claims — most recent first | ✓ |
| Take over an interrupted session (refuses completed/live ones) | |
| Store health: size, counts, interrupted sessions, estimated tokens | ✓ |
| Google Drive sync status (login, token, oauth config, this project's remote) | ✓ |
| Force sync with Google Drive: merge remote changes in, then push local |
Every tool except
load_contextandsearch_contextrequiresload_contextto have run first in that session.
🤖 Supported agents
Agent | Config written to | Protocol block | Enforcement |
Claude Code |
|
|
|
Codex CLI |
|
|
|
Cursor |
| Manual paste from setup |
|
Gemini CLI |
|
|
|
OpenCode |
|
| Plugin at |
Kilo Code |
| protocol file added to its | Rules only |
Cline |
|
| Rules only |
Goose |
|
| Rules only |
Freebuff |
|
| Rules only |
Hermes Agent |
|
| Rules only |
Muse |
|
| Skill + hooks |
Qwen Code |
|
| Rules only |
Zed |
| Manual paste into the project's | Rules only |
Windsurf |
|
| Rules only |
Kiro |
|
| Rules only |
Aider | Not configured: Aider has no MCP client | none | none |
Kilo Code, Cline, Goose, Freebuff, Hermes Agent, Qwen Code, Zed, Windsurf and Kiro do not have hooks yet, so for them the protocol is advice the model follows, not a gate. A kilo.jsonc with comments is refused rather than rewritten: add the server by hand in that case. Freebuff shares Codebuff's MCP loader; its paths come from the Codebuff source and were not run against a live Freebuff session.
Text outside the managed block is never touched; reruns replace only that block.
⚙️ Configuration
Variable | Default | Meaning |
| working directory | Project folder; its store is |
|
| Store file, overriding the project folder |
| random per process | Stable agent identity (e.g. |
| git origin, else folder hash | Drive sync identity: same project on every machine must resolve to the same id |
|
| Idle time before a session is marked dead |
|
| Claim lifetime without renewal |
|
| Cap on any single tool response |
|
| Max chars the brief |
|
| Completed sessions kept; older ones move to archive |
|
| Completed sessions older than this move to archive |
|
|
|
|
|
|
| unset | Skip setup prompt after global install |
| unset | Skip enforcement hooks for every tool that has them (Claude Code, Codex, Cursor, Gemini, OpenCode, Muse) in |
| (from ~/.aura/google-oauth.env) | Google OAuth client ID (Desktop app type) |
| (from ~/.aura/google-oauth.env) | Google OAuth client secret |
| unset | Set to |
🔄 Multi-agent behaviour
Heartbeats. Each write refreshes its session's heartbeat. When an agent calls
load_context, any session whose heartbeat is older thanCONTEXT_MCP_STALE_MINUTESis markedinterrupted. Sessions still heartbeating are listed as active elsewhere.Claims. A claim blocks other agents until it expires or is released. Expired claims are removed on the next
load_context.Resuming.
resume_sessionrefuses completed sessions and sessions another live agent is heartbeating — two agents can't drive the same session.
If a task involves long silent stretches, call save_context or session_status periodically, or raise CONTEXT_MCP_STALE_MINUTES.
☁️ Google Drive sync (optional, cross-machine)
Sign in with a Google account to sync each project's common-context.json with your Drive's hidden app folder, so the same context is available on every machine.
ccm login # opens Google consent in your browser
ccm status # shows login/token/sync state
ccm sync # force pull + push now
ccm logout # revokes the token with Google, removes local tokenslogin needs a Google OAuth client: set GOOGLE_CLIENT_ID/GOOGLE_CLIENT_SECRET, or put them in ~/.config/common-context-mcp/oauth.env. logout revokes the token server-side when reachable, and always clears the local token file — even offline.
Creating the OAuth client (one time, about 2 minutes): open console.cloud.google.com/apis/credentials → Create Credentials → OAuth client ID → Application type: Desktop app → copy the Client ID and Client secret into ~/.config/common-context-mcp/oauth.env as above, then run ccm again. No redirect URIs to configure (Desktop apps may use the local loopback). To skip login entirely and stay local-only: ccm --local.
Scope is
drive.appdataonly (a hidden app folder; counts toward your 15 GB, nothing lands in My Drive).Login is part of first setup (
ccmasks for it before anything else), because the cloud stores your context. After that everything also works offline from the local copy: while logged in, every write uploads in the background (within about half a second), andload_contextpulls and merges remote changes so work continues from the cloud copy. Right afterlogin, the current local file is stored to the cloud at once.An upload that fails (e.g. offline) stays queued, and the running server retries it quietly about once a minute until it lands. Hook-only writes (failure records) ride along with the next upload rather than pushing themselves.
Each project gets its own remote file (
common-context--<project>.json), so projects never overwrite each other. The identity isCONTEXT_MCP_SYNC_IDwhen set, else the git origin URL, else a hash of the folder. If you check out the same non-git project at different paths on different machines, setCONTEXT_MCP_SYNC_IDto the same value on all of them.Sync state lives in
<store>.sync.jsonnext to the store (last remote version seen, last push hash). It is advisory: deleting it just causes one redundant sync.Conflict strategy: union merge, nothing is deleted. Contexts resolve per key by latest
updated(the losing value is kept in history); sessions union by id (a completed session is never resurrected by a stale copy; an id collision between different sessions keeps both); failures, broadcasts and patterns are unioned.A push never clobbers a remote that changed since the last sync: the remote is merged first, then the union is uploaded.
An unreadable remote is backed up to
<store>.remote-backup-<timestamp>and overwritten on the next push. A remote from a newer schema version is never overwritten — upgrade instead.All machines must use the same Google OAuth client ID: the app folder is per-client, so different client IDs cannot see each other's files.
OAuth client credentials are read from
GOOGLE_CLIENT_ID/GOOGLE_CLIENT_SECRET(orAURA_*) env vars, or~/.aura/google-oauth.env/~/.config/common-context-mcp/oauth.env.
Two extra MCP tools: sync_status (read-only) and sync_now.
💾 Storage & safety
File. One JSON file (
common-context.jsonper project folder). Writes go to a temp file and are renamed into place — a crash never leaves a half-written store.Locking. Mutations run under
<store>.lock(exclusive create). A lock older than 10 seconds is treated as crash-left-behind and removed.Corruption. An unreadable store is copied to
<store>.corrupt-<timestamp>before a fresh store starts. Nothing is silently discarded.Schema. Schema v2 is current. Older v1 stores upgrade on first write. A newer schema is refused rather than overwritten.
Permissions. File created with mode
0600.Growth. Nothing is deleted.
load_contextshows recent items; older ones are reachable viasearch_contextandget_audit_trail.session_statuswarns when the store is large.Secrets. The store is plain text — do not save credentials or tokens with
save_context.
🩺 Health check
ccm doctorChecks Node version, binary on PATH, store writability, read/lock capability, interrupted sessions, and agent registration. Exits non-zero if anything's broken. Also reports Google sync state (login freshness, remote reachability) as advisory warnings that never fail.
ccm doctor --tokensShows estimated token cost of each part agents see every session.
🛠️ Development
npm install # install dependencies
npm run build # compile src/ to dist/
npm run typecheck # TypeScript strict check
npm test # build, then run the test suiteCI runs on Node 18, 20, 22, 24 (ubuntu + macOS). The suite covers cross-process locking with real concurrent processes, corruption and schema handling, the full MCP tool surface over stdio, and the installer against a temporary HOME.
🤝 Contributing
Contributions are welcome!
Fork the repo and create a feature branch from
mainAdd or update tests for any behavior change
Run
npm testandnpm run typecheckOpen a pull request describing what changed and why
See CHANGELOG.md for release history and LICENSE for the MIT license.
🔗 Related
Resource | Link |
common-context-mcp on Glama | https://glama.ai/mcp/servers/Gokulanand-art/common-context-mcp |
common-context-mcp on npm | |
Gokulanand-art on GitHub |
Built and maintained by Gokulanand.
If this helps your agents stay in sync, ⭐ star the repo — it helps others discover it.
License
Available Tools
15 toolsbroadcastB
Broadcast a decision/message to all agents.
Inputs: message (required).
claim_areaA
Claim a file or area so other agents avoid it. Expires after CONTEXT_MCP_CLAIM_MINUTES (default 30).
Inputs: area (required).
get_audit_trailARead-only
Get the audit trail of sessions, failures and claims (most recent first, capped).
Inputs: no named parameters.
get_patternsBRead-only
Get learned patterns (what works and what fails).
Inputs: no named parameters.
handoffA
Transfer work to another agent with full context. Records a completed handoff session and a broadcast.
Inputs: context (required), summary (required), to_agent (required).
list_claimsARead-only
List all currently active (unexpired) area claims.
Inputs: no named parameters.
load_contextA
Start a session and load shared context: other agents' work, recent sessions, failures to avoid. Brief by default.
Inputs: detail.
record_successA
Record an approach that worked, so future agents prefer it.
Inputs: approach (required).
release_areaB
Release a claimed area.
Inputs: area (required).
resume_sessionA
Take over an interrupted session under this agent. Refuses completed sessions and ones another live agent is using.
Inputs: session_id (required).
save_contextA
Save a fact, decision or config under a key. This is the checkpoint. Overwriting keeps the old value in history.
Inputs: key (required), value (required), tags.
save_failureB
Record a failed approach IMMEDIATELY when something doesn't work.
Inputs: approach (required), why_failed (required).
save_summaryA
Save session summary at end of work. MANDATORY before giving final response. Marks session as complete.
Inputs: title (required), accomplished (required), learned, decisions, +1 more.
search_contextARead-only
Search shared context by keyword. Returns short excerpts with ids; use get_audit_trail or load_context detail "full" for more.
Inputs: query (required), limit.
session_statusBRead-only
Store health: size, counts, interrupted sessions, estimated tokens of context.
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 15 tools
Most tools map to a distinct resource+action, but the write-side has several similar-sounding verbs (save_context, save_summary, save_failure, record_success, broadcast) that require careful reading of descriptions to separate. The read side (load_context, search_context, get_patterns, get_audit_trail, session_status) is mostly clear, though load_context vs resume_session could be confused at a glance.
Strong verb_noun convention dominates (load_context, save_context, claim_area, release_area, get_patterns, get_audit_trail). A few outliers break the pattern: broadcast, handoff, and session_status use bare verbs or noun phrases instead of verb_noun.
15 tools sits at the top of the healthy range and each one maps to a real coordination concern (session lifecycle, memory, claims, handoff, audit). No tool appears redundant or filler.
The surface covers session lifecycle, persistence (facts/failures/successes), search, claims, broadcast, handoff and audit, which is solid for a shared-context server. Minor gaps: no delete/forget/expire operation for saved context, no bulk listing of keys, and no explicit force-release for stale claims.
Maintenance
Related MCP Connectors
Shared project context for AI agents and teams: docs, tasks, and messages that stay current.
Durable agent-to-agent handoffs and shared scratchpad for multi-agent workflows.
A shared, governed brain for AI agents: versioned context with approvals, local or hosted.
Shared, versioned context that humans and AI agents can publish, review, annotate, and continue.
Related MCP Servers
- FlicenseNot gradedqualityBmaintenanceEnables AI agents to share a local, searchable context store with summary-first reads, so a new agent can resume a long-running task at a flat token cost without re-reading prior history.1-
- AlicenseAqualityBmaintenanceSelf-hosted task tracker and MCP server for AI coding agents. Append-only case files preserve decisions, failed attempts, questions, and check results across sessions. A live web board lets people track progress and answer agents. Runs locally in Docker and connects to Claude Code, Codex, Cursor, and other Streamable HTTP MCP clients. MIT licensed.306MIT
- AlicenseBqualityBmaintenanceEnables multiple AI coding agents and humans to coordinate through a Git-native Markdown blackboard (.context/ + AGENTS.md), where they can inspect workspace overviews, claim and toggle ready tasks, record architecture decisions, synthesize shared prompts, and hand off work via atomic, lock-protected writes that prevent lost updates and formatting drift. It also serves a fully offline local web dashboard that live-syncs any blackboard change over WebSocket.71MIT
- AlicenseNot gradedqualityAmaintenanceEnables AI coding assistants to persist and restore context across sessions, preserving decisions, progress, files, and checkpoints. It supports topic-based channels, search, change tracking, git-aware correlation, batch operations, and shared memory across parallel sessions.195 npmMIT