brain-memory 0.1.0-beta.3 → 0.1.0-beta.31

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.
Files changed (66) hide show
  1. package/CHANGELOG.md +339 -0
  2. package/README.md +400 -94
  3. package/SECURITY.md +61 -0
  4. package/assets/brand/README.md +28 -0
  5. package/assets/brand/icon-dark.svg +19 -0
  6. package/assets/brand/icon-light.svg +20 -0
  7. package/assets/brand/linkedin_cover.png +0 -0
  8. package/assets/brand/linkedin_cover_light.png +0 -0
  9. package/assets/brand/mark-dark.svg +19 -0
  10. package/assets/brand/mark-light.svg +20 -0
  11. package/assets/brand/png/icon-dark-1024.png +0 -0
  12. package/assets/brand/png/icon-dark-128.png +0 -0
  13. package/assets/brand/png/icon-dark-256.png +0 -0
  14. package/assets/brand/png/icon-dark-512.png +0 -0
  15. package/assets/brand/png/icon-dark-64.png +0 -0
  16. package/assets/brand/png/icon-light-1024.png +0 -0
  17. package/assets/brand/png/icon-light-128.png +0 -0
  18. package/assets/brand/png/icon-light-256.png +0 -0
  19. package/assets/brand/png/icon-light-512.png +0 -0
  20. package/assets/brand/png/icon-light-64.png +0 -0
  21. package/assets/brand/png/mark-dark-1024.png +0 -0
  22. package/assets/brand/png/mark-light-1024.png +0 -0
  23. package/assets/icon.png +0 -0
  24. package/assets/icon.svg +19 -0
  25. package/bin/brain.js +111 -0
  26. package/bin/cloud-sync.js +150 -0
  27. package/bin/forget.js +122 -0
  28. package/bin/install.js +229 -254
  29. package/bin/memorize.js +458 -0
  30. package/bin/pin.js +44 -0
  31. package/bin/recall.js +259 -0
  32. package/bin/reinforce.js +187 -0
  33. package/bin/session-start.js +298 -0
  34. package/bin/skill.js +67 -0
  35. package/bin/unpin.js +38 -0
  36. package/commands/brain/forget.md +245 -15
  37. package/commands/brain/memorize.md +76 -144
  38. package/commands/brain/pin.md +79 -0
  39. package/commands/brain/remember.md +48 -105
  40. package/commands/brain/skills.md +60 -0
  41. package/commands/brain/sleep.md +69 -28
  42. package/commands/brain/status.md +24 -10
  43. package/commands/brain/sync.md +386 -0
  44. package/package.json +22 -8
  45. package/prompts/antigravity.md +180 -0
  46. package/prompts/claude.md +124 -20
  47. package/prompts/openai.md +124 -20
  48. package/prompts/opencode.md +179 -0
  49. package/src/cloud-sync.js +534 -0
  50. package/src/crypto.js +130 -0
  51. package/src/export-import.js +200 -0
  52. package/src/git-sync.js +444 -0
  53. package/src/index-manager.js +219 -18
  54. package/src/installer.js +444 -0
  55. package/src/pinning.js +124 -0
  56. package/src/scorer.js +45 -11
  57. package/src/skills.js +208 -0
  58. package/src/tfidf.js +520 -0
  59. package/commands/brain/consolidate.md +0 -153
  60. package/commands/brain/explore.md +0 -79
  61. package/commands/brain/init.md +0 -157
  62. package/commands/brain/review.md +0 -130
  63. package/commands/brain/sunshine.md +0 -337
  64. package/hooks/session-end.md +0 -48
  65. package/hooks/session-start.md +0 -48
  66. package/prompts/gemini.md +0 -76
@@ -1,22 +1,19 @@
1
+ ---
2
+ description: Recall relevant memories with spreading activation and context matching
3
+ argument-hint: "[query]"
4
+ ---
5
+
1
6
  # /brain:remember — Recall Relevant Memories
2
7
 
3
- You are recalling memories from the Brain Memory system. This command searches the `.brain/` hierarchy, scores memories by relevance, strength, associative links, and context match, and returns the most useful memories — either individually or as a consolidated synthesis.
8
+ You are recalling memories from the Brain Memory system. This command uses the **deterministic recall engine** (`brain recall`) to score and rank memories, then presents the results.
4
9
 
5
10
  **User query:** $ARGUMENTS
6
11
 
7
12
  ## Steps
8
13
 
9
- ### 1. Parse the Query
10
-
11
- Analyze $ARGUMENTS to determine:
12
- - **Keywords**: Extract key terms and concepts
13
- - **Category hints**: Does the query suggest a specific life domain? (professional, personal, social, family)
14
- - **Time hints**: Is the user asking about recent or old memories?
15
- - **Intent**: Are they looking for a specific memory, a pattern, or general knowledge?
14
+ ### 1. Determine Context
16
15
 
17
- ### 2. Capture Recall Context
18
-
19
- Determine the current session context for context-dependent matching:
16
+ Identify the current session context:
20
17
 
21
18
  ```yaml
22
19
  recall_context:
@@ -25,51 +22,30 @@ recall_context:
25
22
  task_type: <debugging|implementing|designing|reviewing|discussing|learning>
26
23
  ```
27
24
 
28
- ### 3. Search the Brain
29
-
30
- Read `.brain/index.json` to get the full memory inventory.
31
-
32
- **Search strategy (in order):**
25
+ ### 2. Run the Recall Engine
33
26
 
34
- 1. **Category-first**: If the query clearly maps to a category, traverse that subtree first
35
- 2. **Tag matching**: Match query keywords against memory tags
36
- 3. **Title matching**: Match against memory titles in the index
37
- 4. **Full-text search**: If index matching yields few results, read memory files in relevant categories and search content
27
+ Execute the recall CLI to get deterministically scored results:
38
28
 
39
- Collect all candidate memories.
40
-
41
- ### 3.5. Spreading Activation
42
-
43
- Read `.brain/associations.json`. For each candidate memory scoring > 0.3 in initial relevance:
44
- 1. Traverse the association graph up to 2 hops
45
- 2. For each reached memory: `spread_bonus = parent_score * link_weight * 0.5^hop`
46
- 3. Memories NOT in the initial candidates but reached via spreading activation with bonus >= 0.05 are **added** to the candidate pool (they were "reminded" by association)
47
-
48
- This implements how the brain works: thinking about topic A naturally activates related topics B and C.
29
+ ```bash
30
+ node <brain-memory-install-path>/bin/recall.js "$ARGUMENTS" \
31
+ --project "<project>" \
32
+ --task "<task_type>" \
33
+ --topics "<topic1,topic2>" \
34
+ --top 10
35
+ ```
49
36
 
50
- ### 4. Score Candidates
37
+ If the brain-memory package is installed globally, use:
38
+ ```bash
39
+ brain recall "$ARGUMENTS" --project "<project>" --task "<task_type>" --top 10
40
+ ```
51
41
 
52
- For each candidate memory, compute an **effective score** using the v4 formula:
42
+ The engine computes **TF-IDF relevance** (cosine similarity between query and memory content), then combines it with decayed strength, recency, spreading activation, context match, and salience using the v4 formula. All scoring is deterministic — same query always produces the same ranking.
53
43
 
54
- ```
55
- days_elapsed = (now - last_accessed) / (1000 * 60 * 60 * 24)
56
- decayed_strength = strength * (decay_rate ^ days_elapsed)
57
- recency_bonus = max(0, 1 - (days_elapsed / 365))
58
- spreading_bonus = <computed in step 3.5, 0 if not reached via associations>
59
- context_match = 0.3*(project matches) + 0.4*jaccard(topics) + 0.3*(task_type matches)
60
- salience_bonus = salience (from memory frontmatter, default 0.5)
61
-
62
- effective_score = 0.38 * relevance
63
- + 0.18 * decayed_strength
64
- + 0.08 * recency_bonus
65
- + 0.14 * spreading_bonus
66
- + 0.14 * context_match
67
- + 0.08 * salience_bonus
68
- ```
44
+ ### 3. Read Top Memories
69
45
 
70
- **Note:** If a memory lacks newer fields (spreading_bonus, context_match, salience), the formula renormalizes weights across the available terms. This ensures backward compatibility with v1 memories.
46
+ Parse the JSON output. For the top results (score > 0.3), read the actual memory files from `~/.brain/<path>` to get full content.
71
47
 
72
- ### 5. Decide Response Strategy
48
+ ### 4. Decide Response Strategy
73
49
 
74
50
  Based on the scored results:
75
51
 
@@ -81,68 +57,49 @@ Read all candidate memory files and synthesize a **consolidated response** that:
81
57
  - Weaves together insights from all relevant memories
82
58
  - Notes which memories contributed (by ID and title)
83
59
  - Highlights patterns or evolution across memories
84
- - Presents the most current/relevant information prominently
85
60
 
86
61
  **Case C — Many weak matches (>5 candidates, all scores < 0.4):**
87
- List the top 5-7 memories with titles, paths, types, and effective scores.
62
+ List the top 5-7 memories with titles, paths, types, and scores.
88
63
  Ask the user which ones they'd like to explore in detail.
89
64
 
90
- **Case D — No matches in active brain:**
91
- Search `.brain/_archived/` via the archive index (`_archived/index.json`). If archived matches are found with relevance > 0.3:
92
- - Present them with a note that they're archived
93
- - Offer to restore them (move back to active brain with strength +0.10)
65
+ **Case D — No matches:**
66
+ Search `~/.brain/_archived/` via the archive index. If archived matches found, present them and offer to restore. Otherwise suggest different keywords, or browsing the memory tree directly under `~/.brain/`.
94
67
 
95
- If still no matches, inform the user and suggest:
96
- - Trying different keywords
97
- - Exploring the brain structure with `/brain:explore`
98
- - Storing new memories with `/brain:memorize`
68
+ ### 5. Reinforce Retrieved Memories
99
69
 
100
- ### 6. Reinforce Retrieved Memories (Spaced Reinforcement)
70
+ After presenting results, run the reinforcement engine for all memories shown to the user:
101
71
 
102
- For every memory that was returned to the user (Cases A and B), apply spaced reinforcement:
103
-
104
- **Calculate spacing-aware boost:**
105
- ```
106
- daysSinceLastAccess = (now - last_accessed) / (1000 * 60 * 60 * 24)
107
- recallCount = access_count (or len(recall_history))
108
- spacingMultiplier = min(3.0, 1.0 + log2(1 + daysSinceLastAccess))
109
- diminishingFactor = 1.0 / (1.0 + 0.1 * recallCount)
110
- boost = 0.05 * spacingMultiplier * diminishingFactor
72
+ ```bash
73
+ node <brain-memory-install-path>/bin/reinforce.js <mem_id1> <mem_id2> ...
111
74
  ```
112
75
 
113
- Examples: 1 day gap = +0.05 (same as v1), 7 days = +0.08, 30 days = +0.10, cramming same day 20th recall = +0.02.
114
-
115
- **Update in both the memory file AND index.json:**
116
- - `last_accessed` → current timestamp
117
- - `access_count` → increment by 1
118
- - `recall_history` → append current timestamp
119
- - `strength` → min(1.0, strength + boost)
120
- - `decay_rate` → improved via: `decay_rate + 0.10 * (0.999 - decay_rate)` (memories become progressively more forgetting-resistant)
121
-
122
- ### 7. Hebbian Co-Retrieval Learning
123
-
124
- When multiple memories are returned together (Case B), strengthen their mutual association edges in `associations.json`:
125
- - For each pair of retrieved memories, call `reinforceEdge()` with origin `co_retrieval`
126
- - This implements "neurons that fire together wire together" — memories recalled in the same context become more tightly linked over time
76
+ Or if globally installed:
77
+ ```bash
78
+ brain reinforce <mem_id1> <mem_id2> ...
79
+ ```
127
80
 
128
- Write the updated `associations.json`.
81
+ This deterministically applies:
82
+ - **Spaced reinforcement** — strength boost based on time since last access
83
+ - **Decay rate improvement** — memories become more forgetting-resistant
84
+ - **Hebbian co-retrieval** — strengthens association edges between all returned memories
129
85
 
130
- ### 8. Present Results
86
+ ### 6. Present Results
131
87
 
132
88
  Format the output clearly. Include confidence indicators for low-confidence memories.
133
89
 
134
90
  ```
135
91
  ## Recalled Memory: <Title>
136
92
 
137
- **Path:** .brain/<path>
93
+ **Path:** ~/.brain/<path>
138
94
  **Strength:** <decayed_strength> (original: <base_strength>)
95
+ **Score:** <score> (relevance: <relevance>, context: <context_match>)
139
96
  **Type:** <type> (<cognitive_type>) | **Created:** <date> | **Recalled:** <access_count> times
140
- **Confidence:** <confidence> <show ⚠️ if < 0.5>
97
+ **Confidence:** <confidence> <show warning if < 0.5>
141
98
 
142
99
  <memory content>
143
100
 
144
101
  ---
145
- *Memory reinforced — strength updated to <new_strength>, decay improved to <new_decay_rate>*
102
+ *Memory reinforced — strength updated, decay improved*
146
103
  ```
147
104
 
148
105
  For consolidated responses (Case B):
@@ -153,24 +110,10 @@ For consolidated responses (Case B):
153
110
  <consolidated narrative>
154
111
 
155
112
  ### Contributing Memories
156
- 1. **<title>** (.brain/<path>) — score: <score>, confidence: <confidence>
157
- 2. **<title>** (.brain/<path>) — score: <score>, confidence: <confidence>
113
+ 1. **<title>** (~/.brain/<path>) — score: <score>
114
+ 2. **<title>** (~/.brain/<path>) — score: <score>
158
115
  ...
159
116
 
160
117
  ---
161
- *<N> memories reinforced, <M> association links strengthened*
162
- ```
163
-
164
- For archived matches (Case D fallback):
165
-
166
- ```
167
- ## Found in Archive: <Title>
168
-
169
- **Path:** .brain/_archived/<path>
170
- **Original Strength:** <strength> | **Archived:** <date>
171
-
172
- <memory content summary>
173
-
174
- ---
175
- *Would you like to restore this memory to active brain?*
118
+ *<N> memories reinforced, association links strengthened*
176
119
  ```
@@ -0,0 +1,60 @@
1
+ ---
2
+ description: Manage procedural skills (list, show, add, use, remove, export)
3
+ argument-hint: "[subcommand]"
4
+ ---
5
+
6
+ # /brain:skills — Manage Procedural Skills
7
+
8
+ You are managing **procedural memory** — reusable "how to do things" stored as `~/.brain/_skills/<name>/SKILL.md`. Skills use **progressive disclosure** so they never bloat the context window:
9
+
10
+ - **L0 (session start):** only each skill's name + description is advertised (≈100 tokens each).
11
+ - **L1 (on a matching task):** read the full `SKILL.md` for step-by-step instructions.
12
+ - **L2 (at execution):** load any referenced `resources/` (templates, scripts) only when a step needs them.
13
+
14
+ **User input:** $ARGUMENTS
15
+
16
+ ## Actions
17
+
18
+ **List** advertised skills:
19
+ ```bash
20
+ brain skill list
21
+ ```
22
+
23
+ **Show** a skill's full instructions (do this when a task matches a skill's description/triggers):
24
+ ```bash
25
+ brain skill show <name>
26
+ ```
27
+
28
+ **Add** a skill — pipe JSON on stdin:
29
+ ```bash
30
+ brain skill add <<'EOF'
31
+ {
32
+ "name": "structured-code-review",
33
+ "description": "One-paragraph advertised summary used for matching (~100 tokens).",
34
+ "triggers": ["code review", "review PR", "audit changes"],
35
+ "body": "## Steps\n1. ...\n2. ..."
36
+ }
37
+ EOF
38
+ ```
39
+
40
+ **Use** — record an outcome after running a skill. Success strengthens it; `--failed` weakens it (a skill that fails too often demotes itself out of the advertised L0 index):
41
+ ```bash
42
+ brain skill use <name> # succeeded
43
+ brain skill use <name> --failed # produced a bad outcome
44
+ ```
45
+
46
+ **Remove** a skill:
47
+ ```bash
48
+ brain skill remove <name>
49
+ ```
50
+
51
+ **Export** a skill into the host agent's native format so it becomes directly executable (writes `.claude/skills/<name>/SKILL.md` or `.gemini/...` in the current project):
52
+ ```bash
53
+ brain skill export <name> [--target claude|gemini]
54
+ ```
55
+
56
+ ## Guidance
57
+
58
+ - Advertise skills with a **crisp, matchable description** — that single line is all the agent sees at L0, so it must convey when to reach for the skill.
59
+ - Reach for `show` only when a task genuinely matches; don't pre-load skills speculatively.
60
+ - Always record the outcome with `use` (success or `--failed`) so the strength/demotion feedback loop stays accurate.
@@ -1,6 +1,11 @@
1
+ ---
2
+ description: Full maintenance cycle: replay, homeostasis, consolidation, pruning, dreaming
3
+ argument-hint: "[scope]"
4
+ ---
5
+
1
6
  # /brain:sleep — Overnight Memory Reorganization
2
7
 
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.
8
+ 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
9
 
5
10
  **Scope:** $ARGUMENTS
6
11
 
@@ -12,37 +17,20 @@ Sleep performs nine phases, mimicking real neuroscience:
12
17
  2. **Synaptic Homeostasis** — Proportionally scale down all strengths to prevent inflation (Tononi & Cirelli SHY)
13
18
  3. **Knowledge Propagation** — Evaluate recent memories against the hierarchy and update related memories
14
19
  4. **Semantic Crystallization** — Extract generalizable knowledge from frequently-recalled episodic memories
20
+ - **4b. Procedural Crystallization** — Distill repeated procedures into reusable skills (CoALA Phase 3)
15
21
  5. **Reorganize** — Detect flat clusters and restructure into deeper sub-categories
16
22
  6. **Consolidate** — Merge weak related memories into stronger combined knowledge
17
- 7. **Prune** — Archive memories that have decayed beyond recovery
23
+ 7. **Prune** — Archive memories that have decayed beyond recovery, including context-shift obsolescence (Tier B §10.1)
18
24
  8. **REM Dreaming** — Discover creative cross-domain associations via analogical reasoning
19
25
  9. **Expertise Detection** — Identify dense knowledge areas and generate expertise profiles
20
26
 
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
27
  ## Phase 1: Replay (Hippocampal Scan)
40
28
 
41
29
  During sleep, the hippocampus replays the day's events. Here, we scan and assess the full brain state.
42
30
 
43
31
  ### Steps
44
32
 
45
- 1. Read `.brain/index.json` to load all memories
33
+ 1. Read `~/.brain/index.json` to load all memories
46
34
  2. If $ARGUMENTS specifies a category path, limit scope to that subtree. Otherwise, process the entire brain.
47
35
  3. For **every** memory, compute the current decayed strength:
48
36
 
@@ -51,6 +39,8 @@ days_elapsed = (now - last_accessed) / (1000 * 60 * 60 * 24)
51
39
  decayed_strength = strength * (decay_rate ^ days_elapsed)
52
40
  ```
53
41
 
42
+ **Decay-exempt memories (CoALA Phase 1):** if a memory is `pinned` or `stable`, its `decayed_strength` equals its raw `strength` (it never fades). Treat such memories as **Strong** regardless of elapsed time.
43
+
54
44
  4. Categorize each memory into tiers:
55
45
  - **Strong** (decayed_strength >= 0.6) — healthy, no action needed
56
46
  - **Moderate** (0.3 <= decayed_strength < 0.6) — consolidation candidates
@@ -96,7 +86,7 @@ Based on Tononi & Cirelli's **Synaptic Homeostasis Hypothesis (SHY)** — during
96
86
  scaling_factor = max(0.85, 0.5 / mean_effective_strength)
97
87
  ```
98
88
 
99
- 3. For every memory: `strength = strength * scaling_factor`
89
+ 3. For every memory: `strength = strength * scaling_factor` — **except** `pinned` or `stable` memories, which are exempt from homeostatic downscaling (their strength is never altered).
100
90
 
101
91
  4. Selectively re-boost important memories:
102
92
  - **High salience** (salience >= 0.7): +0.05
@@ -282,6 +272,47 @@ Approve crystallizations? [all / select / skip]
282
272
 
283
273
  ---
284
274
 
275
+ ## Phase 4b: Procedural Crystallization (Episodic → Procedural) — CoALA Phase 3
276
+
277
+ Beyond abstracting *principles* (Phase 4), the brain also turns repeated *procedures* into skills. When the same kind of task has been solved the same way several times, distill it into a reusable `SKILL.md` — Brain's genuine value-add over CoALA, which only describes hand-authored skills.
278
+
279
+ ### Steps
280
+
281
+ 1. Cluster `procedural`/`experience` memories by tag overlap + association edges (the same clustering used elsewhere). Look for a recurring *task-solving procedure* represented across **≥ N similar memories** (default N = 3).
282
+
283
+ 2. For each qualifying cluster, evaluate: **is there a repeatable, step-by-step procedure here that would help on a future task?**
284
+
285
+ 3. If yes, draft a skill (do not write silently — propose it):
286
+ - `name`: a short kebab-case slug
287
+ - `description`: one matchable line (~100 tokens) — the L0 advertisement
288
+ - `triggers`: phrases that should surface it
289
+ - body: the step-by-step instructions, drawn from the source memories
290
+ - Create it with `brain skill add` once approved.
291
+
292
+ 4. Link the new skill to its source memories (note the skill name in their `related`/notes).
293
+
294
+ **Example:**
295
+ - 3× episodic: "set up Cloudflare Worker + D1 for project X / Y / Z" solved the same way
296
+ - → Skill `deploy-cloudflare-worker-d1`: the distilled step list.
297
+
298
+ Present proposals for user approval (never auto-create):
299
+
300
+ ```
301
+ ## Phase 4b: Procedural Crystallization
302
+
303
+ Found <N> recurring procedures ready to become skills:
304
+
305
+ 🛠️ Pattern seen 3× across {projX, projY, projZ}
306
+ → Proposed skill: "deploy-cloudflare-worker-d1"
307
+ Triggers: "deploy worker", "set up D1"
308
+
309
+ Approve skill creation? [all / select / skip]
310
+ ```
311
+
312
+ These crystallized skills are *hypotheses*: their strength/demotion feedback (`brain skill use [--failed]`) validates or retires them over time.
313
+
314
+ ---
315
+
285
316
  ## Phase 5: Reorganize (Neocortical Restructuring)
286
317
 
287
318
  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.
@@ -345,7 +376,7 @@ During deep sleep, the brain merges related experiences into generalized knowled
345
376
 
346
377
  5. For approved consolidations:
347
378
  - 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`
379
+ - Archive source memories to `~/.brain/_archived/` and add them to `_archived/index.json`
349
380
  - Transfer association edges from source memories to the consolidated memory in `associations.json`
350
381
  - Update `index.json` and `_meta.json` files
351
382
 
@@ -355,21 +386,32 @@ During deep sleep, the brain merges related experiences into generalized knowled
355
386
 
356
387
  During sleep, the brain prunes weak synaptic connections to maintain efficiency. Here, we archive memories that have faded beyond usefulness.
357
388
 
389
+ ### Obsolescence / context-shift detection (Tier B §10.1)
390
+
391
+ Decay handles *slow fade*; this catches *abrupt relevance loss*. A memory cluster can become obsolete overnight (the user changed jobs, abandoned a project, switched stacks) while still carrying high strength — so decay alone never retires it.
392
+
393
+ - Read `~/.brain/contexts.json`. Identify any `encoding_context.project` (or role/domain) that appears in older memories but has been **absent from the last N sessions** (default N = 10).
394
+ - Flag the affected cluster (by project + association edges) as **candidate-obsolete** — these become *additional* archive candidates below.
395
+ - **Never** flag `pinned` memories (an explicit, active user choice). `stable` memories *can* be flagged — stability exempts from decay, not from obsolescence (a timeless fact about a former employer is still obsolete).
396
+ - This is reversible: candidates are *archived* (recoverable from `_archived/`), never erased, and only after user confirmation.
397
+
358
398
  ### Steps
359
399
 
360
- 1. Take all **Fading** tier memories (decayed_strength < 0.1) that were NOT already consolidated in Phase 6
400
+ 1. Take all **Fading** tier memories (decayed_strength < 0.1) that were NOT already consolidated in Phase 6 — plus any **candidate-obsolete** clusters from the detection step above
361
401
 
362
402
  2. **Salience protection**: Memories with `salience >= 0.7` are NEVER auto-pruned, regardless of strength. Skip them with a note:
363
403
  ```
364
404
  ⚡ Skipping <title> — high salience (0.8) protects from auto-pruning
365
405
  ```
366
406
 
367
- 3. Present the prune list (excluding salience-protected memories)
407
+ **Pinned/stable protection (CoALA Phase 1):** `pinned` or `stable` memories are also NEVER pruned or archived — they are decay-exempt, so they never reach the Fading tier in the first place. Skip them too.
408
+
409
+ 3. Present the prune list (excluding salience- and pin/stable-protected memories)
368
410
 
369
411
  4. Get user approval (default: archive all)
370
412
 
371
413
  5. Execute:
372
- - Move to `.brain/_archived/`, preserving directory structure
414
+ - Move to `~/.brain/_archived/`, preserving directory structure
373
415
  - Add to `_archived/index.json` with original metadata
374
416
  - Remove from `index.json` and update `_meta.json` files
375
417
  - Remove association edges involving pruned memories from `associations.json`
@@ -513,7 +555,7 @@ After all phases complete, present a comprehensive sleep report:
513
555
  <creative associations from Phase 8>
514
556
 
515
557
  ### Memories Due for Review
516
- <count> memories due within the next 7 days — run /brain:review
558
+ <count> memories due within the next 7 days — reinforced during this and future sleep cycles
517
559
 
518
560
  ### Recommendations
519
561
  - <actionable suggestions based on what sleep revealed>
@@ -532,4 +574,3 @@ After all phases complete, present a comprehensive sleep report:
532
574
  7. **Idempotent expertise** — if `_expertise.md` already exists, update it rather than creating a duplicate.
533
575
  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
576
  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.
@@ -1,3 +1,7 @@
1
+ ---
2
+ description: Dashboard with brain health overview
3
+ ---
4
+
1
5
  # /brain:status — Brain Overview Dashboard
2
6
 
3
7
  You are displaying a comprehensive overview of the Brain Memory system's current state.
@@ -6,12 +10,13 @@ You are displaying a comprehensive overview of the Brain Memory system's current
6
10
 
7
11
  ### 1. Read Brain State
8
12
 
9
- Read `.brain/index.json` to get the full memory inventory. If `.brain/` doesn't exist, inform the user and suggest running `/brain:init`.
13
+ Read `~/.brain/index.json` to get the full memory inventory. If `~/.brain/` doesn't exist, inform the user — it is created automatically by the installer, or on the first `/brain:memorize` or `/brain:sync`.
10
14
 
11
15
  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
16
+ - `~/.brain/associations.json` — for association network stats
17
+ - `~/.brain/review-queue.json` — for review schedule info
18
+ - `~/.brain/_archived/index.json` — for archive stats
19
+ - `~/.brain/.sync/config.json` — for git sync configuration
15
20
 
16
21
  ### 2. Compute Statistics
17
22
 
@@ -36,7 +41,7 @@ Calculate aggregate stats:
36
41
 
37
42
  ```
38
43
  ╔══════════════════════════════════════════╗
39
- ║ 🧠 BRAIN STATUS ║
44
+ ║ ◉ BRAIN STATUS ║
40
45
  ╠══════════════════════════════════════════╣
41
46
  ║ Total Memories: <count> ║
42
47
  ║ Archived: <count> ║
@@ -92,18 +97,26 @@ Calculate aggregate stats:
92
97
 
93
98
  ## Fading Memories (decayed strength < 0.3)
94
99
  ⚠ <count> memories below consolidation threshold
95
- Run /brain:consolidate to preserve them
100
+ Run /brain:sleep to consolidate and preserve them
96
101
 
97
102
  ## Review Queue
98
103
  📋 Due now: <count> memories
99
104
  📋 Due this week: <count> memories
100
105
  📋 Total in queue: <count> memories
101
- Run /brain:review to start a review session
106
+ Due memories are reinforced automatically during /brain:sleep
102
107
 
103
108
  ## Recent Memories (Last 7 days)
104
109
  + <title> (<path>) — <date>
105
110
  + <title> (<path>) — <date>
106
111
  ...
112
+
113
+ ## Sync
114
+ Remote: <remote URL or "not configured">
115
+ Encryption: <enabled/disabled>
116
+ Last Push: <timestamp or "never">
117
+ Last Pull: <timestamp or "never">
118
+ Ahead: <count> commits
119
+ Behind: <count> commits
107
120
  ```
108
121
 
109
122
  ### 4. Health Check
@@ -111,12 +124,13 @@ Calculate aggregate stats:
111
124
  Analyze the brain's health and provide recommendations:
112
125
 
113
126
  - **"Healthy"** — Good distribution across categories, strong average strength
114
- - **"Needs consolidation"** — Many memories below threshold, suggest `/brain:consolidate`
127
+ - **"Needs consolidation"** — Many memories below threshold, suggest `/brain:sleep`
115
128
  - **"Imbalanced"** — One category dominates, suggest diversifying
116
129
  - **"Stale"** — No new memories in 14+ days, suggest `/brain:memorize`
117
130
  - **"Overloaded"** — More than 200 active memories, suggest pruning with `/brain:forget --prune`
118
131
  - **"Needs propagation"** — Recent memories exist alongside older related memories that haven't been updated. Suggest `/brain:sleep`
119
132
  - **"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
133
  - **"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.
134
+ - **"Review overdue"** — More than 10 memories are past their review date. Suggest `/brain:sleep` (its replay pass reinforces them)
135
+ - **"Sync available"** — Git sync is not configured. Suggest `/brain:sync setup` for cross-device access.
136
+ - **"Sync stale"** — Last push was more than 7 days ago. Suggest `/brain:sync push`.