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.
Files changed (82) hide show
  1. ccr_memory-0.2.0/PKG-INFO +278 -0
  2. ccr_memory-0.2.0/README.md +232 -0
  3. ccr_memory-0.2.0/ccr/__init__.py +46 -0
  4. ccr_memory-0.2.0/ccr/ace/__init__.py +1 -0
  5. ccr_memory-0.2.0/ccr/ace/agents.py +308 -0
  6. ccr_memory-0.2.0/ccr/ace/engine.py +404 -0
  7. ccr_memory-0.2.0/ccr/ace/playbook.py +1645 -0
  8. ccr_memory-0.2.0/ccr/ace/prompts.py +242 -0
  9. ccr_memory-0.2.0/ccr/cli.py +867 -0
  10. ccr_memory-0.2.0/ccr/context/__init__.py +0 -0
  11. ccr_memory-0.2.0/ccr/context/embeddings.py +233 -0
  12. ccr_memory-0.2.0/ccr/context/indexer.py +1020 -0
  13. ccr_memory-0.2.0/ccr/context/packer.py +220 -0
  14. ccr_memory-0.2.0/ccr/context/prompts.py +133 -0
  15. ccr_memory-0.2.0/ccr/context/vec_store.py +212 -0
  16. ccr_memory-0.2.0/ccr/core/__init__.py +0 -0
  17. ccr_memory-0.2.0/ccr/core/engine.py +453 -0
  18. ccr_memory-0.2.0/ccr/core/exceptions.py +124 -0
  19. ccr_memory-0.2.0/ccr/core/hooks.py +122 -0
  20. ccr_memory-0.2.0/ccr/core/memory.py +67 -0
  21. ccr_memory-0.2.0/ccr/core/memory_pkg/__init__.py +55 -0
  22. ccr_memory-0.2.0/ccr/core/memory_pkg/memory_admission.py +418 -0
  23. ccr_memory-0.2.0/ccr/core/memory_pkg/memory_branch_ops.py +265 -0
  24. ccr_memory-0.2.0/ccr/core/memory_pkg/memory_commit.py +568 -0
  25. ccr_memory-0.2.0/ccr/core/memory_pkg/memory_consolidation.py +590 -0
  26. ccr_memory-0.2.0/ccr/core/memory_pkg/memory_context.py +467 -0
  27. ccr_memory-0.2.0/ccr/core/memory_pkg/memory_discussions.py +264 -0
  28. ccr_memory-0.2.0/ccr/core/memory_pkg/memory_embeddings.py +120 -0
  29. ccr_memory-0.2.0/ccr/core/memory_pkg/memory_evolution.py +189 -0
  30. ccr_memory-0.2.0/ccr/core/memory_pkg/memory_experiments.py +330 -0
  31. ccr_memory-0.2.0/ccr/core/memory_pkg/memory_file_io.py +147 -0
  32. ccr_memory-0.2.0/ccr/core/memory_pkg/memory_init.py +154 -0
  33. ccr_memory-0.2.0/ccr/core/memory_pkg/memory_links.py +898 -0
  34. ccr_memory-0.2.0/ccr/core/memory_pkg/memory_ota.py +99 -0
  35. ccr_memory-0.2.0/ccr/core/memory_pkg/memory_patterns.py +394 -0
  36. ccr_memory-0.2.0/ccr/core/memory_pkg/memory_registry.py +194 -0
  37. ccr_memory-0.2.0/ccr/core/memory_pkg/memory_rolling_summary.py +217 -0
  38. ccr_memory-0.2.0/ccr/core/memory_pkg/memory_types.py +136 -0
  39. ccr_memory-0.2.0/ccr/core/router.py +206 -0
  40. ccr_memory-0.2.0/ccr/core/scratchpad.py +198 -0
  41. ccr_memory-0.2.0/ccr/core/session_store.py +387 -0
  42. ccr_memory-0.2.0/ccr/core/triples.py +233 -0
  43. ccr_memory-0.2.0/ccr/core/types.py +650 -0
  44. ccr_memory-0.2.0/ccr/gateway.py +289 -0
  45. ccr_memory-0.2.0/ccr/hooks/__init__.py +0 -0
  46. ccr_memory-0.2.0/ccr/hooks/on_compact.py +55 -0
  47. ccr_memory-0.2.0/ccr/hooks/on_session_end.py +31 -0
  48. ccr_memory-0.2.0/ccr/hooks/on_session_start.py +272 -0
  49. ccr_memory-0.2.0/ccr/hooks/on_stop.py +319 -0
  50. ccr_memory-0.2.0/ccr/hooks/on_tool_use.py +92 -0
  51. ccr_memory-0.2.0/ccr/hooks/state_accumulator.py +135 -0
  52. ccr_memory-0.2.0/ccr/mcp/__init__.py +14 -0
  53. ccr_memory-0.2.0/ccr/mcp/ace_tools.py +1638 -0
  54. ccr_memory-0.2.0/ccr/mcp/audit.py +65 -0
  55. ccr_memory-0.2.0/ccr/mcp/gcc_tools.py +1265 -0
  56. ccr_memory-0.2.0/ccr/mcp/index_tools.py +324 -0
  57. ccr_memory-0.2.0/ccr/mcp/rlm_tools.py +393 -0
  58. ccr_memory-0.2.0/ccr/mcp/server.py +448 -0
  59. ccr_memory-0.2.0/ccr/mcp/session_tools.py +255 -0
  60. ccr_memory-0.2.0/ccr/mcp_server.py +173 -0
  61. ccr_memory-0.2.0/ccr/mcp_types.py +267 -0
  62. ccr_memory-0.2.0/ccr/models/__init__.py +0 -0
  63. ccr_memory-0.2.0/ccr/models/anthropic_client.py +161 -0
  64. ccr_memory-0.2.0/ccr/models/base.py +47 -0
  65. ccr_memory-0.2.0/ccr/models/openai_compat.py +125 -0
  66. ccr_memory-0.2.0/ccr/models/retry.py +114 -0
  67. ccr_memory-0.2.0/ccr/rlm/__init__.py +6 -0
  68. ccr_memory-0.2.0/ccr/rlm/orchestrator.py +547 -0
  69. ccr_memory-0.2.0/ccr/rlm/repl.py +809 -0
  70. ccr_memory-0.2.0/ccr/rlm/sandbox.py +834 -0
  71. ccr_memory-0.2.0/ccr/utils/__init__.py +0 -0
  72. ccr_memory-0.2.0/ccr/utils/costs.py +106 -0
  73. ccr_memory-0.2.0/ccr/utils/parsing.py +211 -0
  74. ccr_memory-0.2.0/ccr/utils/tokens.py +80 -0
  75. ccr_memory-0.2.0/ccr_memory.egg-info/PKG-INFO +278 -0
  76. ccr_memory-0.2.0/ccr_memory.egg-info/SOURCES.txt +80 -0
  77. ccr_memory-0.2.0/ccr_memory.egg-info/dependency_links.txt +1 -0
  78. ccr_memory-0.2.0/ccr_memory.egg-info/entry_points.txt +3 -0
  79. ccr_memory-0.2.0/ccr_memory.egg-info/requires.txt +27 -0
  80. ccr_memory-0.2.0/ccr_memory.egg-info/top_level.txt +1 -0
  81. ccr_memory-0.2.0/pyproject.toml +83 -0
  82. 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."""