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,130 @@
1
+ # /brain:review — Spaced Repetition Review
2
+
3
+ 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.
4
+
5
+ **Scope:** $ARGUMENTS
6
+
7
+ ## Overview
8
+
9
+ 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.
10
+
11
+ ## Steps
12
+
13
+ ### 1. Load Review Queue
14
+
15
+ Read `.brain/review-queue.json`. If it doesn't exist or is empty, generate it:
16
+ - Scan all memories in `index.json`
17
+ - For memories with `access_count > 0`, calculate initial review schedule
18
+ - For memories never recalled, add with `next_review` = now (immediate first review)
19
+ - If $ARGUMENTS specifies a category path, limit to that subtree
20
+
21
+ ### 2. Find Due Memories
22
+
23
+ Filter the review queue for items where `next_review <= now`.
24
+
25
+ If no memories are due:
26
+ ```
27
+ ## No Memories Due for Review
28
+
29
+ Next review due: <soonest date>
30
+ Total in queue: <count>
31
+
32
+ Run /brain:status for a full overview.
33
+ ```
34
+
35
+ ### 3. Present Review Session
36
+
37
+ For each due memory (process up to 10 per session):
38
+
39
+ 1. **Present the memory's title and path** (but NOT the full content initially):
40
+ ```
41
+ ### Review 1 of <N>
42
+
43
+ **Memory:** <title>
44
+ **Path:** .brain/<path>
45
+ **Type:** <type> (<cognitive_type>) | **Last reviewed:** <date> | **Interval:** <days>d
46
+ **Confidence:** <confidence>
47
+
48
+ Can you recall what this memory is about? Try to remember before seeing the content.
49
+ ```
50
+
51
+ 2. **Reveal the full content** after the user responds (or on request):
52
+ ```
53
+ <full memory content>
54
+ ```
55
+
56
+ 3. **Ask for recall quality** (1-5 scale):
57
+ - **5 — Perfect**: Recalled immediately and completely
58
+ - **4 — Good**: Recalled with minor effort
59
+ - **3 — Okay**: Recalled with significant effort
60
+ - **2 — Poor**: Could barely recall, needed heavy hints
61
+ - **1 — Failed**: Could not recall at all
62
+
63
+ ### 4. Update Based on Recall Quality
64
+
65
+ For each reviewed memory, update using the SM-2 algorithm:
66
+
67
+ **Ease factor adjustment:**
68
+ ```
69
+ new_ease = ease_factor + (0.1 - (5 - quality) * (0.08 + (5 - quality) * 0.02))
70
+ ease_factor = max(1.3, new_ease)
71
+ ```
72
+
73
+ **Interval calculation:**
74
+ ```
75
+ if quality >= 3: // Successful recall
76
+ if review_count == 0: interval = 1
77
+ elif review_count == 1: interval = 6
78
+ else: interval = previous_interval * ease_factor
79
+ else: // Failed recall
80
+ interval = 1 // Reset to 1 day
81
+ review_count = 0 // Reset review count
82
+ ```
83
+
84
+ **Update memory:**
85
+ - `last_accessed` → current timestamp
86
+ - `access_count` → increment by 1
87
+ - `recall_history` → append current timestamp
88
+ - Apply spaced reinforcement to `strength` (same formula as /brain:remember)
89
+ - Improve `decay_rate` on successful recall (quality >= 3)
90
+
91
+ **Update review queue entry:**
92
+ ```json
93
+ {
94
+ "memory_id": "<id>",
95
+ "next_review": "<now + interval days>",
96
+ "interval_days": <interval>,
97
+ "ease_factor": <ease_factor>,
98
+ "review_count": <review_count + 1>
99
+ }
100
+ ```
101
+
102
+ ### 5. Session Summary
103
+
104
+ After reviewing all due memories:
105
+
106
+ ```
107
+ ## Review Session Complete
108
+
109
+ Reviewed: <N> memories
110
+ Perfect (5): <count>
111
+ Good (4): <count>
112
+ Okay (3): <count>
113
+ Poor (2): <count>
114
+ Failed (1): <count>
115
+
116
+ Average recall quality: <avg>
117
+ Next review due: <soonest date>
118
+ Remaining in queue: <count>
119
+
120
+ Memories strengthened through review — keep it up!
121
+ ```
122
+
123
+ ## Rules
124
+
125
+ 1. **Never skip the recall attempt** — always present the title first and let the user try to recall before revealing content
126
+ 2. **Be encouraging** — spaced repetition is about building long-term retention, not testing
127
+ 3. **Update everything** — update the memory file, index.json, review-queue.json, and associations.json (reinforce edges between co-reviewed memories)
128
+ 4. **Respect scope** — if $ARGUMENTS specifies a category, only review memories in that subtree
129
+ 5. **Session limit** — review at most 10 memories per session to avoid fatigue
130
+ 6. **Failed recalls** — for quality 1-2, suggest the user re-read the memory and offer to update it if the information is outdated
@@ -0,0 +1,535 @@
1
+ # /brain:sleep — Overnight Memory Reorganization
2
+
3
+ You are performing a **sleep cycle** on the Brain Memory system. Just like the human brain during sleep — where the hippocampus replays recent experiences and the neocortex reorganizes them into long-term structured knowledge — this command restructures, consolidates, prunes, and deepens the `.brain/` hierarchy.
4
+
5
+ **Scope:** $ARGUMENTS
6
+
7
+ ## Overview
8
+
9
+ Sleep performs nine phases, mimicking real neuroscience:
10
+
11
+ 1. **Replay** — Scan recent activity and compute decay across all memories
12
+ 2. **Synaptic Homeostasis** — Proportionally scale down all strengths to prevent inflation (Tononi & Cirelli SHY)
13
+ 3. **Knowledge Propagation** — Evaluate recent memories against the hierarchy and update related memories
14
+ 4. **Semantic Crystallization** — Extract generalizable knowledge from frequently-recalled episodic memories
15
+ 5. **Reorganize** — Detect flat clusters and restructure into deeper sub-categories
16
+ 6. **Consolidate** — Merge weak related memories into stronger combined knowledge
17
+ 7. **Prune** — Archive memories that have decayed beyond recovery
18
+ 8. **REM Dreaming** — Discover creative cross-domain associations via analogical reasoning
19
+ 9. **Expertise Detection** — Identify dense knowledge areas and generate expertise profiles
20
+
21
+ ### Migration Phase (Phase 0)
22
+
23
+ If the brain's `index.json` has `version: 1` (pre-v2), run migration first:
24
+
25
+ 1. Create `associations.json` from existing `related` fields — for each memory with `related` entries, create edges with weight 0.20 and origin `manual`
26
+ 2. Auto-discover associations: for any two memories sharing 2+ tags, create edges with weight 0.10 and origin `tag_overlap`
27
+ 3. Create `contexts.json` with `{"version": 1, "sessions": []}`
28
+ 4. Create `review-queue.json` with `{"version": 1, "items": []}`
29
+ 5. Create `_archived/index.json` if not present with `{"version": 1, "archived_count": 0, "memories": {}}`
30
+ 6. For each memory: backfill `recall_history` from `access_count` (if `access_count > 0`, set `recall_history: [last_accessed]`; otherwise `recall_history: []`)
31
+ 7. Set defaults for missing fields: `cognitive_type: "semantic"`, `salience: 0.5`, `confidence: 0.8`
32
+ 8. Update both memory files (frontmatter) and `index.json` entries
33
+ 9. Set `index.json` version to 2
34
+
35
+ Present migration summary, then proceed to Phase 1.
36
+
37
+ ---
38
+
39
+ ## Phase 1: Replay (Hippocampal Scan)
40
+
41
+ During sleep, the hippocampus replays the day's events. Here, we scan and assess the full brain state.
42
+
43
+ ### Steps
44
+
45
+ 1. Read `.brain/index.json` to load all memories
46
+ 2. If $ARGUMENTS specifies a category path, limit scope to that subtree. Otherwise, process the entire brain.
47
+ 3. For **every** memory, compute the current decayed strength:
48
+
49
+ ```
50
+ days_elapsed = (now - last_accessed) / (1000 * 60 * 60 * 24)
51
+ decayed_strength = strength * (decay_rate ^ days_elapsed)
52
+ ```
53
+
54
+ 4. Categorize each memory into tiers:
55
+ - **Strong** (decayed_strength >= 0.6) — healthy, no action needed
56
+ - **Moderate** (0.3 <= decayed_strength < 0.6) — consolidation candidates
57
+ - **Weak** (0.1 <= decayed_strength < 0.3) — urgent: consolidate or lose
58
+ - **Fading** (decayed_strength < 0.1) — prune candidates
59
+
60
+ 5. Collect statistics:
61
+ - Memories per tier
62
+ - Memories per directory (for cluster detection)
63
+ - Tag frequency analysis (for sub-category extraction)
64
+ - Mean effective strength across all memories (for Synaptic Homeostasis)
65
+
66
+ Present a brief replay summary before continuing:
67
+
68
+ ```
69
+ ## Phase 1: Replay Complete
70
+
71
+ Scanned <N> memories across <M> categories
72
+
73
+ Strong (>=0.6): <count> memories — healthy
74
+ Moderate (0.3-0.6): <count> memories — consolidation candidates
75
+ Weak (0.1-0.3): <count> memories — urgent attention needed
76
+ Fading (<0.1): <count> memories — pruning candidates
77
+
78
+ Mean effective strength: <value>
79
+
80
+ Proceeding to synaptic homeostasis...
81
+ ```
82
+
83
+ ---
84
+
85
+ ## Phase 2: Synaptic Homeostasis (Global Downscaling)
86
+
87
+ Based on Tononi & Cirelli's **Synaptic Homeostasis Hypothesis (SHY)** — during sleep the brain proportionally scales down ALL synaptic strengths, then selectively re-boosts important ones. This prevents "strength inflation" where frequent recall pushes everything toward 1.0, making the scoring system less discriminating.
88
+
89
+ ### Steps
90
+
91
+ 1. Compute `mean_effective_strength` from Phase 1 across all memories
92
+
93
+ 2. If `mean_effective_strength > 0.5`, apply downscaling:
94
+
95
+ ```
96
+ scaling_factor = max(0.85, 0.5 / mean_effective_strength)
97
+ ```
98
+
99
+ 3. For every memory: `strength = strength * scaling_factor`
100
+
101
+ 4. Selectively re-boost important memories:
102
+ - **High salience** (salience >= 0.7): +0.05
103
+ - **Recently accessed** (within 7 days): +0.03
104
+ - **Frequently recalled** (access_count >= 5): +0.02
105
+
106
+ 5. Also downscale association weights in `associations.json`:
107
+ - Apply `weight = weight * scaling_factor` to all edges
108
+ - Prune edges that fall below the `link_prune_threshold` (default 0.05)
109
+
110
+ 6. Update all memory files (frontmatter) and `index.json` entries
111
+
112
+ If `mean_effective_strength <= 0.5`, skip this phase:
113
+
114
+ ```
115
+ ## Phase 2: Synaptic Homeostasis — Skipped
116
+
117
+ Mean effective strength (0.42) is within healthy range. No downscaling needed.
118
+ ```
119
+
120
+ Otherwise present:
121
+
122
+ ```
123
+ ## Phase 2: Synaptic Homeostasis Complete
124
+
125
+ Mean strength before: <before>
126
+ Scaling factor applied: <factor>
127
+ Mean strength after: <after>
128
+
129
+ Re-boosted:
130
+ High salience: <count> memories (+0.05 each)
131
+ Recently accessed: <count> memories (+0.03 each)
132
+ Frequently recalled: <count> memories (+0.02 each)
133
+
134
+ Association links downscaled: <count>, pruned: <count>
135
+ ```
136
+
137
+ ---
138
+
139
+ ## Phase 3: Knowledge Propagation (Reconsolidation)
140
+
141
+ In neuroscience, **memory reconsolidation** is the process where recalling an existing memory makes it temporarily malleable — allowing the brain to update it with new information before re-stabilizing it. During sleep, recently acquired knowledge is replayed against the existing memory network, triggering updates to related older memories. This is how a single new insight can reshape your understanding of an entire topic.
142
+
143
+ This phase takes each **recent memory** and walks the brain hierarchy — checking both upper-level (parent) and lower-level (child) categories, plus sibling and tag-related memories — to determine if existing knowledge should be updated in light of what was recently learned.
144
+
145
+ ### Steps
146
+
147
+ #### 3.1 Identify Recent Memories
148
+
149
+ From the Phase 1 scan, identify **recent memories** — those meeting any of these criteria:
150
+ - Created within the last `propagation_window_days` (default: 7 days, configurable in `index.json` config)
151
+ - `last_accessed` within the propagation window AND `access_count` increased (recently recalled and reinforced)
152
+ - Memories flagged with `source` matching recent session identifiers
153
+
154
+ These are the "trigger memories" — the new knowledge that may require updates to existing memories.
155
+
156
+ If no recent memories are found, skip this phase with a brief note:
157
+
158
+ ```
159
+ ## Phase 3: Knowledge Propagation — Skipped
160
+
161
+ No recent memories found within the propagation window (7 days).
162
+ Nothing to propagate.
163
+ ```
164
+
165
+ #### 3.2 Find Related Memories for Each Trigger
166
+
167
+ For each recent (trigger) memory, find related memories through **five traversal strategies**:
168
+
169
+ **A. Hierarchical — Upper levels (ancestors)**
170
+ Walk UP from the trigger memory's directory to the top-level category:
171
+ - Read all memory files in each parent directory
172
+ - These represent broader context that may need updating with the new specific knowledge
173
+
174
+ **B. Hierarchical — Lower levels (descendants)**
175
+ Walk DOWN into any child directories from the trigger memory's directory:
176
+ - Read all memory files in subdirectories (up to 2 levels deep to avoid excessive scanning)
177
+ - These represent more specific knowledge that the new broader insight may affect
178
+
179
+ **C. Sibling memories**
180
+ Read all memory files at the SAME directory level as the trigger memory:
181
+ - These are directly related knowledge in the same category
182
+ - Most likely to need updating since they cover the same topic area
183
+
184
+ **D. Tag-related memories**
185
+ From `index.json`, find memories anywhere in the brain that share **2 or more tags** with the trigger memory:
186
+ - These capture cross-domain connections that the hierarchy alone might miss
187
+
188
+ **E. Association-linked memories** (NEW)
189
+ From `associations.json`, find all neighbors of the trigger memory with edge weight >= 0.15:
190
+ - These capture learned associations from previous co-retrievals and manual links
191
+ - Includes memories that might not share tags or hierarchy but have been used together
192
+
193
+ Also include any memories explicitly listed in the trigger memory's `related` field.
194
+
195
+ **Deduplication**: A memory found through multiple strategies is only evaluated once, but mark it as having stronger relation (found via multiple paths).
196
+
197
+ #### 3.3 Evaluate Each Related Memory
198
+
199
+ For each related memory found, read it fully and evaluate it against the trigger memory. Classify the relationship as one or more of:
200
+
201
+ **Enrichment** — The new knowledge adds detail, nuance, or a new perspective to the existing memory:
202
+ - *Action*: Propose appending new information to the existing memory's Key Details or Connections section
203
+
204
+ **Contradiction** — The new knowledge conflicts with or supersedes existing knowledge:
205
+ - *Action*: Flag for user review — propose updating the existing memory with the corrected information and noting what changed and why
206
+ - Also reduce the contradicted memory's `confidence` by -0.20 (floored at 0.1)
207
+
208
+ **Validation** — The new knowledge confirms or strengthens existing knowledge:
209
+ - *Action*: Boost the existing memory's `strength` by +0.05 (capped at 1.0), update `last_accessed`
210
+ - Also boost the validated memory's `confidence` by +0.10 (capped at 1.0)
211
+
212
+ **Obsolescence** — The new knowledge makes the existing memory outdated or irrelevant:
213
+ - *Action*: Propose marking the existing memory for accelerated decay (`decay_rate` → 0.90) or archival
214
+
215
+ **Cross-reference** — The memories should reference each other but don't yet:
216
+ - *Action*: Add bidirectional cross-references (update `related` arrays in both memories)
217
+ - Also create/strengthen association edges in `associations.json` with origin `propagation`
218
+
219
+ #### 3.4 Present Propagation Plan
220
+
221
+ Group all proposed updates by action type and present to the user (same format as before).
222
+
223
+ #### 3.5 Get User Approval
224
+
225
+ The user can approve all, select specific updates, modify, or skip.
226
+
227
+ #### 3.6 Execute Approved Updates
228
+
229
+ Execute as before, plus:
230
+ - For contradictions: also reduce `confidence` by -0.20
231
+ - For validations: also boost `confidence` by +0.10
232
+ - For cross-references: also create/strengthen edges in `associations.json`
233
+
234
+ ---
235
+
236
+ ## Phase 4: Semantic Crystallization (Episodic → Semantic)
237
+
238
+ In the brain, specific episodic memories (tied to events) gradually transform into abstracted semantic knowledge (general principles) through repeated recall. The event details fade, but the lesson persists.
239
+
240
+ ### Steps
241
+
242
+ 1. Find episodic memories (cognitive_type: episodic) with:
243
+ - `access_count >= 3` (recalled multiple times — the pattern has been reinforced)
244
+ - `decayed_strength >= 0.4` (still meaningfully strong)
245
+
246
+ 2. For each candidate, evaluate: **Is there a generalizable lesson or principle that can be extracted from this specific event?**
247
+
248
+ 3. If yes, create a new **semantic** memory:
249
+ - `cognitive_type: semantic`
250
+ - `type`: usually `insight` or `learning`
251
+ - Content: the generalized principle/pattern, not the specific event
252
+ - `related`: link to the source episodic memory
253
+ - `strength`: inherit from source, but with semantic default decay (slower)
254
+ - `salience`: inherit from source
255
+ - `confidence`: source confidence - 0.10 (abstraction introduces some uncertainty)
256
+
257
+ 4. For the source episodic memory:
258
+ - Accelerate its decay: multiply `decay_rate` by 0.990 (the event details fade faster)
259
+ - Add reference to the new semantic memory in `related`
260
+ - Add note: `<!-- Crystallized into <semantic_id> on <date> -->`
261
+
262
+ 5. Create/strengthen association edge between the episodic source and semantic output with origin `propagation`
263
+
264
+ **Example:**
265
+ - Episodic: "OAuth token expired mid-session on Tuesday causing 30min outage"
266
+ - → Semantic: "Always refresh tokens proactively before API calls, not reactively after failures"
267
+
268
+ Present crystallization proposals for user approval:
269
+
270
+ ```
271
+ ## Phase 4: Semantic Crystallization
272
+
273
+ Found <N> episodic memories ready for crystallization:
274
+
275
+ 🔬 **oauth-token-incident.md** (episodic, recalled 4x, strength 0.65)
276
+ → Proposed semantic memory: "Proactive Token Refresh Strategy"
277
+ Generalized principle: Always refresh tokens proactively before API calls
278
+ Source event details will begin fading (decay accelerated)
279
+
280
+ Approve crystallizations? [all / select / skip]
281
+ ```
282
+
283
+ ---
284
+
285
+ ## Phase 5: Reorganize (Neocortical Restructuring)
286
+
287
+ During sleep, the brain transfers memories from the hippocampus to the neocortex, organizing them into structured long-term storage. This phase detects **flat clusters** — directories with many memories that should be organized into deeper sub-categories.
288
+
289
+ ### Steps
290
+
291
+ 1. **Scan for flat clusters**: For each directory in the brain, count the number of memory files (not counting `_meta.json`).
292
+
293
+ 2. **Identify restructuring candidates** — directories where:
294
+ - There are **3 or more** memory files at the same level, AND
295
+ - The memories can be meaningfully grouped by **tag overlap**, **title similarity**, or **semantic themes**
296
+
297
+ 3. **Extract sub-categories**: For each candidate directory, analyze the memory files within it:
298
+ - Read each memory's tags, title, and content summary
299
+ - Identify natural groupings (2+ memories that share a common theme)
300
+ - Propose sub-category directory names using kebab-case
301
+
302
+ **Sub-category extraction rules:**
303
+ - A group needs at least **2 memories** to justify a sub-category
304
+ - The sub-category name should be a **clear, descriptive noun** (e.g., `authentication`, `state-management`, `deployment`)
305
+ - Memories that don't fit any group stay at the current level (don't force-categorize)
306
+ - Never exceed `max_depth` from config
307
+
308
+ 4. **Present the reorganization plan** to the user
309
+
310
+ 5. **Get user approval**
311
+
312
+ 6. **Execute approved reorganizations**:
313
+ - Create new sub-category directories with `_meta.json`
314
+ - Move memory files to their new locations
315
+ - Update `index.json` with new paths for all moved memories
316
+ - Update `_meta.json` in affected directories (memory counts, subcategories)
317
+ - **Preserve all memory content and metadata** — only the path changes
318
+
319
+ ---
320
+
321
+ ## Phase 6: Consolidate (Memory Integration)
322
+
323
+ During deep sleep, the brain merges related experiences into generalized knowledge. Weak memories that share themes are combined into stronger, more durable memories.
324
+
325
+ ### Steps
326
+
327
+ 1. From the Phase 1 scan, take all **Moderate** and **Weak** tier memories (decayed_strength < 0.6) that were NOT already updated in Phase 3 (Knowledge Propagation) or Phase 4 (Semantic Crystallization)
328
+
329
+ 2. Group consolidation candidates by:
330
+ - **Path proximity** — memories in the same or nearby directories (highest priority after reorganization)
331
+ - **Tag overlap** — memories sharing 2+ tags
332
+ - **Type similarity** — same memory type
333
+ - **Temporal proximity** — created within similar time periods
334
+
335
+ 3. For each viable group (2+ memories):
336
+ - Read all source memories fully
337
+ - Synthesize a consolidated memory that preserves all key details and insights
338
+ - Calculate: `new_strength = max(source_strengths) + 0.15` (capped at 1.0)
339
+ - Use the slowest decay rate from the sources
340
+ - Merge all tags (union)
341
+ - **Salience anchoring**: The highest-salience memory in the group becomes the "anchor" — its key details and framing take priority in the synthesis. The consolidated memory inherits the maximum salience from the group.
342
+ - Inherit the maximum confidence from the group
343
+
344
+ 4. Present consolidation plan to user for approval
345
+
346
+ 5. For approved consolidations:
347
+ - Write consolidated memory files using the standard format with `type: consolidated`
348
+ - Archive source memories to `.brain/_archived/` and add them to `_archived/index.json`
349
+ - Transfer association edges from source memories to the consolidated memory in `associations.json`
350
+ - Update `index.json` and `_meta.json` files
351
+
352
+ ---
353
+
354
+ ## Phase 7: Prune (Synaptic Pruning)
355
+
356
+ During sleep, the brain prunes weak synaptic connections to maintain efficiency. Here, we archive memories that have faded beyond usefulness.
357
+
358
+ ### Steps
359
+
360
+ 1. Take all **Fading** tier memories (decayed_strength < 0.1) that were NOT already consolidated in Phase 6
361
+
362
+ 2. **Salience protection**: Memories with `salience >= 0.7` are NEVER auto-pruned, regardless of strength. Skip them with a note:
363
+ ```
364
+ ⚡ Skipping <title> — high salience (0.8) protects from auto-pruning
365
+ ```
366
+
367
+ 3. Present the prune list (excluding salience-protected memories)
368
+
369
+ 4. Get user approval (default: archive all)
370
+
371
+ 5. Execute:
372
+ - Move to `.brain/_archived/`, preserving directory structure
373
+ - Add to `_archived/index.json` with original metadata
374
+ - Remove from `index.json` and update `_meta.json` files
375
+ - Remove association edges involving pruned memories from `associations.json`
376
+
377
+ ---
378
+
379
+ ## Phase 8: REM Dreaming (Creative Association Discovery)
380
+
381
+ During REM sleep, the brain creates novel connections between seemingly unrelated memories — this is why we often have creative breakthroughs after sleeping on a problem. This phase implements that creative association mechanism.
382
+
383
+ ### Steps
384
+
385
+ 1. Select 5-10 random memories from **different top-level categories** that have decayed_strength >= 0.3
386
+
387
+ 2. For each pair of memories from different categories, evaluate potential cross-domain connections using **analogical reasoning**:
388
+ - Are there structural similarities? (both involve X pattern)
389
+ - Are there shared underlying principles? (both deal with expiration/renewal)
390
+ - Could techniques from one domain apply to the other?
391
+ - Are there complementary perspectives?
392
+
393
+ 3. Score each potential connection:
394
+ ```
395
+ dream_score = 0.5 * novelty + 0.3 * utility + 0.2 * surprise
396
+ ```
397
+ - **novelty**: How unexpected is this connection? (0-1)
398
+ - **utility**: How useful could this insight be? (0-1)
399
+ - **surprise**: How non-obvious is this? (0-1)
400
+
401
+ 4. For connections scoring >= 0.5:
402
+ - Create association edges in `associations.json` with origin `creative` and initial weight 0.15
403
+ - Present as "dream insights"
404
+
405
+ 5. Present discoveries:
406
+
407
+ ```
408
+ ## Phase 8: REM Dreaming — Creative Insights
409
+
410
+ 💭 **Dream Insight 1** (score: 0.72)
411
+ "Token refresh patterns" ↔ "Subscription renewal flows"
412
+ Both involve: expiration handling, silent renewal, fallback strategies
413
+ Potential application: Apply token refresh retry logic to subscription renewals
414
+
415
+ 💭 **Dream Insight 2** (score: 0.58)
416
+ "Database migration strategies" ↔ "Moving to a new apartment"
417
+ Both involve: careful planning, rollback capability, staged execution
418
+ Potential application: Use the migration checklist pattern for personal life transitions
419
+
420
+ <N> creative associations discovered and linked
421
+ ```
422
+
423
+ ---
424
+
425
+ ## Phase 9: Expertise Detection (Knowledge Crystallization)
426
+
427
+ This is the most powerful phase. When the brain repeatedly processes information in a domain, it forms **expertise** — fast, intuitive access to deep knowledge. Here, we detect when a sub-tree has become dense enough to represent genuine expertise.
428
+
429
+ ### Steps
430
+
431
+ 1. **Scan for expertise candidates**: For each directory (including newly reorganized ones), evaluate:
432
+ - **Memory density**: 3+ memories in the subtree
433
+ - **Average strength**: Mean decayed strength of memories in the subtree
434
+ - **Recall frequency**: Sum of `access_count` across memories in the subtree
435
+ - **Time span**: Duration between the oldest and newest memory
436
+ - **Topic coherence**: How tightly related the memories are (based on tag overlap)
437
+
438
+ 2. **Calculate expertise score** for each candidate directory:
439
+
440
+ ```
441
+ density_score = min(1.0, memory_count / 5)
442
+ strength_score = average_decayed_strength
443
+ recall_score = min(1.0, total_access_count / 10)
444
+ span_score = min(1.0, time_span_days / 30)
445
+ coherence_score = shared_tags / total_unique_tags
446
+
447
+ expertise_score = (0.25 * density_score) + (0.25 * strength_score) + (0.20 * recall_score) + (0.15 * span_score) + (0.15 * coherence_score)
448
+ ```
449
+
450
+ 3. **Classify expertise level** based on the score:
451
+ - **Awareness** (0.2 - 0.4) — Surface-level familiarity. You know it exists.
452
+ - **Working Knowledge** (0.4 - 0.6) — Can work with this competently with some reference.
453
+ - **Deep Knowledge** (0.6 - 0.8) — Strong command. Can reason about trade-offs and edge cases.
454
+ - **Expert** (0.8 - 1.0) — Mastery. Dense, frequently-recalled, long-standing knowledge.
455
+
456
+ 4. **Generate or update expertise profiles**: For each directory scoring >= 0.2, create or update an `_expertise.md` file.
457
+
458
+ 5. **Knowledge gap detection**: By analyzing what sub-topics exist vs. what commonly appears alongside them (using tag relationships across the whole brain), identify areas where expertise could be deepened. List these as "Knowledge Gaps" in the expertise profile.
459
+
460
+ 6. **Generate review queue**: After expertise detection, populate `review-queue.json` using simplified SM-2 scheduling. For each memory with `access_count > 0`:
461
+ ```
462
+ interval = base_interval * (2.5 ^ (successful_reviews - 1))
463
+ next_review = last_accessed + interval
464
+ ```
465
+ Where `base_interval = 1 day` and `successful_reviews = min(access_count, 10)`.
466
+
467
+ Add or update entries in `review-queue.json`:
468
+ ```json
469
+ {
470
+ "memory_id": "<id>",
471
+ "next_review": "<ISO timestamp>",
472
+ "interval_days": <interval>,
473
+ "ease_factor": 2.5,
474
+ "review_count": <count>
475
+ }
476
+ ```
477
+
478
+ 7. Present expertise findings.
479
+
480
+ ---
481
+
482
+ ## Sleep Report
483
+
484
+ After all phases complete, present a comprehensive sleep report:
485
+
486
+ ```
487
+ ╔═══════════════════════════════════════════════════════════════╗
488
+ ║ 🌙 SLEEP CYCLE COMPLETE ║
489
+ ╠═══════════════════════════════════════════════════════════════╣
490
+ ║ ║
491
+ ║ Phase 1 — Replay: <N> memories scanned ║
492
+ ║ Phase 2 — Homeostasis: Scaling factor: <X> ║
493
+ ║ Phase 3 — Propagated: <N> updates from <M> recent ║
494
+ ║ Phase 4 — Crystallized: <N> episodic → semantic ║
495
+ ║ Phase 5 — Reorganized: <N> memories, <M> new dirs ║
496
+ ║ Phase 6 — Consolidated: <N> memories merged into <M> ║
497
+ ║ Phase 7 — Pruned: <N> faded memories archived ║
498
+ ║ Phase 8 — REM Dreams: <N> creative insights ║
499
+ ║ Phase 9 — Expertise: <N> domains profiled ║
500
+ ║ ║
501
+ ║ Brain Health: ║
502
+ ║ Before sleep: <count> memories, avg strength <X> ║
503
+ ║ After sleep: <count> memories, avg strength <Y> ║
504
+ ║ Expertise areas: <count> domains mapped ║
505
+ ║ Review queue: <count> memories scheduled ║
506
+ ║ ║
507
+ ╚═══════════════════════════════════════════════════════════════╝
508
+
509
+ ### Expertise Summary
510
+ <expertise level list from Phase 9>
511
+
512
+ ### Dream Insights
513
+ <creative associations from Phase 8>
514
+
515
+ ### Memories Due for Review
516
+ <count> memories due within the next 7 days — run /brain:review
517
+
518
+ ### Recommendations
519
+ - <actionable suggestions based on what sleep revealed>
520
+ ```
521
+
522
+ ---
523
+
524
+ ## Important Rules
525
+
526
+ 1. **Always ask for approval** before executing reorganization, consolidation, crystallization, or pruning. Present the plan first.
527
+ 2. **Never delete permanently** — pruned memories go to `_archived/` (recoverable).
528
+ 3. **Preserve all content** — reorganization only changes paths, never memory content.
529
+ 4. **Update all references** — when moving files, update `index.json`, all `_meta.json` files, `associations.json`, and `related` fields in other memories that reference moved memories.
530
+ 5. **Respect max_depth** — never create directories beyond the configured `max_depth`.
531
+ 6. **Scope control** — if $ARGUMENTS specifies a path (e.g., "professional/skills"), only sleep-process that subtree.
532
+ 7. **Idempotent expertise** — if `_expertise.md` already exists, update it rather than creating a duplicate.
533
+ 8. **Skip empty phases** — if there's nothing to do in a phase (e.g., no flat clusters to reorganize), briefly note it and move on.
534
+ 9. **Salience protection** — never auto-prune memories with salience >= 0.7.
535
+ 10. **Run migration** — if `index.json` version is 1, run Phase 0 migration before proceeding.