brain-memory 0.1.0-beta.21 → 0.1.0-beta.23
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/README.md +11 -15
- package/bin/install.js +9 -11
- package/bin/recall.js +1 -1
- package/commands/brain/forget.md +240 -15
- package/commands/brain/pin.md +53 -11
- package/commands/brain/remember.md +1 -1
- package/commands/brain/sleep.md +1 -1
- package/commands/brain/status.md +5 -5
- package/commands/brain/sync.md +27 -1
- package/package.json +1 -1
- package/prompts/claude.md +13 -12
- package/prompts/gemini.md +13 -12
- package/prompts/openai.md +13 -12
- package/prompts/opencode.md +13 -12
- package/src/export-import.js +1 -1
- package/src/installer.js +5 -1
- package/commands/brain/consolidate.md +0 -158
- package/commands/brain/explore.md +0 -84
- package/commands/brain/init.md +0 -153
- package/commands/brain/review.md +0 -135
- package/commands/brain/sunshine.md +0 -342
- package/commands/brain/unpin.md +0 -26
package/prompts/gemini.md
CHANGED
|
@@ -49,20 +49,21 @@ Memories store their encoding context (project, topics, task type). During recal
|
|
|
49
49
|
## Available Commands
|
|
50
50
|
|
|
51
51
|
Commands are available via `/brain:` prefix:
|
|
52
|
-
|
|
53
|
-
|
|
52
|
+
The everyday loop is **ambient** — `remember` and `memorize` run automatically at session start/end; you rarely type them.
|
|
53
|
+
|
|
54
|
+
**Core**
|
|
54
55
|
- `/brain:remember [query]` — Recall relevant memories with spreading activation and context matching
|
|
55
|
-
- `/brain:
|
|
56
|
-
- `/brain:explore [category]` — Browse the brain hierarchy
|
|
57
|
-
- `/brain:consolidate [scope]` — Merge related weak memories into stronger ones
|
|
58
|
-
- `/brain:forget [target]` — Decay or archive memories
|
|
59
|
-
- `/brain:sunshine [target]` — Deep forensic erasure — trace and remove all references to a memory
|
|
60
|
-
- `/brain:sleep [scope]` — Full maintenance cycle: replay, synaptic homeostasis, knowledge propagation, semantic crystallization, reorganize, consolidate, prune, REM dreaming, and expertise detection
|
|
56
|
+
- `/brain:memorize [topic]` — Store memories from the current context
|
|
61
57
|
- `/brain:status` — Dashboard with brain health overview
|
|
62
|
-
- `/brain:
|
|
63
|
-
- `/brain:
|
|
64
|
-
|
|
65
|
-
|
|
58
|
+
- `/brain:pin [id|query]` — Pin a memory to the always-present tier (toggle — also unpins, e.g. `--off`)
|
|
59
|
+
- `/brain:forget [target]` — Decay or archive memories (`--deep` = forensic erasure of every reference)
|
|
60
|
+
|
|
61
|
+
**Sync & skills**
|
|
62
|
+
- `/brain:sync [subcommand]` — Sync via Brain Cloud, Git remote, or export/import (auto-initializes on first run)
|
|
63
|
+
- `/brain:skills [list|show|add|use|remove|export]` — Manage procedural skills
|
|
64
|
+
|
|
65
|
+
**Maintenance (usually automatic — runs in the background)**
|
|
66
|
+
- `/brain:sleep [scope]` — Full maintenance cycle: replay, homeostasis, propagation, crystallization, reorganize, consolidate, prune, review reinforcement, REM dreaming, expertise detection
|
|
66
67
|
|
|
67
68
|
## Session Start Behavior
|
|
68
69
|
|
package/prompts/openai.md
CHANGED
|
@@ -49,20 +49,21 @@ Memories store their encoding context (project, topics, task type). During recal
|
|
|
49
49
|
## Available Commands
|
|
50
50
|
|
|
51
51
|
Brain skills are available via `/brain-` prefix:
|
|
52
|
-
|
|
53
|
-
|
|
52
|
+
The everyday loop is **ambient** — `remember` and `memorize` run automatically at session start/end; you rarely type them.
|
|
53
|
+
|
|
54
|
+
Core:
|
|
54
55
|
- `/brain-remember [query]` — Recall relevant memories with spreading activation and context matching
|
|
55
|
-
- `/brain-
|
|
56
|
-
- `/brain-explore [category]` — Browse the brain hierarchy
|
|
57
|
-
- `/brain-consolidate [scope]` — Merge related weak memories into stronger ones
|
|
58
|
-
- `/brain-forget [target]` — Decay or archive memories
|
|
59
|
-
- `/brain-sunshine [target]` — Deep forensic erasure — trace and remove all references to a memory
|
|
60
|
-
- `/brain-sleep [scope]` — Full maintenance cycle: replay, synaptic homeostasis, knowledge propagation, semantic crystallization, reorganize, consolidate, prune, REM dreaming, and expertise detection
|
|
56
|
+
- `/brain-memorize [topic]` — Store memories from the current context
|
|
61
57
|
- `/brain-status` — Dashboard with brain health overview
|
|
62
|
-
- `/brain-
|
|
63
|
-
- `/brain-
|
|
64
|
-
|
|
65
|
-
|
|
58
|
+
- `/brain-pin [id|query]` — Pin a memory to the always-present tier (toggle — also unpins, e.g. `--off`)
|
|
59
|
+
- `/brain-forget [target]` — Decay or archive memories (`--deep` = forensic erasure of every reference)
|
|
60
|
+
|
|
61
|
+
Sync & skills:
|
|
62
|
+
- `/brain-sync [subcommand]` — Sync via Brain Cloud, Git remote, or export/import (auto-initializes on first run)
|
|
63
|
+
- `/brain-skill [list|show|add|use|remove|export]` — Manage procedural skills
|
|
64
|
+
|
|
65
|
+
Maintenance (usually automatic — runs in the background):
|
|
66
|
+
- `/brain-sleep [scope]` — Full maintenance cycle: replay, homeostasis, propagation, crystallization, reorganize, consolidate, prune, review reinforcement, REM dreaming, expertise detection
|
|
66
67
|
|
|
67
68
|
## Session Start Behavior
|
|
68
69
|
|
package/prompts/opencode.md
CHANGED
|
@@ -48,20 +48,21 @@ Memories store their encoding context (project, topics, task type). During recal
|
|
|
48
48
|
|
|
49
49
|
## Available Commands
|
|
50
50
|
|
|
51
|
-
|
|
52
|
-
|
|
51
|
+
The everyday loop is **ambient** — `remember` and `memorize` run automatically at session start/end; you rarely type them.
|
|
52
|
+
|
|
53
|
+
**Core**
|
|
53
54
|
- `/brain:remember [query]` — Recall relevant memories with spreading activation and context matching
|
|
54
|
-
- `/brain:
|
|
55
|
-
- `/brain:explore [category]` — Browse the brain hierarchy
|
|
56
|
-
- `/brain:consolidate [scope]` — Merge related weak memories into stronger ones
|
|
57
|
-
- `/brain:forget [target]` — Decay or archive memories
|
|
58
|
-
- `/brain:sunshine [target]` — Deep forensic erasure — trace and remove all references to a memory
|
|
59
|
-
- `/brain:sleep [scope]` — Full maintenance cycle: replay, synaptic homeostasis, knowledge propagation, semantic crystallization, reorganize, consolidate, prune, REM dreaming, and expertise detection
|
|
55
|
+
- `/brain:memorize [topic]` — Store memories from the current context
|
|
60
56
|
- `/brain:status` — Dashboard with brain health overview
|
|
61
|
-
- `/brain:
|
|
62
|
-
- `/brain:
|
|
63
|
-
|
|
64
|
-
|
|
57
|
+
- `/brain:pin [id|query]` — Pin a memory to the always-present tier (toggle — also unpins, e.g. `--off`)
|
|
58
|
+
- `/brain:forget [target]` — Decay or archive memories (`--deep` = forensic erasure of every reference)
|
|
59
|
+
|
|
60
|
+
**Sync & skills**
|
|
61
|
+
- `/brain:sync [subcommand]` — Sync via Brain Cloud, Git remote, or export/import (auto-initializes on first run)
|
|
62
|
+
- `/brain:skills [list|show|add|use|remove|export]` — Manage procedural skills
|
|
63
|
+
|
|
64
|
+
**Maintenance (usually automatic — runs in the background)**
|
|
65
|
+
- `/brain:sleep [scope]` — Full maintenance cycle: replay, homeostasis, propagation, crystallization, reorganize, consolidate, prune, review reinforcement, REM dreaming, expertise detection
|
|
65
66
|
|
|
66
67
|
## Session Start Behavior
|
|
67
68
|
|
package/src/export-import.js
CHANGED
|
@@ -25,7 +25,7 @@ const EXCLUDED = new Set(['.sync', '.DS_Store']);
|
|
|
25
25
|
*/
|
|
26
26
|
function exportBrain(brainDir, outputPath, passphrase) {
|
|
27
27
|
if (!fs.existsSync(brainDir)) {
|
|
28
|
-
throw new Error('~/.brain/ directory not found.
|
|
28
|
+
throw new Error('~/.brain/ directory not found. Reinstall with `npx brain-memory`, or run /brain:sync to create it.');
|
|
29
29
|
}
|
|
30
30
|
|
|
31
31
|
const files = {};
|
package/src/installer.js
CHANGED
|
@@ -114,7 +114,11 @@ function detectInstallations() {
|
|
|
114
114
|
let commandsFound = false;
|
|
115
115
|
if (config.commandStyle === 'skills') {
|
|
116
116
|
const skillsDir = path.join(targetDir, config.commandsSubdir);
|
|
117
|
-
commandsFound = fs.existsSync(
|
|
117
|
+
commandsFound = fs.existsSync(skillsDir) &&
|
|
118
|
+
fs.readdirSync(skillsDir).some(
|
|
119
|
+
(d) => d.startsWith('brain-') &&
|
|
120
|
+
fs.existsSync(path.join(skillsDir, d, 'SKILL.md'))
|
|
121
|
+
);
|
|
118
122
|
} else {
|
|
119
123
|
const commandsDir = path.join(targetDir, config.commandsSubdir, 'brain');
|
|
120
124
|
commandsFound = fs.existsSync(commandsDir) &&
|
|
@@ -1,158 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
description: Merge related weak memories into stronger combined memories
|
|
3
|
-
argument-hint: "[scope]"
|
|
4
|
-
---
|
|
5
|
-
|
|
6
|
-
# /brain:consolidate — Merge Related Memories
|
|
7
|
-
|
|
8
|
-
You are consolidating memories in the Brain Memory system. Consolidation combines multiple related or weakening memories into a single stronger, more coherent memory — mimicking how human brains merge similar experiences into generalized knowledge.
|
|
9
|
-
|
|
10
|
-
**Target scope:** $ARGUMENTS
|
|
11
|
-
|
|
12
|
-
## Steps
|
|
13
|
-
|
|
14
|
-
### 1. Determine Scope
|
|
15
|
-
|
|
16
|
-
- If $ARGUMENTS specifies a category path, consolidate within that subtree
|
|
17
|
-
- If $ARGUMENTS is empty, scan the entire `~/.brain/` for consolidation candidates
|
|
18
|
-
- If $ARGUMENTS is "auto", perform automatic consolidation based on thresholds
|
|
19
|
-
|
|
20
|
-
### 2. Find Consolidation Candidates
|
|
21
|
-
|
|
22
|
-
Read `index.json` and identify candidate groups using these criteria:
|
|
23
|
-
|
|
24
|
-
**Automatic candidates (any of):**
|
|
25
|
-
- Memories with effective (decayed) strength below `consolidation_threshold` (default: 0.3)
|
|
26
|
-
- Clusters of 3+ memories in the same directory with overlapping tags
|
|
27
|
-
- Memories with the same type in the same category that are older than 30 days
|
|
28
|
-
|
|
29
|
-
**Compute decayed strength for each:**
|
|
30
|
-
```
|
|
31
|
-
days_elapsed = (now - last_accessed) / (1000 * 60 * 60 * 24)
|
|
32
|
-
decayed_strength = strength * (decay_rate ^ days_elapsed)
|
|
33
|
-
```
|
|
34
|
-
|
|
35
|
-
### 3. Group Related Memories
|
|
36
|
-
|
|
37
|
-
Group candidates by:
|
|
38
|
-
1. **Path proximity** — memories in the same or nearby directories
|
|
39
|
-
2. **Tag overlap** — memories sharing 2+ tags
|
|
40
|
-
3. **Type similarity** — same memory type
|
|
41
|
-
4. **Temporal proximity** — created within similar time periods
|
|
42
|
-
|
|
43
|
-
Present the proposed groups to the user:
|
|
44
|
-
|
|
45
|
-
```
|
|
46
|
-
## Consolidation Candidates
|
|
47
|
-
|
|
48
|
-
### Group 1: Kubernetes Deployments (professional/companies/acme/projects/)
|
|
49
|
-
- deployment-v1.md (strength: 0.22, type: experience)
|
|
50
|
-
- deployment-v2.md (strength: 0.18, type: experience)
|
|
51
|
-
- k8s-config-issue.md (strength: 0.15, type: learning)
|
|
52
|
-
→ Proposed: Merge into "kubernetes-deployment-lessons.md" (strength: 0.75)
|
|
53
|
-
|
|
54
|
-
### Group 2: TypeScript Learnings (personal/education/)
|
|
55
|
-
- ts-generics.md (strength: 0.28, type: learning)
|
|
56
|
-
- ts-utility-types.md (strength: 0.25, type: learning)
|
|
57
|
-
→ Proposed: Merge into "typescript-advanced-types.md" (strength: 0.65)
|
|
58
|
-
```
|
|
59
|
-
|
|
60
|
-
### 4. Get User Approval
|
|
61
|
-
|
|
62
|
-
Ask the user which groups to consolidate. They can:
|
|
63
|
-
- Approve all proposed groups
|
|
64
|
-
- Select specific groups
|
|
65
|
-
- Modify groupings
|
|
66
|
-
- Cancel
|
|
67
|
-
|
|
68
|
-
### 5. Perform Consolidation
|
|
69
|
-
|
|
70
|
-
For each approved group:
|
|
71
|
-
|
|
72
|
-
1. **Read all source memories** in the group
|
|
73
|
-
2. **Synthesize** a new consolidated memory that:
|
|
74
|
-
- Preserves all key details and insights from the sources
|
|
75
|
-
- Identifies patterns and evolution across the memories
|
|
76
|
-
- Creates a coherent narrative or structured summary
|
|
77
|
-
- Is more concise than the sum of its parts
|
|
78
|
-
3. **Calculate new strength**: `max(source_strengths) + 0.15` (capped at 1.0)
|
|
79
|
-
4. **Set new decay rate**: Use the slowest decay rate from the sources
|
|
80
|
-
5. **Merge tags**: Union of all source memory tags
|
|
81
|
-
6. **Set related**: Include all source memory IDs in the `related` field
|
|
82
|
-
7. **Salience anchoring**: The highest-salience memory in the group is the "anchor" — its framing and key details take priority in the synthesis. Inherit max salience.
|
|
83
|
-
8. **Confidence**: Inherit the maximum confidence from the group
|
|
84
|
-
9. **Cognitive type**: Set to `semantic` (consolidation abstracts knowledge)
|
|
85
|
-
|
|
86
|
-
### 6. Write Consolidated Memory
|
|
87
|
-
|
|
88
|
-
Create the new memory file in the appropriate location (same directory as the majority of sources, or in `_consolidated/` if sources span categories).
|
|
89
|
-
|
|
90
|
-
Use the standard memory format with an additional section:
|
|
91
|
-
|
|
92
|
-
```markdown
|
|
93
|
-
---
|
|
94
|
-
id: mem_<date>_<hex>
|
|
95
|
-
type: consolidated
|
|
96
|
-
cognitive_type: semantic
|
|
97
|
-
created: <now>
|
|
98
|
-
last_accessed: <now>
|
|
99
|
-
access_count: 0
|
|
100
|
-
recall_history: []
|
|
101
|
-
strength: <calculated>
|
|
102
|
-
decay_rate: <calculated>
|
|
103
|
-
salience: <max from sources>
|
|
104
|
-
confidence: <max from sources>
|
|
105
|
-
tags: [<merged tags>]
|
|
106
|
-
related: [<all source IDs>]
|
|
107
|
-
consolidated_from: [<source IDs>]
|
|
108
|
-
source: consolidation
|
|
109
|
-
encoding_context:
|
|
110
|
-
project: <project if shared, otherwise omit>
|
|
111
|
-
topics: [<merged key topics>]
|
|
112
|
-
task_type: <most common from sources>
|
|
113
|
-
---
|
|
114
|
-
|
|
115
|
-
# <Descriptive Title>
|
|
116
|
-
|
|
117
|
-
<Synthesized summary>
|
|
118
|
-
|
|
119
|
-
## Key Patterns
|
|
120
|
-
|
|
121
|
-
<Patterns identified across the source memories>
|
|
122
|
-
|
|
123
|
-
## Timeline
|
|
124
|
-
|
|
125
|
-
<Chronological evolution if applicable>
|
|
126
|
-
|
|
127
|
-
## Source Memories
|
|
128
|
-
|
|
129
|
-
<List of original memories that were merged, with their dates and original titles>
|
|
130
|
-
```
|
|
131
|
-
|
|
132
|
-
### 7. Archive Source Memories
|
|
133
|
-
|
|
134
|
-
Move the original source memory files to a `~/.brain/_archived/` directory (create if needed), preserving their paths as subdirectories. This keeps them recoverable and searchable via `/brain:remember`.
|
|
135
|
-
|
|
136
|
-
Update `index.json`:
|
|
137
|
-
- Remove archived memory entries from `memories`
|
|
138
|
-
- Add the new consolidated memory
|
|
139
|
-
- Update `memory_count`
|
|
140
|
-
- Update `last_updated`
|
|
141
|
-
|
|
142
|
-
Update `_archived/index.json`:
|
|
143
|
-
- Add entries for each archived memory with original metadata and `archived_reason: "consolidation"`
|
|
144
|
-
|
|
145
|
-
Update `associations.json`:
|
|
146
|
-
- Transfer association edges from source memories to the new consolidated memory
|
|
147
|
-
- Remove edges pointing to archived source memories
|
|
148
|
-
|
|
149
|
-
Update `review-queue.json`:
|
|
150
|
-
- Remove entries for archived source memories
|
|
151
|
-
- Add entry for the new consolidated memory if applicable
|
|
152
|
-
|
|
153
|
-
### 8. Confirm
|
|
154
|
-
|
|
155
|
-
Print a summary:
|
|
156
|
-
- How many memories were consolidated into how many
|
|
157
|
-
- New consolidated memory titles, paths, and strengths
|
|
158
|
-
- Space saved (number of files reduced)
|
|
@@ -1,84 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
description: Browse the brain memory hierarchy
|
|
3
|
-
argument-hint: "[category]"
|
|
4
|
-
---
|
|
5
|
-
|
|
6
|
-
# /brain:explore — Browse the Brain Structure
|
|
7
|
-
|
|
8
|
-
You are exploring the Brain Memory system's hierarchical structure. This gives the user a visual overview of their memory landscape.
|
|
9
|
-
|
|
10
|
-
**Target path:** $ARGUMENTS
|
|
11
|
-
|
|
12
|
-
## Steps
|
|
13
|
-
|
|
14
|
-
### 1. Determine Scope
|
|
15
|
-
|
|
16
|
-
- If $ARGUMENTS is empty, show the full top-level overview
|
|
17
|
-
- If $ARGUMENTS specifies a category or path (e.g., "professional" or "professional/companies"), explore that subtree
|
|
18
|
-
|
|
19
|
-
### 2. Read Structure
|
|
20
|
-
|
|
21
|
-
Read the directory structure of `~/.brain/` (or the specified subtree). For each directory, read its `_meta.json` to get metadata.
|
|
22
|
-
|
|
23
|
-
### 3. Display Tree View
|
|
24
|
-
|
|
25
|
-
Present the brain structure as a visual tree with statistics:
|
|
26
|
-
|
|
27
|
-
```
|
|
28
|
-
🧠 Brain Memory Overview
|
|
29
|
-
Last updated: <timestamp>
|
|
30
|
-
Total memories: <count>
|
|
31
|
-
|
|
32
|
-
~/.brain/
|
|
33
|
-
├── professional/ (12 memories)
|
|
34
|
-
│ ├── companies/ (8 memories)
|
|
35
|
-
│ │ ├── acme-corp/ (5 memories)
|
|
36
|
-
│ │ │ ├── projects/ (3 memories)
|
|
37
|
-
│ │ │ │ ├── alpha-launch.md ⚡ 0.82
|
|
38
|
-
│ │ │ │ ├── beta-planning.md ⚡ 0.65
|
|
39
|
-
│ │ │ │ └── tech-debt-review.md ⚡ 0.41
|
|
40
|
-
│ │ │ ├── team-dynamics.md ⚡ 0.70
|
|
41
|
-
│ │ │ └── joining-decision.md ⚡ 0.88
|
|
42
|
-
│ │ └── prev-startup/ (3 memories)
|
|
43
|
-
│ ├── skills/ (3 memories)
|
|
44
|
-
│ └── career/ (1 memory)
|
|
45
|
-
├── personal/ (6 memories)
|
|
46
|
-
│ ├── education/ (3 memories)
|
|
47
|
-
│ ├── health/ (2 memories)
|
|
48
|
-
│ └── goals/ (1 memory)
|
|
49
|
-
├── social/ (2 memories)
|
|
50
|
-
│ └── communities/ (2 memories)
|
|
51
|
-
├── family/ (3 memories)
|
|
52
|
-
│ └── events/ (3 memories)
|
|
53
|
-
└── _consolidated/ (1 memory)
|
|
54
|
-
```
|
|
55
|
-
|
|
56
|
-
The ⚡ indicator shows the current effective (decayed) strength of each memory.
|
|
57
|
-
|
|
58
|
-
### 4. Category Summary
|
|
59
|
-
|
|
60
|
-
For the explored scope, provide:
|
|
61
|
-
- **Strongest memory**: Title and path of the highest-strength memory
|
|
62
|
-
- **Most accessed**: Title and path of the most frequently recalled memory
|
|
63
|
-
- **Needs attention**: Memories with decayed strength below the consolidation threshold (0.3)
|
|
64
|
-
- **Recent additions**: Memories created in the last 7 days
|
|
65
|
-
|
|
66
|
-
### 5. Offer Navigation
|
|
67
|
-
|
|
68
|
-
Suggest next actions:
|
|
69
|
-
- "Use `/brain:explore <subcategory>` to drill deeper"
|
|
70
|
-
- "Use `/brain:remember <query>` to search for specific memories"
|
|
71
|
-
- "Use `/brain:consolidate <category>` to merge weak memories in a category"
|
|
72
|
-
- "Use `/brain:sleep` to reorganize, consolidate, and detect expertise areas"
|
|
73
|
-
|
|
74
|
-
### 6. Show Expertise (if available)
|
|
75
|
-
|
|
76
|
-
If any directories in the explored scope contain `_expertise.md` files, display a brief expertise summary:
|
|
77
|
-
|
|
78
|
-
```
|
|
79
|
-
## Expertise Areas
|
|
80
|
-
🟢 Expert — professional/skills/flutter/authentication/ (0.85)
|
|
81
|
-
🔵 Deep Knowledge — professional/skills/react/ (0.68)
|
|
82
|
-
🟡 Working Knowledge — personal/education/psychology/ (0.45)
|
|
83
|
-
⚪ Awareness — social/communities/open-source/ (0.28)
|
|
84
|
-
```
|
package/commands/brain/init.md
DELETED
|
@@ -1,153 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
description: Initialize the brain memory structure
|
|
3
|
-
---
|
|
4
|
-
|
|
5
|
-
# /brain:init — Initialize Brain Memory Structure
|
|
6
|
-
|
|
7
|
-
You are initializing the Brain Memory system. This creates a `~/.brain/` directory that serves as a hierarchical, file-system-based memory store inspired by human cognition.
|
|
8
|
-
|
|
9
|
-
## Steps
|
|
10
|
-
|
|
11
|
-
### 1. Check for Existing Brain
|
|
12
|
-
|
|
13
|
-
Check if `~/.brain/` directory already exists in the user's home directory.
|
|
14
|
-
|
|
15
|
-
- If it exists, inform the user and ask if they want to reset or keep it.
|
|
16
|
-
- If not, proceed with creation.
|
|
17
|
-
|
|
18
|
-
### 2. Create Directory Structure
|
|
19
|
-
|
|
20
|
-
Create the following structure:
|
|
21
|
-
|
|
22
|
-
```
|
|
23
|
-
~/.brain/
|
|
24
|
-
├── index.json
|
|
25
|
-
├── associations.json
|
|
26
|
-
├── contexts.json
|
|
27
|
-
├── review-queue.json
|
|
28
|
-
├── professional/
|
|
29
|
-
│ └── _meta.json
|
|
30
|
-
├── personal/
|
|
31
|
-
│ └── _meta.json
|
|
32
|
-
├── social/
|
|
33
|
-
│ └── _meta.json
|
|
34
|
-
├── family/
|
|
35
|
-
│ └── _meta.json
|
|
36
|
-
├── _consolidated/
|
|
37
|
-
│ └── _meta.json
|
|
38
|
-
└── _archived/
|
|
39
|
-
└── index.json
|
|
40
|
-
```
|
|
41
|
-
|
|
42
|
-
### 3. Create index.json
|
|
43
|
-
|
|
44
|
-
```json
|
|
45
|
-
{
|
|
46
|
-
"version": 2,
|
|
47
|
-
"created": "<current ISO timestamp>",
|
|
48
|
-
"last_updated": "<current ISO timestamp>",
|
|
49
|
-
"memory_count": 0,
|
|
50
|
-
"memories": {},
|
|
51
|
-
"config": {
|
|
52
|
-
"max_depth": 6,
|
|
53
|
-
"consolidation_threshold": 0.3,
|
|
54
|
-
"decay_check_interval_days": 7,
|
|
55
|
-
"strength_boost_on_recall": 0.05,
|
|
56
|
-
"auto_consolidate": true,
|
|
57
|
-
"propagation_window_days": 7,
|
|
58
|
-
"association_config": {
|
|
59
|
-
"co_retrieval_boost": 0.10,
|
|
60
|
-
"link_decay_rate": 0.998,
|
|
61
|
-
"link_prune_threshold": 0.05,
|
|
62
|
-
"spreading_activation_depth": 2,
|
|
63
|
-
"spreading_activation_decay": 0.5
|
|
64
|
-
}
|
|
65
|
-
}
|
|
66
|
-
}
|
|
67
|
-
```
|
|
68
|
-
|
|
69
|
-
### 4. Create associations.json
|
|
70
|
-
|
|
71
|
-
The associative network stores weighted connections between memories — implementing spreading activation (like neurons activating linked memories) and Hebbian learning (memories that fire together wire together).
|
|
72
|
-
|
|
73
|
-
```json
|
|
74
|
-
{
|
|
75
|
-
"version": 1,
|
|
76
|
-
"edges": {}
|
|
77
|
-
}
|
|
78
|
-
```
|
|
79
|
-
|
|
80
|
-
### 5. Create contexts.json
|
|
81
|
-
|
|
82
|
-
Stores session-level context snapshots used for context-dependent recall — memories encoded in a similar context to the current one are scored higher.
|
|
83
|
-
|
|
84
|
-
```json
|
|
85
|
-
{
|
|
86
|
-
"version": 1,
|
|
87
|
-
"sessions": []
|
|
88
|
-
}
|
|
89
|
-
```
|
|
90
|
-
|
|
91
|
-
### 6. Create review-queue.json
|
|
92
|
-
|
|
93
|
-
Implements spaced repetition scheduling — surfaces memories for review at optimal intervals to maximize long-term retention.
|
|
94
|
-
|
|
95
|
-
```json
|
|
96
|
-
{
|
|
97
|
-
"version": 1,
|
|
98
|
-
"items": []
|
|
99
|
-
}
|
|
100
|
-
```
|
|
101
|
-
|
|
102
|
-
### 7. Create _archived/index.json
|
|
103
|
-
|
|
104
|
-
A searchable index of archived memories so they can be found and restored if needed.
|
|
105
|
-
|
|
106
|
-
```json
|
|
107
|
-
{
|
|
108
|
-
"version": 1,
|
|
109
|
-
"archived_count": 0,
|
|
110
|
-
"memories": {}
|
|
111
|
-
}
|
|
112
|
-
```
|
|
113
|
-
|
|
114
|
-
### 8. Create _meta.json for Each Top Category
|
|
115
|
-
|
|
116
|
-
For each top-level category (professional, personal, social, family, _consolidated), create a `_meta.json`:
|
|
117
|
-
|
|
118
|
-
```json
|
|
119
|
-
{
|
|
120
|
-
"category": "<category_name>",
|
|
121
|
-
"description": "<description from defaults>",
|
|
122
|
-
"created": "<current ISO timestamp>",
|
|
123
|
-
"memory_count": 0,
|
|
124
|
-
"subcategories": []
|
|
125
|
-
}
|
|
126
|
-
```
|
|
127
|
-
|
|
128
|
-
### 9. Ask User for Customization (Optional)
|
|
129
|
-
|
|
130
|
-
Ask the user:
|
|
131
|
-
- "Would you like to add any custom top-level categories beyond the defaults (professional, personal, social, family)?"
|
|
132
|
-
- "Do you have specific subcategories you'd like pre-created? (e.g., a company name under professional/companies/)"
|
|
133
|
-
|
|
134
|
-
If the user provides custom categories or subcategories, create them with appropriate `_meta.json` files.
|
|
135
|
-
|
|
136
|
-
### 10. Add .brain to .gitignore (Optional)
|
|
137
|
-
|
|
138
|
-
Ask the user if they want `~/.brain/` added to `.gitignore` (some users may want to track their memory in git, others may not).
|
|
139
|
-
|
|
140
|
-
### 11. Confirm
|
|
141
|
-
|
|
142
|
-
Print a summary of what was created, including the full tree structure. Inform the user of available commands:
|
|
143
|
-
|
|
144
|
-
- `/brain:memorize` — Store a new memory
|
|
145
|
-
- `/brain:remember` — Recall relevant memories
|
|
146
|
-
- `/brain:explore` — Browse the brain structure
|
|
147
|
-
- `/brain:consolidate` — Merge related memories
|
|
148
|
-
- `/brain:forget` — Decay or remove memories
|
|
149
|
-
- `/brain:sunshine` — Deep forensic erasure: trace and remove all references to a memory
|
|
150
|
-
- `/brain:sleep` — Overnight reorganization: restructure, consolidate, prune, and detect expertise areas
|
|
151
|
-
- `/brain:status` — View brain overview
|
|
152
|
-
- `/brain:review` — Spaced repetition review of memories due for reinforcement
|
|
153
|
-
|
package/commands/brain/review.md
DELETED
|
@@ -1,135 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
description: Spaced-repetition review session for memories due for reinforcement
|
|
3
|
-
argument-hint: "[scope]"
|
|
4
|
-
---
|
|
5
|
-
|
|
6
|
-
# /brain:review — Spaced Repetition Review
|
|
7
|
-
|
|
8
|
-
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.
|
|
9
|
-
|
|
10
|
-
**Scope:** $ARGUMENTS
|
|
11
|
-
|
|
12
|
-
## Overview
|
|
13
|
-
|
|
14
|
-
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.
|
|
15
|
-
|
|
16
|
-
## Steps
|
|
17
|
-
|
|
18
|
-
### 1. Load Review Queue
|
|
19
|
-
|
|
20
|
-
Read `~/.brain/review-queue.json`. If it doesn't exist or is empty, generate it:
|
|
21
|
-
- Scan all memories in `index.json`
|
|
22
|
-
- For memories with `access_count > 0`, calculate initial review schedule
|
|
23
|
-
- For memories never recalled, add with `next_review` = now (immediate first review)
|
|
24
|
-
- If $ARGUMENTS specifies a category path, limit to that subtree
|
|
25
|
-
|
|
26
|
-
### 2. Find Due Memories
|
|
27
|
-
|
|
28
|
-
Filter the review queue for items where `next_review <= now`.
|
|
29
|
-
|
|
30
|
-
If no memories are due:
|
|
31
|
-
```
|
|
32
|
-
## No Memories Due for Review
|
|
33
|
-
|
|
34
|
-
Next review due: <soonest date>
|
|
35
|
-
Total in queue: <count>
|
|
36
|
-
|
|
37
|
-
Run /brain:status for a full overview.
|
|
38
|
-
```
|
|
39
|
-
|
|
40
|
-
### 3. Present Review Session
|
|
41
|
-
|
|
42
|
-
For each due memory (process up to 10 per session):
|
|
43
|
-
|
|
44
|
-
1. **Present the memory's title and path** (but NOT the full content initially):
|
|
45
|
-
```
|
|
46
|
-
### Review 1 of <N>
|
|
47
|
-
|
|
48
|
-
**Memory:** <title>
|
|
49
|
-
**Path:** ~/.brain/<path>
|
|
50
|
-
**Type:** <type> (<cognitive_type>) | **Last reviewed:** <date> | **Interval:** <days>d
|
|
51
|
-
**Confidence:** <confidence>
|
|
52
|
-
|
|
53
|
-
Can you recall what this memory is about? Try to remember before seeing the content.
|
|
54
|
-
```
|
|
55
|
-
|
|
56
|
-
2. **Reveal the full content** after the user responds (or on request):
|
|
57
|
-
```
|
|
58
|
-
<full memory content>
|
|
59
|
-
```
|
|
60
|
-
|
|
61
|
-
3. **Ask for recall quality** (1-5 scale):
|
|
62
|
-
- **5 — Perfect**: Recalled immediately and completely
|
|
63
|
-
- **4 — Good**: Recalled with minor effort
|
|
64
|
-
- **3 — Okay**: Recalled with significant effort
|
|
65
|
-
- **2 — Poor**: Could barely recall, needed heavy hints
|
|
66
|
-
- **1 — Failed**: Could not recall at all
|
|
67
|
-
|
|
68
|
-
### 4. Update Based on Recall Quality
|
|
69
|
-
|
|
70
|
-
For each reviewed memory, update using the SM-2 algorithm:
|
|
71
|
-
|
|
72
|
-
**Ease factor adjustment:**
|
|
73
|
-
```
|
|
74
|
-
new_ease = ease_factor + (0.1 - (5 - quality) * (0.08 + (5 - quality) * 0.02))
|
|
75
|
-
ease_factor = max(1.3, new_ease)
|
|
76
|
-
```
|
|
77
|
-
|
|
78
|
-
**Interval calculation:**
|
|
79
|
-
```
|
|
80
|
-
if quality >= 3: // Successful recall
|
|
81
|
-
if review_count == 0: interval = 1
|
|
82
|
-
elif review_count == 1: interval = 6
|
|
83
|
-
else: interval = previous_interval * ease_factor
|
|
84
|
-
else: // Failed recall
|
|
85
|
-
interval = 1 // Reset to 1 day
|
|
86
|
-
review_count = 0 // Reset review count
|
|
87
|
-
```
|
|
88
|
-
|
|
89
|
-
**Update memory:**
|
|
90
|
-
- `last_accessed` → current timestamp
|
|
91
|
-
- `access_count` → increment by 1
|
|
92
|
-
- `recall_history` → append current timestamp
|
|
93
|
-
- Apply spaced reinforcement to `strength` (same formula as /brain:remember)
|
|
94
|
-
- Improve `decay_rate` on successful recall (quality >= 3)
|
|
95
|
-
|
|
96
|
-
**Update review queue entry:**
|
|
97
|
-
```json
|
|
98
|
-
{
|
|
99
|
-
"memory_id": "<id>",
|
|
100
|
-
"next_review": "<now + interval days>",
|
|
101
|
-
"interval_days": <interval>,
|
|
102
|
-
"ease_factor": <ease_factor>,
|
|
103
|
-
"review_count": <review_count + 1>
|
|
104
|
-
}
|
|
105
|
-
```
|
|
106
|
-
|
|
107
|
-
### 5. Session Summary
|
|
108
|
-
|
|
109
|
-
After reviewing all due memories:
|
|
110
|
-
|
|
111
|
-
```
|
|
112
|
-
## Review Session Complete
|
|
113
|
-
|
|
114
|
-
Reviewed: <N> memories
|
|
115
|
-
Perfect (5): <count>
|
|
116
|
-
Good (4): <count>
|
|
117
|
-
Okay (3): <count>
|
|
118
|
-
Poor (2): <count>
|
|
119
|
-
Failed (1): <count>
|
|
120
|
-
|
|
121
|
-
Average recall quality: <avg>
|
|
122
|
-
Next review due: <soonest date>
|
|
123
|
-
Remaining in queue: <count>
|
|
124
|
-
|
|
125
|
-
Memories strengthened through review — keep it up!
|
|
126
|
-
```
|
|
127
|
-
|
|
128
|
-
## Rules
|
|
129
|
-
|
|
130
|
-
1. **Never skip the recall attempt** — always present the title first and let the user try to recall before revealing content
|
|
131
|
-
2. **Be encouraging** — spaced repetition is about building long-term retention, not testing
|
|
132
|
-
3. **Update everything** — update the memory file, index.json, review-queue.json, and associations.json (reinforce edges between co-reviewed memories)
|
|
133
|
-
4. **Respect scope** — if $ARGUMENTS specifies a category, only review memories in that subtree
|
|
134
|
-
5. **Session limit** — review at most 10 memories per session to avoid fatigue
|
|
135
|
-
6. **Failed recalls** — for quality 1-2, suggest the user re-read the memory and offer to update it if the information is outdated
|