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

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