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.
- package/CHANGELOG.md +339 -0
- package/README.md +400 -94
- package/SECURITY.md +61 -0
- package/assets/brand/README.md +28 -0
- package/assets/brand/icon-dark.svg +19 -0
- package/assets/brand/icon-light.svg +20 -0
- package/assets/brand/linkedin_cover.png +0 -0
- package/assets/brand/linkedin_cover_light.png +0 -0
- package/assets/brand/mark-dark.svg +19 -0
- package/assets/brand/mark-light.svg +20 -0
- package/assets/brand/png/icon-dark-1024.png +0 -0
- package/assets/brand/png/icon-dark-128.png +0 -0
- package/assets/brand/png/icon-dark-256.png +0 -0
- package/assets/brand/png/icon-dark-512.png +0 -0
- package/assets/brand/png/icon-dark-64.png +0 -0
- package/assets/brand/png/icon-light-1024.png +0 -0
- package/assets/brand/png/icon-light-128.png +0 -0
- package/assets/brand/png/icon-light-256.png +0 -0
- package/assets/brand/png/icon-light-512.png +0 -0
- package/assets/brand/png/icon-light-64.png +0 -0
- package/assets/brand/png/mark-dark-1024.png +0 -0
- package/assets/brand/png/mark-light-1024.png +0 -0
- package/assets/icon.png +0 -0
- package/assets/icon.svg +19 -0
- package/bin/brain.js +111 -0
- package/bin/cloud-sync.js +150 -0
- package/bin/forget.js +122 -0
- package/bin/install.js +229 -254
- package/bin/memorize.js +458 -0
- package/bin/pin.js +44 -0
- package/bin/recall.js +259 -0
- package/bin/reinforce.js +187 -0
- package/bin/session-start.js +298 -0
- package/bin/skill.js +67 -0
- package/bin/unpin.js +38 -0
- package/commands/brain/forget.md +245 -15
- package/commands/brain/memorize.md +76 -144
- package/commands/brain/pin.md +79 -0
- package/commands/brain/remember.md +48 -105
- package/commands/brain/skills.md +60 -0
- package/commands/brain/sleep.md +69 -28
- package/commands/brain/status.md +24 -10
- package/commands/brain/sync.md +386 -0
- package/package.json +22 -8
- package/prompts/antigravity.md +180 -0
- package/prompts/claude.md +124 -20
- package/prompts/openai.md +124 -20
- package/prompts/opencode.md +179 -0
- package/src/cloud-sync.js +534 -0
- package/src/crypto.js +130 -0
- package/src/export-import.js +200 -0
- package/src/git-sync.js +444 -0
- package/src/index-manager.js +219 -18
- package/src/installer.js +444 -0
- package/src/pinning.js +124 -0
- package/src/scorer.js +45 -11
- package/src/skills.js +208 -0
- package/src/tfidf.js +520 -0
- package/commands/brain/consolidate.md +0 -153
- package/commands/brain/explore.md +0 -79
- package/commands/brain/init.md +0 -157
- package/commands/brain/review.md +0 -130
- package/commands/brain/sunshine.md +0 -337
- package/hooks/session-end.md +0 -48
- package/hooks/session-start.md +0 -48
- 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
|
|
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.
|
|
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
|
-
|
|
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
|
-
###
|
|
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
|
-
|
|
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
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
###
|
|
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
|
|
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
|
|
91
|
-
Search
|
|
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
|
-
|
|
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
|
-
|
|
70
|
+
After presenting results, run the reinforcement engine for all memories shown to the user:
|
|
101
71
|
|
|
102
|
-
|
|
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
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
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
|
-
|
|
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
|
-
###
|
|
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:**
|
|
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
|
|
97
|
+
**Confidence:** <confidence> <show warning if < 0.5>
|
|
141
98
|
|
|
142
99
|
<memory content>
|
|
143
100
|
|
|
144
101
|
---
|
|
145
|
-
*Memory reinforced — strength updated
|
|
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>** (
|
|
157
|
-
2. **<title>** (
|
|
113
|
+
1. **<title>** (~/.brain/<path>) — score: <score>
|
|
114
|
+
2. **<title>** (~/.brain/<path>) — score: <score>
|
|
158
115
|
...
|
|
159
116
|
|
|
160
117
|
---
|
|
161
|
-
*<N> memories reinforced,
|
|
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.
|
package/commands/brain/sleep.md
CHANGED
|
@@ -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
|
|
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
|
|
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
|
|
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
|
-
|
|
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
|
|
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 —
|
|
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.
|
package/commands/brain/status.md
CHANGED
|
@@ -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
|
|
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
|
-
-
|
|
13
|
-
-
|
|
14
|
-
-
|
|
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
|
-
║
|
|
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:
|
|
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
|
-
|
|
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:
|
|
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:
|
|
122
|
-
- **"
|
|
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`.
|