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

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