cc-brain 0.1.0 β 0.1.2
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.
- package/README.md +98 -67
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,67 +1,104 @@
|
|
|
1
|
-
|
|
1
|
+
<p align="center">
|
|
2
|
+
<h1 align="center">π§ cc-brain</h1>
|
|
3
|
+
<p align="center">
|
|
4
|
+
<strong>Persistent memory for Claude Code</strong><br>
|
|
5
|
+
<em>Remember context across sessions</em>
|
|
6
|
+
</p>
|
|
7
|
+
</p>
|
|
2
8
|
|
|
3
|
-
|
|
9
|
+
<p align="center">
|
|
10
|
+
<a href="https://www.npmjs.com/package/cc-brain"><img src="https://img.shields.io/npm/v/cc-brain?style=flat-square&color=blue" alt="npm version"></a>
|
|
11
|
+
<a href="https://www.npmjs.com/package/cc-brain"><img src="https://img.shields.io/npm/dm/cc-brain?style=flat-square&color=green" alt="npm downloads"></a>
|
|
12
|
+
<a href="https://github.com/tripzcodes/cc-brain/blob/master/LICENSE"><img src="https://img.shields.io/npm/l/cc-brain?style=flat-square" alt="license"></a>
|
|
13
|
+
<a href="https://github.com/tripzcodes/cc-brain"><img src="https://img.shields.io/github/stars/tripzcodes/cc-brain?style=flat-square" alt="github stars"></a>
|
|
14
|
+
</p>
|
|
4
15
|
|
|
5
|
-
|
|
16
|
+
<p align="center">
|
|
17
|
+
<a href="#installation">Installation</a> β’
|
|
18
|
+
<a href="#how-it-works">How It Works</a> β’
|
|
19
|
+
<a href="#commands">Commands</a> β’
|
|
20
|
+
<a href="#cli">CLI</a>
|
|
21
|
+
</p>
|
|
6
22
|
|
|
7
|
-
|
|
23
|
+
---
|
|
8
24
|
|
|
9
|
-
|
|
10
|
-
- **Saving** important learnings before context compaction
|
|
11
|
-
- **Searching** past sessions for decisions and context
|
|
25
|
+
## The Problem
|
|
12
26
|
|
|
13
|
-
|
|
27
|
+
Claude Code sessions are **ephemeral**. When context fills up or you start a new session, everything is forgotten. Your preferences, project decisions, debugging history β gone.
|
|
28
|
+
|
|
29
|
+
## The Solution
|
|
30
|
+
|
|
31
|
+
cc-brain creates a persistent memory layer that:
|
|
32
|
+
|
|
33
|
+
- **Loads** your profile and project context on every session
|
|
34
|
+
- **Saves** important learnings before context compaction
|
|
35
|
+
- **Searches** past sessions for decisions and context
|
|
14
36
|
|
|
15
|
-
|
|
37
|
+
---
|
|
16
38
|
|
|
17
|
-
|
|
39
|
+
## Installation
|
|
18
40
|
|
|
41
|
+
### npm (recommended)
|
|
19
42
|
```bash
|
|
20
43
|
npm install -g cc-brain
|
|
21
44
|
cc-brain install
|
|
22
45
|
```
|
|
23
46
|
|
|
24
|
-
###
|
|
25
|
-
|
|
47
|
+
### npx (no install)
|
|
26
48
|
```bash
|
|
27
49
|
npx cc-brain install
|
|
28
|
-
# or
|
|
29
|
-
bunx cc-brain install
|
|
30
50
|
```
|
|
31
51
|
|
|
32
|
-
###
|
|
33
|
-
|
|
52
|
+
### bunx
|
|
34
53
|
```bash
|
|
35
|
-
|
|
54
|
+
bunx cc-brain install
|
|
36
55
|
```
|
|
37
56
|
|
|
38
|
-
###
|
|
39
|
-
|
|
57
|
+
### Claude Plugin
|
|
40
58
|
```bash
|
|
41
|
-
|
|
42
|
-
cd cc-brain
|
|
43
|
-
node scripts/install.js
|
|
59
|
+
claude plugins add cc-brain
|
|
44
60
|
```
|
|
45
61
|
|
|
46
|
-
|
|
62
|
+
---
|
|
63
|
+
|
|
64
|
+
## How It Works
|
|
47
65
|
|
|
48
66
|
```
|
|
49
67
|
~/.claude/brain/
|
|
50
|
-
βββ user.md #
|
|
51
|
-
βββ preferences.md #
|
|
68
|
+
βββ user.md # Your profile (always loaded)
|
|
69
|
+
βββ preferences.md # Code preferences (always loaded)
|
|
52
70
|
βββ projects/{id}/
|
|
53
|
-
βββ context.md #
|
|
54
|
-
βββ archive/ #
|
|
71
|
+
βββ context.md # Current project state
|
|
72
|
+
βββ archive/ # Session history
|
|
55
73
|
βββ 2025-01-31.md
|
|
56
74
|
```
|
|
57
75
|
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
|
61
|
-
|
|
62
|
-
|
|
|
76
|
+
### Memory Tiers
|
|
77
|
+
|
|
78
|
+
| Tier | Content | Limit | Loaded |
|
|
79
|
+
|:----:|---------|:-----:|:------:|
|
|
80
|
+
| **T1** | User identity & preferences | 80 lines | Always |
|
|
81
|
+
| **T2** | Project context | 120 lines | Current project |
|
|
82
|
+
| **T3** | Archive history | Unlimited | On-demand |
|
|
83
|
+
|
|
84
|
+
### Lifecycle
|
|
85
|
+
|
|
86
|
+
```
|
|
87
|
+
βββββββββββββββββββ βββββββββββββββββββ βββββββββββββββββββ
|
|
88
|
+
β Session Start ββββββΆβ Brain Loaded ββββββΆβ You Work... β
|
|
89
|
+
βββββββββββββββββββ βββββββββββββββββββ ββββββββββ¬βββββββββ
|
|
90
|
+
β
|
|
91
|
+
βββββββββββββββββββ βββββββββββββββββββ β
|
|
92
|
+
β Next Session βββββββ Brain Saved ββββββββββββββββ
|
|
93
|
+
βββββββββββββββββββ βββββββββββββββββββ
|
|
94
|
+
(before compaction)
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
---
|
|
63
98
|
|
|
64
|
-
##
|
|
99
|
+
## Commands
|
|
100
|
+
|
|
101
|
+
Use these skills in Claude Code:
|
|
65
102
|
|
|
66
103
|
| Command | Description |
|
|
67
104
|
|---------|-------------|
|
|
@@ -69,37 +106,31 @@ node scripts/install.js
|
|
|
69
106
|
| `/recall <query>` | Search archive for past context |
|
|
70
107
|
| `/brain` | View current brain state |
|
|
71
108
|
|
|
109
|
+
---
|
|
110
|
+
|
|
72
111
|
## CLI
|
|
73
112
|
|
|
74
113
|
```bash
|
|
75
|
-
|
|
76
|
-
cc-brain
|
|
77
|
-
cc-brain uninstall
|
|
114
|
+
# Setup
|
|
115
|
+
cc-brain install # Install hooks
|
|
116
|
+
cc-brain uninstall # Remove hooks
|
|
117
|
+
cc-brain uninstall --purge # Remove everything
|
|
78
118
|
|
|
79
|
-
|
|
80
|
-
cc-brain
|
|
81
|
-
cc-brain archive
|
|
82
|
-
cc-brain archive
|
|
119
|
+
# Search & Archive
|
|
120
|
+
cc-brain recall "query" # Search archive
|
|
121
|
+
cc-brain archive list # List entries
|
|
122
|
+
cc-brain archive stats # Show statistics
|
|
123
|
+
cc-brain archive prune --keep 20
|
|
83
124
|
|
|
84
|
-
|
|
125
|
+
# Project Identity
|
|
126
|
+
cc-brain project-id --init # Create stable .brain-id
|
|
127
|
+
|
|
128
|
+
# Manual Save
|
|
85
129
|
cc-brain save --dry-run --json '{"t2": {"focus": "testing"}}'
|
|
130
|
+
cc-brain save --json '{"t2": {"focus": "testing"}}'
|
|
86
131
|
```
|
|
87
132
|
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
1. **SessionStart hook** runs on every session:
|
|
91
|
-
- Loads T1 (user profile + preferences)
|
|
92
|
-
- Loads T2 (current project context)
|
|
93
|
-
- Auto-prunes archives older than 90 days
|
|
94
|
-
|
|
95
|
-
2. **PreCompact hook** triggers before context dies:
|
|
96
|
-
- Analyzes session for important learnings
|
|
97
|
-
- Saves to appropriate tier using structured format
|
|
98
|
-
|
|
99
|
-
3. **Skills** for manual control:
|
|
100
|
-
- `/save` - capture context anytime
|
|
101
|
-
- `/recall` - search past sessions
|
|
102
|
-
- `/brain` - see what's loaded
|
|
133
|
+
---
|
|
103
134
|
|
|
104
135
|
## Project Identity
|
|
105
136
|
|
|
@@ -109,26 +140,26 @@ By default, projects are identified by directory name. For stable identity that
|
|
|
109
140
|
cc-brain project-id --init
|
|
110
141
|
```
|
|
111
142
|
|
|
112
|
-
|
|
143
|
+
Creates a `.brain-id` file with a UUID. Commit it to your repo.
|
|
144
|
+
|
|
145
|
+
---
|
|
113
146
|
|
|
114
147
|
## Uninstall
|
|
115
148
|
|
|
116
149
|
```bash
|
|
117
|
-
cc-brain uninstall
|
|
118
|
-
cc-brain uninstall --purge
|
|
150
|
+
cc-brain uninstall # Remove hooks, keep data
|
|
151
|
+
cc-brain uninstall --purge # Remove everything
|
|
119
152
|
```
|
|
120
153
|
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
```bash
|
|
124
|
-
npm uninstall -g cc-brain
|
|
125
|
-
```
|
|
154
|
+
---
|
|
126
155
|
|
|
127
156
|
## Requirements
|
|
128
157
|
|
|
129
|
-
- Node.js >= 18 or [Bun](https://bun.sh)
|
|
130
|
-
- [Claude Code](https://github.com/anthropics/claude-code)
|
|
158
|
+
- **Node.js** >= 18 or [Bun](https://bun.sh)
|
|
159
|
+
- [Claude Code](https://github.com/anthropics/claude-code)
|
|
160
|
+
|
|
161
|
+
---
|
|
131
162
|
|
|
132
163
|
## License
|
|
133
164
|
|
|
134
|
-
MIT
|
|
165
|
+
MIT Β© [tripzcodes](https://github.com/tripzcodes)
|