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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -119,22 +119,18 @@ Then append the contents of the corresponding prompt file to your agent's instru
119
119
 
120
120
  ## Commands
121
121
 
122
+ The everyday loop is **ambient** — `remember` and `memorize` run automatically at session start/end, so you rarely type a command. The surface is a small core plus a background maintenance job:
123
+
122
124
  | Command | Description |
123
125
  |---------|-------------|
124
- | `/brain:init` | Initialize `~/.brain/` directory structure with default categories |
125
- | `/brain:memorize [topic] [--sync]` | Store memories from current session context (add `--sync` to auto-push) |
126
126
  | `/brain:remember [query]` | Recall relevant memories with spreading activation and context matching |
127
- | `/brain:pin [id\|query]` | Pin a memory to the always-present tier — loads every session, never decays |
128
- | `/brain:unpin [id\|query]` | Remove a memory from the always-present tier |
129
- | `/brain:review [scope]` | Spaced repetition review session for due memories |
130
- | `/brain:explore [category]` | Browse the brain hierarchy with visual tree view |
131
- | `/brain:consolidate [scope]` | Merge related weak memories into stronger combined ones |
132
- | `/brain:forget [target]` | Decay, archive, or remove memories |
133
- | `/brain:sunshine [target]` | Deep forensic erasure — trace and remove all references |
134
- | `/brain:sleep [scope]` | Full maintenance cycle — 9 neuroscience-inspired phases |
127
+ | `/brain:memorize [topic] [--sync]` | Store memories from current session context (add `--sync` to auto-push) |
135
128
  | `/brain:status` | Dashboard with brain health metrics and recommendations |
129
+ | `/brain:pin [id\|query]` | Pin a memory to the always-present tier — loads every session, never decays. Toggles: also unpins (`--off`) |
130
+ | `/brain:forget [target]` | Decay, archive, or remove memories. `--deep` performs forensic erasure — traces and removes every reference |
131
+ | `/brain:sync [subcommand]` | Sync via Brain Cloud, Git remote, or export/import (auto-initializes the brain on first run) |
136
132
  | `/brain:skills [list\|show\|add\|use\|remove\|export]` | Manage procedural skills — reusable how-to workflows with progressive disclosure |
137
- | `/brain:sync [subcommand]` | Sync memories via Git remote or export/import for portability |
133
+ | `/brain:sleep [scope]` | Full maintenance cycle — 9 neuroscience-inspired phases (replay, consolidation, review reinforcement, pruning, dreaming, …). Usually runs automatically/in the background |
138
134
 
139
135
  ## Session Lifecycle
140
136
 
@@ -151,7 +147,7 @@ When a session begins and `~/.brain/` exists, the agent makes a single `brain se
151
147
 
152
148
  ```
153
149
  🧠 Brain active — 42 memories loaded (8 in current project context)
154
- 📋 3 memories due for review — run /brain:review
150
+ 📋 3 memories due for review — reinforced automatically during /brain:sleep
155
151
  ```
156
152
 
157
153
  The agent treats pinned facts as active constraints, notes which skills exist, silently internalizes relevant memories, and references them naturally during the session — no information dump.
@@ -201,8 +197,8 @@ Create → Store → Decay → Recall → Reinforce → Review → Sleep → Arc
201
197
  3. **Decay** — Memories naturally weaken over time: `effective_strength = base_strength * (decay_rate ^ days_since_access)`
202
198
  4. **Recall** — `/brain:remember` searches, scores with spreading activation and context matching, and returns the best memories. Archived memories are searched as a fallback.
203
199
  5. **Reinforce** — Each recall applies spaced reinforcement (longer gaps = bigger boosts) and improves the memory's decay resistance
204
- 6. **Review** — `/brain:review` implements SM-2 spaced repetition, surfacing memories at optimal intervals for long-term retention
205
- 7. **Sleep** — `/brain:sleep` performs a 9-phase maintenance cycle inspired by real neuroscience
200
+ 6. **Review** — SM-2 spaced repetition surfaces memories at optimal intervals for long-term retention; reinforcement runs automatically during the sleep cycle
201
+ 7. **Sleep** — `/brain:sleep` performs a 9-phase maintenance cycle inspired by real neuroscience (replay, consolidation, review reinforcement, pruning, dreaming, …), usually run automatically/in the background
206
202
  8. **Archive** — Fully decayed memories move to `_archived/` (recoverable and searchable) or can be permanently deleted
207
203
 
208
204
  ### Neuroscience Foundations
@@ -440,7 +436,7 @@ Each expertise area gets an `_expertise.md` profile documenting what you know we
440
436
 
441
437
  ### Spaced Repetition Review
442
438
 
443
- `/brain:review` implements the SM-2 algorithm to surface memories at optimal intervals for long-term retention. The review queue is generated during sleep and tracks:
439
+ Brain Memory implements the SM-2 algorithm to surface memories at optimal intervals for long-term retention. The review queue is generated and reinforced during `/brain:sleep`, and tracks:
444
440
 
445
441
  - **Interval** — Time until next review (grows exponentially with successful recalls)
446
442
  - **Ease factor** — How easily the memory is recalled (adjusts based on recall quality 1-5)
@@ -450,7 +446,9 @@ Failed recalls reset the interval to 1 day. Successful recalls extend the interv
450
446
 
451
447
  ### Cross-Agent Memory Sharing
452
448
 
453
- `~/.brain/` is a single global directory in the user's home folder. All memories are shared across every project and every supported agent automatically. A decision stored by Claude Code in one project is immediately available to Gemini CLI or Codex CLI in any other project — no configuration, no export, no per-project setup. The format is agent-agnostic: plain Markdown files with YAML frontmatter, readable by any tool.
449
+ `~/.brain/` is a single global directory in the user's home folder. All memories are shared across every project and every supported agent automatically. A decision stored by Claude Code in one project is immediately available to Gemini CLI, OpenAI Codex CLI, or OpenCode in any other project — no configuration, no export, no per-project setup. The format is agent-agnostic: plain Markdown files with YAML frontmatter, readable by any tool.
450
+
451
+ Brain Memory is **model-agnostic** as well as agent-portable: because memory is plain files rather than embeddings welded to a particular model, the LLM underneath your agent can be anything — GPT, Claude, Gemini, or any model routed through a gateway — and your memory is unaffected. **Switch your model or switch your agent, and you keep remembering and pick up exactly where you left off.**
454
452
 
455
453
  To share memories across different machines, use `/brain:sync` (see below).
456
454
 
@@ -612,7 +610,7 @@ npm test # Unit tests
612
610
  node harness/runner.js # Full benchmark (cloud APIs)
613
611
  ```
614
612
 
615
- Live methodology and per-scenario detail: [brainmemory.work/docs/benchmarks](https://brainmemory.work/docs/benchmarks) · Source: [`benchmark/`](benchmark/)
613
+ Live methodology and per-scenario detail: [brainmemory.ai/docs/benchmarks](https://brainmemory.ai/docs/benchmarks) · Source: [`benchmark/`](benchmark/)
616
614
 
617
615
  ## Contributing
618
616
 
package/bin/install.js CHANGED
@@ -148,19 +148,17 @@ async function runInstall(flags) {
148
148
  ✓ Installation complete!
149
149
 
150
150
  Available commands:
151
- /brain:init Initialize brain structure
152
- /brain:memorize Store a new memory
153
151
  /brain:remember Recall relevant memories
154
- /brain:review Spaced repetition review session
155
- /brain:explore Browse the brain hierarchy
156
- /brain:consolidate Merge related memories
157
- /brain:forget Decay or remove memories
158
- /brain:sunshine Deep forensic memory erasure
159
- /brain:sleep Full maintenance cycle
152
+ /brain:memorize Store a new memory
160
153
  /brain:status Brain overview dashboard
161
- /brain:sync Sync memories via Git remote or export/import
162
-
163
- Get started by running /brain:init in your agent session.
154
+ /brain:pin Pin (or unpin) a memory in the always-present tier
155
+ /brain:forget Decay, archive, or forensically erase (--deep) memories
156
+ /brain:sync Sync via Brain Cloud, Git remote, or export/import
157
+ /brain:skills Manage procedural skills
158
+ /brain:sleep Full maintenance cycle (usually automatic)
159
+
160
+ Your brain is ready — recall and memorize happen automatically. Just start working,
161
+ or run /brain:status to see an overview.
164
162
  `);
165
163
  } finally {
166
164
  rl.close();
package/bin/memorize.js CHANGED
@@ -246,7 +246,10 @@ async function main() {
246
246
  process.exit(1);
247
247
  }
248
248
 
249
- inputData = fs.readFileSync('/dev/stdin', 'utf-8');
249
+ // Read from fd 0 rather than the '/dev/stdin' path: the path form fails with
250
+ // ENXIO on Linux CI runners and doesn't exist on Windows, whereas fd 0 reads
251
+ // piped stdin portably across Linux, macOS, and Windows.
252
+ inputData = fs.readFileSync(0, 'utf-8');
250
253
 
251
254
  let input;
252
255
  try {
package/bin/recall.js CHANGED
@@ -43,7 +43,7 @@ function main() {
43
43
  const brainDir = getBrainDir();
44
44
 
45
45
  if (!fs.existsSync(path.join(brainDir, 'index.json'))) {
46
- console.error(JSON.stringify({ error: 'Brain not initialized. Run /brain:init first.' }));
46
+ console.error(JSON.stringify({ error: 'Brain not initialized. Reinstall with `npx brain-memory`, or run /brain:sync to create it.' }));
47
47
  process.exit(1);
48
48
  }
49
49
 
package/bin/skill.js CHANGED
@@ -51,7 +51,7 @@ function main(argv) {
51
51
  case 'add': {
52
52
  if (process.stdin.isTTY) return fail({ error: 'Pipe a skill JSON via stdin' });
53
53
  let input;
54
- try { input = JSON.parse(fs.readFileSync('/dev/stdin', 'utf-8')); }
54
+ try { input = JSON.parse(fs.readFileSync(0, 'utf-8')); }
55
55
  catch (e) { return fail({ error: `Invalid JSON: ${e.message}` }); }
56
56
  return done(addSkill(undefined, input));
57
57
  }
@@ -1,28 +1,33 @@
1
1
  ---
2
- description: Decay or archive memories
3
- argument-hint: "[target]"
2
+ description: Decay, archive, or forensically erase memories
3
+ argument-hint: "[target] [--deep]"
4
4
  ---
5
5
 
6
- # /brain:forget — Decay or Remove Memories
6
+ # /brain:forget — Decay, Remove, or Forensically Erase Memories
7
7
 
8
- You are managing memory decay in the Brain Memory system. This command accelerates forgetting for specific memories or prunes memories that have naturally decayed below usefulness.
8
+ You are managing memory removal in the Brain Memory system. This command accelerates
9
+ forgetting for specific memories, prunes naturally-decayed memories, or — with `--deep` —
10
+ performs **forensic erasure** that traces and removes every reference to a memory across the
11
+ entire `~/.brain/` tree.
9
12
 
10
13
  **Target:** $ARGUMENTS
11
14
 
12
- ## Steps
15
+ ## Modes
13
16
 
14
- ### 1. Determine Mode
17
+ | Invocation | Mode |
18
+ |------------|------|
19
+ | `/brain:forget <query>` | **A — Targeted forget**: decay or remove memories matching a query |
20
+ | `/brain:forget --prune [threshold]` | **B — Threshold prune**: archive memories below a decayed-strength threshold (default 0.2) |
21
+ | `/brain:forget <category/path>` | **C — Category prune**: decay/remove an entire subtree |
22
+ | `/brain:forget --deep <target>` | **D — Forensic erasure**: trace + remove every reference to a memory (see "Deep mode" below) |
15
23
 
16
- Based on $ARGUMENTS:
24
+ ---
17
25
 
18
- **Mode A — Targeted forget** (e.g., "/brain:forget kubernetes deployment issue"):
19
- Find specific memories matching the query and offer to accelerate their decay or remove them.
26
+ ## Modes A–C — Decay & Archive
20
27
 
21
- **Mode B — Threshold prune** (e.g., "/brain:forget --prune" or "/brain:forget --prune 0.2"):
22
- Find all memories whose effective (decayed) strength is below the given threshold (default: 0.2) and offer to archive them.
28
+ ### 1. Determine Mode
23
29
 
24
- **Mode C — Category prune** (e.g., "/brain:forget professional/companies/old-corp"):
25
- Apply decay/removal to an entire category subtree.
30
+ Based on $ARGUMENTS, select Mode A, B, or C. If `--deep` is present, jump to **Deep mode**.
26
31
 
27
32
  ### 2. Find Affected Memories
28
33
 
@@ -37,7 +42,8 @@ For Mode A: Match query against titles, tags, and paths.
37
42
  For Mode B: Filter by decayed strength < threshold.
38
43
  For Mode C: Filter by path prefix.
39
44
 
40
- **Salience protection**: Flag any memories with `salience >= 0.7` — these require explicit `/brain:forget` with direct confirmation (never included in bulk prune operations).
45
+ **Salience protection**: Flag any memories with `salience >= 0.7` — these require explicit
46
+ confirmation and are never included in bulk prune operations.
41
47
 
42
48
  ### 3. Present Candidates
43
49
 
@@ -58,6 +64,7 @@ Show the user what would be affected:
58
64
  - **Archive**: Move to `_archived/` (recoverable, searchable via /brain:remember)
59
65
  - **Accelerate decay**: Set decay_rate to 0.90 (fast fade)
60
66
  - **Delete permanently**: Remove files entirely (not recoverable)
67
+ - **Forensic erase**: Use `/brain:forget --deep` to also scrub all cross-references (for secrets)
61
68
  ```
62
69
 
63
70
  ### 4. Get User Confirmation
@@ -109,7 +116,9 @@ The user must explicitly choose an action. Default to **archive** (safest).
109
116
 
110
117
  ### 6. Suggest Consolidation
111
118
 
112
- If any remaining memories in the affected area are also weak (decayed strength < 0.4), suggest running `/brain:consolidate` on that category to preserve the knowledge in a more durable form before it fades.
119
+ If any remaining memories in the affected area are also weak (decayed strength < 0.4), suggest
120
+ running `/brain:sleep` — its consolidation pass preserves the knowledge in a more durable
121
+ combined form before it fades.
113
122
 
114
123
  ### 7. Confirm
115
124
 
@@ -118,3 +127,219 @@ Print summary:
118
127
  - Action taken (archived/accelerated/deleted)
119
128
  - Current brain stats (total memories, average strength)
120
129
  - Archive searchability note: "Archived memories are searchable via /brain:remember if needed in the future"
130
+
131
+ ---
132
+
133
+ ## Deep mode — `/brain:forget --deep` (Forensic Erasure)
134
+
135
+ Like the procedure in *Eternal Sunshine of the Spotless Mind*, deep mode doesn't just delete a
136
+ memory — it traces every ripple that memory left across the entire `~/.brain/` tree and
137
+ surgically removes or repairs each one. When complete, it's as if the memory never existed.
138
+
139
+ Use this for erasing accidentally stored credentials, removing a deprecated anti-pattern that
140
+ leaked into other memories, or cleaning up after a fully reversed technical decision.
141
+
142
+ ### Deep-mode flags
143
+
144
+ | Flag | Behavior |
145
+ |------|----------|
146
+ | `--deep` | Enter forensic erasure: remove target + clean all references; follow derivative chains, asking about each |
147
+ | `--dry-run` | Show blast radius only — no changes are made |
148
+ | `--cascade` | Auto-remove derivative memories without asking |
149
+ | `--sensitive` | Overwrite file content with null bytes before deletion (for credentials, secrets) |
150
+ | `--no-trace` | Skip writing to `_erased.json` audit log |
151
+ | `--reason "<text>"` | Reason recorded in the audit log entry |
152
+
153
+ ### 1. Parse Target and Flags
154
+
155
+ Extract the **target identifier** (memory ID like `mem_20260215_a3f2c1`, title substring, or
156
+ file path) and any flags. If no target is provided, ask the user what memory to erase.
157
+
158
+ ### 2. Locate Target Memory
159
+
160
+ 1. Read `~/.brain/index.json` and search `memories` by exact ID, title substring
161
+ (case-insensitive), or path substring.
162
+ 2. If not found in active memories, check `~/.brain/_archived/index.json`.
163
+ 3. If still not found, check `~/.brain/_erased.json` — if found there, report the previous
164
+ erasure date + reason and stop ("No further action needed").
165
+ 4. If not found anywhere, report and stop.
166
+ 5. If multiple matches, present them and ask the user to pick one.
167
+
168
+ Once located, read the full memory file to capture its ID, title, path, tags, `related` array,
169
+ `consolidated_from` array, and content.
170
+
171
+ ### 3. Trace All References (Blast Radius Scan)
172
+
173
+ Scan the entire `~/.brain/` tree for every trace of the target. Track 8 reference types:
174
+
175
+ **3a. `related` arrays** — parse the YAML frontmatter of every `.md` memory file; record any
176
+ whose `related` array contains the target ID (with the current array contents).
177
+
178
+ **3b. Content body mentions** — search the Markdown body of all memory files for the target ID
179
+ and the target title (exact). Record each file path and matching line.
180
+
181
+ **3c. `consolidated_from` arrays** — among memories with `type: consolidated`, record any whose
182
+ `consolidated_from` contains the target ID, plus how many other sources remain.
183
+
184
+ **3d. Association edges** (`associations.json`) — find outgoing `edges[target_id][*]` and
185
+ incoming `edges[*][target_id]`; record each with neighbor, weight, origin.
186
+
187
+ **3e. Context sessions** (`contexts.json`) — record any session with the target ID in
188
+ `memories_created` or `memories_recalled`.
189
+
190
+ **3f. Review queue** (`review-queue.json`) — check for an item with `memory_id == target`.
191
+
192
+ **3g. Archive index** (`_archived/index.json`) — check if the target ID exists as a key.
193
+
194
+ **3h. Crystallization comments** — search all files for `<!-- Crystallized into <target_id> -->`.
195
+
196
+ ### 4. Identify Derivative Memories
197
+
198
+ Derivatives exist *because of* the target and may not make sense without it:
199
+
200
+ **4a. Sole crystallization derivatives** — semantic memories whose sole source is the target
201
+ (their `related` contains the target, a crystallization comment links them, and they have no
202
+ other source memories).
203
+
204
+ **4b. Sole consolidation derivatives** — a consolidated memory whose `consolidated_from`
205
+ contains the target and the target is its **only** remaining source (0 sources after removal).
206
+
207
+ **4c. Chain following** — recursively check each derivative for its own derivatives. Maintain a
208
+ `visited` set to prevent infinite loops on circular references.
209
+
210
+ ### 5. Visualize Blast Radius
211
+
212
+ Present the complete blast radius:
213
+
214
+ ```
215
+ ## Blast Radius: "<title>" (<id>)
216
+
217
+ ### TARGET (will be deleted)
218
+ <id> | <path> | <type> | strength: <strength> | salience: <salience>
219
+
220
+ ### DIRECT REFERENCES (will be cleaned) — <N> found
221
+ [REL] <path.md> — related: [..., <target_id>, ...]
222
+ [BODY] <path.md> — "<matching line snippet>"
223
+ [CONS] <path.md> — consolidated_from: [..., <target_id>, ...] (<M> sources remain)
224
+ [EDGE] <target_id> <-> <other_id> (weight: <w>, origin: <origin>)
225
+ [CTX] Session <timestamp> — in <memories_created|memories_recalled>
226
+ [REV] Review queue entry (next_review: <date>)
227
+ [ARCH] Archive index entry
228
+ [CRYS] <path.md> — <!-- Crystallized into <target_id> -->
229
+
230
+ ### DERIVATIVES (may cascade) — <N> found
231
+ <derivative_id> | <path> — sole <crystallization|consolidation> derivative of target
232
+
233
+ ### CONSOLIDATED REPAIRS — <N> needed
234
+ <path.md> — consolidated_from shrinks from <before> to <after> sources
235
+ ⚠️ <path.md> — will have only 1 source remaining (flagged for review)
236
+
237
+ ### SUMMARY
238
+ Files to modify: <count> References to clean: <count>
239
+ Derivatives found: <count> Risk level: <low|medium|high>
240
+ ```
241
+
242
+ **Risk level:** Low (<=3 refs, no derivatives) · Medium (4–10 refs, or derivatives present) ·
243
+ High (>10 refs, or target salience >= 0.7).
244
+
245
+ If `--dry-run` is set, stop here. Print "Dry run complete — no changes made." and exit.
246
+
247
+ ### 6. Confirm with User
248
+
249
+ **Standard:** `Proceed with erasure? This will modify <N> files and remove <M> references. [yes / no / select specific items]`
250
+
251
+ **High-salience (salience >= 0.7):** require the user to type the memory ID to confirm.
252
+
253
+ **Derivative handling** (without `--cascade`): for each derivative, ask individually whether to
254
+ delete it too, keep it (remove only the reference to target), or skip. With `--cascade`, all
255
+ derivatives are automatically included.
256
+
257
+ ### 7. Execute Erasure
258
+
259
+ Execute in this exact order (dependencies matter):
260
+
261
+ **7a. Handle derivatives first** (if approved): recursively apply 7b–7g, processing deepest
262
+ derivatives first (reverse topological order) to avoid dangling references.
263
+
264
+ **7b. Repair consolidated memories**: for each consolidated memory listing the target in
265
+ `consolidated_from`, remove the target from `consolidated_from` and `related`. If 1 source
266
+ remains, add `<!-- WARNING: only 1 source remains after erasure of <target_id>. Review. -->`.
267
+ Update the `index.json` entry.
268
+
269
+ **7c. Clean all direct references:**
270
+ 1. **`related` arrays** — remove the target ID; leave empty arrays as `related: []`.
271
+ 2. **Content body mentions** — remove reference-only lines; in mixed lines remove just the
272
+ target reference; drop a `## Connections` header if it becomes empty.
273
+ 3. **Association edges** — use `removeEdgesForMemory()` from `index-manager.js`; write the file.
274
+ 4. **Context sessions** — remove the target ID from `memories_created`/`memories_recalled`;
275
+ never delete the session entry itself.
276
+ 5. **Review queue** — use `removeFromReviewQueue()` from `index-manager.js`.
277
+ 6. **Archive index** — remove the entry and decrement `archived_count` if present.
278
+ 7. **Crystallization comments** — remove the comment line from each file.
279
+
280
+ **7d. Remove from `index.json`** using `removeMemory()` from `index-manager.js`.
281
+
282
+ **7e. Update `_meta.json` files** — decrement `memory_count` for each directory in the path.
283
+
284
+ **7f. Delete target file** — with `--sensitive`, overwrite with null bytes (same byte length)
285
+ before deleting; otherwise delete directly. Clean up empty parent dirs (never top-level ones).
286
+
287
+ **7g. Remove archived copy** if one exists (overwrite first under `--sensitive`).
288
+
289
+ ### 8. Write Audit Log
290
+
291
+ Unless `--no-trace` is set, append to `~/.brain/_erased.json`:
292
+
293
+ ```json
294
+ {
295
+ "version": 1,
296
+ "erasures": [
297
+ {
298
+ "erased_id": "<memory_id>",
299
+ "erased_date": "<ISO timestamp>",
300
+ "reason": "<user-provided reason or 'unspecified'>",
301
+ "references_cleaned": <count>,
302
+ "derivatives_removed": <count>,
303
+ "consolidated_repaired": <count>,
304
+ "flags_used": ["<flags that were active>"]
305
+ }
306
+ ]
307
+ }
308
+ ```
309
+
310
+ **IMPORTANT**: The audit log intentionally omits the title, content, tags, and path — it proves
311
+ an erasure happened without preserving what was erased.
312
+
313
+ ### 9. Post-Erasure Integrity Check
314
+
315
+ Scan for: dangling references (grep all files for the erased ID), orphaned associations, index
316
+ consistency (`memory_count` matches actual entries), and empty directories. If issues are found,
317
+ report them and note they can be fixed by running `/brain:sleep`.
318
+
319
+ ### 10. Confirm
320
+
321
+ ```
322
+ ## Erasure Complete: "<title>"
323
+
324
+ Memory deleted: <id>
325
+ References cleaned: <count> across <file_count> files
326
+ Derivatives removed: <count>
327
+ Consolidated memories repaired: <count>
328
+ Audit log: <written to _erased.json | skipped (--no-trace)>
329
+
330
+ Brain stats: <total_memories> memories, average strength <avg>
331
+ ```
332
+
333
+ ### Deep-mode rules
334
+
335
+ 1. **Always confirm before executing.** High-salience memories require typing the ID.
336
+ 2. **Order matters.** Follow Step 7 exactly — derivatives, repairs, references, index, deletion.
337
+ 3. **Audit by default.** Always write `_erased.json` unless `--no-trace`; the log carries no
338
+ identifying information.
339
+ 4. **No collateral damage.** Only remove references to the specific target.
340
+ 5. **Preserve other memories' integrity** when editing their frontmatter or content.
341
+ 6. **Sensitive data** — with `--sensitive`, overwrite before deletion to prevent recovery.
342
+ 7. **Integrity check is mandatory.**
343
+ 8. **Recursive safety** — maintain a `visited` set with `--cascade`.
344
+ 9. **Never delete top-level category directories** even if empty.
345
+ 10. **Context sessions are preserved** — remove IDs from arrays, never the session itself.
@@ -1,37 +1,79 @@
1
1
  ---
2
- description: Pin a memory to the always-present tier
3
- argument-hint: "[id|query]"
2
+ description: Pin or unpin a memory in the always-present tier
3
+ argument-hint: "[id|query] [--off]"
4
4
  ---
5
5
 
6
- # /brain:pin — Pin a Memory (Always-Present Tier)
6
+ # /brain:pin — Pin or Unpin a Memory (Always-Present Tier)
7
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.
8
+ You are managing the **always-present semantic tier**. Pinned memories are injected at every
9
+ session start regardless of recall score, and are decay-exempt — they never fade. This command
10
+ is a **toggle**: it pins by default, and unpins when asked.
9
11
 
10
12
  **User input:** $ARGUMENTS
11
13
 
12
- ## Behavior
14
+ ## Determine direction
15
+
16
+ - **Unpin** if the input contains `--off`, `unpin`, `remove`, or names a memory that is already
17
+ pinned (present in `~/.brain/pinned.json`).
18
+ - **Pin** otherwise.
19
+
20
+ When ambiguous (e.g. a bare query that matches a pinned memory), state which direction you're
21
+ taking and confirm before acting.
22
+
23
+ ---
24
+
25
+ ## Pin
13
26
 
14
27
  1. **Resolve the target memory:**
15
28
  - 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.
29
+ - Otherwise run `brain recall "$ARGUMENTS" --top 5`, show the top matches, and confirm which
30
+ one to pin.
17
31
 
18
32
  2. **Choose a scope** (default `global`):
19
33
  - `global` — loads in every project.
20
- - `project:<name>` — loads only while working in that project. Use for project-specific conventions.
34
+ - `project:<name>` — loads only while working in that project. Use for project-specific
35
+ conventions.
21
36
 
22
37
  3. **Pin it:**
23
38
  ```bash
24
39
  brain pin <id> [--scope global|project:<name>] [--priority N]
25
40
  ```
26
- `--priority` (default 0) breaks ties when the pin budget (`~/.brain/config.json` → `pin_budget_tokens`) is tight; higher wins.
41
+ `--priority` (default 0) breaks ties when the pin budget
42
+ (`~/.brain/config.json` → `pin_budget_tokens`) is tight; higher wins.
27
43
 
28
44
  4. Confirm:
29
45
  ```
30
46
  📌 Pinned <title> (<scope>) — will load every session.
31
47
  ```
32
48
 
33
- ## When to pin
49
+ ### When to pin
50
+
51
+ Durable conventions, preferences, and standing decisions the agent must **always** honor — e.g.
52
+ "always use tabs", "deploy via Cloudflare", "never touch the legacy billing module". Good
53
+ candidates are `preference`, `decision`, `insight`, and `relationship` memories with high
54
+ confidence and low time-sensitivity.
55
+
56
+ **Do not pin** episodic or time-sensitive content (a one-off incident, a temporary workaround).
57
+ Those belong in normal recall, where decay can retire them.
58
+
59
+ ---
34
60
 
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.
61
+ ## Unpin
36
62
 
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.
63
+ The memory will no longer load automatically at session start and returns to normal recall +
64
+ decay (an independent `stable` flag, if set, is left untouched).
65
+
66
+ 1. **Resolve the target:**
67
+ - If `$ARGUMENTS` is a memory ID (`mem_...`), use it directly.
68
+ - Otherwise inspect `~/.brain/pinned.json` (the list of current pins) or run
69
+ `brain recall "$ARGUMENTS" --top 5`, and confirm which pin to remove.
70
+
71
+ 2. **Unpin it:**
72
+ ```bash
73
+ brain unpin <id>
74
+ ```
75
+
76
+ 3. Confirm:
77
+ ```
78
+ 📌 Unpinned <title> — no longer auto-loaded.
79
+ ```
@@ -63,7 +63,7 @@ List the top 5-7 memories with titles, paths, types, and scores.
63
63
  Ask the user which ones they'd like to explore in detail.
64
64
 
65
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`.
66
+ Search `~/.brain/_archived/` via the archive index. If archived matches found, present them and offer to restore. Otherwise suggest different keywords, or browsing the memory tree directly under `~/.brain/`.
67
67
 
68
68
  ### 5. Reinforce Retrieved Memories
69
69
 
@@ -555,7 +555,7 @@ After all phases complete, present a comprehensive sleep report:
555
555
  <creative associations from Phase 8>
556
556
 
557
557
  ### Memories Due for Review
558
- <count> memories due within the next 7 days — run /brain:review
558
+ <count> memories due within the next 7 days — reinforced during this and future sleep cycles
559
559
 
560
560
  ### Recommendations
561
561
  - <actionable suggestions based on what sleep revealed>
@@ -10,7 +10,7 @@ You are displaying a comprehensive overview of the Brain Memory system's current
10
10
 
11
11
  ### 1. Read Brain State
12
12
 
13
- Read `~/.brain/index.json` to get the full memory inventory. If `~/.brain/` doesn't exist, inform the user and suggest running `/brain:init`.
13
+ Read `~/.brain/index.json` to get the full memory inventory. If `~/.brain/` doesn't exist, inform the user — it is created automatically by the installer, or on the first `/brain:memorize` or `/brain:sync`.
14
14
 
15
15
  Also read (if they exist):
16
16
  - `~/.brain/associations.json` — for association network stats
@@ -97,13 +97,13 @@ Calculate aggregate stats:
97
97
 
98
98
  ## Fading Memories (decayed strength < 0.3)
99
99
  ⚠ <count> memories below consolidation threshold
100
- Run /brain:consolidate to preserve them
100
+ Run /brain:sleep to consolidate and preserve them
101
101
 
102
102
  ## Review Queue
103
103
  📋 Due now: <count> memories
104
104
  📋 Due this week: <count> memories
105
105
  📋 Total in queue: <count> memories
106
- Run /brain:review to start a review session
106
+ Due memories are reinforced automatically during /brain:sleep
107
107
 
108
108
  ## Recent Memories (Last 7 days)
109
109
  + <title> (<path>) — <date>
@@ -124,13 +124,13 @@ Calculate aggregate stats:
124
124
  Analyze the brain's health and provide recommendations:
125
125
 
126
126
  - **"Healthy"** — Good distribution across categories, strong average strength
127
- - **"Needs consolidation"** — Many memories below threshold, suggest `/brain:consolidate`
127
+ - **"Needs consolidation"** — Many memories below threshold, suggest `/brain:sleep`
128
128
  - **"Imbalanced"** — One category dominates, suggest diversifying
129
129
  - **"Stale"** — No new memories in 14+ days, suggest `/brain:memorize`
130
130
  - **"Overloaded"** — More than 200 active memories, suggest pruning with `/brain:forget --prune`
131
131
  - **"Needs propagation"** — Recent memories exist alongside older related memories that haven't been updated. Suggest `/brain:sleep`
132
132
  - **"Needs sleep"** — Multiple flat clusters detected, OR many memories in moderate/weak tiers, OR no `_expertise.md` profiles exist despite having 10+ memories. Suggest `/brain:sleep`
133
133
  - **"Low confidence"** — More than 30% of memories have confidence < 0.5. Suggest reviewing and validating uncertain memories.
134
- - **"Review overdue"** — More than 10 memories are past their review date. Suggest `/brain:review`
134
+ - **"Review overdue"** — More than 10 memories are past their review date. Suggest `/brain:sleep` (its replay pass reinforces them)
135
135
  - **"Sync available"** — Git sync is not configured. Suggest `/brain:sync setup` for cross-device access.
136
136
  - **"Sync stale"** — Last push was more than 7 days ago. Suggest `/brain:sync push`.
@@ -14,6 +14,32 @@ You are managing synchronization for the Brain Memory system. This enables manua
14
14
  - Push operations execute immediately (no confirmation) — the user said "push"
15
15
  - Pull/import operations warn before overwriting local data
16
16
 
17
+ ## First run — auto-initialize if missing
18
+
19
+ The installer normally creates `~/.brain/` at install time. If `~/.brain/index.json` is
20
+ **missing** when any sync subcommand runs, create the standard structure first (no separate
21
+ init command is needed), then continue:
22
+
23
+ ```
24
+ ~/.brain/
25
+ ├── index.json # { version: 2, memory_count: 0, memories: {}, config: {…} }
26
+ ├── associations.json # { version: 1, edges: {} }
27
+ ├── contexts.json # { version: 1, sessions: [] }
28
+ ├── review-queue.json # { version: 1, items: [] }
29
+ ├── professional/_meta.json
30
+ ├── personal/_meta.json
31
+ ├── social/_meta.json
32
+ ├── family/_meta.json
33
+ ├── _consolidated/_meta.json
34
+ └── _archived/index.json # { version: 1, archived_count: 0, memories: {} }
35
+ ```
36
+
37
+ Each `_meta.json` is `{ "category": "<name>", "description": "<from defaults>", "created":
38
+ "<ISO>", "memory_count": 0, "subcategories": [] }`. The `index.json` `config` block carries the
39
+ standard decay/association defaults (max_depth 6, consolidation_threshold 0.3, association_config
40
+ with spreading-activation depth 2, etc.). After creating the structure, proceed with the
41
+ requested subcommand.
42
+
17
43
  ## Subcommands
18
44
 
19
45
  Parse the user's input to determine the subcommand:
@@ -172,7 +198,7 @@ Then return — do not attempt the push.
172
198
  ### Steps
173
199
 
174
200
  1. **Check prerequisites:**
175
- - Verify `~/.brain/` exists. If not, suggest `/brain:init` first.
201
+ - Verify `~/.brain/` exists. If not, auto-initialize it first (see "First run" above).
176
202
  - Verify `git` is available (`checkGitAvailable()` from `src/git-sync.js`).
177
203
  - Check if sync is already configured (`~/.brain/.sync/config.json`). If so, ask if they want to reconfigure.
178
204