brain-memory 0.1.0-beta.1
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/LICENSE +21 -0
- package/README.md +466 -0
- package/bin/install.js +361 -0
- package/commands/brain/consolidate.md +153 -0
- package/commands/brain/explore.md +79 -0
- package/commands/brain/forget.md +115 -0
- package/commands/brain/init.md +157 -0
- package/commands/brain/memorize.md +176 -0
- package/commands/brain/remember.md +176 -0
- package/commands/brain/review.md +130 -0
- package/commands/brain/sleep.md +535 -0
- package/commands/brain/status.md +122 -0
- package/commands/brain/sunshine.md +337 -0
- package/hooks/session-end.md +48 -0
- package/hooks/session-start.md +48 -0
- package/package.json +46 -0
- package/prompts/claude.md +75 -0
- package/prompts/gemini.md +76 -0
- package/prompts/openai.md +76 -0
- package/src/index-manager.js +401 -0
- package/src/scorer.js +452 -0
- package/templates/default-categories.json +82 -0
|
@@ -0,0 +1,122 @@
|
|
|
1
|
+
# /brain:status — Brain Overview Dashboard
|
|
2
|
+
|
|
3
|
+
You are displaying a comprehensive overview of the Brain Memory system's current state.
|
|
4
|
+
|
|
5
|
+
## Steps
|
|
6
|
+
|
|
7
|
+
### 1. Read Brain State
|
|
8
|
+
|
|
9
|
+
Read `.brain/index.json` to get the full memory inventory. If `.brain/` doesn't exist, inform the user and suggest running `/brain:init`.
|
|
10
|
+
|
|
11
|
+
Also read (if they exist):
|
|
12
|
+
- `.brain/associations.json` — for association network stats
|
|
13
|
+
- `.brain/review-queue.json` — for review schedule info
|
|
14
|
+
- `.brain/_archived/index.json` — for archive stats
|
|
15
|
+
|
|
16
|
+
### 2. Compute Statistics
|
|
17
|
+
|
|
18
|
+
For each memory in the index, compute:
|
|
19
|
+
|
|
20
|
+
```
|
|
21
|
+
days_elapsed = (now - last_accessed) / (1000 * 60 * 60 * 24)
|
|
22
|
+
decayed_strength = strength * (decay_rate ^ days_elapsed)
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
Calculate aggregate stats:
|
|
26
|
+
- Total memory count
|
|
27
|
+
- Memories per top-level category
|
|
28
|
+
- Average effective (decayed) strength
|
|
29
|
+
- Memories by type distribution
|
|
30
|
+
- Memories by cognitive type (episodic / semantic / procedural)
|
|
31
|
+
- Total tags (unique count)
|
|
32
|
+
- Confidence distribution
|
|
33
|
+
- Salience distribution
|
|
34
|
+
|
|
35
|
+
### 3. Display Dashboard
|
|
36
|
+
|
|
37
|
+
```
|
|
38
|
+
╔══════════════════════════════════════════╗
|
|
39
|
+
║ 🧠 BRAIN STATUS ║
|
|
40
|
+
╠══════════════════════════════════════════╣
|
|
41
|
+
║ Total Memories: <count> ║
|
|
42
|
+
║ Archived: <count> ║
|
|
43
|
+
║ Last Updated: <date> ║
|
|
44
|
+
║ Average Strength: <avg> / 1.00 ║
|
|
45
|
+
║ Average Confidence: <avg> / 1.00 ║
|
|
46
|
+
║ Brain Age: <days since init> ║
|
|
47
|
+
║ Brain Version: <version> ║
|
|
48
|
+
╚══════════════════════════════════════════╝
|
|
49
|
+
|
|
50
|
+
## Categories
|
|
51
|
+
professional: ████████████░░░ <N> memories (avg ⚡<strength>)
|
|
52
|
+
personal: ██████░░░░░░░░░ <N> memories (avg ⚡<strength>)
|
|
53
|
+
social: ███░░░░░░░░░░░░ <N> memories (avg ⚡<strength>)
|
|
54
|
+
family: ████░░░░░░░░░░░ <N> memories (avg ⚡<strength>)
|
|
55
|
+
|
|
56
|
+
## Memory Types
|
|
57
|
+
decision: <N> | learning: <N>
|
|
58
|
+
experience: <N> | insight: <N>
|
|
59
|
+
observation: <N> | goal: <N>
|
|
60
|
+
preference: <N> | relationship:<N>
|
|
61
|
+
|
|
62
|
+
## Cognitive Types
|
|
63
|
+
episodic: <N> (event-specific, faster decay)
|
|
64
|
+
semantic: <N> (abstracted knowledge, stable)
|
|
65
|
+
procedural: <N> (skills/workflows, very stable)
|
|
66
|
+
|
|
67
|
+
## Confidence Distribution
|
|
68
|
+
High (0.8-1.0): <count> memories — verified/reliable
|
|
69
|
+
Medium (0.5-0.7): <count> memories — plausible
|
|
70
|
+
Low (< 0.5): <count> memories — uncertain ⚠️
|
|
71
|
+
|
|
72
|
+
## Associative Network
|
|
73
|
+
Total links: <count> edges
|
|
74
|
+
Avg link weight: <avg>
|
|
75
|
+
Strongest links:
|
|
76
|
+
1. <mem_a title> ↔ <mem_b title> (weight: <w>)
|
|
77
|
+
2. <mem_a title> ↔ <mem_b title> (weight: <w>)
|
|
78
|
+
|
|
79
|
+
## Strongest Memories (Top 5)
|
|
80
|
+
1. ⚡0.92 — <title> (<path>)
|
|
81
|
+
2. ⚡0.88 — <title> (<path>)
|
|
82
|
+
...
|
|
83
|
+
|
|
84
|
+
## Most Recalled (Top 5)
|
|
85
|
+
1. 🔄 <count>x — <title> (<path>)
|
|
86
|
+
2. 🔄 <count>x — <title> (<path>)
|
|
87
|
+
...
|
|
88
|
+
|
|
89
|
+
## High-Salience Memories (protected from auto-pruning)
|
|
90
|
+
🛡️ <title> (salience: <s>, strength: <str>)
|
|
91
|
+
🛡️ <title> (salience: <s>, strength: <str>)
|
|
92
|
+
|
|
93
|
+
## Fading Memories (decayed strength < 0.3)
|
|
94
|
+
⚠ <count> memories below consolidation threshold
|
|
95
|
+
Run /brain:consolidate to preserve them
|
|
96
|
+
|
|
97
|
+
## Review Queue
|
|
98
|
+
📋 Due now: <count> memories
|
|
99
|
+
📋 Due this week: <count> memories
|
|
100
|
+
📋 Total in queue: <count> memories
|
|
101
|
+
Run /brain:review to start a review session
|
|
102
|
+
|
|
103
|
+
## Recent Memories (Last 7 days)
|
|
104
|
+
+ <title> (<path>) — <date>
|
|
105
|
+
+ <title> (<path>) — <date>
|
|
106
|
+
...
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
### 4. Health Check
|
|
110
|
+
|
|
111
|
+
Analyze the brain's health and provide recommendations:
|
|
112
|
+
|
|
113
|
+
- **"Healthy"** — Good distribution across categories, strong average strength
|
|
114
|
+
- **"Needs consolidation"** — Many memories below threshold, suggest `/brain:consolidate`
|
|
115
|
+
- **"Imbalanced"** — One category dominates, suggest diversifying
|
|
116
|
+
- **"Stale"** — No new memories in 14+ days, suggest `/brain:memorize`
|
|
117
|
+
- **"Overloaded"** — More than 200 active memories, suggest pruning with `/brain:forget --prune`
|
|
118
|
+
- **"Needs propagation"** — Recent memories exist alongside older related memories that haven't been updated. Suggest `/brain:sleep`
|
|
119
|
+
- **"Needs sleep"** — Multiple flat clusters detected, OR many memories in moderate/weak tiers, OR no `_expertise.md` profiles exist despite having 10+ memories. Suggest `/brain:sleep`
|
|
120
|
+
- **"Low confidence"** — More than 30% of memories have confidence < 0.5. Suggest reviewing and validating uncertain memories.
|
|
121
|
+
- **"Review overdue"** — More than 10 memories are past their review date. Suggest `/brain:review`
|
|
122
|
+
- **"Needs migration"** — Brain is v1 and needs upgrade. Suggest `/brain:sleep` to trigger migration.
|
|
@@ -0,0 +1,337 @@
|
|
|
1
|
+
# /brain:sunshine — Deep Forensic Memory Erasure
|
|
2
|
+
|
|
3
|
+
You are performing **deep forensic erasure** on a memory in the Brain Memory system. Like the procedure in *Eternal Sunshine of the Spotless Mind*, this command doesn't just delete a memory — it traces every ripple that memory left across the entire `.brain/` tree and surgically removes or repairs each one. When complete, it's as if the memory never existed.
|
|
4
|
+
|
|
5
|
+
Use this for erasing accidentally stored credentials, removing knowledge of a deprecated anti-pattern that leaked into other memories, or cleaning up after a fully reversed technical decision.
|
|
6
|
+
|
|
7
|
+
**Target:** $ARGUMENTS
|
|
8
|
+
|
|
9
|
+
## Flags
|
|
10
|
+
|
|
11
|
+
| Flag | Behavior |
|
|
12
|
+
|------|----------|
|
|
13
|
+
| *(default)* | Remove target + clean all direct references. Ask about derivatives individually |
|
|
14
|
+
| `--deep` | Also handle derivative memories and repair consolidated memories that lose sources |
|
|
15
|
+
| `--dry-run` | Show blast radius only — no changes are made |
|
|
16
|
+
| `--cascade` | With `--deep`, auto-remove derivative memories without asking |
|
|
17
|
+
| `--sensitive` | Overwrite file content with null bytes before deletion (for credentials, secrets) |
|
|
18
|
+
| `--no-trace` | Skip writing to `_erased.json` audit log |
|
|
19
|
+
| `--reason "<text>"` | Reason recorded in audit log entry |
|
|
20
|
+
|
|
21
|
+
## Steps
|
|
22
|
+
|
|
23
|
+
### 1. Parse Target and Flags
|
|
24
|
+
|
|
25
|
+
Extract:
|
|
26
|
+
- **Target identifier**: memory ID (e.g., `mem_20260215_a3f2c1`), title substring, or file path
|
|
27
|
+
- **Flags**: `--deep`, `--dry-run`, `--cascade`, `--sensitive`, `--no-trace`, `--reason`
|
|
28
|
+
|
|
29
|
+
If no target is provided, ask the user what memory they want to erase.
|
|
30
|
+
|
|
31
|
+
### 2. Locate Target Memory
|
|
32
|
+
|
|
33
|
+
Search for the target memory:
|
|
34
|
+
|
|
35
|
+
1. Read `.brain/index.json` and search `memories` by:
|
|
36
|
+
- Exact ID match
|
|
37
|
+
- Title substring match (case-insensitive)
|
|
38
|
+
- Path substring match
|
|
39
|
+
2. If not found in active memories, check `.brain/_archived/index.json`
|
|
40
|
+
3. If still not found, check `.brain/_erased.json` — if found there, report:
|
|
41
|
+
```
|
|
42
|
+
Memory was previously erased on <date>.
|
|
43
|
+
Reason: <reason or "unspecified">
|
|
44
|
+
No further action needed.
|
|
45
|
+
```
|
|
46
|
+
4. If not found anywhere, report and stop.
|
|
47
|
+
5. If multiple matches, present them and ask the user to pick one.
|
|
48
|
+
|
|
49
|
+
Once located, read the full memory file to capture its ID, title, path, tags, `related` array, `consolidated_from` array, and content.
|
|
50
|
+
|
|
51
|
+
### 3. Trace All References (Blast Radius Scan)
|
|
52
|
+
|
|
53
|
+
Scan the entire `.brain/` tree for every trace of the target memory. Track 8 reference types:
|
|
54
|
+
|
|
55
|
+
**3a. `related` arrays in other memories' frontmatter:**
|
|
56
|
+
Parse the YAML frontmatter of every `.md` memory file in `.brain/`. For each file whose `related` array contains the target ID, record:
|
|
57
|
+
- File path
|
|
58
|
+
- Current `related` array contents
|
|
59
|
+
|
|
60
|
+
**3b. Content body mentions:**
|
|
61
|
+
Search the Markdown body (below frontmatter) of all memory files for:
|
|
62
|
+
- The target memory ID (e.g., `mem_20260215_a3f2c1`)
|
|
63
|
+
- The target memory title (exact match)
|
|
64
|
+
Record each file path and the matching line.
|
|
65
|
+
|
|
66
|
+
**3c. `consolidated_from` arrays:**
|
|
67
|
+
Among all memory files with `type: consolidated`, check if their `consolidated_from` array contains the target ID. Record:
|
|
68
|
+
- File path
|
|
69
|
+
- Full `consolidated_from` array
|
|
70
|
+
- Number of other sources remaining
|
|
71
|
+
|
|
72
|
+
**3d. Association edges (`associations.json`):**
|
|
73
|
+
Read `.brain/associations.json`. Find all edges involving the target ID:
|
|
74
|
+
- Outgoing: `edges[target_id][*]`
|
|
75
|
+
- Incoming: `edges[*][target_id]`
|
|
76
|
+
Record each edge with its neighbor, weight, and origin.
|
|
77
|
+
|
|
78
|
+
**3e. Context sessions (`contexts.json`):**
|
|
79
|
+
Read `.brain/contexts.json`. Search all sessions for the target ID in:
|
|
80
|
+
- `memories_created` arrays
|
|
81
|
+
- `memories_recalled` arrays
|
|
82
|
+
Record each session timestamp and which array contained the reference.
|
|
83
|
+
|
|
84
|
+
**3f. Review queue (`review-queue.json`):**
|
|
85
|
+
Read `.brain/review-queue.json`. Check if any item has `memory_id` equal to the target ID.
|
|
86
|
+
|
|
87
|
+
**3g. Archive index (`_archived/index.json`):**
|
|
88
|
+
Read `.brain/_archived/index.json`. Check if the target ID exists as a key in `memories`.
|
|
89
|
+
|
|
90
|
+
**3h. Crystallization comments:**
|
|
91
|
+
Search all memory files for HTML comments matching the pattern:
|
|
92
|
+
```
|
|
93
|
+
<!-- Crystallized into <target_id> -->
|
|
94
|
+
```
|
|
95
|
+
This catches episodic memories that were crystallized into the target.
|
|
96
|
+
|
|
97
|
+
### 4. Identify Derivative Memories
|
|
98
|
+
|
|
99
|
+
Derivatives are memories that exist *because of* the target and may not make sense without it:
|
|
100
|
+
|
|
101
|
+
**4a. Sole crystallization derivatives:**
|
|
102
|
+
If the target is an episodic memory, search for semantic memories whose sole source is the target — identified by:
|
|
103
|
+
- Their `related` array contains the target ID
|
|
104
|
+
- A crystallization comment `<!-- Crystallized into <derivative_id> -->` exists in the target
|
|
105
|
+
- The derivative's creation was triggered by the target (check if the derivative has no other source memories in its `related` array besides the target)
|
|
106
|
+
|
|
107
|
+
**4b. Sole consolidation derivatives:**
|
|
108
|
+
If a consolidated memory's `consolidated_from` array contains the target ID and the target is its **only** remaining source (after removing the target, 0 sources remain), it's a sole derivative.
|
|
109
|
+
|
|
110
|
+
**4c. Chain following (with `--deep`):**
|
|
111
|
+
If `--deep` is set, recursively check each derivative for its own derivatives. Maintain a `visited` set to prevent infinite loops on circular references.
|
|
112
|
+
|
|
113
|
+
### 5. Visualize Blast Radius
|
|
114
|
+
|
|
115
|
+
Present the complete blast radius to the user:
|
|
116
|
+
|
|
117
|
+
```
|
|
118
|
+
## Blast Radius: "<title>" (<id>)
|
|
119
|
+
|
|
120
|
+
### TARGET (will be deleted)
|
|
121
|
+
<id> | <path> | <type> | strength: <strength> | salience: <salience>
|
|
122
|
+
|
|
123
|
+
### DIRECT REFERENCES (will be cleaned) — <N> found
|
|
124
|
+
[REL] <path.md> — related: [..., <target_id>, ...]
|
|
125
|
+
[BODY] <path.md> — "<matching line snippet>"
|
|
126
|
+
[CONS] <path.md> — consolidated_from: [..., <target_id>, ...] (<M> sources remain)
|
|
127
|
+
[EDGE] <target_id> <-> <other_id> (weight: <w>, origin: <origin>)
|
|
128
|
+
[CTX] Session <timestamp> — in <memories_created|memories_recalled>
|
|
129
|
+
[REV] Review queue entry (next_review: <date>)
|
|
130
|
+
[ARCH] Archive index entry
|
|
131
|
+
[CRYS] <path.md> — <!-- Crystallized into <target_id> -->
|
|
132
|
+
|
|
133
|
+
### DERIVATIVES (may cascade) — <N> found
|
|
134
|
+
<derivative_id> | <path> — sole <crystallization|consolidation> derivative of target
|
|
135
|
+
<explanation of why this is a derivative>
|
|
136
|
+
|
|
137
|
+
### CONSOLIDATED REPAIRS — <N> needed
|
|
138
|
+
<path.md> — consolidated_from shrinks from <before> to <after> sources
|
|
139
|
+
⚠️ <path.md> — will have only 1 source remaining (flagged for review)
|
|
140
|
+
|
|
141
|
+
### SUMMARY
|
|
142
|
+
Files to modify: <count>
|
|
143
|
+
References to clean: <count>
|
|
144
|
+
Derivatives found: <count>
|
|
145
|
+
Risk level: <low|medium|high>
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
**Risk level:**
|
|
149
|
+
- **Low**: <=3 references, no derivatives
|
|
150
|
+
- **Medium**: 4-10 references, or derivatives present
|
|
151
|
+
- **High**: >10 references, or target has salience >= 0.7
|
|
152
|
+
|
|
153
|
+
If `--dry-run` is set, stop here. Print "Dry run complete — no changes made." and exit.
|
|
154
|
+
|
|
155
|
+
### 6. Confirm with User
|
|
156
|
+
|
|
157
|
+
**Standard confirmation:**
|
|
158
|
+
```
|
|
159
|
+
Proceed with erasure? This will modify <N> files and remove <M> references.
|
|
160
|
+
[yes / no / select specific items]
|
|
161
|
+
```
|
|
162
|
+
|
|
163
|
+
**High-salience confirmation** (salience >= 0.7):
|
|
164
|
+
```
|
|
165
|
+
⚠️ HIGH-SALIENCE MEMORY (salience: <value>)
|
|
166
|
+
This memory was marked as significant. To confirm erasure, type the memory ID:
|
|
167
|
+
> <user must type the ID>
|
|
168
|
+
```
|
|
169
|
+
|
|
170
|
+
**Derivative handling** (without `--cascade`):
|
|
171
|
+
For each derivative found, ask individually:
|
|
172
|
+
```
|
|
173
|
+
Derivative: "<derivative_title>" (<derivative_id>)
|
|
174
|
+
This memory was <crystallized from|solely consolidated from> the target.
|
|
175
|
+
[delete] Remove this derivative too
|
|
176
|
+
[keep] Keep it (remove only the reference to target)
|
|
177
|
+
[skip] Skip — decide later
|
|
178
|
+
```
|
|
179
|
+
|
|
180
|
+
With `--cascade`, all derivatives are automatically included in the erasure.
|
|
181
|
+
|
|
182
|
+
### 7. Execute Erasure
|
|
183
|
+
|
|
184
|
+
Execute in this exact order (dependencies matter):
|
|
185
|
+
|
|
186
|
+
**7a. Handle derivatives first** (if `--deep` and user approved):
|
|
187
|
+
For each derivative marked for deletion, recursively apply steps 7b-7g. Process deepest derivatives first (reverse topological order) to avoid dangling references.
|
|
188
|
+
|
|
189
|
+
**7b. Repair consolidated memories** (if `--deep`):
|
|
190
|
+
For each consolidated memory that lists the target in `consolidated_from`:
|
|
191
|
+
- Remove the target ID from the `consolidated_from` array
|
|
192
|
+
- Remove the target ID from the `related` array
|
|
193
|
+
- If 0 sources remain: this was caught as a derivative in Step 4
|
|
194
|
+
- If 1 source remains: add a warning comment to the file:
|
|
195
|
+
```
|
|
196
|
+
<!-- WARNING: This consolidated memory now has only 1 source after erasure of <target_id>. Consider reviewing. -->
|
|
197
|
+
```
|
|
198
|
+
- Update the corresponding `index.json` entry
|
|
199
|
+
|
|
200
|
+
**7c. Clean all direct references:**
|
|
201
|
+
|
|
202
|
+
1. **`related` arrays**: For each memory file containing the target ID in its `related` array, parse the frontmatter, remove the target ID from the array, and write the file back. Leave empty arrays as `related: []`.
|
|
203
|
+
|
|
204
|
+
2. **Content body mentions**: For each memory file with body mentions of the target ID or title:
|
|
205
|
+
- Remove lines that are solely a reference to the target (e.g., `Related to the X decision (mem_20260215_a3f2c1)`)
|
|
206
|
+
- In mixed-content lines, remove just the target reference (ID or parenthetical mention)
|
|
207
|
+
- If a `## Connections` section becomes empty, remove the section header too
|
|
208
|
+
|
|
209
|
+
3. **Association edges**: Remove all edges involving the target from `associations.json`. Use the `removeEdgesForMemory()` utility from `index-manager.js`. Write the updated file.
|
|
210
|
+
|
|
211
|
+
4. **Context sessions**: In `contexts.json`, for each session containing the target ID:
|
|
212
|
+
- Remove the target ID from `memories_created` and `memories_recalled` arrays
|
|
213
|
+
- Do NOT delete the session itself (other memories may reference it)
|
|
214
|
+
|
|
215
|
+
5. **Review queue**: Remove the target's entry from `review-queue.json`. Use the `removeFromReviewQueue()` utility from `index-manager.js`. Write the updated file.
|
|
216
|
+
|
|
217
|
+
6. **Archive index**: If the target exists in `_archived/index.json`, remove its entry and decrement `archived_count`. Write the updated file.
|
|
218
|
+
|
|
219
|
+
7. **Crystallization comments**: For each memory file containing `<!-- Crystallized into <target_id> -->`, remove the comment line.
|
|
220
|
+
|
|
221
|
+
**7d. Remove from `index.json`:**
|
|
222
|
+
Remove the target memory from `index.json` using `removeMemory()` from `index-manager.js`. Write the updated file.
|
|
223
|
+
|
|
224
|
+
**7e. Update `_meta.json` files:**
|
|
225
|
+
For each directory in the target's path, read the `_meta.json` and decrement `memory_count`. Write the updated file.
|
|
226
|
+
|
|
227
|
+
**7f. Delete target file:**
|
|
228
|
+
- If `--sensitive`: first overwrite the file content with null bytes (same byte length as original), then delete
|
|
229
|
+
- Otherwise: delete the file directly
|
|
230
|
+
- Clean up empty parent directories (but never delete top-level category directories)
|
|
231
|
+
|
|
232
|
+
**7g. Remove archived copy:**
|
|
233
|
+
If an archived copy exists at `.brain/_archived/<original-path>`, delete it.
|
|
234
|
+
- If `--sensitive`: overwrite with null bytes before deletion
|
|
235
|
+
- Clean up empty directories in `_archived/`
|
|
236
|
+
|
|
237
|
+
### 8. Write Audit Log
|
|
238
|
+
|
|
239
|
+
Unless `--no-trace` is set, write or append to `.brain/_erased.json`:
|
|
240
|
+
|
|
241
|
+
```json
|
|
242
|
+
{
|
|
243
|
+
"version": 1,
|
|
244
|
+
"erasures": [
|
|
245
|
+
{
|
|
246
|
+
"erased_id": "<memory_id>",
|
|
247
|
+
"erased_date": "<ISO timestamp>",
|
|
248
|
+
"reason": "<user-provided reason or 'unspecified'>",
|
|
249
|
+
"references_cleaned": <count>,
|
|
250
|
+
"derivatives_removed": <count>,
|
|
251
|
+
"consolidated_repaired": <count>,
|
|
252
|
+
"flags_used": ["<flags that were active>"]
|
|
253
|
+
}
|
|
254
|
+
]
|
|
255
|
+
}
|
|
256
|
+
```
|
|
257
|
+
|
|
258
|
+
If the file already exists, read it, append the new entry to the `erasures` array, and write back.
|
|
259
|
+
|
|
260
|
+
**IMPORTANT**: The audit log intentionally omits the memory title, content, tags, path, or any identifying information. It proves an erasure happened for audit purposes without preserving what was erased.
|
|
261
|
+
|
|
262
|
+
### 9. Post-Erasure Integrity Check
|
|
263
|
+
|
|
264
|
+
After erasure, perform a quick integrity scan:
|
|
265
|
+
|
|
266
|
+
1. **Dangling references**: Grep all memory files for the erased ID. If any remain, report them as warnings.
|
|
267
|
+
2. **Orphaned associations**: Check `associations.json` for any edges pointing to the erased ID.
|
|
268
|
+
3. **Index consistency**: Verify `memory_count` in `index.json` matches the actual number of entries in `memories`.
|
|
269
|
+
4. **Empty directories**: Report any empty directories that may need cleanup.
|
|
270
|
+
|
|
271
|
+
If any issues are found:
|
|
272
|
+
```
|
|
273
|
+
⚠️ Post-erasure integrity issues:
|
|
274
|
+
- <description of issue>
|
|
275
|
+
|
|
276
|
+
These can be fixed by running /brain:sleep.
|
|
277
|
+
```
|
|
278
|
+
|
|
279
|
+
### 10. Confirm
|
|
280
|
+
|
|
281
|
+
Print a summary:
|
|
282
|
+
|
|
283
|
+
```
|
|
284
|
+
## Erasure Complete: "<title>"
|
|
285
|
+
|
|
286
|
+
Memory deleted: <id>
|
|
287
|
+
References cleaned: <count> across <file_count> files
|
|
288
|
+
Derivatives removed: <count>
|
|
289
|
+
Consolidated memories repaired: <count>
|
|
290
|
+
Audit log: <written to _erased.json | skipped (--no-trace)>
|
|
291
|
+
|
|
292
|
+
Brain stats: <total_memories> memories, average strength <avg>
|
|
293
|
+
|
|
294
|
+
The memory has been fully erased. All traces have been removed
|
|
295
|
+
from the associative network, context logs, review queue, and
|
|
296
|
+
cross-references in other memories.
|
|
297
|
+
```
|
|
298
|
+
|
|
299
|
+
## Edge Cases
|
|
300
|
+
|
|
301
|
+
1. **Memory already archived**: Still perform the full blast radius scan. The target may have references in active memories, associations, contexts, and the review queue even though it's in the archive. Clean all references, then remove the archived copy.
|
|
302
|
+
|
|
303
|
+
2. **Memory not found**: Check `_erased.json` first. If found there, report the previous erasure date and reason. If not found anywhere, report clearly and suggest checking the ID/title spelling.
|
|
304
|
+
|
|
305
|
+
3. **Circular references**: When following derivative chains with `--deep`, maintain a `visited` set. If a memory has already been visited, skip it and note the cycle.
|
|
306
|
+
|
|
307
|
+
4. **High-salience memories (salience >= 0.7)**: Require double confirmation — the user must type the memory ID to proceed. This prevents accidental erasure of important memories.
|
|
308
|
+
|
|
309
|
+
5. **Consolidated memory loses ALL sources**: This is caught as a sole consolidation derivative in Step 4. With `--deep`, it's removed. Without `--deep`, warn prominently:
|
|
310
|
+
```
|
|
311
|
+
⚠️ CRITICAL: "<consolidated_title>" will have ZERO sources after erasure.
|
|
312
|
+
This consolidated memory only existed because of the target.
|
|
313
|
+
Recommend: use --deep to handle this, or manually review.
|
|
314
|
+
```
|
|
315
|
+
|
|
316
|
+
6. **Consolidated memory left with 1 source**: Add a warning comment to the file and flag in the output. The memory is still valid but may benefit from review.
|
|
317
|
+
|
|
318
|
+
7. **Empty `related` arrays after cleanup**: Leave as `related: []`. Do not remove the field entirely — it maintains schema consistency.
|
|
319
|
+
|
|
320
|
+
8. **Memory referenced by memories outside `.brain/`**: This command only operates within `.brain/`. If external files (e.g., `CLAUDE.md`, project docs) reference the memory, note this limitation in the summary.
|
|
321
|
+
|
|
322
|
+
9. **Multiple memories matching a title substring**: Present all matches with their IDs, paths, and strengths. Ask the user to select the specific memory to erase.
|
|
323
|
+
|
|
324
|
+
10. **Target is itself a consolidated memory**: Its `consolidated_from` sources (if archived) are NOT affected — they remain in the archive. Only forward references are cleaned.
|
|
325
|
+
|
|
326
|
+
## Important Rules
|
|
327
|
+
|
|
328
|
+
1. **Always confirm before executing**. Never erase without explicit user approval. High-salience memories require typing the ID.
|
|
329
|
+
2. **Order matters**. Follow the execution order in Step 7 exactly — derivatives first, then repairs, then references, then index, then file deletion.
|
|
330
|
+
3. **Audit by default**. Always write to `_erased.json` unless `--no-trace` is explicitly set. The audit log contains no identifying information about the erased memory.
|
|
331
|
+
4. **No collateral damage**. Only remove references to the specific target. Never modify content unrelated to the target memory.
|
|
332
|
+
5. **Preserve other memories' integrity**. When editing other memories' frontmatter or content, preserve all other fields and content exactly.
|
|
333
|
+
6. **Sensitive data handling**. With `--sensitive`, overwrite file content before deletion to prevent filesystem-level recovery.
|
|
334
|
+
7. **Integrity check is mandatory**. Always run the post-erasure integrity check, even if no issues are expected.
|
|
335
|
+
8. **Recursive safety**. When processing derivatives with `--deep --cascade`, always maintain a `visited` set to prevent infinite loops.
|
|
336
|
+
9. **Never delete top-level category directories**. Even if they become empty after erasure, preserve `professional/`, `personal/`, `social/`, `family/`, `_consolidated/`, and `_archived/`.
|
|
337
|
+
10. **Context sessions are preserved**. Remove memory IDs from session arrays, but never delete the session entry itself.
|
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
# Brain Memory — Session End Hook
|
|
2
|
+
|
|
3
|
+
This hook is triggered at the end of a coding session. Its purpose is to prompt the agent to consider storing important memories and to save session context.
|
|
4
|
+
|
|
5
|
+
## Behavior
|
|
6
|
+
|
|
7
|
+
### Memory Suggestion
|
|
8
|
+
|
|
9
|
+
When a session ends, evaluate whether the session contained any of the following:
|
|
10
|
+
|
|
11
|
+
1. **Decisions** — Architecture choices, technology selections, trade-off resolutions
|
|
12
|
+
2. **Learnings** — New patterns, debugging insights, API discoveries
|
|
13
|
+
3. **Insights** — Realizations about the codebase, project, or process
|
|
14
|
+
4. **Experiences** — Significant events like incidents, deployments, milestones
|
|
15
|
+
5. **Goals** — New objectives discussed or planned
|
|
16
|
+
|
|
17
|
+
If the session contained meaningful content in any of these categories, suggest to the user:
|
|
18
|
+
|
|
19
|
+
```
|
|
20
|
+
💡 This session contained notable <type(s)>. Would you like to store them as brain memories?
|
|
21
|
+
Run /brain:memorize to capture them before this context is lost.
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
### Session Context Capture
|
|
25
|
+
|
|
26
|
+
If `.brain/contexts.json` exists, append a session summary:
|
|
27
|
+
|
|
28
|
+
```json
|
|
29
|
+
{
|
|
30
|
+
"session_id": "<timestamp-based-id>",
|
|
31
|
+
"started": "<session start ISO timestamp>",
|
|
32
|
+
"ended": "<session end ISO timestamp>",
|
|
33
|
+
"project": "<current project name>",
|
|
34
|
+
"topics": ["<key topics discussed>"],
|
|
35
|
+
"task_type": "<primary task type: debugging|implementing|designing|reviewing|discussing|learning>",
|
|
36
|
+
"memories_created": ["<IDs of memories stored this session>"],
|
|
37
|
+
"memories_recalled": ["<IDs of memories retrieved this session>"]
|
|
38
|
+
}
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
Keep only the last 20 session entries in `contexts.json` to prevent unbounded growth.
|
|
42
|
+
|
|
43
|
+
**Rules:**
|
|
44
|
+
- Do NOT auto-memorize without user consent
|
|
45
|
+
- Do NOT prompt for trivial sessions (quick fixes, typo corrections, simple questions)
|
|
46
|
+
- Only suggest when there is genuinely valuable context worth preserving
|
|
47
|
+
- Keep the suggestion brief and non-intrusive
|
|
48
|
+
- Always save session context to `contexts.json` regardless of whether the user memorizes anything
|
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
# Brain Memory — Session Start Hook
|
|
2
|
+
|
|
3
|
+
This hook is triggered at the start of a coding session. Its purpose is to load relevant context from the brain memory system and capture session context for context-dependent recall.
|
|
4
|
+
|
|
5
|
+
## Behavior
|
|
6
|
+
|
|
7
|
+
At session start, if `.brain/index.json` exists:
|
|
8
|
+
|
|
9
|
+
1. **Read the index** to understand the current brain state
|
|
10
|
+
2. **Identify high-value memories** — the top 3-5 memories by effective strength that are relevant to the current project
|
|
11
|
+
3. **Silently load context** — internalize these memories so you can reference them naturally during the session
|
|
12
|
+
4. **Do NOT dump memories** — do not print memory contents at session start unless the user asks
|
|
13
|
+
|
|
14
|
+
### Context Capture
|
|
15
|
+
|
|
16
|
+
Capture the current session context for context-dependent recall:
|
|
17
|
+
- **Project name**: from the current working directory or project config
|
|
18
|
+
- **Topics**: inferred from recent files, open issues, or conversation
|
|
19
|
+
- **Task type**: will be determined as the session progresses
|
|
20
|
+
|
|
21
|
+
This context is used by `/brain:remember` to boost memories that were encoded in a similar context.
|
|
22
|
+
|
|
23
|
+
### Review Queue Check
|
|
24
|
+
|
|
25
|
+
Read `.brain/review-queue.json` if it exists. If there are memories due for review:
|
|
26
|
+
|
|
27
|
+
```
|
|
28
|
+
🧠 Brain active — <N> memories loaded (<M> in current project context)
|
|
29
|
+
📋 <X> memories due for review — run /brain:review
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
Otherwise:
|
|
33
|
+
|
|
34
|
+
```
|
|
35
|
+
🧠 Brain active — <N> memories loaded (<M> in current project context)
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
### Low-Confidence Alert
|
|
39
|
+
|
|
40
|
+
If any frequently-used memories (access_count >= 3) have confidence < 0.5, briefly note:
|
|
41
|
+
|
|
42
|
+
```
|
|
43
|
+
⚠️ <N> frequently-used memories have low confidence — consider verifying
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
**The goal is ambient awareness** — you should know about important past decisions, learnings, and preferences without explicitly reciting them. If a situation arises where a past memory is relevant, naturally reference it.
|
|
47
|
+
|
|
48
|
+
Keep the status output to 1-3 lines. The user can run `/brain:status` for details.
|
package/package.json
ADDED
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "brain-memory",
|
|
3
|
+
"version": "0.1.0-beta.1",
|
|
4
|
+
"description": "A brain-inspired hierarchical memory system for AI coding agents. Deep nested file structure that mimics human memory with time-decay and strength-based recall.",
|
|
5
|
+
"keywords": [
|
|
6
|
+
"claude-code",
|
|
7
|
+
"gemini-cli",
|
|
8
|
+
"openai-codex",
|
|
9
|
+
"memory",
|
|
10
|
+
"ai-agent",
|
|
11
|
+
"context-engineering",
|
|
12
|
+
"hierarchical-memory"
|
|
13
|
+
],
|
|
14
|
+
"author": {
|
|
15
|
+
"name": "Onur Karali",
|
|
16
|
+
"email": "onur@omelas.tech"
|
|
17
|
+
},
|
|
18
|
+
"homepage": "https://github.com/onurkarali/brain#readme",
|
|
19
|
+
"bugs": {
|
|
20
|
+
"url": "https://github.com/onurkarali/brain/issues"
|
|
21
|
+
},
|
|
22
|
+
"bin": {
|
|
23
|
+
"brain-memory": "bin/install.js"
|
|
24
|
+
},
|
|
25
|
+
"files": [
|
|
26
|
+
"bin/",
|
|
27
|
+
"commands/",
|
|
28
|
+
"prompts/",
|
|
29
|
+
"templates/",
|
|
30
|
+
"hooks/",
|
|
31
|
+
"src/",
|
|
32
|
+
"README.md",
|
|
33
|
+
"LICENSE"
|
|
34
|
+
],
|
|
35
|
+
"repository": {
|
|
36
|
+
"type": "git",
|
|
37
|
+
"url": "git+https://github.com/onurkarali/brain.git"
|
|
38
|
+
},
|
|
39
|
+
"scripts": {
|
|
40
|
+
"test": "node --test 'test/*.test.js'"
|
|
41
|
+
},
|
|
42
|
+
"license": "MIT",
|
|
43
|
+
"engines": {
|
|
44
|
+
"node": ">=18.0.0"
|
|
45
|
+
}
|
|
46
|
+
}
|
|
@@ -0,0 +1,75 @@
|
|
|
1
|
+
# Brain Memory System
|
|
2
|
+
|
|
3
|
+
This project uses the **Brain Memory** plugin — a hierarchical, file-system-based memory system that mimics human cognition with neuroscience-inspired mechanisms including associative networks, spreading activation, context-dependent recall, spaced reinforcement, and cognitive memory types.
|
|
4
|
+
|
|
5
|
+
## Memory Location
|
|
6
|
+
|
|
7
|
+
All memories are stored in `.brain/` with a deep nested directory structure organized by life domains (professional, personal, social, family) with on-demand subcategories.
|
|
8
|
+
|
|
9
|
+
## How It Works
|
|
10
|
+
|
|
11
|
+
### Memory Format
|
|
12
|
+
Each memory is a Markdown file with YAML frontmatter containing: `id`, `type`, `cognitive_type` (episodic/semantic/procedural), `created`, `last_accessed`, `access_count`, `recall_history`, `strength` (0.0-1.0), `decay_rate` (per day), `salience` (0.0-1.0), `confidence` (0.0-1.0), `tags`, `related` memory IDs, `source`, and `encoding_context`.
|
|
13
|
+
|
|
14
|
+
### Strength & Decay Model
|
|
15
|
+
- Memories have a base `strength` set at creation based on their impact/type/cognitive type
|
|
16
|
+
- Strength decays over time: `effective = strength * (decay_rate ^ days_since_access)`
|
|
17
|
+
- Recalled memories get **stronger** via spaced reinforcement — the longer since last recall, the bigger the boost
|
|
18
|
+
- Memories become progressively more forgetting-resistant with each recall (decay_rate improves)
|
|
19
|
+
- Weak memories can be consolidated into stronger combined memories
|
|
20
|
+
- During sleep, global synaptic homeostasis prevents strength inflation
|
|
21
|
+
|
|
22
|
+
### Cognitive Types
|
|
23
|
+
- **Episodic** — Event-specific memories. Higher initial strength, faster decay. The details fade but lessons persist.
|
|
24
|
+
- **Semantic** — Abstracted knowledge. Default decay. Stable long-term storage.
|
|
25
|
+
- **Procedural** — Skills and workflows. Lower initial strength but extremely slow decay once established.
|
|
26
|
+
|
|
27
|
+
### Memory Types & Default Strengths
|
|
28
|
+
| Type | Strength | Decay/day | Description |
|
|
29
|
+
|------|----------|-----------|-------------|
|
|
30
|
+
| decision | 0.85 | 0.995 | Choices made and rationale |
|
|
31
|
+
| insight | 0.90 | 0.997 | Deep realizations, patterns |
|
|
32
|
+
| goal | 0.80 | 0.993 | Objectives and aspirations |
|
|
33
|
+
| experience | 0.75 | 0.985 | Notable events or processes |
|
|
34
|
+
| learning | 0.70 | 0.990 | New knowledge acquired |
|
|
35
|
+
| relationship | 0.70 | 0.997 | Connections between entities |
|
|
36
|
+
| preference | 0.60 | 0.998 | User preferences and style |
|
|
37
|
+
| observation | 0.40 | 0.950 | Casual facts or notices |
|
|
38
|
+
|
|
39
|
+
### Associative Network
|
|
40
|
+
Memories are connected via weighted edges in `.brain/associations.json`. When you recall memory A, **spreading activation** automatically surfaces related memories B and C — just like how the brain activates linked neurons. Links are strengthened through **Hebbian learning**: memories recalled together become more tightly connected over time.
|
|
41
|
+
|
|
42
|
+
### Context-Dependent Recall
|
|
43
|
+
Memories store their encoding context (project, topics, task type). During recall, memories encoded in a similar context to the current session are scored higher — matching how human memory works better when recall context matches encoding context.
|
|
44
|
+
|
|
45
|
+
### Salience & Confidence
|
|
46
|
+
- **Salience** (0.0-1.0): Emotional/motivational significance. High-salience memories (>= 0.7) are never auto-pruned.
|
|
47
|
+
- **Confidence** (0.0-1.0): Epistemic certainty. Low-confidence memories are flagged during recall.
|
|
48
|
+
|
|
49
|
+
## Available Commands
|
|
50
|
+
|
|
51
|
+
- `/brain:init` — Initialize the brain structure
|
|
52
|
+
- `/brain:memorize [topic]` — Store memories from current context
|
|
53
|
+
- `/brain:remember [query]` — Recall relevant memories with spreading activation and context matching
|
|
54
|
+
- `/brain:review [scope]` — Spaced repetition review session for due memories
|
|
55
|
+
- `/brain:explore [category]` — Browse the brain hierarchy
|
|
56
|
+
- `/brain:consolidate [scope]` — Merge related weak memories into stronger ones
|
|
57
|
+
- `/brain:forget [target]` — Decay or archive memories
|
|
58
|
+
- `/brain:sunshine [target]` — Deep forensic erasure — trace and remove all references to a memory
|
|
59
|
+
- `/brain:sleep [scope]` — Full maintenance cycle: replay, synaptic homeostasis, knowledge propagation, semantic crystallization, reorganize, consolidate, prune, REM dreaming, and expertise detection
|
|
60
|
+
- `/brain:status` — Dashboard with brain health overview
|
|
61
|
+
|
|
62
|
+
## Auto-Memorize Guidance
|
|
63
|
+
|
|
64
|
+
At the end of significant sessions, consider suggesting `/brain:memorize` to the user if important decisions, learnings, or insights occurred during the conversation. Do NOT automatically memorize without the user's awareness.
|
|
65
|
+
|
|
66
|
+
## When Recalling Memories
|
|
67
|
+
|
|
68
|
+
When the user asks you to "remember" something, or when context from past sessions would be helpful:
|
|
69
|
+
1. Check `.brain/index.json` for relevant memories
|
|
70
|
+
2. Load `.brain/associations.json` for spreading activation
|
|
71
|
+
3. Score by v4 formula: `0.38*relevance + 0.18*decayed_strength + 0.08*recency + 0.14*spreading_bonus + 0.14*context_match + 0.08*salience`
|
|
72
|
+
4. Return strong individual matches or synthesize from multiple related memories
|
|
73
|
+
5. Apply spaced reinforcement (spacing-aware boost) and improve decay rate
|
|
74
|
+
6. Strengthen Hebbian links between co-retrieved memories
|
|
75
|
+
7. If no active matches, search the archive (`.brain/_archived/`)
|