brain-memory 0.1.0-beta.8 → 0.1.0
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 +555 -0
- package/README.md +411 -61
- package/SECURITY.md +100 -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/audit.js +93 -0
- package/bin/brain.js +132 -0
- package/bin/cloud-sync.js +150 -0
- package/bin/forget.js +163 -0
- package/bin/import.js +132 -0
- package/bin/install.js +63 -31
- package/bin/memorize.js +637 -0
- package/bin/pin.js +44 -0
- package/bin/recall.js +287 -0
- package/bin/reinforce.js +191 -0
- package/bin/restore.js +122 -0
- package/bin/session-start.js +337 -0
- package/bin/skill.js +67 -0
- package/bin/unpin.js +38 -0
- package/bin/verify.js +154 -0
- package/commands/brain/forget.md +243 -13
- package/commands/brain/import.md +125 -0
- package/commands/brain/memorize.md +95 -137
- package/commands/brain/pin.md +79 -0
- package/commands/brain/remember.md +53 -103
- package/commands/brain/skills.md +60 -0
- package/commands/brain/sleep.md +93 -6
- package/commands/brain/status.md +15 -6
- package/commands/brain/sync.md +181 -17
- package/commands/brain/verify.md +57 -0
- package/integrations/README.md +29 -0
- package/integrations/agentskills/brain-memory/SKILL.md +115 -0
- package/integrations/agentskills/brain-memory/scripts/session-start.mjs +34 -0
- package/package.json +20 -7
- package/prompts/antigravity.md +201 -0
- package/prompts/claude.md +107 -40
- package/prompts/copilot.md +203 -0
- package/prompts/kilo.md +202 -0
- package/prompts/openai.md +112 -45
- package/prompts/opencode.md +200 -0
- package/src/anomaly.js +260 -0
- package/src/audit.js +71 -0
- package/src/cloud-sync.js +672 -0
- package/src/content-lint.js +118 -0
- package/src/export-import.js +45 -7
- package/src/git-sync.js +170 -11
- package/src/harvest.js +562 -0
- package/src/index-manager.js +250 -11
- package/src/installer.js +250 -29
- package/src/pinning.js +146 -0
- package/src/provenance.js +79 -0
- package/src/quarantine.js +111 -0
- package/src/receipt.js +81 -0
- package/src/scorer.js +69 -12
- package/src/skills.js +208 -0
- package/src/tfidf.js +520 -0
- package/commands/brain/consolidate.md +0 -153
- package/commands/brain/explore.md +0 -79
- package/commands/brain/init.md +0 -149
- package/commands/brain/review.md +0 -130
- package/commands/brain/sunshine.md +0 -337
- package/prompts/gemini.md +0 -134
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
|
|
@@ -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.
|
|
@@ -0,0 +1,125 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: Cold-start your brain from transcripts your agents already wrote
|
|
3
|
+
argument-hint: "[--project P] [--since 30d] [--limit N]"
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# /brain:import — Cold-Start From Past Sessions
|
|
7
|
+
|
|
8
|
+
A new brain is empty. But your agents have been keeping transcripts for months — decisions, preferences, corrections, conventions. This command reads those transcripts and turns them into real memories.
|
|
9
|
+
|
|
10
|
+
**User input:** $ARGUMENTS
|
|
11
|
+
|
|
12
|
+
**Flags** (passed straight through to the CLI):
|
|
13
|
+
- `--source <id>` — Which history store to read (default `claude-code`; `--sources` lists what's detected)
|
|
14
|
+
- `--project <name>` — Only sessions from one project
|
|
15
|
+
- `--since <30d|6m|2026-01-01>` — Only sessions since then
|
|
16
|
+
- `--limit <N>` — Max sessions to consider (default 40)
|
|
17
|
+
- `--all` — Re-offer sessions already imported
|
|
18
|
+
|
|
19
|
+
## Your role
|
|
20
|
+
|
|
21
|
+
The CLI harvests. **You distill.** It hands you a digest of past sessions — titles, prompts, projects, files touched, dates. It does not decide what matters. That is the entire job here, and it is a judgement call the CLI deliberately does not make.
|
|
22
|
+
|
|
23
|
+
## Steps
|
|
24
|
+
|
|
25
|
+
### 1. Harvest
|
|
26
|
+
|
|
27
|
+
```bash
|
|
28
|
+
brain import $ARGUMENTS
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
Returns `{ source, scanned, budget, sessions[] }`. Each session has `session_id`, `title`, `project`, `git_branch`, `started`/`ended`, `turns`, `files_touched`, and a sample of `prompts`.
|
|
32
|
+
|
|
33
|
+
Read `scanned` honestly when you report — the fields mean different things:
|
|
34
|
+
- `skipped` — sessions that held nothing readable (too few real prompts)
|
|
35
|
+
- `filtered` — sessions excluded by the user's own `--project`/`--since` scoping, **not** discarded as junk
|
|
36
|
+
- `already_imported` — sessions a previous run already covered
|
|
37
|
+
- `remaining` — candidates that did not fit this pass; the number to quote when suggesting a re-run
|
|
38
|
+
|
|
39
|
+
If `scanned.files` is 0, tell the user no history was found and stop.
|
|
40
|
+
|
|
41
|
+
### 2. Check what the brain already knows
|
|
42
|
+
|
|
43
|
+
**Do not skip this on a brain that is already populated.** Import is most often run cold, but it is also run against a brain with hundreds of memories, and there the dominant failure is duplication — re-writing facts that are already stored, which inflates the brain and splits recall across near-identical entries.
|
|
44
|
+
|
|
45
|
+
Before distilling, recall against the themes you can see in the digest:
|
|
46
|
+
|
|
47
|
+
```bash
|
|
48
|
+
brain recall "<theme from the digest>" --project <project> --top 4
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
If a theme already scores well against an existing memory, drop it. Only write what is genuinely absent, or what materially *updates* something already stored — and if it's an update, say so in the content rather than filing a near-duplicate.
|
|
52
|
+
|
|
53
|
+
### 3. Read for durable facts, not events
|
|
54
|
+
|
|
55
|
+
You are looking at what someone *did*, and trying to recover what is still *true*. Those are different things.
|
|
56
|
+
|
|
57
|
+
**Worth remembering** — things that outlive the session:
|
|
58
|
+
- Stated preferences and conventions ("always use X", "I hate Y", "we commit straight to main")
|
|
59
|
+
- Architecture and tooling decisions, with the rationale if it's visible
|
|
60
|
+
- Recurring corrections — if the user pushed back on the same thing three times, that is a preference
|
|
61
|
+
- The shape of each project: what it is, its stack, where it deploys
|
|
62
|
+
- Constraints, deadlines, ongoing goals
|
|
63
|
+
|
|
64
|
+
**Not worth remembering** — things that were only true that afternoon:
|
|
65
|
+
- "fix the failing test", "what does this function do", "run the build"
|
|
66
|
+
- Anything already recorded in the repo, git history, or a CLAUDE.md
|
|
67
|
+
- One-off debugging that ended when the bug was fixed
|
|
68
|
+
- Anything superseded by later work in the digest
|
|
69
|
+
|
|
70
|
+
A good import from 40 sessions is roughly **5–20 memories**, not 40. One memory per session means you transcribed instead of distilled.
|
|
71
|
+
|
|
72
|
+
### 4. Prefer synthesis across sessions
|
|
73
|
+
|
|
74
|
+
The digest's real value is the pattern across sessions, which no single session contains. Six sessions in the same repo tell you what that project *is* — that is one strong `semantic` memory, worth more than six thin episodic ones.
|
|
75
|
+
|
|
76
|
+
Merge aggressively. Write the memory the user would want to find in six months.
|
|
77
|
+
|
|
78
|
+
### 5. Classify and write
|
|
79
|
+
|
|
80
|
+
Use the classification rules in `/brain:memorize` — same types, same cognitive types, same hierarchy under `professional/` etc.
|
|
81
|
+
|
|
82
|
+
Two rules specific to import:
|
|
83
|
+
|
|
84
|
+
**`origin` is `agent-inferred`.** You are inferring durable facts from a transcript, not being told them. Do not use `user` — the CLI's provenance gate will reject any attempt to pin or entrench from this path, which is the intended behavior. If a fact deserves entrenchment, the user can `/brain:pin` it deliberately afterwards.
|
|
85
|
+
|
|
86
|
+
**Confidence should reflect the evidence.** A convention stated once in passing is not a convention you are sure about. Something the user repeated across four sessions is. Set `confidence` accordingly rather than defaulting everything to 0.7.
|
|
87
|
+
|
|
88
|
+
Set `encoding_context.project` to the digest's `project` field, and `source` to `"import:<source>:<session_id>"` so the memory traces back to the transcript it came from.
|
|
89
|
+
|
|
90
|
+
Then write them:
|
|
91
|
+
|
|
92
|
+
```bash
|
|
93
|
+
brain memorize <<'EOF'
|
|
94
|
+
{ "memories": [ ... ] }
|
|
95
|
+
EOF
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
### 6. Mark what you used
|
|
99
|
+
|
|
100
|
+
```bash
|
|
101
|
+
brain import --mark <session_id> <session_id> ...
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
Mark **every session you read**, including the ones you decided held nothing worth keeping — otherwise the next run offers them again and you re-litigate the same judgement. This cursor is what makes import incremental.
|
|
105
|
+
|
|
106
|
+
Use the **full** `session_id` from the digest, never a shortened form you printed for display. The CLI rejects ids that match no real session and exits non-zero; check the `unknown` array if it does.
|
|
107
|
+
|
|
108
|
+
### 7. Report
|
|
109
|
+
|
|
110
|
+
```
|
|
111
|
+
◉ Imported <N> memories from <M> sessions across <P> projects
|
|
112
|
+
|
|
113
|
+
<type> <title>
|
|
114
|
+
...
|
|
115
|
+
|
|
116
|
+
<scanned.remaining> sessions remain — re-run to continue.
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
Quote `scanned.remaining` for the re-run line, and mention `scanned.filtered` only if the user passed a scoping flag.
|
|
120
|
+
|
|
121
|
+
## Notes
|
|
122
|
+
|
|
123
|
+
- **Safe to re-run.** The cursor means a second run offers only new sessions. `--all` overrides it.
|
|
124
|
+
- **Start scoped if the history is large.** `--project <name>` or `--since 30d` gives a better first pass than trying to swallow a year at once.
|
|
125
|
+
- **Nothing is written without you.** `brain import` only ever reads and prints; every memory goes through `brain memorize` and its provenance gate.
|