brain-memory 0.1.0-beta.2 → 0.1.0-beta.20

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 (44) hide show
  1. package/README.md +270 -72
  2. package/assets/icon.png +0 -0
  3. package/assets/icon.svg +27 -0
  4. package/bin/brain.js +111 -0
  5. package/bin/cloud-sync.js +149 -0
  6. package/bin/install.js +217 -242
  7. package/bin/memorize.js +433 -0
  8. package/bin/pin.js +44 -0
  9. package/bin/recall.js +237 -0
  10. package/bin/reinforce.js +187 -0
  11. package/bin/session-start.js +292 -0
  12. package/bin/skill.js +67 -0
  13. package/bin/unpin.js +38 -0
  14. package/commands/brain/consolidate.md +7 -2
  15. package/commands/brain/explore.md +7 -2
  16. package/commands/brain/forget.md +7 -2
  17. package/commands/brain/init.md +8 -12
  18. package/commands/brain/memorize.md +76 -144
  19. package/commands/brain/pin.md +37 -0
  20. package/commands/brain/remember.md +48 -105
  21. package/commands/brain/review.md +7 -2
  22. package/commands/brain/skills.md +60 -0
  23. package/commands/brain/sleep.md +68 -27
  24. package/commands/brain/status.md +19 -5
  25. package/commands/brain/sunshine.md +18 -13
  26. package/commands/brain/sync.md +360 -0
  27. package/commands/brain/unpin.md +26 -0
  28. package/package.json +18 -8
  29. package/prompts/claude.md +115 -12
  30. package/prompts/gemini.md +115 -12
  31. package/prompts/openai.md +113 -10
  32. package/prompts/opencode.md +178 -0
  33. package/src/cloud-sync.js +524 -0
  34. package/src/crypto.js +130 -0
  35. package/src/export-import.js +185 -0
  36. package/src/git-sync.js +444 -0
  37. package/src/index-manager.js +205 -18
  38. package/src/installer.js +384 -0
  39. package/src/pinning.js +124 -0
  40. package/src/scorer.js +6 -2
  41. package/src/skills.js +208 -0
  42. package/src/tfidf.js +408 -0
  43. package/hooks/session-end.md +0 -48
  44. package/hooks/session-start.md +0 -48
@@ -1,12 +1,16 @@
1
+ ---
2
+ description: Initialize the brain memory structure
3
+ ---
4
+
1
5
  # /brain:init — Initialize Brain Memory Structure
2
6
 
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.
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.
4
8
 
5
9
  ## Steps
6
10
 
7
11
  ### 1. Check for Existing Brain
8
12
 
9
- Check if `.brain/` directory already exists in the current project root.
13
+ Check if `~/.brain/` directory already exists in the user's home directory.
10
14
 
11
15
  - If it exists, inform the user and ask if they want to reset or keep it.
12
16
  - If not, proceed with creation.
@@ -16,7 +20,7 @@ Check if `.brain/` directory already exists in the current project root.
16
20
  Create the following structure:
17
21
 
18
22
  ```
19
- .brain/
23
+ ~/.brain/
20
24
  ├── index.json
21
25
  ├── associations.json
22
26
  ├── contexts.json
@@ -131,7 +135,7 @@ If the user provides custom categories or subcategories, create them with approp
131
135
 
132
136
  ### 10. Add .brain to .gitignore (Optional)
133
137
 
134
- Ask the user if they want `.brain/` added to `.gitignore` (some users may want to track their memory in git, others may not).
138
+ Ask the user if they want `~/.brain/` added to `.gitignore` (some users may want to track their memory in git, others may not).
135
139
 
136
140
  ### 11. Confirm
137
141
 
@@ -147,11 +151,3 @@ Print a summary of what was created, including the full tree structure. Inform t
147
151
  - `/brain:status` — View brain overview
148
152
  - `/brain:review` — Spaced repetition review of memories due for reinforcement
149
153
 
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,176 +1,108 @@
1
+ ---
2
+ description: Store memories from the current conversation context
3
+ argument-hint: "[topic]"
4
+ ---
5
+
1
6
  # /brain:memorize — Store a New Memory
2
7
 
3
- You are storing a new memory in the Brain Memory system. Memories are filed into the `.brain/` hierarchical directory structure based on their semantic content.
8
+ You are storing memories in the Brain Memory system. Your job is to decide **what** to remember and **how to classify** it. The `brain memorize` CLI handles all file operations.
4
9
 
5
10
  **User input:** $ARGUMENTS
6
11
 
7
- ## Steps
8
-
9
- ### 1. Determine Memory Content
10
-
11
- If the user provided specific content in $ARGUMENTS, use that as the basis for the memory.
12
-
13
- If $ARGUMENTS is empty or vague, analyze the **current conversation context** and extract the most significant learnings, decisions, insights, or experiences from the session. Summarize them into one or more distinct memories.
14
-
15
- ### 2. Classify Each Memory
16
-
17
- For each memory to store, determine:
18
-
19
- **Type** (one of):
20
- - `decision` — A choice that was made and why (strength: 0.85, decay: 0.995/day)
21
- - `learning` — Something new that was learned (strength: 0.70, decay: 0.990/day)
22
- - `experience` — A notable event or process (strength: 0.75, decay: 0.985/day)
23
- - `insight` — A deep realization or pattern (strength: 0.90, decay: 0.997/day)
24
- - `observation` — A casual notice or fact (strength: 0.40, decay: 0.950/day)
25
- - `goal` — An objective or aspiration (strength: 0.80, decay: 0.993/day)
26
- - `preference` — A user preference or style (strength: 0.60, decay: 0.998/day)
27
- - `relationship` — A connection between people/things (strength: 0.70, decay: 0.997/day)
28
-
29
- **Impact assessment** — Adjust the base strength up or down by up to ±0.15 based on:
30
- - How significant is this to the user's life/work?
31
- - Is this likely to be needed again?
32
- - Does it represent a turning point or just routine?
33
-
34
- **Cognitive type** (one of):
35
- - `episodic` — Tied to a specific event/time. Add +0.10 to strength (vivid at first, fades faster). Multiply decay rate by 0.995. E.g., "The deployment failed Tuesday because X"
36
- - `semantic` — Abstracted knowledge, context-free. Use default strength/decay. E.g., "React hooks must follow rules of hooks"
37
- - `procedural` — How-to workflows, skills. Subtract -0.10 from strength but multiply decay rate by 1.003 (extremely slow decay once established). E.g., "Steps to debug memory leaks"
38
-
39
- **Salience** (0.0-1.0) — How emotionally or motivationally significant this memory is:
40
- - 0.0-0.3: Low — routine information
41
- - 0.4-0.6: Moderate — professionally relevant
42
- - 0.7-1.0: High — critical decisions, hard-won lessons, emotionally significant events. High-salience memories are NEVER auto-pruned.
43
-
44
- **Confidence** (0.0-1.0) — Epistemic certainty about the memory's accuracy:
45
- - 0.9-1.0: Verified/tested firsthand
46
- - 0.7-0.8: Reliable source, consistent with experience
47
- - 0.5-0.6: Plausible but unverified
48
- - 0.1-0.4: Uncertain, speculative, or hearsay
49
-
50
- ### 3. Determine File Path (Categorization)
12
+ **Flags:**
13
+ - `--sync` — Auto-push to cloud/git after storing
14
+ - `--confirm` — Ask for confirmation before writing (off by default)
51
15
 
52
- Choose the most appropriate path in the `.brain/` hierarchy. This is the most critical step.
16
+ ## Behavior
53
17
 
54
- **Rules for path selection:**
55
- 1. Start with the top-level category: `professional/`, `personal/`, `social/`, `family/`
56
- 2. Go as deep as semantically justified — but not deeper than necessary
57
- 3. Create subdirectories on demand if they don't exist (add `_meta.json` for each)
58
- 4. Use kebab-case for directory and file names
59
- 5. File name should be a short descriptive slug + `.md`
18
+ **Default: store immediately, show results after.** The user said "memorize" — they want it stored. Do NOT ask "Store these memories?" unless `--confirm` is passed, or $ARGUMENTS is empty AND you're genuinely uncertain which session content to extract.
60
19
 
61
- **Depth guidelines:**
62
- - Generic career thought → `professional/career-direction.md`
63
- - Decision about a specific company → `professional/companies/acme-corp/joining-decision.md`
64
- - A specific project issue → `professional/companies/acme-corp/projects/alpha/deployment-incident.md`
65
- - Learning TypeScript → `personal/education/typescript-generics.md`
66
- - User prefers dark mode → `personal/preferences/dark-mode.md`
67
-
68
- **If a memory spans categories**, place it in the most relevant one and note the cross-reference in `related` metadata.
69
-
70
- ### 4. Generate Memory ID
71
-
72
- Format: `mem_<YYYYMMDD>_<6-char-random-hex>`
73
-
74
- Example: `mem_20260213_a3f2c1`
75
-
76
- ### 5. Write Memory File
20
+ ## Steps
77
21
 
78
- Create the memory file at the determined path with this format:
22
+ ### 1. Determine Content
79
23
 
80
- ```markdown
81
- ---
82
- id: <memory_id>
83
- type: <memory_type>
84
- cognitive_type: <episodic|semantic|procedural>
85
- created: <ISO timestamp>
86
- last_accessed: <ISO timestamp>
87
- access_count: 0
88
- recall_history: []
89
- strength: <calculated strength 0.0-1.0>
90
- decay_rate: <decay rate per day>
91
- salience: <0.0-1.0>
92
- confidence: <0.0-1.0>
93
- tags: [<relevant tags>]
94
- related: [<related memory IDs if any>]
95
- source: <brief session identifier or context>
96
- encoding_context:
97
- project: <current project name>
98
- topics: [<2-5 key topics from session>]
99
- task_type: <debugging|implementing|designing|reviewing|discussing|learning>
100
- ---
24
+ If $ARGUMENTS has specific content, use it. If empty, extract the most significant learnings, decisions, insights, or experiences from the current session.
101
25
 
102
- # <Short Descriptive Title>
26
+ ### 2. Classify Each Memory
103
27
 
104
- <2-5 sentence summary of the memory. Be specific and actionable. Include the WHY, not just the WHAT.>
28
+ For each memory, determine:
105
29
 
106
- ## Context
30
+ **Type** (sets base strength/decay — the CLI computes final values):
31
+ - `decision` (0.85/0.995) — Choices made and rationale
32
+ - `insight` (0.90/0.997) — Deep realizations, patterns
33
+ - `goal` (0.80/0.993) — Objectives and aspirations
34
+ - `experience` (0.75/0.985) — Notable events or processes
35
+ - `learning` (0.70/0.990) — New knowledge acquired
36
+ - `relationship` (0.70/0.997) — Connections between entities
37
+ - `preference` (0.60/0.998) — User preferences and style
38
+ - `observation` (0.40/0.950) — Casual facts or notices
107
39
 
108
- <1-3 sentences about the circumstances — when, where, what was happening>
40
+ **Cognitive type:** `episodic` (event-specific), `semantic` (abstracted knowledge), `procedural` (skills/workflows)
109
41
 
110
- ## Key Details
42
+ **Path:** Where in `~/.brain/` hierarchy: `professional/`, `personal/`, `social/`, `family/` with kebab-case subdirectories as deep as semantically justified. File name = short slug + `.md`.
111
43
 
112
- <Bullet points of the most important specifics>
44
+ **Salience** (0.0-1.0), **confidence** (0.0-1.0), **tags**, **related** memory IDs.
113
45
 
114
- ## Connections
46
+ **strength_adjustment** (optional, -0.15 to +0.15): Tweak base strength based on significance.
115
47
 
116
- <How this relates to other knowledge, patterns, or goals — if applicable>
117
- ```
48
+ **Pinned & stable** (optional, CoALA Phase 1):
49
+ - `pinned: true` — always inject this memory at session start regardless of recall score (and decay-exempt). Optionally `pin_scope: "project:<name>"` (default `"global"`) and `pin_priority: <N>`.
50
+ - `stable: true` — exempt from decay (never fades) without forcing it to always load — for timeless facts recalled on demand.
51
+ - **Propose, don't assume:** when a memory is a durable convention/preference/standing decision (type ∈ {preference, decision, insight, relationship}, high confidence, low time-sensitivity), *suggest* pinning it — but only set `pinned` if the user agrees (or pin later with `/brain:pin`).
118
52
 
119
- ### 6. Update Index
53
+ ### 3. Call brain memorize
120
54
 
121
- Read `.brain/index.json` and add an entry:
55
+ Pipe the classified memories as JSON to the CLI in a **single bash call**:
122
56
 
123
- ```json
57
+ ```bash
58
+ brain memorize <<'EOF'
124
59
  {
125
- "<memory_id>": {
126
- "path": "<relative path from .brain/>",
127
- "title": "<short title>",
128
- "type": "<memory_type>",
129
- "cognitive_type": "<episodic|semantic|procedural>",
130
- "strength": <strength>,
131
- "decay_rate": <decay_rate>,
132
- "salience": <salience>,
133
- "confidence": <confidence>,
134
- "created": "<ISO timestamp>",
135
- "last_accessed": "<ISO timestamp>",
136
- "access_count": 0,
137
- "tags": ["<tags>"],
138
- "encoding_context": {
139
- "project": "<project>",
140
- "topics": ["<topics>"],
141
- "task_type": "<task_type>"
60
+ "memories": [
61
+ {
62
+ "title": "Short descriptive title",
63
+ "type": "learning",
64
+ "cognitive_type": "semantic",
65
+ "path": "professional/projects/foo/what-i-learned.md",
66
+ "tags": ["foo", "patterns"],
67
+ "salience": 0.6,
68
+ "confidence": 0.9,
69
+ "strength_adjustment": 0.05,
70
+ "related": [],
71
+ "source": "Session context description",
72
+ "encoding_context": {
73
+ "project": "current-project",
74
+ "topics": ["topic1", "topic2"],
75
+ "task_type": "implementing"
76
+ },
77
+ "content": "# What I Learned\n\nThe main insight was...\n\n## Context\n\nThis came up while...\n\n## Key Details\n\n- Detail one\n- Detail two\n\n## Connections\n\nRelates to previous work on..."
142
78
  }
143
- }
79
+ ]
144
80
  }
81
+ EOF
145
82
  ```
146
83
 
147
- Increment `memory_count`. Update `last_updated`.
148
-
149
- ### 7. Update Associations
150
-
151
- Read `.brain/associations.json` and create edges for this memory:
152
-
153
- **A. Explicit `related` links:** For each ID in the `related` field, create an edge with weight 0.20 and origin `manual`.
154
-
155
- **B. Auto-discovered links:** Scan `index.json` for other memories sharing **2 or more tags** with this memory. For each match, create an edge with weight 0.10 and origin `tag_overlap`.
84
+ Add `--sync` flag if the user requested it or passed `--sync` to the command:
85
+ ```bash
86
+ brain memorize --sync <<'EOF'
87
+ ...
88
+ EOF
89
+ ```
156
90
 
157
- Use the `reinforceEdge()` function — if an edge already exists (e.g., the related memory already links back), it will be strengthened via Hebbian reinforcement instead of creating a duplicate.
91
+ The CLI handles: ID generation, strength/decay computation, directory creation, file writing, index.json updates, association edges (explicit + tag overlaps), search index updates, and optional sync push.
158
92
 
159
- Write the updated `associations.json`.
93
+ ### 4. Report Results
160
94
 
161
- ### 8. Update _meta.json
95
+ The CLI outputs JSON with what was stored. Present the results to the user:
96
+ - Memory title, ID, and path
97
+ - Type, strength, tags
98
+ - Edges created
99
+ - Sync result (if applicable)
162
100
 
163
- Update the `_meta.json` in each directory along the path:
164
- - Increment `memory_count`
165
- - Add new subcategories to the `subcategories` array if any were created
101
+ ### 5. Resolve contradictions (Tier B §10.2)
166
102
 
167
- ### 9. Confirm
103
+ If a stored memory's result includes `potential_conflicts`, it shares heavy tag overlap with a **pinned or stable** memory — and pinned/stable facts never decay out of contention, so a stale one is dangerous. **Do not silently keep both.** Inspect the conflicting memory (`brain recall` or read its file) and, if the new memory genuinely contradicts it, propose a resolution to the user:
104
+ - **Supersede** — unpin/forget the old fact, keep the new one (record the supersession).
105
+ - **Keep both, scoped** — e.g. pin each to its own project.
106
+ - **Reject the new one** — the old fact stands.
168
107
 
169
- Print what was stored:
170
- - Memory title and ID
171
- - Full path in the brain
172
- - Assigned type, cognitive type, and strength
173
- - Salience and confidence levels
174
- - Tags
175
- - Association edges created (count and targets)
176
- - Any new directories that were created
108
+ Never auto-resolve; surface the conflict and let the user decide.
@@ -0,0 +1,37 @@
1
+ ---
2
+ description: Pin a memory to the always-present tier
3
+ argument-hint: "[id|query]"
4
+ ---
5
+
6
+ # /brain:pin — Pin a Memory (Always-Present Tier)
7
+
8
+ You are pinning a memory into the **always-present semantic tier**. Pinned memories are injected at every session start regardless of recall score, and are decay-exempt — they never fade.
9
+
10
+ **User input:** $ARGUMENTS
11
+
12
+ ## Behavior
13
+
14
+ 1. **Resolve the target memory:**
15
+ - If `$ARGUMENTS` is a memory ID (`mem_...`), use it directly.
16
+ - Otherwise run `brain recall "$ARGUMENTS" --top 5`, show the top matches, and confirm which one to pin.
17
+
18
+ 2. **Choose a scope** (default `global`):
19
+ - `global` — loads in every project.
20
+ - `project:<name>` — loads only while working in that project. Use for project-specific conventions.
21
+
22
+ 3. **Pin it:**
23
+ ```bash
24
+ brain pin <id> [--scope global|project:<name>] [--priority N]
25
+ ```
26
+ `--priority` (default 0) breaks ties when the pin budget (`~/.brain/config.json` → `pin_budget_tokens`) is tight; higher wins.
27
+
28
+ 4. Confirm:
29
+ ```
30
+ 📌 Pinned <title> (<scope>) — will load every session.
31
+ ```
32
+
33
+ ## When to pin
34
+
35
+ Durable conventions, preferences, and standing decisions the agent must **always** honor — e.g. "always use tabs", "deploy via Cloudflare", "never touch the legacy billing module". Good candidates are `preference`, `decision`, `insight`, and `relationship` memories with high confidence and low time-sensitivity.
36
+
37
+ **Do not pin** episodic or time-sensitive content (a one-off incident, a temporary workaround). Those belong in normal recall, where decay can retire them.
@@ -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 `/brain:explore`.
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
  ```
@@ -1,3 +1,8 @@
1
+ ---
2
+ description: Spaced-repetition review session for memories due for reinforcement
3
+ argument-hint: "[scope]"
4
+ ---
5
+
1
6
  # /brain:review — Spaced Repetition Review
2
7
 
3
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.
@@ -12,7 +17,7 @@ This implements a simplified SM-2 (SuperMemo 2) spaced repetition algorithm. Mem
12
17
 
13
18
  ### 1. Load Review Queue
14
19
 
15
- Read `.brain/review-queue.json`. If it doesn't exist or is empty, generate it:
20
+ Read `~/.brain/review-queue.json`. If it doesn't exist or is empty, generate it:
16
21
  - Scan all memories in `index.json`
17
22
  - For memories with `access_count > 0`, calculate initial review schedule
18
23
  - For memories never recalled, add with `next_review` = now (immediate first review)
@@ -41,7 +46,7 @@ For each due memory (process up to 10 per session):
41
46
  ### Review 1 of <N>
42
47
 
43
48
  **Memory:** <title>
44
- **Path:** .brain/<path>
49
+ **Path:** ~/.brain/<path>
45
50
  **Type:** <type> (<cognitive_type>) | **Last reviewed:** <date> | **Interval:** <days>d
46
51
  **Confidence:** <confidence>
47
52
 
@@ -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.