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,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.
|