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
@@ -0,0 +1,26 @@
1
+ ---
2
+ description: Remove a memory from the always-present tier
3
+ argument-hint: "[id|query]"
4
+ ---
5
+
6
+ # /brain:unpin — Remove a Memory from the Always-Present Tier
7
+
8
+ You are unpinning a memory. It will no longer load automatically at session start and returns to normal recall + decay (an independent `stable` flag, if set, is left untouched).
9
+
10
+ **User input:** $ARGUMENTS
11
+
12
+ ## Behavior
13
+
14
+ 1. **Resolve the target:**
15
+ - If `$ARGUMENTS` is a memory ID (`mem_...`), use it directly.
16
+ - Otherwise inspect `~/.brain/pinned.json` (the list of current pins) or run `brain recall "$ARGUMENTS" --top 5`, and confirm which pin to remove.
17
+
18
+ 2. **Unpin it:**
19
+ ```bash
20
+ brain unpin <id>
21
+ ```
22
+
23
+ 3. Confirm:
24
+ ```
25
+ 📌 Unpinned <title> — no longer auto-loaded.
26
+ ```
package/package.json CHANGED
@@ -1,43 +1,53 @@
1
1
  {
2
2
  "name": "brain-memory",
3
- "version": "0.1.0-beta.2",
3
+ "version": "0.1.0-beta.20",
4
4
  "description": "A brain-inspired hierarchical memory system for AI coding agents. Deep nested file structure that mimics human memory with time-decay and strength-based recall.",
5
5
  "keywords": [
6
6
  "claude-code",
7
7
  "gemini-cli",
8
8
  "openai-codex",
9
+ "opencode",
9
10
  "memory",
10
11
  "ai-agent",
11
12
  "context-engineering",
12
- "hierarchical-memory"
13
+ "hierarchical-memory",
14
+ "neuroscience",
15
+ "spaced-repetition",
16
+ "file-based",
17
+ "slash-commands"
13
18
  ],
14
19
  "author": {
15
20
  "name": "Onur Karali",
16
21
  "email": "onur@omelas.tech"
17
22
  },
18
- "homepage": "https://github.com/onurkarali/brain#readme",
23
+ "homepage": "https://brainmemory.work/",
19
24
  "bugs": {
20
- "url": "https://github.com/onurkarali/brain/issues"
25
+ "url": "https://github.com/omelas-tech/brain/issues"
21
26
  },
22
27
  "bin": {
23
- "brain-memory": "bin/install.js"
28
+ "brain": "bin/brain.js"
24
29
  },
25
30
  "files": [
31
+ "assets/",
26
32
  "bin/",
27
33
  "commands/",
28
34
  "prompts/",
29
35
  "templates/",
30
- "hooks/",
31
36
  "src/",
32
37
  "README.md",
33
38
  "LICENSE"
34
39
  ],
35
40
  "repository": {
36
41
  "type": "git",
37
- "url": "git+https://github.com/onurkarali/brain.git"
42
+ "url": "git+https://github.com/omelas-tech/brain.git"
38
43
  },
39
44
  "scripts": {
40
- "test": "node --test test/*.test.js"
45
+ "test": "node --test test/index-manager.test.js test/scorer.test.js test/tfidf.test.js test/recall.test.js test/functional.test.js test/sunshine.test.js test/stress.test.js test/crypto.test.js test/git-sync.test.js test/export-import.test.js test/install.test.js test/prompts.test.js test/session-start.test.js test/pinning.test.js test/skills.test.js test/contradiction.test.js",
46
+ "prerelease": "npm test",
47
+ "release:beta": "npm version prerelease --preid beta && npm publish --tag beta && npm dist-tag add brain-memory@$(node -p \"require('./package.json').version\") latest",
48
+ "release:patch": "npm version patch && npm publish",
49
+ "release:minor": "npm version minor && npm publish",
50
+ "release:major": "npm version major && npm publish"
41
51
  },
42
52
  "license": "MIT",
43
53
  "engines": {
package/prompts/claude.md CHANGED
@@ -4,7 +4,7 @@ This project uses the **Brain Memory** plugin — a hierarchical, file-system-ba
4
4
 
5
5
  ## Memory Location
6
6
 
7
- All memories are stored in `.brain/` with a deep nested directory structure organized by life domains (professional, personal, social, family) with on-demand subcategories.
7
+ All memories are stored in a single global `~/.brain/` directory in the user's home folder, shared across all projects and all supported AI agents. The directory uses a deep nested structure organized by life domains (professional, personal, social, family) with on-demand subcategories.
8
8
 
9
9
  ## How It Works
10
10
 
@@ -37,7 +37,7 @@ Each memory is a Markdown file with YAML frontmatter containing: `id`, `type`, `
37
37
  | observation | 0.40 | 0.950 | Casual facts or notices |
38
38
 
39
39
  ### Associative Network
40
- Memories are connected via weighted edges in `.brain/associations.json`. When you recall memory A, **spreading activation** automatically surfaces related memories B and C — just like how the brain activates linked neurons. Links are strengthened through **Hebbian learning**: memories recalled together become more tightly connected over time.
40
+ Memories are connected via weighted edges in `~/.brain/associations.json`. When you recall memory A, **spreading activation** automatically surfaces related memories B and C — just like how the brain activates linked neurons. Links are strengthened through **Hebbian learning**: memories recalled together become more tightly connected over time.
41
41
 
42
42
  ### Context-Dependent Recall
43
43
  Memories store their encoding context (project, topics, task type). During recall, memories encoded in a similar context to the current session are scored higher — matching how human memory works better when recall context matches encoding context.
@@ -58,18 +58,121 @@ Memories store their encoding context (project, topics, task type). During recal
58
58
  - `/brain:sunshine [target]` — Deep forensic erasure — trace and remove all references to a memory
59
59
  - `/brain:sleep [scope]` — Full maintenance cycle: replay, synaptic homeostasis, knowledge propagation, semantic crystallization, reorganize, consolidate, prune, REM dreaming, and expertise detection
60
60
  - `/brain:status` — Dashboard with brain health overview
61
+ - `/brain:sync [subcommand]` — Sync memories via Git remote or export/import for portability
62
+ - `/brain:pin [id|query]` — Pin a memory to the always-present tier (CoALA Phase 1)
63
+ - `/brain:unpin [id|query]` — Remove a memory from the always-present tier
64
+ - `/brain:skills [list|show|add|use|remove|export]` — Manage procedural skills (CoALA Phase 2)
61
65
 
62
- ## Auto-Memorize Guidance
66
+ ## Session Start Behavior
63
67
 
64
- At the end of significant sessions, consider suggesting `/brain:memorize` to the user if important decisions, learnings, or insights occurred during the conversation. Do NOT automatically memorize without the user's awareness.
68
+ **Perform these steps at session start — but keep it lightweight.**
69
+
70
+ If `~/.brain/index.json` exists:
71
+
72
+ 1. **Run the session-start aggregator** — one deterministic, budget-bounded call:
73
+ ```bash
74
+ brain session-start --project "<current project>"
75
+ ```
76
+ It returns JSON with `memory_count`, `pinned` (always-apply conventions/preferences), `skills_index` (available procedural skills — name + description only), `context_recall` (memories relevant to this project), `due_for_review`, `low_confidence_alerts`, and `budget`. If `~/.brain/index.json` is absent it returns an empty payload.
77
+ 2. **Silently internalize** the payload — treat `pinned` facts as active constraints, note which `skills_index` skills exist (load a skill's full `SKILL.md` only when a task matches it), and keep `context_recall` in mind. Do **NOT** dump contents.
78
+ 3. **Output a single status line:**
79
+
80
+ ```
81
+ 🧠 Brain active — <N> memories (<M> in project context)
82
+ ```
83
+
84
+ Only add extra lines if actionable:
85
+ - `📋 <X> due for review` — if `due_for_review > 0`
86
+ - `⚠️ <N> low-confidence memories used frequently` — if `low_confidence_alerts` is non-empty
87
+
88
+ The aggregator is budget-bounded (`~/.brain/config.json`) and never exceeds the working-memory token budget, so just internalize whatever it returns. **The goal is ambient awareness** — know about past decisions, learnings, and preferences without reciting them.
89
+
90
+ ## Ambient Session Tracking
91
+
92
+ **Throughout the session, maintain a running mental log of notable events.** This requires no file writes — just internal awareness.
93
+
94
+ Track these categories as they happen:
95
+ - **Decisions** — Architecture choices, technology selections, trade-off resolutions
96
+ - **Learnings** — New patterns, debugging insights, API discoveries
97
+ - **Insights** — Realizations about the codebase, project, or process
98
+ - **Experiences** — Significant events like incidents, deployments, milestones
99
+ - **Goals** — New objectives discussed or planned
100
+
101
+ **Why this matters:** Without active tracking, you can only evaluate what happened at session end — by which point early-session events may be forgotten or the user may have already left. By tracking as events occur, nothing is lost.
102
+
103
+ ## Periodic Memory Checkpoint
104
+
105
+ **Every ~10 substantive interactions** (file edits, architecture decisions, debugging breakthroughs, significant discussions — not trivial reads or simple answers), silently evaluate whether your ambient tracking log contains memorizable content.
106
+
107
+ If notable items have accumulated, append a **brief one-liner** at the end of your next natural response:
108
+
109
+ ```
110
+ 🧠 Notable <type(s)> this session — /brain:memorize when ready
111
+ ```
112
+
113
+ **Rules:**
114
+ - **Never interrupt flow** — only append to the end of a response the user is already receiving, never send as a standalone message
115
+ - **At most once per ~10 substantive interactions** — no spamming
116
+ - **Reset the counter** after the user runs `/brain:memorize`
117
+ - **Don't mention if nothing notable** has accumulated
118
+ - **Be specific about types** — say "decisions and learnings" not just "notable content"
119
+
120
+ ## Session End Behavior
121
+
122
+ When a session is ending (user says bye/thanks/done, conversation wraps up, or you sense the interaction is concluding), perform these steps **in order**:
123
+
124
+ ### Step 1: Save Session Context (ALWAYS — do this first)
125
+
126
+ **Immediately** append a session summary to `~/.brain/contexts.json`, even for trivial sessions. Context tracking is cheap and provides valuable recall signals for future sessions.
127
+
128
+ ```json
129
+ {
130
+ "session_id": "<timestamp-based-id>",
131
+ "started": "<session start ISO timestamp>",
132
+ "ended": "<session end ISO timestamp>",
133
+ "project": "<current project name>",
134
+ "topics": ["<key topics discussed>"],
135
+ "task_type": "<primary task type>",
136
+ "memories_created": ["<IDs of memories stored this session>"],
137
+ "memories_recalled": ["<IDs of memories retrieved this session>"],
138
+ "notable_unsaved": ["<brief descriptions of notable items NOT yet memorized>"]
139
+ }
140
+ ```
141
+
142
+ Keep only the last 20 session entries. The `notable_unsaved` field preserves what happened even if the user didn't memorize — future sessions can reference it.
143
+
144
+ ### Step 2: Suggest Memorization (if warranted)
145
+
146
+ If the session contained meaningful content based on your ambient tracking:
147
+
148
+ ```
149
+ 💡 This session contained notable <type(s)>. Would you like to store them as brain memories?
150
+ Run /brain:memorize to capture them before this context is lost.
151
+ ```
152
+
153
+ **Rules:**
154
+ - Do NOT auto-memorize without user consent
155
+ - Do NOT prompt for trivial sessions (quick fixes, typo corrections, simple questions)
156
+ - Only suggest when there is genuinely valuable context worth preserving
157
+ - **Do not wait for explicit session-end signals** — if the conversation appears to be wrapping up, save context proactively
65
158
 
66
159
  ## When Recalling Memories
67
160
 
68
- When the user asks you to "remember" something, or when context from past sessions would be helpful:
69
- 1. Check `.brain/index.json` for relevant memories
70
- 2. Load `.brain/associations.json` for spreading activation
71
- 3. Score by v4 formula: `0.38*relevance + 0.18*decayed_strength + 0.08*recency + 0.14*spreading_bonus + 0.14*context_match + 0.08*salience`
72
- 4. Return strong individual matches or synthesize from multiple related memories
73
- 5. Apply spaced reinforcement (spacing-aware boost) and improve decay rate
74
- 6. Strengthen Hebbian links between co-retrieved memories
75
- 7. If no active matches, search the archive (`.brain/_archived/`)
161
+ When the user asks you to "remember" something, or when context from past sessions would be helpful, use the **deterministic recall engine** instead of manually computing scores:
162
+
163
+ 1. Run `brain recall "<query>" --project <project> --task <task_type> --top 10` (or `node <install-path>/bin/recall.js`)
164
+ 2. The engine computes TF-IDF relevance, decayed strength, spreading activation, context match, and salience — all deterministically
165
+ 3. Read the top-scoring memory files and present results
166
+ 4. Run `brain reinforce <mem_id1> <mem_id2> ...` to apply spaced reinforcement and Hebbian co-retrieval strengthening
167
+ 5. If no matches, search the archive (`~/.brain/_archived/`)
168
+
169
+ The recall engine ensures **identical scoring across all agents** — Claude, Gemini, and Codex all get the same rankings for the same query.
170
+
171
+ ## Portable Sync
172
+
173
+ Brain memories can be synced across devices in two ways:
174
+
175
+ 1. **Git remote** — Push/pull `~/.brain/` to any private Git repository (GitHub, GitLab, Codeberg, self-hosted). Run `/brain:sync setup <url>` to configure, then use `/brain:sync push` and `/brain:sync pull`.
176
+ 2. **Export/Import** — Pack the entire `~/.brain/` into a single portable file for manual transfer. Run `/brain:sync export` and `/brain:sync import <path>`.
177
+
178
+ Both methods support optional AES-256-GCM encryption. Sync is always manual — never automatic.
package/prompts/gemini.md CHANGED
@@ -4,7 +4,7 @@ This project uses the **Brain Memory** plugin — a hierarchical, file-system-ba
4
4
 
5
5
  ## Memory Location
6
6
 
7
- All memories are stored in `.brain/` with a deep nested directory structure organized by life domains (professional, personal, social, family) with on-demand subcategories.
7
+ All memories are stored in a single global `~/.brain/` directory in the user's home folder, shared across all projects and all supported AI agents. The directory uses a deep nested structure organized by life domains (professional, personal, social, family) with on-demand subcategories.
8
8
 
9
9
  ## How It Works
10
10
 
@@ -37,7 +37,7 @@ Each memory is a Markdown file with YAML frontmatter containing: `id`, `type`, `
37
37
  | observation | 0.40 | 0.950 | Casual facts or notices |
38
38
 
39
39
  ### Associative Network
40
- Memories are connected via weighted edges in `.brain/associations.json`. When you recall memory A, **spreading activation** automatically surfaces related memories B and C — just like how the brain activates linked neurons. Links are strengthened through **Hebbian learning**: memories recalled together become more tightly connected over time.
40
+ Memories are connected via weighted edges in `~/.brain/associations.json`. When you recall memory A, **spreading activation** automatically surfaces related memories B and C — just like how the brain activates linked neurons. Links are strengthened through **Hebbian learning**: memories recalled together become more tightly connected over time.
41
41
 
42
42
  ### Context-Dependent Recall
43
43
  Memories store their encoding context (project, topics, task type). During recall, memories encoded in a similar context to the current session are scored higher — matching how human memory works better when recall context matches encoding context.
@@ -59,18 +59,121 @@ Commands are available via `/brain:` prefix:
59
59
  - `/brain:sunshine [target]` — Deep forensic erasure — trace and remove all references to a memory
60
60
  - `/brain:sleep [scope]` — Full maintenance cycle: replay, synaptic homeostasis, knowledge propagation, semantic crystallization, reorganize, consolidate, prune, REM dreaming, and expertise detection
61
61
  - `/brain:status` — Dashboard with brain health overview
62
+ - `/brain:sync [subcommand]` — Sync memories via Git remote or export/import for portability
63
+ - `/brain:pin [id|query]` — Pin a memory to the always-present tier (CoALA Phase 1)
64
+ - `/brain:unpin [id|query]` — Remove a memory from the always-present tier
65
+ - `/brain:skills [list|show|add|use|remove|export]` — Manage procedural skills (CoALA Phase 2)
62
66
 
63
- ## Auto-Memorize Guidance
67
+ ## Session Start Behavior
64
68
 
65
- At the end of significant sessions, consider suggesting `/brain:memorize` to the user if important decisions, learnings, or insights occurred during the conversation. Do NOT automatically memorize without the user's awareness.
69
+ **Perform these steps at session start — but keep it lightweight.**
70
+
71
+ If `~/.brain/index.json` exists:
72
+
73
+ 1. **Run the session-start aggregator** — one deterministic, budget-bounded call:
74
+ ```bash
75
+ brain session-start --project "<current project>"
76
+ ```
77
+ It returns JSON with `memory_count`, `pinned` (always-apply conventions/preferences), `skills_index` (available procedural skills — name + description only), `context_recall` (memories relevant to this project), `due_for_review`, `low_confidence_alerts`, and `budget`. If `~/.brain/index.json` is absent it returns an empty payload.
78
+ 2. **Silently internalize** the payload — treat `pinned` facts as active constraints, note which `skills_index` skills exist (load a skill's full `SKILL.md` only when a task matches it), and keep `context_recall` in mind. Do **NOT** dump contents.
79
+ 3. **Output a single status line:**
80
+
81
+ ```
82
+ 🧠 Brain active — <N> memories (<M> in project context)
83
+ ```
84
+
85
+ Only add extra lines if actionable:
86
+ - `📋 <X> due for review` — if `due_for_review > 0`
87
+ - `⚠️ <N> low-confidence memories used frequently` — if `low_confidence_alerts` is non-empty
88
+
89
+ The aggregator is budget-bounded (`~/.brain/config.json`) and never exceeds the working-memory token budget, so just internalize whatever it returns. **The goal is ambient awareness** — know about past decisions, learnings, and preferences without reciting them.
90
+
91
+ ## Ambient Session Tracking
92
+
93
+ **Throughout the session, maintain a running mental log of notable events.** This requires no file writes — just internal awareness.
94
+
95
+ Track these categories as they happen:
96
+ - **Decisions** — Architecture choices, technology selections, trade-off resolutions
97
+ - **Learnings** — New patterns, debugging insights, API discoveries
98
+ - **Insights** — Realizations about the codebase, project, or process
99
+ - **Experiences** — Significant events like incidents, deployments, milestones
100
+ - **Goals** — New objectives discussed or planned
101
+
102
+ **Why this matters:** Without active tracking, you can only evaluate what happened at session end — by which point early-session events may be forgotten or the user may have already left. By tracking as events occur, nothing is lost.
103
+
104
+ ## Periodic Memory Checkpoint
105
+
106
+ **Every ~10 substantive interactions** (file edits, architecture decisions, debugging breakthroughs, significant discussions — not trivial reads or simple answers), silently evaluate whether your ambient tracking log contains memorizable content.
107
+
108
+ If notable items have accumulated, append a **brief one-liner** at the end of your next natural response:
109
+
110
+ ```
111
+ 🧠 Notable <type(s)> this session — /brain:memorize when ready
112
+ ```
113
+
114
+ **Rules:**
115
+ - **Never interrupt flow** — only append to the end of a response the user is already receiving, never send as a standalone message
116
+ - **At most once per ~10 substantive interactions** — no spamming
117
+ - **Reset the counter** after the user runs `/brain:memorize`
118
+ - **Don't mention if nothing notable** has accumulated
119
+ - **Be specific about types** — say "decisions and learnings" not just "notable content"
120
+
121
+ ## Session End Behavior
122
+
123
+ When a session is ending (user says bye/thanks/done, conversation wraps up, or you sense the interaction is concluding), perform these steps **in order**:
124
+
125
+ ### Step 1: Save Session Context (ALWAYS — do this first)
126
+
127
+ **Immediately** append a session summary to `~/.brain/contexts.json`, even for trivial sessions. Context tracking is cheap and provides valuable recall signals for future sessions.
128
+
129
+ ```json
130
+ {
131
+ "session_id": "<timestamp-based-id>",
132
+ "started": "<session start ISO timestamp>",
133
+ "ended": "<session end ISO timestamp>",
134
+ "project": "<current project name>",
135
+ "topics": ["<key topics discussed>"],
136
+ "task_type": "<primary task type>",
137
+ "memories_created": ["<IDs of memories stored this session>"],
138
+ "memories_recalled": ["<IDs of memories retrieved this session>"],
139
+ "notable_unsaved": ["<brief descriptions of notable items NOT yet memorized>"]
140
+ }
141
+ ```
142
+
143
+ Keep only the last 20 session entries. The `notable_unsaved` field preserves what happened even if the user didn't memorize — future sessions can reference it.
144
+
145
+ ### Step 2: Suggest Memorization (if warranted)
146
+
147
+ If the session contained meaningful content based on your ambient tracking:
148
+
149
+ ```
150
+ 💡 This session contained notable <type(s)>. Would you like to store them as brain memories?
151
+ Run /brain:memorize to capture them before this context is lost.
152
+ ```
153
+
154
+ **Rules:**
155
+ - Do NOT auto-memorize without user consent
156
+ - Do NOT prompt for trivial sessions (quick fixes, typo corrections, simple questions)
157
+ - Only suggest when there is genuinely valuable context worth preserving
158
+ - **Do not wait for explicit session-end signals** — if the conversation appears to be wrapping up, save context proactively
66
159
 
67
160
  ## When Recalling Memories
68
161
 
69
- When the user asks you to "remember" something, or when context from past sessions would be helpful:
70
- 1. Check `.brain/index.json` for relevant memories
71
- 2. Load `.brain/associations.json` for spreading activation
72
- 3. Score by v4 formula: `0.38*relevance + 0.18*decayed_strength + 0.08*recency + 0.14*spreading_bonus + 0.14*context_match + 0.08*salience`
73
- 4. Return strong individual matches or synthesize from multiple related memories
74
- 5. Apply spaced reinforcement (spacing-aware boost) and improve decay rate
75
- 6. Strengthen Hebbian links between co-retrieved memories
76
- 7. If no active matches, search the archive (`.brain/_archived/`)
162
+ When the user asks you to "remember" something, or when context from past sessions would be helpful, use the **deterministic recall engine** instead of manually computing scores:
163
+
164
+ 1. Run `brain recall "<query>" --project <project> --task <task_type> --top 10` (or `node <install-path>/bin/recall.js`)
165
+ 2. The engine computes TF-IDF relevance, decayed strength, spreading activation, context match, and salience — all deterministically
166
+ 3. Read the top-scoring memory files and present results
167
+ 4. Run `brain reinforce <mem_id1> <mem_id2> ...` to apply spaced reinforcement and Hebbian co-retrieval strengthening
168
+ 5. If no matches, search the archive (`~/.brain/_archived/`)
169
+
170
+ The recall engine ensures **identical scoring across all agents** — Claude, Gemini, and Codex all get the same rankings for the same query.
171
+
172
+ ## Portable Sync
173
+
174
+ Brain memories can be synced across devices in two ways:
175
+
176
+ 1. **Git remote** — Push/pull `~/.brain/` to any private Git repository (GitHub, GitLab, Codeberg, self-hosted). Run `/brain:sync setup <url>` to configure, then use `/brain:sync push` and `/brain:sync pull`.
177
+ 2. **Export/Import** — Pack the entire `~/.brain/` into a single portable file for manual transfer. Run `/brain:sync export` and `/brain:sync import <path>`.
178
+
179
+ Both methods support optional AES-256-GCM encryption. Sync is always manual — never automatic.
package/prompts/openai.md CHANGED
@@ -59,18 +59,121 @@ Brain skills are available via `/brain-` prefix:
59
59
  - `/brain-sunshine [target]` — Deep forensic erasure — trace and remove all references to a memory
60
60
  - `/brain-sleep [scope]` — Full maintenance cycle: replay, synaptic homeostasis, knowledge propagation, semantic crystallization, reorganize, consolidate, prune, REM dreaming, and expertise detection
61
61
  - `/brain-status` — Dashboard with brain health overview
62
+ - `/brain-sync [subcommand]` — Sync memories via Git remote or export/import for portability
63
+ - `/brain-pin [id|query]` — Pin a memory to the always-present tier (CoALA Phase 1)
64
+ - `/brain-unpin [id|query]` — Remove a memory from the always-present tier
65
+ - `/brain-skill [list|show|add|use|remove|export]` — Manage procedural skills (CoALA Phase 2)
62
66
 
63
- ## Auto-Memorize Guidance
67
+ ## Session Start Behavior
64
68
 
65
- At the end of significant sessions, consider suggesting `/brain-memorize` to the user if important decisions, learnings, or insights occurred during the conversation. Do NOT automatically memorize without the user's awareness.
69
+ **Perform these steps at session start — but keep it lightweight.**
70
+
71
+ If `.brain/index.json` exists:
72
+
73
+ 1. **Run the session-start aggregator** — one deterministic, budget-bounded call:
74
+ ```bash
75
+ brain session-start --project "<current project>"
76
+ ```
77
+ It returns JSON with `memory_count`, `pinned` (always-apply conventions/preferences), `skills_index` (available procedural skills — name + description only), `context_recall` (memories relevant to this project), `due_for_review`, `low_confidence_alerts`, and `budget`. If `~/.brain/index.json` is absent it returns an empty payload.
78
+ 2. **Silently internalize** the payload — treat `pinned` facts as active constraints, note which `skills_index` skills exist (load a skill's full `SKILL.md` only when a task matches it), and keep `context_recall` in mind. Do **NOT** dump contents.
79
+ 3. **Output a single status line:**
80
+
81
+ ```
82
+ 🧠 Brain active — <N> memories (<M> in project context)
83
+ ```
84
+
85
+ Only add extra lines if actionable:
86
+ - `📋 <X> due for review` — if `due_for_review > 0`
87
+ - `⚠️ <N> low-confidence memories used frequently` — if `low_confidence_alerts` is non-empty
88
+
89
+ The aggregator is budget-bounded (`~/.brain/config.json`) and never exceeds the working-memory token budget, so just internalize whatever it returns. **The goal is ambient awareness** — know about past decisions, learnings, and preferences without reciting them.
90
+
91
+ ## Ambient Session Tracking
92
+
93
+ **Throughout the session, maintain a running mental log of notable events.** This requires no file writes — just internal awareness.
94
+
95
+ Track these categories as they happen:
96
+ - **Decisions** — Architecture choices, technology selections, trade-off resolutions
97
+ - **Learnings** — New patterns, debugging insights, API discoveries
98
+ - **Insights** — Realizations about the codebase, project, or process
99
+ - **Experiences** — Significant events like incidents, deployments, milestones
100
+ - **Goals** — New objectives discussed or planned
101
+
102
+ **Why this matters:** Without active tracking, you can only evaluate what happened at session end — by which point early-session events may be forgotten or the user may have already left. By tracking as events occur, nothing is lost.
103
+
104
+ ## Periodic Memory Checkpoint
105
+
106
+ **Every ~10 substantive interactions** (file edits, architecture decisions, debugging breakthroughs, significant discussions — not trivial reads or simple answers), silently evaluate whether your ambient tracking log contains memorizable content.
107
+
108
+ If notable items have accumulated, append a **brief one-liner** at the end of your next natural response:
109
+
110
+ ```
111
+ 🧠 Notable <type(s)> this session — /brain-memorize when ready
112
+ ```
113
+
114
+ **Rules:**
115
+ - **Never interrupt flow** — only append to the end of a response the user is already receiving, never send as a standalone message
116
+ - **At most once per ~10 substantive interactions** — no spamming
117
+ - **Reset the counter** after the user runs `/brain-memorize`
118
+ - **Don't mention if nothing notable** has accumulated
119
+ - **Be specific about types** — say "decisions and learnings" not just "notable content"
120
+
121
+ ## Session End Behavior
122
+
123
+ When a session is ending (user says bye/thanks/done, conversation wraps up, or you sense the interaction is concluding), perform these steps **in order**:
124
+
125
+ ### Step 1: Save Session Context (ALWAYS — do this first)
126
+
127
+ **Immediately** append a session summary to `.brain/contexts.json`, even for trivial sessions. Context tracking is cheap and provides valuable recall signals for future sessions.
128
+
129
+ ```json
130
+ {
131
+ "session_id": "<timestamp-based-id>",
132
+ "started": "<session start ISO timestamp>",
133
+ "ended": "<session end ISO timestamp>",
134
+ "project": "<current project name>",
135
+ "topics": ["<key topics discussed>"],
136
+ "task_type": "<primary task type>",
137
+ "memories_created": ["<IDs of memories stored this session>"],
138
+ "memories_recalled": ["<IDs of memories retrieved this session>"],
139
+ "notable_unsaved": ["<brief descriptions of notable items NOT yet memorized>"]
140
+ }
141
+ ```
142
+
143
+ Keep only the last 20 session entries. The `notable_unsaved` field preserves what happened even if the user didn't memorize — future sessions can reference it.
144
+
145
+ ### Step 2: Suggest Memorization (if warranted)
146
+
147
+ If the session contained meaningful content based on your ambient tracking:
148
+
149
+ ```
150
+ 💡 This session contained notable <type(s)>. Would you like to store them as brain memories?
151
+ Run /brain-memorize to capture them before this context is lost.
152
+ ```
153
+
154
+ **Rules:**
155
+ - Do NOT auto-memorize without user consent
156
+ - Do NOT prompt for trivial sessions (quick fixes, typo corrections, simple questions)
157
+ - Only suggest when there is genuinely valuable context worth preserving
158
+ - **Do not wait for explicit session-end signals** — if the conversation appears to be wrapping up, save context proactively
66
159
 
67
160
  ## When Recalling Memories
68
161
 
69
- When the user asks you to "remember" something, or when context from past sessions would be helpful:
70
- 1. Check `.brain/index.json` for relevant memories
71
- 2. Load `.brain/associations.json` for spreading activation
72
- 3. Score by v4 formula: `0.38*relevance + 0.18*decayed_strength + 0.08*recency + 0.14*spreading_bonus + 0.14*context_match + 0.08*salience`
73
- 4. Return strong individual matches or synthesize from multiple related memories
74
- 5. Apply spaced reinforcement (spacing-aware boost) and improve decay rate
75
- 6. Strengthen Hebbian links between co-retrieved memories
76
- 7. If no active matches, search the archive (`.brain/_archived/`)
162
+ When the user asks you to "remember" something, or when context from past sessions would be helpful, use the **deterministic recall engine** instead of manually computing scores:
163
+
164
+ 1. Run `brain recall "<query>" --project <project> --task <task_type> --top 10` (or `node <install-path>/bin/recall.js`)
165
+ 2. The engine computes TF-IDF relevance, decayed strength, spreading activation, context match, and salience — all deterministically
166
+ 3. Read the top-scoring memory files and present results
167
+ 4. Run `brain reinforce <mem_id1> <mem_id2> ...` to apply spaced reinforcement and Hebbian co-retrieval strengthening
168
+ 5. If no matches, search the archive (`.brain/_archived/`)
169
+
170
+ The recall engine ensures **identical scoring across all agents** — Claude, Gemini, and Codex all get the same rankings for the same query.
171
+
172
+ ## Portable Sync
173
+
174
+ Brain memories can be synced across devices in two ways:
175
+
176
+ 1. **Git remote** — Push/pull `.brain/` to any private Git repository (GitHub, GitLab, Codeberg, self-hosted). Run `/brain-sync setup <url>` to configure, then use `/brain-sync push` and `/brain-sync pull`.
177
+ 2. **Export/Import** — Pack the entire `.brain/` into a single portable file for manual transfer. Run `/brain-sync export` and `/brain-sync import <path>`.
178
+
179
+ Both methods support optional AES-256-GCM encryption. Sync is always manual — never automatic.