ccr-memory 0.2.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- ccr_memory-0.2.0/PKG-INFO +278 -0
- ccr_memory-0.2.0/README.md +232 -0
- ccr_memory-0.2.0/ccr/__init__.py +46 -0
- ccr_memory-0.2.0/ccr/ace/__init__.py +1 -0
- ccr_memory-0.2.0/ccr/ace/agents.py +308 -0
- ccr_memory-0.2.0/ccr/ace/engine.py +404 -0
- ccr_memory-0.2.0/ccr/ace/playbook.py +1645 -0
- ccr_memory-0.2.0/ccr/ace/prompts.py +242 -0
- ccr_memory-0.2.0/ccr/cli.py +867 -0
- ccr_memory-0.2.0/ccr/context/__init__.py +0 -0
- ccr_memory-0.2.0/ccr/context/embeddings.py +233 -0
- ccr_memory-0.2.0/ccr/context/indexer.py +1020 -0
- ccr_memory-0.2.0/ccr/context/packer.py +220 -0
- ccr_memory-0.2.0/ccr/context/prompts.py +133 -0
- ccr_memory-0.2.0/ccr/context/vec_store.py +212 -0
- ccr_memory-0.2.0/ccr/core/__init__.py +0 -0
- ccr_memory-0.2.0/ccr/core/engine.py +453 -0
- ccr_memory-0.2.0/ccr/core/exceptions.py +124 -0
- ccr_memory-0.2.0/ccr/core/hooks.py +122 -0
- ccr_memory-0.2.0/ccr/core/memory.py +67 -0
- ccr_memory-0.2.0/ccr/core/memory_pkg/__init__.py +55 -0
- ccr_memory-0.2.0/ccr/core/memory_pkg/memory_admission.py +418 -0
- ccr_memory-0.2.0/ccr/core/memory_pkg/memory_branch_ops.py +265 -0
- ccr_memory-0.2.0/ccr/core/memory_pkg/memory_commit.py +568 -0
- ccr_memory-0.2.0/ccr/core/memory_pkg/memory_consolidation.py +590 -0
- ccr_memory-0.2.0/ccr/core/memory_pkg/memory_context.py +467 -0
- ccr_memory-0.2.0/ccr/core/memory_pkg/memory_discussions.py +264 -0
- ccr_memory-0.2.0/ccr/core/memory_pkg/memory_embeddings.py +120 -0
- ccr_memory-0.2.0/ccr/core/memory_pkg/memory_evolution.py +189 -0
- ccr_memory-0.2.0/ccr/core/memory_pkg/memory_experiments.py +330 -0
- ccr_memory-0.2.0/ccr/core/memory_pkg/memory_file_io.py +147 -0
- ccr_memory-0.2.0/ccr/core/memory_pkg/memory_init.py +154 -0
- ccr_memory-0.2.0/ccr/core/memory_pkg/memory_links.py +898 -0
- ccr_memory-0.2.0/ccr/core/memory_pkg/memory_ota.py +99 -0
- ccr_memory-0.2.0/ccr/core/memory_pkg/memory_patterns.py +394 -0
- ccr_memory-0.2.0/ccr/core/memory_pkg/memory_registry.py +194 -0
- ccr_memory-0.2.0/ccr/core/memory_pkg/memory_rolling_summary.py +217 -0
- ccr_memory-0.2.0/ccr/core/memory_pkg/memory_types.py +136 -0
- ccr_memory-0.2.0/ccr/core/router.py +206 -0
- ccr_memory-0.2.0/ccr/core/scratchpad.py +198 -0
- ccr_memory-0.2.0/ccr/core/session_store.py +387 -0
- ccr_memory-0.2.0/ccr/core/triples.py +233 -0
- ccr_memory-0.2.0/ccr/core/types.py +650 -0
- ccr_memory-0.2.0/ccr/gateway.py +289 -0
- ccr_memory-0.2.0/ccr/hooks/__init__.py +0 -0
- ccr_memory-0.2.0/ccr/hooks/on_compact.py +55 -0
- ccr_memory-0.2.0/ccr/hooks/on_session_end.py +31 -0
- ccr_memory-0.2.0/ccr/hooks/on_session_start.py +272 -0
- ccr_memory-0.2.0/ccr/hooks/on_stop.py +319 -0
- ccr_memory-0.2.0/ccr/hooks/on_tool_use.py +92 -0
- ccr_memory-0.2.0/ccr/hooks/state_accumulator.py +135 -0
- ccr_memory-0.2.0/ccr/mcp/__init__.py +14 -0
- ccr_memory-0.2.0/ccr/mcp/ace_tools.py +1638 -0
- ccr_memory-0.2.0/ccr/mcp/audit.py +65 -0
- ccr_memory-0.2.0/ccr/mcp/gcc_tools.py +1265 -0
- ccr_memory-0.2.0/ccr/mcp/index_tools.py +324 -0
- ccr_memory-0.2.0/ccr/mcp/rlm_tools.py +393 -0
- ccr_memory-0.2.0/ccr/mcp/server.py +448 -0
- ccr_memory-0.2.0/ccr/mcp/session_tools.py +255 -0
- ccr_memory-0.2.0/ccr/mcp_server.py +173 -0
- ccr_memory-0.2.0/ccr/mcp_types.py +267 -0
- ccr_memory-0.2.0/ccr/models/__init__.py +0 -0
- ccr_memory-0.2.0/ccr/models/anthropic_client.py +161 -0
- ccr_memory-0.2.0/ccr/models/base.py +47 -0
- ccr_memory-0.2.0/ccr/models/openai_compat.py +125 -0
- ccr_memory-0.2.0/ccr/models/retry.py +114 -0
- ccr_memory-0.2.0/ccr/rlm/__init__.py +6 -0
- ccr_memory-0.2.0/ccr/rlm/orchestrator.py +547 -0
- ccr_memory-0.2.0/ccr/rlm/repl.py +809 -0
- ccr_memory-0.2.0/ccr/rlm/sandbox.py +834 -0
- ccr_memory-0.2.0/ccr/utils/__init__.py +0 -0
- ccr_memory-0.2.0/ccr/utils/costs.py +106 -0
- ccr_memory-0.2.0/ccr/utils/parsing.py +211 -0
- ccr_memory-0.2.0/ccr/utils/tokens.py +80 -0
- ccr_memory-0.2.0/ccr_memory.egg-info/PKG-INFO +278 -0
- ccr_memory-0.2.0/ccr_memory.egg-info/SOURCES.txt +80 -0
- ccr_memory-0.2.0/ccr_memory.egg-info/dependency_links.txt +1 -0
- ccr_memory-0.2.0/ccr_memory.egg-info/entry_points.txt +3 -0
- ccr_memory-0.2.0/ccr_memory.egg-info/requires.txt +27 -0
- ccr_memory-0.2.0/ccr_memory.egg-info/top_level.txt +1 -0
- ccr_memory-0.2.0/pyproject.toml +83 -0
- ccr_memory-0.2.0/setup.cfg +4 -0
|
@@ -0,0 +1,278 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: ccr-memory
|
|
3
|
+
Version: 0.2.0
|
|
4
|
+
Summary: Persistent memory, self-evolving playbooks, and sandboxed REPL for Claude Code
|
|
5
|
+
Author: CCR Team
|
|
6
|
+
License: MIT
|
|
7
|
+
Project-URL: Homepage, https://github.com/qbit-glitch/ccr
|
|
8
|
+
Project-URL: Repository, https://github.com/qbit-glitch/ccr
|
|
9
|
+
Project-URL: Documentation, https://github.com/qbit-glitch/ccr#readme
|
|
10
|
+
Project-URL: Bug Reports, https://github.com/qbit-glitch/ccr/issues
|
|
11
|
+
Keywords: claude,mcp,memory,context,llm,agent,experiment-tracking,research-workflow,reproducibility,persistent-memory,claude-code
|
|
12
|
+
Classifier: Development Status :: 4 - Beta
|
|
13
|
+
Classifier: Intended Audience :: Developers
|
|
14
|
+
Classifier: Intended Audience :: Science/Research
|
|
15
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
16
|
+
Classifier: Programming Language :: Python :: 3
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
20
|
+
Classifier: Topic :: Software Development :: Libraries
|
|
21
|
+
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
|
|
22
|
+
Requires-Python: >=3.11
|
|
23
|
+
Description-Content-Type: text/markdown
|
|
24
|
+
Requires-Dist: click>=8.1.0
|
|
25
|
+
Requires-Dist: pyyaml>=6.0
|
|
26
|
+
Requires-Dist: rich>=13.0.0
|
|
27
|
+
Requires-Dist: python-dotenv>=1.0.0
|
|
28
|
+
Requires-Dist: mcp[cli]>=1.0.0
|
|
29
|
+
Provides-Extra: models
|
|
30
|
+
Requires-Dist: anthropic>=0.40.0; extra == "models"
|
|
31
|
+
Requires-Dist: openai>=1.50.0; extra == "models"
|
|
32
|
+
Requires-Dist: httpx>=0.27.0; extra == "models"
|
|
33
|
+
Requires-Dist: tiktoken>=0.7.0; extra == "models"
|
|
34
|
+
Provides-Extra: semantic
|
|
35
|
+
Requires-Dist: onnxruntime>=1.17.0; extra == "semantic"
|
|
36
|
+
Requires-Dist: tokenizers>=0.15.0; extra == "semantic"
|
|
37
|
+
Requires-Dist: numpy>=1.24.0; extra == "semantic"
|
|
38
|
+
Provides-Extra: vector
|
|
39
|
+
Requires-Dist: sqlite-vec>=0.1.0; extra == "vector"
|
|
40
|
+
Provides-Extra: watch
|
|
41
|
+
Requires-Dist: watchdog>=4.0.0; extra == "watch"
|
|
42
|
+
Provides-Extra: full
|
|
43
|
+
Requires-Dist: ccr-memory[models]; extra == "full"
|
|
44
|
+
Requires-Dist: ccr-memory[semantic]; extra == "full"
|
|
45
|
+
Requires-Dist: ccr-memory[vector]; extra == "full"
|
|
46
|
+
|
|
47
|
+
# CCR — Claude Context Reducer
|
|
48
|
+
|
|
49
|
+
> **Without CCR:** "Can you remind me what we decided about the dataset preprocessing last week?"
|
|
50
|
+
> **With CCR:** Claude already knows — months of decisions, experiments, and code reasoning recalled instantly.
|
|
51
|
+
|
|
52
|
+
CCR gives Claude Code persistent memory, self-evolving strategy playbooks, and a sandboxed Python REPL — no API keys needed. Works with **Claude Max ($20/mo)**.
|
|
53
|
+
|
|
54
|
+
> **New to CCR?** See the [Student & Researcher Quickstart](docs/quickstart-students.md) — setup in 3 minutes, before/after examples, PhD workflow guide.
|
|
55
|
+
|
|
56
|
+
## Quick Start
|
|
57
|
+
|
|
58
|
+
```bash
|
|
59
|
+
# 1. Install
|
|
60
|
+
pip install ccr-memory # or: pip install -e . (from source)
|
|
61
|
+
|
|
62
|
+
# 2. Configure hooks for automatic memory management
|
|
63
|
+
ccr install
|
|
64
|
+
|
|
65
|
+
# 3. Open Claude Code from your project directory — CCR handles the rest
|
|
66
|
+
cd /your/project && claude
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
That's it. Claude will automatically load your project memory on every session start and auto-commit progress when you finish.
|
|
70
|
+
|
|
71
|
+
### What CCR Does
|
|
72
|
+
|
|
73
|
+
CCR is an MCP server that gives Claude Code three capabilities it doesn't have natively:
|
|
74
|
+
|
|
75
|
+
1. **Persistent Memory (GCC)** — Git-style version-controlled memory that survives across sessions. Branch, merge, and search your project's decision history.
|
|
76
|
+
2. **Self-Evolving Playbooks (ACE)** — Strategy bullets that track what works and what doesn't, with temporal decay and automatic pruning.
|
|
77
|
+
3. **Sandboxed REPL (RLM)** — An isolated Python environment for iterative analysis, with repo search and structured output.
|
|
78
|
+
|
|
79
|
+
All tools run as pure logic with zero LLM calls. Claude Code itself provides the reasoning.
|
|
80
|
+
|
|
81
|
+
### For Researchers and Students
|
|
82
|
+
|
|
83
|
+
On Claude Max ($20/mo), you're not paying per token — you're paying for continuity. CCR makes that continuity real: Claude carries your experiment history, design decisions, and open questions forward across every session.
|
|
84
|
+
|
|
85
|
+
A 3-month project means ~90 sessions. Without CCR, each starts from scratch. With CCR, each starts where the last left off.
|
|
86
|
+
|
|
87
|
+
**Researcher-specific features:**
|
|
88
|
+
- `gcc_commit(experiment={"metrics": {"val_loss": 0.23}})` — log ML runs with metrics and hypothesis
|
|
89
|
+
- `gcc_experiments(metric_filter={"val_loss": {"lt": 0.3}})` — find all runs meeting a metric threshold
|
|
90
|
+
- `gcc_discuss(topic=..., decision=..., rationale=...)` — persistent decision log for architecture choices
|
|
91
|
+
- `gcc_search("preprocessing decision")` — find any past decision across commits, discussions, and sessions
|
|
92
|
+
|
|
93
|
+
See the [Student & Researcher Quickstart](docs/quickstart-students.md) for a full PhD workflow guide.
|
|
94
|
+
|
|
95
|
+
### Manual Setup (without `ccr install`)
|
|
96
|
+
|
|
97
|
+
Add to your project's `.mcp.json`:
|
|
98
|
+
|
|
99
|
+
```json
|
|
100
|
+
{
|
|
101
|
+
"mcpServers": {
|
|
102
|
+
"ccr": {
|
|
103
|
+
"command": ".venv/bin/python",
|
|
104
|
+
"args": ["-m", "ccr.mcp_server", "--project", "."]
|
|
105
|
+
}
|
|
106
|
+
}
|
|
107
|
+
}
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
Then in your Claude Code session, call `gcc_context(level=2)` to load memory and `gcc_commit` after completing tasks.
|
|
111
|
+
|
|
112
|
+
## Features
|
|
113
|
+
|
|
114
|
+
### Persistent Memory (GCC)
|
|
115
|
+
|
|
116
|
+
- **Commits**: Save what you did, why, files changed, and what's next
|
|
117
|
+
- **Branches**: Isolate experiments with `gcc_branch`, merge when decided
|
|
118
|
+
- **Context levels**: 5 levels of detail retrieval (summary → full history)
|
|
119
|
+
- **Pattern buffer**: Transferable skills extracted from commits, with quality scoring
|
|
120
|
+
- **Cross-linking**: Automatic bidirectional links between related commits
|
|
121
|
+
- **Semantic search**: Find past work by meaning, not just keywords (ONNX embeddings)
|
|
122
|
+
|
|
123
|
+
### Self-Evolving Playbooks (ACE)
|
|
124
|
+
|
|
125
|
+
- **Strategy bullets**: "When X, do Y" rules with helpful/harmful counters
|
|
126
|
+
- **Temporal decay**: Unused strategies fade (30 days → 21% weight, 90 days → 1%)
|
|
127
|
+
- **Two-tier scope**: Global strategies (all projects) + project-specific strategies
|
|
128
|
+
- **Failure lessons**: Structured analysis of what went wrong and prevention principles
|
|
129
|
+
- **Schema evolution**: The playbook structure itself evolves based on usage metrics
|
|
130
|
+
|
|
131
|
+
### Sandboxed REPL (RLM)
|
|
132
|
+
|
|
133
|
+
- **Kernel-level isolation**: macOS Seatbelt sandbox (deny-default + allowlist)
|
|
134
|
+
- **Module allowlist**: Only safe standard library modules permitted
|
|
135
|
+
- **Repo tools**: `search_repo()`, `get_file()`, `estimate_tokens()` available in REPL
|
|
136
|
+
- **Structured output**: `FINAL_VAR` termination pattern for clean results
|
|
137
|
+
|
|
138
|
+
### Repo Indexing
|
|
139
|
+
|
|
140
|
+
- **Hybrid search**: Keyword + semantic + combined modes
|
|
141
|
+
- **Per-language parsing**: Symbol extraction for Python, TypeScript, Rust, Go, and more
|
|
142
|
+
- **ONNX embeddings**: Optional dense embeddings (all-MiniLM-L6-v2, 384-dim)
|
|
143
|
+
- **Zero-config**: Works immediately; semantic search available with `pip install ccr-memory[semantic]`
|
|
144
|
+
|
|
145
|
+
### Session Logger
|
|
146
|
+
|
|
147
|
+
Every Q&A turn (user message + Claude's response) is persisted to `.ccr/sessions.db` (SQLite). Use it to replay any past session, debug unexpected Claude behaviour, or export conversation pairs for fine-tuning. Logging is automatic when hooks are active — Claude calls `session_log_turn` after each response. See [docs/session-logger.md](docs/session-logger.md) for the full reference.
|
|
148
|
+
|
|
149
|
+
## Architecture
|
|
150
|
+
|
|
151
|
+
```
|
|
152
|
+
Claude Code ──stdio──> CCR MCP Server
|
|
153
|
+
├── GCC Memory (.ccr/commits, branches, patterns)
|
|
154
|
+
├── ACE Playbook (.ccr/playbook.txt, failure_lessons.json)
|
|
155
|
+
├── RLM Sandbox (isolated Python subprocess)
|
|
156
|
+
└── Repo Index (.ccr/index.json, embeddings)
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
CCR stores all data in a `.ccr/` directory within your project (like `.git/`). Global strategies live in `~/.ccr/`.
|
|
160
|
+
|
|
161
|
+
## Tools
|
|
162
|
+
|
|
163
|
+
### Core (used in every session)
|
|
164
|
+
|
|
165
|
+
| Tool | Purpose |
|
|
166
|
+
|------|---------|
|
|
167
|
+
| `gcc_commit` | Save progress with what/why/files/next |
|
|
168
|
+
| `gcc_context` | Retrieve memory at 5 detail levels |
|
|
169
|
+
| `gcc_status` | Show current memory state |
|
|
170
|
+
| `ace_get_playbook` | View strategies with stats |
|
|
171
|
+
| `ace_update_counters` | Rate strategies helpful/harmful |
|
|
172
|
+
| `ace_apply_delta` | Add/update/merge/remove strategies |
|
|
173
|
+
|
|
174
|
+
### Extended
|
|
175
|
+
|
|
176
|
+
| Tool | Purpose |
|
|
177
|
+
|------|---------|
|
|
178
|
+
| `gcc_branch` / `gcc_merge` | Experiment isolation |
|
|
179
|
+
| `gcc_links` | Trace commit relationships |
|
|
180
|
+
| `gcc_patterns` | Query transferable patterns |
|
|
181
|
+
| `gcc_scratchpad` | Ephemeral working memory |
|
|
182
|
+
| `gcc_consolidate` | Generate hierarchical summaries |
|
|
183
|
+
| `ace_find_similar` | Find duplicate strategies |
|
|
184
|
+
| `ace_prune` | Remove harmful strategies |
|
|
185
|
+
| `rlm_init` / `rlm_execute` / `rlm_finalize` | Sandboxed REPL |
|
|
186
|
+
| `index_build` / `index_search` | Repo search |
|
|
187
|
+
|
|
188
|
+
### Session Logger
|
|
189
|
+
|
|
190
|
+
| Tool | Purpose |
|
|
191
|
+
|------|---------|
|
|
192
|
+
| `session_log_turn` | Log the current Q&A turn (called automatically after each response) |
|
|
193
|
+
| `session_get_history` | Retrieve recent turns for a session (defaults to current session) |
|
|
194
|
+
| `session_search` | Full-text search across all session turns (FTS5) |
|
|
195
|
+
| `session_export` | Export a session as `json`, `jsonl` (OpenAI fine-tune), or `markdown` |
|
|
196
|
+
|
|
197
|
+
## Research Foundation
|
|
198
|
+
|
|
199
|
+
CCR draws on 16 research papers across three tiers of implementation fidelity:
|
|
200
|
+
|
|
201
|
+
### Implemented (>70% fidelity)
|
|
202
|
+
- **GCC** (arXiv:2508.00031) — Git-style version-controlled agent memory
|
|
203
|
+
- **ACE** (arXiv:2510.04618) — Evolving playbooks with structured bullets and delta operations
|
|
204
|
+
- **RLM** (arXiv:2512.24601) — REPL-based execution with metadata-only stdout
|
|
205
|
+
|
|
206
|
+
### Substantially Adapted (30-70% fidelity)
|
|
207
|
+
- **A-MAC** (arXiv:2603.04549) — Admission control with 3 of 5 scoring factors
|
|
208
|
+
- **A-RAG** (arXiv:2602.03442) — Hierarchical retrieval with keyword/semantic/hybrid modes
|
|
209
|
+
- **CER** (arXiv:2506.06698) — Pattern buffer with dedup and quality scoring
|
|
210
|
+
- **MCE** (arXiv:2601.21557) — Schema evolution with rule-based structural proposals
|
|
211
|
+
- **SkillRL** (arXiv:2602.08234) — Failure-side skill distillation via structured lessons
|
|
212
|
+
|
|
213
|
+
### Inspired By (<30% fidelity)
|
|
214
|
+
- **A-MEM/MAGMA** — Commit cross-linking taxonomy
|
|
215
|
+
- **ERL** — Trigger/action bullet structure
|
|
216
|
+
- **Memori** — Semantic triple extraction
|
|
217
|
+
- **EverMemOS** — Thematic commit clustering
|
|
218
|
+
- **EvolveR** — Bayesian quality scoring for patterns
|
|
219
|
+
- **AgeMem** — Working memory scratchpad
|
|
220
|
+
- **AgentEvolver** — Contribution-weighted counters
|
|
221
|
+
- **ALMA** — Meta-learned retrieval parameters
|
|
222
|
+
|
|
223
|
+
All implementations use mechanical heuristics (zero LLM calls). See `CLAUDE.md` for detailed limitation tables comparing CCR's implementation vs. each paper.
|
|
224
|
+
|
|
225
|
+
## vs. Alternatives
|
|
226
|
+
|
|
227
|
+
| Feature | CCR | Mem0 | Letta/MemGPT | Graphiti |
|
|
228
|
+
|---------|-----|------|--------------|---------|
|
|
229
|
+
| Auto-manages memory | Yes (hooks) | Yes | Yes | Yes |
|
|
230
|
+
| Version control (branch/merge) | Yes | No | No | No |
|
|
231
|
+
| Self-evolving strategies | Yes | No | No | No |
|
|
232
|
+
| Sandboxed REPL | Yes | No | No | No |
|
|
233
|
+
| Zero LLM calls | Yes | No | No | No |
|
|
234
|
+
| Zero infrastructure | Yes | No | No (DB) | No (Neo4j) |
|
|
235
|
+
| Works with Claude Max only | Yes | No | No | No |
|
|
236
|
+
| Open source | MIT | Yes | Apache 2.0 | Apache 2.0 |
|
|
237
|
+
|
|
238
|
+
## Configuration
|
|
239
|
+
|
|
240
|
+
### Optional Dependencies
|
|
241
|
+
|
|
242
|
+
```bash
|
|
243
|
+
pip install ccr-memory[semantic] # ONNX embeddings for semantic search
|
|
244
|
+
pip install ccr-memory[vector] # sqlite-vec for persistent vector store
|
|
245
|
+
pip install ccr-memory[full] # Both of the above
|
|
246
|
+
```
|
|
247
|
+
|
|
248
|
+
### Environment Variables
|
|
249
|
+
|
|
250
|
+
| Variable | Purpose |
|
|
251
|
+
|----------|---------|
|
|
252
|
+
| `CCR_PROJECT_ROOT` | Override project root detection |
|
|
253
|
+
| `CCR_OLLAMA_MODEL` | Enable Ollama sub-model (e.g., `qwen2.5:7b`) |
|
|
254
|
+
| `ANTHROPIC_API_KEY_SUB` | Enable Anthropic Haiku sub-model |
|
|
255
|
+
|
|
256
|
+
Sub-models are optional — they enable LLM-powered features like rolling summary synthesis and automatic bullet generation.
|
|
257
|
+
|
|
258
|
+
### Diagnostics
|
|
259
|
+
|
|
260
|
+
```bash
|
|
261
|
+
ccr doctor # Check CCR health (deps, config, hooks)
|
|
262
|
+
ccr status # Show memory state
|
|
263
|
+
ccr context # Print project context
|
|
264
|
+
```
|
|
265
|
+
|
|
266
|
+
## Development
|
|
267
|
+
|
|
268
|
+
```bash
|
|
269
|
+
git clone https://github.com/qbit-glitch/ccr.git
|
|
270
|
+
cd ccr
|
|
271
|
+
python -m venv .venv && source .venv/bin/activate
|
|
272
|
+
pip install -e ".[dev]"
|
|
273
|
+
pytest tests/unit/ tests/integration/ -x -q
|
|
274
|
+
```
|
|
275
|
+
|
|
276
|
+
## License
|
|
277
|
+
|
|
278
|
+
MIT
|
|
@@ -0,0 +1,232 @@
|
|
|
1
|
+
# CCR — Claude Context Reducer
|
|
2
|
+
|
|
3
|
+
> **Without CCR:** "Can you remind me what we decided about the dataset preprocessing last week?"
|
|
4
|
+
> **With CCR:** Claude already knows — months of decisions, experiments, and code reasoning recalled instantly.
|
|
5
|
+
|
|
6
|
+
CCR gives Claude Code persistent memory, self-evolving strategy playbooks, and a sandboxed Python REPL — no API keys needed. Works with **Claude Max ($20/mo)**.
|
|
7
|
+
|
|
8
|
+
> **New to CCR?** See the [Student & Researcher Quickstart](docs/quickstart-students.md) — setup in 3 minutes, before/after examples, PhD workflow guide.
|
|
9
|
+
|
|
10
|
+
## Quick Start
|
|
11
|
+
|
|
12
|
+
```bash
|
|
13
|
+
# 1. Install
|
|
14
|
+
pip install ccr-memory # or: pip install -e . (from source)
|
|
15
|
+
|
|
16
|
+
# 2. Configure hooks for automatic memory management
|
|
17
|
+
ccr install
|
|
18
|
+
|
|
19
|
+
# 3. Open Claude Code from your project directory — CCR handles the rest
|
|
20
|
+
cd /your/project && claude
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
That's it. Claude will automatically load your project memory on every session start and auto-commit progress when you finish.
|
|
24
|
+
|
|
25
|
+
### What CCR Does
|
|
26
|
+
|
|
27
|
+
CCR is an MCP server that gives Claude Code three capabilities it doesn't have natively:
|
|
28
|
+
|
|
29
|
+
1. **Persistent Memory (GCC)** — Git-style version-controlled memory that survives across sessions. Branch, merge, and search your project's decision history.
|
|
30
|
+
2. **Self-Evolving Playbooks (ACE)** — Strategy bullets that track what works and what doesn't, with temporal decay and automatic pruning.
|
|
31
|
+
3. **Sandboxed REPL (RLM)** — An isolated Python environment for iterative analysis, with repo search and structured output.
|
|
32
|
+
|
|
33
|
+
All tools run as pure logic with zero LLM calls. Claude Code itself provides the reasoning.
|
|
34
|
+
|
|
35
|
+
### For Researchers and Students
|
|
36
|
+
|
|
37
|
+
On Claude Max ($20/mo), you're not paying per token — you're paying for continuity. CCR makes that continuity real: Claude carries your experiment history, design decisions, and open questions forward across every session.
|
|
38
|
+
|
|
39
|
+
A 3-month project means ~90 sessions. Without CCR, each starts from scratch. With CCR, each starts where the last left off.
|
|
40
|
+
|
|
41
|
+
**Researcher-specific features:**
|
|
42
|
+
- `gcc_commit(experiment={"metrics": {"val_loss": 0.23}})` — log ML runs with metrics and hypothesis
|
|
43
|
+
- `gcc_experiments(metric_filter={"val_loss": {"lt": 0.3}})` — find all runs meeting a metric threshold
|
|
44
|
+
- `gcc_discuss(topic=..., decision=..., rationale=...)` — persistent decision log for architecture choices
|
|
45
|
+
- `gcc_search("preprocessing decision")` — find any past decision across commits, discussions, and sessions
|
|
46
|
+
|
|
47
|
+
See the [Student & Researcher Quickstart](docs/quickstart-students.md) for a full PhD workflow guide.
|
|
48
|
+
|
|
49
|
+
### Manual Setup (without `ccr install`)
|
|
50
|
+
|
|
51
|
+
Add to your project's `.mcp.json`:
|
|
52
|
+
|
|
53
|
+
```json
|
|
54
|
+
{
|
|
55
|
+
"mcpServers": {
|
|
56
|
+
"ccr": {
|
|
57
|
+
"command": ".venv/bin/python",
|
|
58
|
+
"args": ["-m", "ccr.mcp_server", "--project", "."]
|
|
59
|
+
}
|
|
60
|
+
}
|
|
61
|
+
}
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
Then in your Claude Code session, call `gcc_context(level=2)` to load memory and `gcc_commit` after completing tasks.
|
|
65
|
+
|
|
66
|
+
## Features
|
|
67
|
+
|
|
68
|
+
### Persistent Memory (GCC)
|
|
69
|
+
|
|
70
|
+
- **Commits**: Save what you did, why, files changed, and what's next
|
|
71
|
+
- **Branches**: Isolate experiments with `gcc_branch`, merge when decided
|
|
72
|
+
- **Context levels**: 5 levels of detail retrieval (summary → full history)
|
|
73
|
+
- **Pattern buffer**: Transferable skills extracted from commits, with quality scoring
|
|
74
|
+
- **Cross-linking**: Automatic bidirectional links between related commits
|
|
75
|
+
- **Semantic search**: Find past work by meaning, not just keywords (ONNX embeddings)
|
|
76
|
+
|
|
77
|
+
### Self-Evolving Playbooks (ACE)
|
|
78
|
+
|
|
79
|
+
- **Strategy bullets**: "When X, do Y" rules with helpful/harmful counters
|
|
80
|
+
- **Temporal decay**: Unused strategies fade (30 days → 21% weight, 90 days → 1%)
|
|
81
|
+
- **Two-tier scope**: Global strategies (all projects) + project-specific strategies
|
|
82
|
+
- **Failure lessons**: Structured analysis of what went wrong and prevention principles
|
|
83
|
+
- **Schema evolution**: The playbook structure itself evolves based on usage metrics
|
|
84
|
+
|
|
85
|
+
### Sandboxed REPL (RLM)
|
|
86
|
+
|
|
87
|
+
- **Kernel-level isolation**: macOS Seatbelt sandbox (deny-default + allowlist)
|
|
88
|
+
- **Module allowlist**: Only safe standard library modules permitted
|
|
89
|
+
- **Repo tools**: `search_repo()`, `get_file()`, `estimate_tokens()` available in REPL
|
|
90
|
+
- **Structured output**: `FINAL_VAR` termination pattern for clean results
|
|
91
|
+
|
|
92
|
+
### Repo Indexing
|
|
93
|
+
|
|
94
|
+
- **Hybrid search**: Keyword + semantic + combined modes
|
|
95
|
+
- **Per-language parsing**: Symbol extraction for Python, TypeScript, Rust, Go, and more
|
|
96
|
+
- **ONNX embeddings**: Optional dense embeddings (all-MiniLM-L6-v2, 384-dim)
|
|
97
|
+
- **Zero-config**: Works immediately; semantic search available with `pip install ccr-memory[semantic]`
|
|
98
|
+
|
|
99
|
+
### Session Logger
|
|
100
|
+
|
|
101
|
+
Every Q&A turn (user message + Claude's response) is persisted to `.ccr/sessions.db` (SQLite). Use it to replay any past session, debug unexpected Claude behaviour, or export conversation pairs for fine-tuning. Logging is automatic when hooks are active — Claude calls `session_log_turn` after each response. See [docs/session-logger.md](docs/session-logger.md) for the full reference.
|
|
102
|
+
|
|
103
|
+
## Architecture
|
|
104
|
+
|
|
105
|
+
```
|
|
106
|
+
Claude Code ──stdio──> CCR MCP Server
|
|
107
|
+
├── GCC Memory (.ccr/commits, branches, patterns)
|
|
108
|
+
├── ACE Playbook (.ccr/playbook.txt, failure_lessons.json)
|
|
109
|
+
├── RLM Sandbox (isolated Python subprocess)
|
|
110
|
+
└── Repo Index (.ccr/index.json, embeddings)
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
CCR stores all data in a `.ccr/` directory within your project (like `.git/`). Global strategies live in `~/.ccr/`.
|
|
114
|
+
|
|
115
|
+
## Tools
|
|
116
|
+
|
|
117
|
+
### Core (used in every session)
|
|
118
|
+
|
|
119
|
+
| Tool | Purpose |
|
|
120
|
+
|------|---------|
|
|
121
|
+
| `gcc_commit` | Save progress with what/why/files/next |
|
|
122
|
+
| `gcc_context` | Retrieve memory at 5 detail levels |
|
|
123
|
+
| `gcc_status` | Show current memory state |
|
|
124
|
+
| `ace_get_playbook` | View strategies with stats |
|
|
125
|
+
| `ace_update_counters` | Rate strategies helpful/harmful |
|
|
126
|
+
| `ace_apply_delta` | Add/update/merge/remove strategies |
|
|
127
|
+
|
|
128
|
+
### Extended
|
|
129
|
+
|
|
130
|
+
| Tool | Purpose |
|
|
131
|
+
|------|---------|
|
|
132
|
+
| `gcc_branch` / `gcc_merge` | Experiment isolation |
|
|
133
|
+
| `gcc_links` | Trace commit relationships |
|
|
134
|
+
| `gcc_patterns` | Query transferable patterns |
|
|
135
|
+
| `gcc_scratchpad` | Ephemeral working memory |
|
|
136
|
+
| `gcc_consolidate` | Generate hierarchical summaries |
|
|
137
|
+
| `ace_find_similar` | Find duplicate strategies |
|
|
138
|
+
| `ace_prune` | Remove harmful strategies |
|
|
139
|
+
| `rlm_init` / `rlm_execute` / `rlm_finalize` | Sandboxed REPL |
|
|
140
|
+
| `index_build` / `index_search` | Repo search |
|
|
141
|
+
|
|
142
|
+
### Session Logger
|
|
143
|
+
|
|
144
|
+
| Tool | Purpose |
|
|
145
|
+
|------|---------|
|
|
146
|
+
| `session_log_turn` | Log the current Q&A turn (called automatically after each response) |
|
|
147
|
+
| `session_get_history` | Retrieve recent turns for a session (defaults to current session) |
|
|
148
|
+
| `session_search` | Full-text search across all session turns (FTS5) |
|
|
149
|
+
| `session_export` | Export a session as `json`, `jsonl` (OpenAI fine-tune), or `markdown` |
|
|
150
|
+
|
|
151
|
+
## Research Foundation
|
|
152
|
+
|
|
153
|
+
CCR draws on 16 research papers across three tiers of implementation fidelity:
|
|
154
|
+
|
|
155
|
+
### Implemented (>70% fidelity)
|
|
156
|
+
- **GCC** (arXiv:2508.00031) — Git-style version-controlled agent memory
|
|
157
|
+
- **ACE** (arXiv:2510.04618) — Evolving playbooks with structured bullets and delta operations
|
|
158
|
+
- **RLM** (arXiv:2512.24601) — REPL-based execution with metadata-only stdout
|
|
159
|
+
|
|
160
|
+
### Substantially Adapted (30-70% fidelity)
|
|
161
|
+
- **A-MAC** (arXiv:2603.04549) — Admission control with 3 of 5 scoring factors
|
|
162
|
+
- **A-RAG** (arXiv:2602.03442) — Hierarchical retrieval with keyword/semantic/hybrid modes
|
|
163
|
+
- **CER** (arXiv:2506.06698) — Pattern buffer with dedup and quality scoring
|
|
164
|
+
- **MCE** (arXiv:2601.21557) — Schema evolution with rule-based structural proposals
|
|
165
|
+
- **SkillRL** (arXiv:2602.08234) — Failure-side skill distillation via structured lessons
|
|
166
|
+
|
|
167
|
+
### Inspired By (<30% fidelity)
|
|
168
|
+
- **A-MEM/MAGMA** — Commit cross-linking taxonomy
|
|
169
|
+
- **ERL** — Trigger/action bullet structure
|
|
170
|
+
- **Memori** — Semantic triple extraction
|
|
171
|
+
- **EverMemOS** — Thematic commit clustering
|
|
172
|
+
- **EvolveR** — Bayesian quality scoring for patterns
|
|
173
|
+
- **AgeMem** — Working memory scratchpad
|
|
174
|
+
- **AgentEvolver** — Contribution-weighted counters
|
|
175
|
+
- **ALMA** — Meta-learned retrieval parameters
|
|
176
|
+
|
|
177
|
+
All implementations use mechanical heuristics (zero LLM calls). See `CLAUDE.md` for detailed limitation tables comparing CCR's implementation vs. each paper.
|
|
178
|
+
|
|
179
|
+
## vs. Alternatives
|
|
180
|
+
|
|
181
|
+
| Feature | CCR | Mem0 | Letta/MemGPT | Graphiti |
|
|
182
|
+
|---------|-----|------|--------------|---------|
|
|
183
|
+
| Auto-manages memory | Yes (hooks) | Yes | Yes | Yes |
|
|
184
|
+
| Version control (branch/merge) | Yes | No | No | No |
|
|
185
|
+
| Self-evolving strategies | Yes | No | No | No |
|
|
186
|
+
| Sandboxed REPL | Yes | No | No | No |
|
|
187
|
+
| Zero LLM calls | Yes | No | No | No |
|
|
188
|
+
| Zero infrastructure | Yes | No | No (DB) | No (Neo4j) |
|
|
189
|
+
| Works with Claude Max only | Yes | No | No | No |
|
|
190
|
+
| Open source | MIT | Yes | Apache 2.0 | Apache 2.0 |
|
|
191
|
+
|
|
192
|
+
## Configuration
|
|
193
|
+
|
|
194
|
+
### Optional Dependencies
|
|
195
|
+
|
|
196
|
+
```bash
|
|
197
|
+
pip install ccr-memory[semantic] # ONNX embeddings for semantic search
|
|
198
|
+
pip install ccr-memory[vector] # sqlite-vec for persistent vector store
|
|
199
|
+
pip install ccr-memory[full] # Both of the above
|
|
200
|
+
```
|
|
201
|
+
|
|
202
|
+
### Environment Variables
|
|
203
|
+
|
|
204
|
+
| Variable | Purpose |
|
|
205
|
+
|----------|---------|
|
|
206
|
+
| `CCR_PROJECT_ROOT` | Override project root detection |
|
|
207
|
+
| `CCR_OLLAMA_MODEL` | Enable Ollama sub-model (e.g., `qwen2.5:7b`) |
|
|
208
|
+
| `ANTHROPIC_API_KEY_SUB` | Enable Anthropic Haiku sub-model |
|
|
209
|
+
|
|
210
|
+
Sub-models are optional — they enable LLM-powered features like rolling summary synthesis and automatic bullet generation.
|
|
211
|
+
|
|
212
|
+
### Diagnostics
|
|
213
|
+
|
|
214
|
+
```bash
|
|
215
|
+
ccr doctor # Check CCR health (deps, config, hooks)
|
|
216
|
+
ccr status # Show memory state
|
|
217
|
+
ccr context # Print project context
|
|
218
|
+
```
|
|
219
|
+
|
|
220
|
+
## Development
|
|
221
|
+
|
|
222
|
+
```bash
|
|
223
|
+
git clone https://github.com/qbit-glitch/ccr.git
|
|
224
|
+
cd ccr
|
|
225
|
+
python -m venv .venv && source .venv/bin/activate
|
|
226
|
+
pip install -e ".[dev]"
|
|
227
|
+
pytest tests/unit/ tests/integration/ -x -q
|
|
228
|
+
```
|
|
229
|
+
|
|
230
|
+
## License
|
|
231
|
+
|
|
232
|
+
MIT
|
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
"""CCR — Claude Context Reducer.
|
|
2
|
+
|
|
3
|
+
Token-efficient middleware for Claude Code.
|
|
4
|
+
Combines RLM (Recursive Language Models) REPL-based context packing
|
|
5
|
+
with GCC (Git Context Controller) version-controlled memory.
|
|
6
|
+
"""
|
|
7
|
+
|
|
8
|
+
__version__ = "0.1.0"
|
|
9
|
+
|
|
10
|
+
from ccr.core.engine import CCREngine
|
|
11
|
+
from ccr.core.exceptions import (
|
|
12
|
+
CCRError,
|
|
13
|
+
ConfigError,
|
|
14
|
+
ModelAuthError,
|
|
15
|
+
ModelConnectionError,
|
|
16
|
+
ModelError,
|
|
17
|
+
ModelRateLimitError,
|
|
18
|
+
ModelTimeoutError,
|
|
19
|
+
PackingError,
|
|
20
|
+
PlaybookError,
|
|
21
|
+
RoutingError,
|
|
22
|
+
)
|
|
23
|
+
from ccr.core.hooks import HookManager
|
|
24
|
+
from ccr.core.memory import MemoryManager
|
|
25
|
+
from ccr.core.types import CCREngineConfig, CCRConfig, RouterConfig, RLMConfig
|
|
26
|
+
from ccr.gateway import CCRGateway
|
|
27
|
+
from ccr.rlm import CCRRlm, CCRRepl
|
|
28
|
+
|
|
29
|
+
__all__ = [
|
|
30
|
+
"CCREngine",
|
|
31
|
+
"CCRError",
|
|
32
|
+
"CCRGateway",
|
|
33
|
+
"ConfigError",
|
|
34
|
+
"MemoryManager",
|
|
35
|
+
"ModelAuthError",
|
|
36
|
+
"ModelConnectionError",
|
|
37
|
+
"ModelError",
|
|
38
|
+
"ModelRateLimitError",
|
|
39
|
+
"ModelTimeoutError",
|
|
40
|
+
"CCREngineConfig",
|
|
41
|
+
"CCRConfig",
|
|
42
|
+
"PackingError",
|
|
43
|
+
"PlaybookError",
|
|
44
|
+
"RouterConfig",
|
|
45
|
+
"RoutingError",
|
|
46
|
+
]
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
"""ACE (Agentic Context Engineering) — evolving playbooks for self-improving LLM systems."""
|