Persistent memory and context management for Claude Code sessions.
CCCM prevents context window blowout in long, multi-agent Claude Code sessions by automatically snapshotting state before compaction, re-injecting continuity after compaction, tracking file changes, enforcing subagent brevity, and persisting durable project memory.
Zero changes to Claude Code itself. Everything works through native integration points: hooks, CLAUDE.md, and MCP servers.
In multi-agent Claude Code sessions, the context window fills with repetitive agent reasoning, tool outputs, file diffs, and duplicate architectural discussion. When compaction triggers, the summary often drops precision details — exact function signatures, why a decision was made, what was already tried. This causes rework and degraded performance.
| Hook | Fires When | What It Does |
|---|---|---|
SessionStart |
Session begins, resumes, or post-compact | Injects protocol rules; reinjects latest continuity snapshot after compaction |
PreCompact |
Before context compaction | Creates a snapshot and tells Claude exactly what to preserve |
PostToolUse |
After Write/Edit/Bash | Silently tracks which files were touched |
SubagentStart |
Subagent spawned | Per-agent-type brevity rules + memory injection for research agents |
UserPromptSubmit |
User sends a prompt | Injects relevant memory when prompt keywords match stored knowledge |
Stop |
Claude finishes responding | Auto-captures architectural decisions from responses |
Plus an MCP memory server that gives Claude direct access to search, write, and retrieve project memory.
pip install git+https://github.com/pedrommaiaa/cccm.gitOr for development:
git clone https://github.com/pedrommaiaa/cccm.git
cd cccm
pip install -e ".[dev]"cd /path/to/your-project
cccm initThat's it. This single command creates everything CCCM needs:
.cccm/directory with memory docs, config, and snapshots folder.claude/settings.jsonwith all 6 hook registrations.claude/settings.local.jsonwith the MCP memory serverCLAUDE.mdwith compaction instructions (appends to existing file if present)
Initializing CCCM in /path/to/your-project
Setup:
+ Created .cccm/ directory structure (memory, snapshots, config, index)
+ Wrote .claude/settings.json with all 6 hooks
+ Wrote .claude/settings.local.json with cccm-memory MCP server
+ Created CLAUDE.md with CCCM context management sections
All checks passed. CCCM is ready in /path/to/your-project
Run cccm doctor anytime to check health without changing anything, or cccm doctor --fix to re-run the full setup.
Once hooks are installed, CCCM works silently in the background. Start Claude Code normally — CCCM handles the rest:
- Snapshots are created before compaction
- Continuity is re-injected after compaction
- File changes are tracked
- Subagents get brevity rules
- Decisions are auto-captured
- Relevant memory is injected when your prompts match stored knowledge
cccm init # Full setup: dirs, hooks, MCP config, CLAUDE.md
cccm doctor # Health check (diagnose only)
cccm doctor --fix # Re-run full setup (same as init)
cccm snapshot # Force a continuity snapshot
cccm snapshot --show # Snapshot + print content
cccm status # Show tracked files, events, last snapshot
cccm memory # Print all memory docsWhen the MCP server is running, Claude has these tools available:
| Tool | Purpose |
|---|---|
memory_search(query, top_k) |
Keyword search across memory docs and snapshots |
memory_write(doc_type, content) |
Persist knowledge to a memory doc |
memory_latest() |
Get the latest continuity snapshot |
memory_status() |
Check system status |
The real power of CCCM comes from seeding your memory docs. These survive compaction and get injected into research agents automatically.
Record architectural decisions with rationale:
## Database
Chose PostgreSQL because we need JSONB columns and complex joins.
## Auth
Using JWT with refresh tokens. No sessions — must be stateless for horizontal scaling.Hard rules and boundaries:
- Must support Python 3.10+
- No external dependencies in core module
- All API responses under 200ms p95Key contracts and APIs:
## User API
- POST /users — create user (email, name)
- GET /users/:id — returns {id, email, name, created_at}Domain-specific terminology for your project.
CCCM applies different rules based on agent type:
| Agent Type | Output Limit | Gets Memory? | Style |
|---|---|---|---|
Bash |
3 lines | No | Extremely concise |
Explore |
15 lines | Yes | Thorough but structured |
Plan |
15 lines | Yes | Include tradeoffs |
| Other | 8 lines | No | Default structured output |
Override in .cccm/config.json:
{
"agent_budgets": {
"Bash": {
"max_output_lines": 5,
"inject_memory": false
}
}
}{
"snapshot": {
"max_chars_injected": 6000,
"max_snapshot_chars": 25000,
"max_snapshots": 50
},
"tracking": {
"track_decisions": true,
"track_tools": ["Write", "Edit", "MultiEdit", "Bash"]
},
"prompt_inject": {
"max_chars": 2000
},
"agent_budgets": {}
}Hook registrations for Claude Code. See the included file for the full configuration.
MCP server configuration (git-ignored by default):
{
"mcpServers": {
"cccm-memory": {
"command": "python3",
"args": ["-m", "cccm.mcp_server"],
"env": {
"PYTHONPATH": "./src",
"CCCM_PROJECT_ROOT": "."
}
}
}
}src/cccm/
├── __init__.py
├── cli.py # CLI entry point
├── mcp_server.py # MCP memory server (FastMCP)
├── core/
│ ├── memory.py # Memory store, index, config
│ ├── snapshot.py # Continuity packet engine
│ ├── search.py # Keyword-based memory search
│ └── decisions.py # Auto-decision capture
└── hooks/
└── runner.py # Hook event dispatcher (6 events)
.cccm/ # Project-local memory (created per-project)
├── config.json
├── index.json
├── memory/
│ ├── decisions.md
│ ├── constraints.md
│ ├── interfaces.md
│ └── glossary.md
└── snapshots/
tests/ # 99 tests
├── test_memory.py
├── test_snapshot.py
├── test_hooks.py
├── test_v1_hooks.py
├── test_search.py
├── test_decisions.py
├── test_mcp_server.py
└── test_cli.py
# Install with dev dependencies
pip install -e ".[dev]"
# Run tests
pytest
# Run linter
ruff check src/ tests/- Python 3.10+
- Claude Code CLI
- MCP Python SDK (
mcp>=1.0) — installed automatically
MIT