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.
@@ -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/`)