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