brain-memory 0.1.0-beta.10 → 0.1.0-beta.11

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 CHANGED
@@ -140,9 +140,27 @@ When a session begins and `~/.brain/` exists, the agent automatically:
140
140
 
141
141
  The agent silently internalizes relevant memories and references them naturally during the session — no information dump.
142
142
 
143
+ ### Ambient Session Tracking
144
+
145
+ Throughout the session, the agent maintains a running mental log of notable events — decisions made, things learned, insights realized, significant experiences. This is purely internal awareness with no file writes. It ensures that early-session events aren't forgotten by the time the session ends.
146
+
147
+ ### Periodic Memory Checkpoint
148
+
149
+ Every ~10 substantive interactions (file edits, architecture decisions, debugging breakthroughs), the agent evaluates whether memorizable content has accumulated. If so, it appends a brief reminder to its next response:
150
+
151
+ ```
152
+ 🧠 Notable decisions and learnings this session — /brain:memorize when ready
153
+ ```
154
+
155
+ This never interrupts your flow — it's a one-liner appended to an existing response, at most once per ~10 interactions. The counter resets after you run `/brain:memorize`.
156
+
143
157
  ### Session End
144
158
 
145
- When a session ends, the agent evaluates whether significant decisions, learnings, insights, or experiences occurred. If so, it suggests:
159
+ When a session ends, the agent performs two steps in order:
160
+
161
+ 1. **Saves session context** to `~/.brain/contexts.json` — always, even for trivial sessions. This includes a `notable_unsaved` field listing items you didn't memorize, so future sessions can reference what happened.
162
+
163
+ 2. **Suggests memorization** if the session contained meaningful decisions, learnings, or insights:
146
164
 
147
165
  ```
148
166
  💡 This session contained notable decisions and learnings.
@@ -150,7 +168,7 @@ When a session ends, the agent evaluates whether significant decisions, learning
150
168
  Run /brain:memorize to capture them before this context is lost.
151
169
  ```
152
170
 
153
- The agent never auto-memorizes without user consent. Session context is always saved to `~/.brain/contexts.json` for context-dependent recall.
171
+ The agent never auto-memorizes without user consent. Context is saved proactively — the agent doesn't wait for an explicit goodbye signal.
154
172
 
155
173
  ## How It Works
156
174
 
package/assets/icon.png CHANGED
Binary file
@@ -4,6 +4,16 @@ You are storing a new memory in the Brain Memory system. Memories are filed into
4
4
 
5
5
  **User input:** $ARGUMENTS
6
6
 
7
+ ## Efficiency Rules
8
+
9
+ **CRITICAL — minimize tool call round-trips:**
10
+ - **Plan everything before writing anything.** Steps 1-4 are pure reasoning — no tool calls needed.
11
+ - **Generate all IDs in a single shell call** using: `hexdump -n 3 -e '"%06x\n"' /dev/urandom` (one per memory, chain multiple with `;`).
12
+ - **Skip reads when you already have the file contents in context** (e.g., you just wrote them, or read them earlier this session). Only read `index.json` and `associations.json` if you do NOT already know their current state.
13
+ - **Batch all file writes into a single parallel tool call** — memory files, _meta.json files, index.json, and associations.json should all be written together.
14
+ - **Create directories in a single mkdir -p call** before the write batch.
15
+ - **Target: 3-4 tool call rounds total** — (1) read current state if needed + generate IDs, (2) present proposal to user, (3) write all files, (4) reindex.
16
+
7
17
  ## Steps
8
18
 
9
19
  ### 1. Determine Memory Content
@@ -67,15 +77,45 @@ Choose the most appropriate path in the `~/.brain/` hierarchy. This is the most
67
77
 
68
78
  **If a memory spans categories**, place it in the most relevant one and note the cross-reference in `related` metadata.
69
79
 
70
- ### 4. Generate Memory ID
80
+ ### 4. Present Proposal for Confirmation
81
+
82
+ Before writing anything, show the user what you plan to store:
83
+
84
+ For each proposed memory, display:
85
+ - **Title** and proposed **path**
86
+ - **Type** / **cognitive type** / **strength**
87
+ - **Salience** / **confidence**
88
+ - **Tags**
89
+ - A 1-2 sentence summary
90
+
91
+ Ask: "Store these memories?" and wait for confirmation. If the user wants changes, adjust before proceeding.
92
+
93
+ **Skip this step only if** the user explicitly passed detailed $ARGUMENTS that leave no ambiguity about what to store.
94
+
95
+ ### 5. Generate Memory IDs and Prepare Directories
96
+
97
+ **In a single tool call**, generate all needed random hex IDs and create any new directories:
98
+
99
+ ```bash
100
+ # Generate N IDs (one per memory) and create directories in one call
101
+ hexdump -n 3 -e '"%06x\n"' /dev/urandom; hexdump -n 3 -e '"%06x\n"' /dev/urandom; mkdir -p ~/.brain/path/to/new/dir
102
+ ```
71
103
 
72
104
  Format: `mem_<YYYYMMDD>_<6-char-random-hex>`
73
105
 
74
- Example: `mem_20260213_a3f2c1`
106
+ ### 6. Read Current State (only if needed)
107
+
108
+ **If you already have `index.json` and `associations.json` contents in context from this session, SKIP this step entirely.**
109
+
110
+ Otherwise, read them now in a single parallel call:
111
+ - `~/.brain/index.json`
112
+ - `~/.brain/associations.json`
75
113
 
76
- ### 5. Write Memory File
114
+ ### 7. Write Everything in One Batch
77
115
 
78
- Create the memory file at the determined path with this format:
116
+ **Write ALL files in a single parallel tool call:**
117
+
118
+ **A. Memory files** — one per memory, at the determined paths:
79
119
 
80
120
  ```markdown
81
121
  ---
@@ -116,9 +156,7 @@ encoding_context:
116
156
  <How this relates to other knowledge, patterns, or goals — if applicable>
117
157
  ```
118
158
 
119
- ### 6. Update Index
120
-
121
- Read `~/.brain/index.json` and add an entry:
159
+ **B. Updated index.json** — add entries for all new memories:
122
160
 
123
161
  ```json
124
162
  {
@@ -146,21 +184,19 @@ Read `~/.brain/index.json` and add an entry:
146
184
 
147
185
  Increment `memory_count`. Update `last_updated`.
148
186
 
149
- ### 7. Update Associations
150
-
151
- Read `~/.brain/associations.json` and create edges for this memory:
187
+ **C. Updated associations.json** — create edges for new memories:
152
188
 
153
- **A. Explicit `related` links:** For each ID in the `related` field, create an edge with weight 0.20 and origin `manual`.
189
+ - **Explicit `related` links:** For each ID in the `related` field, create an edge with weight 0.20 and origin `manual`.
190
+ - **Auto-discovered links:** Scan `index.json` for other memories sharing **2 or more tags** with the new memory. For each match, create an edge with weight 0.10 and origin `tag_overlap`.
191
+ - Use the `reinforceEdge()` function — if an edge already exists, strengthen it via Hebbian reinforcement instead of creating a duplicate.
154
192
 
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`.
156
-
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.
158
-
159
- Write the updated `associations.json`.
193
+ **D. _meta.json files** — for each directory along the path:
194
+ - Increment `memory_count`
195
+ - Add new subcategories to the `subcategories` array if any were created
160
196
 
161
197
  ### 8. Update Search Index
162
198
 
163
- If `~/.brain/search-index.json` exists, update it so the new memory is discoverable by the recall engine. Run:
199
+ Rebuild the TF-IDF search index so the new memories are discoverable by the recall engine:
164
200
 
165
201
  ```bash
166
202
  node <brain-memory-install-path>/bin/recall.js --reindex
@@ -171,15 +207,7 @@ Or if globally installed:
171
207
  brain-recall --reindex
172
208
  ```
173
209
 
174
- This rebuilds the TF-IDF search index from all memories, enabling deterministic semantic search via the recall engine.
175
-
176
- ### 9. Update _meta.json
177
-
178
- Update the `_meta.json` in each directory along the path:
179
- - Increment `memory_count`
180
- - Add new subcategories to the `subcategories` array if any were created
181
-
182
- ### 10. Confirm
210
+ ### 9. Confirm
183
211
 
184
212
  Print what was stored:
185
213
  - Memory title and ID
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "brain-memory",
3
- "version": "0.1.0-beta.10",
3
+ "version": "0.1.0-beta.11",
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",
package/prompts/claude.md CHANGED
@@ -94,16 +94,64 @@ If any frequently-used memories (access_count >= 3) have confidence < 0.5:
94
94
 
95
95
  **The goal is ambient awareness** — know about past decisions, learnings, and preferences without reciting them. When a situation arises where a past memory is relevant, naturally reference it.
96
96
 
97
- ## Session End Behavior
97
+ ## Ambient Session Tracking
98
+
99
+ **Throughout the session, maintain a running mental log of notable events.** This requires no file writes — just internal awareness.
98
100
 
99
- When a session is ending or the user signals they are done, evaluate whether the session contained:
101
+ Track these categories as they happen:
100
102
  - **Decisions** — Architecture choices, technology selections, trade-off resolutions
101
103
  - **Learnings** — New patterns, debugging insights, API discoveries
102
104
  - **Insights** — Realizations about the codebase, project, or process
103
105
  - **Experiences** — Significant events like incidents, deployments, milestones
104
106
  - **Goals** — New objectives discussed or planned
105
107
 
106
- If the session contained meaningful content in any of these categories, suggest:
108
+ **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.
109
+
110
+ ## Periodic Memory Checkpoint
111
+
112
+ **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.
113
+
114
+ If notable items have accumulated, append a **brief one-liner** at the end of your next natural response:
115
+
116
+ ```
117
+ 🧠 Notable <type(s)> this session — /brain:memorize when ready
118
+ ```
119
+
120
+ **Rules:**
121
+ - **Never interrupt flow** — only append to the end of a response the user is already receiving, never send as a standalone message
122
+ - **At most once per ~10 substantive interactions** — no spamming
123
+ - **Reset the counter** after the user runs `/brain:memorize`
124
+ - **Don't mention if nothing notable** has accumulated
125
+ - **Be specific about types** — say "decisions and learnings" not just "notable content"
126
+
127
+ ## Session End Behavior
128
+
129
+ 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**:
130
+
131
+ ### Step 1: Save Session Context (ALWAYS — do this first)
132
+
133
+ **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.
134
+
135
+ ```json
136
+ {
137
+ "session_id": "<timestamp-based-id>",
138
+ "started": "<session start ISO timestamp>",
139
+ "ended": "<session end ISO timestamp>",
140
+ "project": "<current project name>",
141
+ "topics": ["<key topics discussed>"],
142
+ "task_type": "<primary task type>",
143
+ "memories_created": ["<IDs of memories stored this session>"],
144
+ "memories_recalled": ["<IDs of memories retrieved this session>"],
145
+ "notable_unsaved": ["<brief descriptions of notable items NOT yet memorized>"]
146
+ }
147
+ ```
148
+
149
+ 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.
150
+
151
+ ### Step 2: Suggest Memorization (if warranted)
152
+
153
+ If the session contained meaningful content based on your ambient tracking:
154
+
107
155
  ```
108
156
  💡 This session contained notable <type(s)>. Would you like to store them as brain memories?
109
157
  Run /brain:memorize to capture them before this context is lost.
@@ -113,7 +161,7 @@ If the session contained meaningful content in any of these categories, suggest:
113
161
  - Do NOT auto-memorize without user consent
114
162
  - Do NOT prompt for trivial sessions (quick fixes, typo corrections, simple questions)
115
163
  - Only suggest when there is genuinely valuable context worth preserving
116
- - Always save session context to `~/.brain/contexts.json` regardless (append a session summary, keep last 20 entries)
164
+ - **Do not wait for explicit session-end signals** — if the conversation appears to be wrapping up, save context proactively
117
165
 
118
166
  ## When Recalling Memories
119
167
 
package/prompts/gemini.md CHANGED
@@ -95,16 +95,64 @@ If any frequently-used memories (access_count >= 3) have confidence < 0.5:
95
95
 
96
96
  **The goal is ambient awareness** — know about past decisions, learnings, and preferences without reciting them. When a situation arises where a past memory is relevant, naturally reference it.
97
97
 
98
- ## Session End Behavior
98
+ ## Ambient Session Tracking
99
+
100
+ **Throughout the session, maintain a running mental log of notable events.** This requires no file writes — just internal awareness.
99
101
 
100
- When a session is ending or the user signals they are done, evaluate whether the session contained:
102
+ Track these categories as they happen:
101
103
  - **Decisions** — Architecture choices, technology selections, trade-off resolutions
102
104
  - **Learnings** — New patterns, debugging insights, API discoveries
103
105
  - **Insights** — Realizations about the codebase, project, or process
104
106
  - **Experiences** — Significant events like incidents, deployments, milestones
105
107
  - **Goals** — New objectives discussed or planned
106
108
 
107
- If the session contained meaningful content in any of these categories, suggest:
109
+ **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.
110
+
111
+ ## Periodic Memory Checkpoint
112
+
113
+ **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.
114
+
115
+ If notable items have accumulated, append a **brief one-liner** at the end of your next natural response:
116
+
117
+ ```
118
+ 🧠 Notable <type(s)> this session — /brain:memorize when ready
119
+ ```
120
+
121
+ **Rules:**
122
+ - **Never interrupt flow** — only append to the end of a response the user is already receiving, never send as a standalone message
123
+ - **At most once per ~10 substantive interactions** — no spamming
124
+ - **Reset the counter** after the user runs `/brain:memorize`
125
+ - **Don't mention if nothing notable** has accumulated
126
+ - **Be specific about types** — say "decisions and learnings" not just "notable content"
127
+
128
+ ## Session End Behavior
129
+
130
+ 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**:
131
+
132
+ ### Step 1: Save Session Context (ALWAYS — do this first)
133
+
134
+ **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.
135
+
136
+ ```json
137
+ {
138
+ "session_id": "<timestamp-based-id>",
139
+ "started": "<session start ISO timestamp>",
140
+ "ended": "<session end ISO timestamp>",
141
+ "project": "<current project name>",
142
+ "topics": ["<key topics discussed>"],
143
+ "task_type": "<primary task type>",
144
+ "memories_created": ["<IDs of memories stored this session>"],
145
+ "memories_recalled": ["<IDs of memories retrieved this session>"],
146
+ "notable_unsaved": ["<brief descriptions of notable items NOT yet memorized>"]
147
+ }
148
+ ```
149
+
150
+ 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.
151
+
152
+ ### Step 2: Suggest Memorization (if warranted)
153
+
154
+ If the session contained meaningful content based on your ambient tracking:
155
+
108
156
  ```
109
157
  💡 This session contained notable <type(s)>. Would you like to store them as brain memories?
110
158
  Run /brain:memorize to capture them before this context is lost.
@@ -114,7 +162,7 @@ If the session contained meaningful content in any of these categories, suggest:
114
162
  - Do NOT auto-memorize without user consent
115
163
  - Do NOT prompt for trivial sessions (quick fixes, typo corrections, simple questions)
116
164
  - Only suggest when there is genuinely valuable context worth preserving
117
- - Always save session context to `~/.brain/contexts.json` regardless (append a session summary, keep last 20 entries)
165
+ - **Do not wait for explicit session-end signals** — if the conversation appears to be wrapping up, save context proactively
118
166
 
119
167
  ## When Recalling Memories
120
168
 
package/prompts/openai.md CHANGED
@@ -95,16 +95,64 @@ If any frequently-used memories (access_count >= 3) have confidence < 0.5:
95
95
 
96
96
  **The goal is ambient awareness** — know about past decisions, learnings, and preferences without reciting them. When a situation arises where a past memory is relevant, naturally reference it.
97
97
 
98
- ## Session End Behavior
98
+ ## Ambient Session Tracking
99
+
100
+ **Throughout the session, maintain a running mental log of notable events.** This requires no file writes — just internal awareness.
99
101
 
100
- When a session is ending or the user signals they are done, evaluate whether the session contained:
102
+ Track these categories as they happen:
101
103
  - **Decisions** — Architecture choices, technology selections, trade-off resolutions
102
104
  - **Learnings** — New patterns, debugging insights, API discoveries
103
105
  - **Insights** — Realizations about the codebase, project, or process
104
106
  - **Experiences** — Significant events like incidents, deployments, milestones
105
107
  - **Goals** — New objectives discussed or planned
106
108
 
107
- If the session contained meaningful content in any of these categories, suggest:
109
+ **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.
110
+
111
+ ## Periodic Memory Checkpoint
112
+
113
+ **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.
114
+
115
+ If notable items have accumulated, append a **brief one-liner** at the end of your next natural response:
116
+
117
+ ```
118
+ 🧠 Notable <type(s)> this session — /brain-memorize when ready
119
+ ```
120
+
121
+ **Rules:**
122
+ - **Never interrupt flow** — only append to the end of a response the user is already receiving, never send as a standalone message
123
+ - **At most once per ~10 substantive interactions** — no spamming
124
+ - **Reset the counter** after the user runs `/brain-memorize`
125
+ - **Don't mention if nothing notable** has accumulated
126
+ - **Be specific about types** — say "decisions and learnings" not just "notable content"
127
+
128
+ ## Session End Behavior
129
+
130
+ 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**:
131
+
132
+ ### Step 1: Save Session Context (ALWAYS — do this first)
133
+
134
+ **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.
135
+
136
+ ```json
137
+ {
138
+ "session_id": "<timestamp-based-id>",
139
+ "started": "<session start ISO timestamp>",
140
+ "ended": "<session end ISO timestamp>",
141
+ "project": "<current project name>",
142
+ "topics": ["<key topics discussed>"],
143
+ "task_type": "<primary task type>",
144
+ "memories_created": ["<IDs of memories stored this session>"],
145
+ "memories_recalled": ["<IDs of memories retrieved this session>"],
146
+ "notable_unsaved": ["<brief descriptions of notable items NOT yet memorized>"]
147
+ }
148
+ ```
149
+
150
+ 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.
151
+
152
+ ### Step 2: Suggest Memorization (if warranted)
153
+
154
+ If the session contained meaningful content based on your ambient tracking:
155
+
108
156
  ```
109
157
  💡 This session contained notable <type(s)>. Would you like to store them as brain memories?
110
158
  Run /brain-memorize to capture them before this context is lost.
@@ -114,7 +162,7 @@ If the session contained meaningful content in any of these categories, suggest:
114
162
  - Do NOT auto-memorize without user consent
115
163
  - Do NOT prompt for trivial sessions (quick fixes, typo corrections, simple questions)
116
164
  - Only suggest when there is genuinely valuable context worth preserving
117
- - Always save session context to `.brain/contexts.json` regardless (append a session summary, keep last 20 entries)
165
+ - **Do not wait for explicit session-end signals** — if the conversation appears to be wrapping up, save context proactively
118
166
 
119
167
  ## When Recalling Memories
120
168