brain-memory 0.1.0-beta.21 → 0.1.0-beta.24

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.
@@ -1,135 +0,0 @@
1
- ---
2
- description: Spaced-repetition review session for memories due for reinforcement
3
- argument-hint: "[scope]"
4
- ---
5
-
6
- # /brain:review — Spaced Repetition Review
7
-
8
- You are conducting a spaced repetition review session. This command surfaces memories that are due for review based on optimal spacing intervals, measures recall quality, and schedules the next review. Regular review sessions dramatically improve long-term retention.
9
-
10
- **Scope:** $ARGUMENTS
11
-
12
- ## Overview
13
-
14
- This implements a simplified SM-2 (SuperMemo 2) spaced repetition algorithm. Memories are scheduled for review at increasing intervals based on how well they are recalled. Well-recalled memories are reviewed less frequently; poorly-recalled memories are reviewed more often.
15
-
16
- ## Steps
17
-
18
- ### 1. Load Review Queue
19
-
20
- Read `~/.brain/review-queue.json`. If it doesn't exist or is empty, generate it:
21
- - Scan all memories in `index.json`
22
- - For memories with `access_count > 0`, calculate initial review schedule
23
- - For memories never recalled, add with `next_review` = now (immediate first review)
24
- - If $ARGUMENTS specifies a category path, limit to that subtree
25
-
26
- ### 2. Find Due Memories
27
-
28
- Filter the review queue for items where `next_review <= now`.
29
-
30
- If no memories are due:
31
- ```
32
- ## No Memories Due for Review
33
-
34
- Next review due: <soonest date>
35
- Total in queue: <count>
36
-
37
- Run /brain:status for a full overview.
38
- ```
39
-
40
- ### 3. Present Review Session
41
-
42
- For each due memory (process up to 10 per session):
43
-
44
- 1. **Present the memory's title and path** (but NOT the full content initially):
45
- ```
46
- ### Review 1 of <N>
47
-
48
- **Memory:** <title>
49
- **Path:** ~/.brain/<path>
50
- **Type:** <type> (<cognitive_type>) | **Last reviewed:** <date> | **Interval:** <days>d
51
- **Confidence:** <confidence>
52
-
53
- Can you recall what this memory is about? Try to remember before seeing the content.
54
- ```
55
-
56
- 2. **Reveal the full content** after the user responds (or on request):
57
- ```
58
- <full memory content>
59
- ```
60
-
61
- 3. **Ask for recall quality** (1-5 scale):
62
- - **5 — Perfect**: Recalled immediately and completely
63
- - **4 — Good**: Recalled with minor effort
64
- - **3 — Okay**: Recalled with significant effort
65
- - **2 — Poor**: Could barely recall, needed heavy hints
66
- - **1 — Failed**: Could not recall at all
67
-
68
- ### 4. Update Based on Recall Quality
69
-
70
- For each reviewed memory, update using the SM-2 algorithm:
71
-
72
- **Ease factor adjustment:**
73
- ```
74
- new_ease = ease_factor + (0.1 - (5 - quality) * (0.08 + (5 - quality) * 0.02))
75
- ease_factor = max(1.3, new_ease)
76
- ```
77
-
78
- **Interval calculation:**
79
- ```
80
- if quality >= 3: // Successful recall
81
- if review_count == 0: interval = 1
82
- elif review_count == 1: interval = 6
83
- else: interval = previous_interval * ease_factor
84
- else: // Failed recall
85
- interval = 1 // Reset to 1 day
86
- review_count = 0 // Reset review count
87
- ```
88
-
89
- **Update memory:**
90
- - `last_accessed` → current timestamp
91
- - `access_count` → increment by 1
92
- - `recall_history` → append current timestamp
93
- - Apply spaced reinforcement to `strength` (same formula as /brain:remember)
94
- - Improve `decay_rate` on successful recall (quality >= 3)
95
-
96
- **Update review queue entry:**
97
- ```json
98
- {
99
- "memory_id": "<id>",
100
- "next_review": "<now + interval days>",
101
- "interval_days": <interval>,
102
- "ease_factor": <ease_factor>,
103
- "review_count": <review_count + 1>
104
- }
105
- ```
106
-
107
- ### 5. Session Summary
108
-
109
- After reviewing all due memories:
110
-
111
- ```
112
- ## Review Session Complete
113
-
114
- Reviewed: <N> memories
115
- Perfect (5): <count>
116
- Good (4): <count>
117
- Okay (3): <count>
118
- Poor (2): <count>
119
- Failed (1): <count>
120
-
121
- Average recall quality: <avg>
122
- Next review due: <soonest date>
123
- Remaining in queue: <count>
124
-
125
- Memories strengthened through review — keep it up!
126
- ```
127
-
128
- ## Rules
129
-
130
- 1. **Never skip the recall attempt** — always present the title first and let the user try to recall before revealing content
131
- 2. **Be encouraging** — spaced repetition is about building long-term retention, not testing
132
- 3. **Update everything** — update the memory file, index.json, review-queue.json, and associations.json (reinforce edges between co-reviewed memories)
133
- 4. **Respect scope** — if $ARGUMENTS specifies a category, only review memories in that subtree
134
- 5. **Session limit** — review at most 10 memories per session to avoid fatigue
135
- 6. **Failed recalls** — for quality 1-2, suggest the user re-read the memory and offer to update it if the information is outdated
@@ -1,342 +0,0 @@
1
- ---
2
- description: Deep forensic erasure — trace and remove all references to a memory
3
- argument-hint: "[target]"
4
- ---
5
-
6
- # /brain:sunshine — Deep Forensic Memory Erasure
7
-
8
- 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.
9
-
10
- 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.
11
-
12
- **Target:** $ARGUMENTS
13
-
14
- ## Flags
15
-
16
- | Flag | Behavior |
17
- |------|----------|
18
- | *(default)* | Remove target + clean all direct references. Ask about derivatives individually |
19
- | `--deep` | Also handle derivative memories and repair consolidated memories that lose sources |
20
- | `--dry-run` | Show blast radius only — no changes are made |
21
- | `--cascade` | With `--deep`, auto-remove derivative memories without asking |
22
- | `--sensitive` | Overwrite file content with null bytes before deletion (for credentials, secrets) |
23
- | `--no-trace` | Skip writing to `_erased.json` audit log |
24
- | `--reason "<text>"` | Reason recorded in audit log entry |
25
-
26
- ## Steps
27
-
28
- ### 1. Parse Target and Flags
29
-
30
- Extract:
31
- - **Target identifier**: memory ID (e.g., `mem_20260215_a3f2c1`), title substring, or file path
32
- - **Flags**: `--deep`, `--dry-run`, `--cascade`, `--sensitive`, `--no-trace`, `--reason`
33
-
34
- If no target is provided, ask the user what memory they want to erase.
35
-
36
- ### 2. Locate Target Memory
37
-
38
- Search for the target memory:
39
-
40
- 1. Read `~/.brain/index.json` and search `memories` by:
41
- - Exact ID match
42
- - Title substring match (case-insensitive)
43
- - Path substring match
44
- 2. If not found in active memories, check `~/.brain/_archived/index.json`
45
- 3. If still not found, check `~/.brain/_erased.json` — if found there, report:
46
- ```
47
- Memory was previously erased on <date>.
48
- Reason: <reason or "unspecified">
49
- No further action needed.
50
- ```
51
- 4. If not found anywhere, report and stop.
52
- 5. If multiple matches, present them and ask the user to pick one.
53
-
54
- Once located, read the full memory file to capture its ID, title, path, tags, `related` array, `consolidated_from` array, and content.
55
-
56
- ### 3. Trace All References (Blast Radius Scan)
57
-
58
- Scan the entire `~/.brain/` tree for every trace of the target memory. Track 8 reference types:
59
-
60
- **3a. `related` arrays in other memories' frontmatter:**
61
- Parse the YAML frontmatter of every `.md` memory file in `~/.brain/`. For each file whose `related` array contains the target ID, record:
62
- - File path
63
- - Current `related` array contents
64
-
65
- **3b. Content body mentions:**
66
- Search the Markdown body (below frontmatter) of all memory files for:
67
- - The target memory ID (e.g., `mem_20260215_a3f2c1`)
68
- - The target memory title (exact match)
69
- Record each file path and the matching line.
70
-
71
- **3c. `consolidated_from` arrays:**
72
- Among all memory files with `type: consolidated`, check if their `consolidated_from` array contains the target ID. Record:
73
- - File path
74
- - Full `consolidated_from` array
75
- - Number of other sources remaining
76
-
77
- **3d. Association edges (`associations.json`):**
78
- Read `~/.brain/associations.json`. Find all edges involving the target ID:
79
- - Outgoing: `edges[target_id][*]`
80
- - Incoming: `edges[*][target_id]`
81
- Record each edge with its neighbor, weight, and origin.
82
-
83
- **3e. Context sessions (`contexts.json`):**
84
- Read `~/.brain/contexts.json`. Search all sessions for the target ID in:
85
- - `memories_created` arrays
86
- - `memories_recalled` arrays
87
- Record each session timestamp and which array contained the reference.
88
-
89
- **3f. Review queue (`review-queue.json`):**
90
- Read `~/.brain/review-queue.json`. Check if any item has `memory_id` equal to the target ID.
91
-
92
- **3g. Archive index (`_archived/index.json`):**
93
- Read `~/.brain/_archived/index.json`. Check if the target ID exists as a key in `memories`.
94
-
95
- **3h. Crystallization comments:**
96
- Search all memory files for HTML comments matching the pattern:
97
- ```
98
- <!-- Crystallized into <target_id> -->
99
- ```
100
- This catches episodic memories that were crystallized into the target.
101
-
102
- ### 4. Identify Derivative Memories
103
-
104
- Derivatives are memories that exist *because of* the target and may not make sense without it:
105
-
106
- **4a. Sole crystallization derivatives:**
107
- If the target is an episodic memory, search for semantic memories whose sole source is the target — identified by:
108
- - Their `related` array contains the target ID
109
- - A crystallization comment `<!-- Crystallized into <derivative_id> -->` exists in the target
110
- - 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)
111
-
112
- **4b. Sole consolidation derivatives:**
113
- 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.
114
-
115
- **4c. Chain following (with `--deep`):**
116
- If `--deep` is set, recursively check each derivative for its own derivatives. Maintain a `visited` set to prevent infinite loops on circular references.
117
-
118
- ### 5. Visualize Blast Radius
119
-
120
- Present the complete blast radius to the user:
121
-
122
- ```
123
- ## Blast Radius: "<title>" (<id>)
124
-
125
- ### TARGET (will be deleted)
126
- <id> | <path> | <type> | strength: <strength> | salience: <salience>
127
-
128
- ### DIRECT REFERENCES (will be cleaned) — <N> found
129
- [REL] <path.md> — related: [..., <target_id>, ...]
130
- [BODY] <path.md> — "<matching line snippet>"
131
- [CONS] <path.md> — consolidated_from: [..., <target_id>, ...] (<M> sources remain)
132
- [EDGE] <target_id> <-> <other_id> (weight: <w>, origin: <origin>)
133
- [CTX] Session <timestamp> — in <memories_created|memories_recalled>
134
- [REV] Review queue entry (next_review: <date>)
135
- [ARCH] Archive index entry
136
- [CRYS] <path.md> — <!-- Crystallized into <target_id> -->
137
-
138
- ### DERIVATIVES (may cascade) — <N> found
139
- <derivative_id> | <path> — sole <crystallization|consolidation> derivative of target
140
- <explanation of why this is a derivative>
141
-
142
- ### CONSOLIDATED REPAIRS — <N> needed
143
- <path.md> — consolidated_from shrinks from <before> to <after> sources
144
- ⚠️ <path.md> — will have only 1 source remaining (flagged for review)
145
-
146
- ### SUMMARY
147
- Files to modify: <count>
148
- References to clean: <count>
149
- Derivatives found: <count>
150
- Risk level: <low|medium|high>
151
- ```
152
-
153
- **Risk level:**
154
- - **Low**: <=3 references, no derivatives
155
- - **Medium**: 4-10 references, or derivatives present
156
- - **High**: >10 references, or target has salience >= 0.7
157
-
158
- If `--dry-run` is set, stop here. Print "Dry run complete — no changes made." and exit.
159
-
160
- ### 6. Confirm with User
161
-
162
- **Standard confirmation:**
163
- ```
164
- Proceed with erasure? This will modify <N> files and remove <M> references.
165
- [yes / no / select specific items]
166
- ```
167
-
168
- **High-salience confirmation** (salience >= 0.7):
169
- ```
170
- ⚠️ HIGH-SALIENCE MEMORY (salience: <value>)
171
- This memory was marked as significant. To confirm erasure, type the memory ID:
172
- > <user must type the ID>
173
- ```
174
-
175
- **Derivative handling** (without `--cascade`):
176
- For each derivative found, ask individually:
177
- ```
178
- Derivative: "<derivative_title>" (<derivative_id>)
179
- This memory was <crystallized from|solely consolidated from> the target.
180
- [delete] Remove this derivative too
181
- [keep] Keep it (remove only the reference to target)
182
- [skip] Skip — decide later
183
- ```
184
-
185
- With `--cascade`, all derivatives are automatically included in the erasure.
186
-
187
- ### 7. Execute Erasure
188
-
189
- Execute in this exact order (dependencies matter):
190
-
191
- **7a. Handle derivatives first** (if `--deep` and user approved):
192
- For each derivative marked for deletion, recursively apply steps 7b-7g. Process deepest derivatives first (reverse topological order) to avoid dangling references.
193
-
194
- **7b. Repair consolidated memories** (if `--deep`):
195
- For each consolidated memory that lists the target in `consolidated_from`:
196
- - Remove the target ID from the `consolidated_from` array
197
- - Remove the target ID from the `related` array
198
- - If 0 sources remain: this was caught as a derivative in Step 4
199
- - If 1 source remains: add a warning comment to the file:
200
- ```
201
- <!-- WARNING: This consolidated memory now has only 1 source after erasure of <target_id>. Consider reviewing. -->
202
- ```
203
- - Update the corresponding `index.json` entry
204
-
205
- **7c. Clean all direct references:**
206
-
207
- 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: []`.
208
-
209
- 2. **Content body mentions**: For each memory file with body mentions of the target ID or title:
210
- - Remove lines that are solely a reference to the target (e.g., `Related to the X decision (mem_20260215_a3f2c1)`)
211
- - In mixed-content lines, remove just the target reference (ID or parenthetical mention)
212
- - If a `## Connections` section becomes empty, remove the section header too
213
-
214
- 3. **Association edges**: Remove all edges involving the target from `associations.json`. Use the `removeEdgesForMemory()` utility from `index-manager.js`. Write the updated file.
215
-
216
- 4. **Context sessions**: In `contexts.json`, for each session containing the target ID:
217
- - Remove the target ID from `memories_created` and `memories_recalled` arrays
218
- - Do NOT delete the session itself (other memories may reference it)
219
-
220
- 5. **Review queue**: Remove the target's entry from `review-queue.json`. Use the `removeFromReviewQueue()` utility from `index-manager.js`. Write the updated file.
221
-
222
- 6. **Archive index**: If the target exists in `_archived/index.json`, remove its entry and decrement `archived_count`. Write the updated file.
223
-
224
- 7. **Crystallization comments**: For each memory file containing `<!-- Crystallized into <target_id> -->`, remove the comment line.
225
-
226
- **7d. Remove from `index.json`:**
227
- Remove the target memory from `index.json` using `removeMemory()` from `index-manager.js`. Write the updated file.
228
-
229
- **7e. Update `_meta.json` files:**
230
- For each directory in the target's path, read the `_meta.json` and decrement `memory_count`. Write the updated file.
231
-
232
- **7f. Delete target file:**
233
- - If `--sensitive`: first overwrite the file content with null bytes (same byte length as original), then delete
234
- - Otherwise: delete the file directly
235
- - Clean up empty parent directories (but never delete top-level category directories)
236
-
237
- **7g. Remove archived copy:**
238
- If an archived copy exists at `~/.brain/_archived/<original-path>`, delete it.
239
- - If `--sensitive`: overwrite with null bytes before deletion
240
- - Clean up empty directories in `_archived/`
241
-
242
- ### 8. Write Audit Log
243
-
244
- Unless `--no-trace` is set, write or append to `~/.brain/_erased.json`:
245
-
246
- ```json
247
- {
248
- "version": 1,
249
- "erasures": [
250
- {
251
- "erased_id": "<memory_id>",
252
- "erased_date": "<ISO timestamp>",
253
- "reason": "<user-provided reason or 'unspecified'>",
254
- "references_cleaned": <count>,
255
- "derivatives_removed": <count>,
256
- "consolidated_repaired": <count>,
257
- "flags_used": ["<flags that were active>"]
258
- }
259
- ]
260
- }
261
- ```
262
-
263
- If the file already exists, read it, append the new entry to the `erasures` array, and write back.
264
-
265
- **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.
266
-
267
- ### 9. Post-Erasure Integrity Check
268
-
269
- After erasure, perform a quick integrity scan:
270
-
271
- 1. **Dangling references**: Grep all memory files for the erased ID. If any remain, report them as warnings.
272
- 2. **Orphaned associations**: Check `associations.json` for any edges pointing to the erased ID.
273
- 3. **Index consistency**: Verify `memory_count` in `index.json` matches the actual number of entries in `memories`.
274
- 4. **Empty directories**: Report any empty directories that may need cleanup.
275
-
276
- If any issues are found:
277
- ```
278
- ⚠️ Post-erasure integrity issues:
279
- - <description of issue>
280
-
281
- These can be fixed by running /brain:sleep.
282
- ```
283
-
284
- ### 10. Confirm
285
-
286
- Print a summary:
287
-
288
- ```
289
- ## Erasure Complete: "<title>"
290
-
291
- Memory deleted: <id>
292
- References cleaned: <count> across <file_count> files
293
- Derivatives removed: <count>
294
- Consolidated memories repaired: <count>
295
- Audit log: <written to _erased.json | skipped (--no-trace)>
296
-
297
- Brain stats: <total_memories> memories, average strength <avg>
298
-
299
- The memory has been fully erased. All traces have been removed
300
- from the associative network, context logs, review queue, and
301
- cross-references in other memories.
302
- ```
303
-
304
- ## Edge Cases
305
-
306
- 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.
307
-
308
- 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.
309
-
310
- 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.
311
-
312
- 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.
313
-
314
- 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:
315
- ```
316
- ⚠️ CRITICAL: "<consolidated_title>" will have ZERO sources after erasure.
317
- This consolidated memory only existed because of the target.
318
- Recommend: use --deep to handle this, or manually review.
319
- ```
320
-
321
- 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.
322
-
323
- 7. **Empty `related` arrays after cleanup**: Leave as `related: []`. Do not remove the field entirely — it maintains schema consistency.
324
-
325
- 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.
326
-
327
- 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.
328
-
329
- 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.
330
-
331
- ## Important Rules
332
-
333
- 1. **Always confirm before executing**. Never erase without explicit user approval. High-salience memories require typing the ID.
334
- 2. **Order matters**. Follow the execution order in Step 7 exactly — derivatives first, then repairs, then references, then index, then file deletion.
335
- 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.
336
- 4. **No collateral damage**. Only remove references to the specific target. Never modify content unrelated to the target memory.
337
- 5. **Preserve other memories' integrity**. When editing other memories' frontmatter or content, preserve all other fields and content exactly.
338
- 6. **Sensitive data handling**. With `--sensitive`, overwrite file content before deletion to prevent filesystem-level recovery.
339
- 7. **Integrity check is mandatory**. Always run the post-erasure integrity check, even if no issues are expected.
340
- 8. **Recursive safety**. When processing derivatives with `--deep --cascade`, always maintain a `visited` set to prevent infinite loops.
341
- 9. **Never delete top-level category directories**. Even if they become empty after erasure, preserve `professional/`, `personal/`, `social/`, `family/`, `_consolidated/`, and `_archived/`.
342
- 10. **Context sessions are preserved**. Remove memory IDs from session arrays, but never delete the session entry itself.
@@ -1,26 +0,0 @@
1
- ---
2
- description: Remove a memory from the always-present tier
3
- argument-hint: "[id|query]"
4
- ---
5
-
6
- # /brain:unpin — Remove a Memory from the Always-Present Tier
7
-
8
- You are unpinning a memory. It will no longer load automatically at session start and returns to normal recall + decay (an independent `stable` flag, if set, is left untouched).
9
-
10
- **User input:** $ARGUMENTS
11
-
12
- ## Behavior
13
-
14
- 1. **Resolve the target:**
15
- - If `$ARGUMENTS` is a memory ID (`mem_...`), use it directly.
16
- - Otherwise inspect `~/.brain/pinned.json` (the list of current pins) or run `brain recall "$ARGUMENTS" --top 5`, and confirm which pin to remove.
17
-
18
- 2. **Unpin it:**
19
- ```bash
20
- brain unpin <id>
21
- ```
22
-
23
- 3. Confirm:
24
- ```
25
- 📌 Unpinned <title> — no longer auto-loaded.
26
- ```