brain-memory 0.1.0-beta.3 → 0.1.0-beta.30
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/CHANGELOG.md +319 -0
- package/README.md +379 -95
- package/SECURITY.md +61 -0
- package/assets/brand/README.md +28 -0
- package/assets/brand/icon-dark.svg +19 -0
- package/assets/brand/icon-light.svg +20 -0
- package/assets/brand/linkedin_cover.png +0 -0
- package/assets/brand/linkedin_cover_light.png +0 -0
- package/assets/brand/mark-dark.svg +19 -0
- package/assets/brand/mark-light.svg +20 -0
- package/assets/brand/png/icon-dark-1024.png +0 -0
- package/assets/brand/png/icon-dark-128.png +0 -0
- package/assets/brand/png/icon-dark-256.png +0 -0
- package/assets/brand/png/icon-dark-512.png +0 -0
- package/assets/brand/png/icon-dark-64.png +0 -0
- package/assets/brand/png/icon-light-1024.png +0 -0
- package/assets/brand/png/icon-light-128.png +0 -0
- package/assets/brand/png/icon-light-256.png +0 -0
- package/assets/brand/png/icon-light-512.png +0 -0
- package/assets/brand/png/icon-light-64.png +0 -0
- package/assets/brand/png/mark-dark-1024.png +0 -0
- package/assets/brand/png/mark-light-1024.png +0 -0
- package/assets/icon.png +0 -0
- package/assets/icon.svg +19 -0
- package/bin/brain.js +111 -0
- package/bin/cloud-sync.js +150 -0
- package/bin/forget.js +122 -0
- package/bin/install.js +229 -254
- package/bin/memorize.js +458 -0
- package/bin/pin.js +44 -0
- package/bin/recall.js +251 -0
- package/bin/reinforce.js +187 -0
- package/bin/session-start.js +298 -0
- package/bin/skill.js +67 -0
- package/bin/unpin.js +38 -0
- package/commands/brain/forget.md +245 -15
- package/commands/brain/memorize.md +76 -144
- package/commands/brain/pin.md +79 -0
- package/commands/brain/remember.md +48 -105
- package/commands/brain/skills.md +60 -0
- package/commands/brain/sleep.md +69 -28
- package/commands/brain/status.md +24 -10
- package/commands/brain/sync.md +386 -0
- package/package.json +22 -8
- package/prompts/antigravity.md +180 -0
- package/prompts/claude.md +124 -20
- package/prompts/openai.md +124 -20
- package/prompts/opencode.md +179 -0
- package/src/cloud-sync.js +534 -0
- package/src/crypto.js +130 -0
- package/src/export-import.js +200 -0
- package/src/git-sync.js +444 -0
- package/src/index-manager.js +219 -18
- package/src/installer.js +444 -0
- package/src/pinning.js +124 -0
- package/src/scorer.js +22 -9
- package/src/skills.js +208 -0
- package/src/tfidf.js +501 -0
- package/commands/brain/consolidate.md +0 -153
- package/commands/brain/explore.md +0 -79
- package/commands/brain/init.md +0 -157
- package/commands/brain/review.md +0 -130
- package/commands/brain/sunshine.md +0 -337
- package/hooks/session-end.md +0 -48
- package/hooks/session-start.md +0 -48
- package/prompts/gemini.md +0 -76
package/commands/brain/forget.md
CHANGED
|
@@ -1,23 +1,33 @@
|
|
|
1
|
-
|
|
1
|
+
---
|
|
2
|
+
description: Decay, archive, or forensically erase memories
|
|
3
|
+
argument-hint: "[target] [--deep]"
|
|
4
|
+
---
|
|
2
5
|
|
|
3
|
-
|
|
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
|
-
##
|
|
15
|
+
## Modes
|
|
8
16
|
|
|
9
|
-
|
|
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
|
-
|
|
24
|
+
---
|
|
12
25
|
|
|
13
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
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
|
|
68
|
-
- Add entry to
|
|
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
|
|
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
|
|
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
|
-
|
|
8
|
-
|
|
9
|
-
|
|
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
|
-
|
|
16
|
+
## Behavior
|
|
53
17
|
|
|
54
|
-
**
|
|
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
|
-
|
|
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
|
-
|
|
22
|
+
### 1. Determine Content
|
|
79
23
|
|
|
80
|
-
|
|
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
|
-
|
|
26
|
+
### 2. Classify Each Memory
|
|
103
27
|
|
|
104
|
-
|
|
28
|
+
For each memory, determine:
|
|
105
29
|
|
|
106
|
-
|
|
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
|
-
|
|
40
|
+
**Cognitive type:** `episodic` (event-specific), `semantic` (abstracted knowledge), `procedural` (skills/workflows)
|
|
109
41
|
|
|
110
|
-
|
|
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
|
-
|
|
44
|
+
**Salience** (0.0-1.0), **confidence** (0.0-1.0), **tags**, **related** memory IDs.
|
|
113
45
|
|
|
114
|
-
|
|
46
|
+
**strength_adjustment** (optional, -0.15 to +0.15): Tweak base strength based on significance.
|
|
115
47
|
|
|
116
|
-
|
|
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
|
-
###
|
|
53
|
+
### 3. Call brain memorize
|
|
120
54
|
|
|
121
|
-
|
|
55
|
+
Pipe the classified memories as JSON to the CLI in a **single bash call**:
|
|
122
56
|
|
|
123
|
-
```
|
|
57
|
+
```bash
|
|
58
|
+
brain memorize <<'EOF'
|
|
124
59
|
{
|
|
125
|
-
"
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
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
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
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
|
-
|
|
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
|
-
|
|
93
|
+
### 4. Report Results
|
|
160
94
|
|
|
161
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
+
```
|