brain-memory 0.1.0-beta.20 → 0.1.0-beta.23
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +15 -17
- package/bin/install.js +9 -11
- package/bin/memorize.js +4 -1
- package/bin/recall.js +1 -1
- package/bin/skill.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 +3 -3
- 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/cloud-sync.js +16 -6
- package/src/export-import.js +19 -4
- package/src/installer.js +5 -1
- package/src/scorer.js +2 -0
- 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/commands/brain/init.md
DELETED
|
@@ -1,153 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
description: Initialize the brain memory structure
|
|
3
|
-
---
|
|
4
|
-
|
|
5
|
-
# /brain:init — Initialize Brain Memory Structure
|
|
6
|
-
|
|
7
|
-
You are initializing the Brain Memory system. This creates a `~/.brain/` directory that serves as a hierarchical, file-system-based memory store inspired by human cognition.
|
|
8
|
-
|
|
9
|
-
## Steps
|
|
10
|
-
|
|
11
|
-
### 1. Check for Existing Brain
|
|
12
|
-
|
|
13
|
-
Check if `~/.brain/` directory already exists in the user's home directory.
|
|
14
|
-
|
|
15
|
-
- If it exists, inform the user and ask if they want to reset or keep it.
|
|
16
|
-
- If not, proceed with creation.
|
|
17
|
-
|
|
18
|
-
### 2. Create Directory Structure
|
|
19
|
-
|
|
20
|
-
Create the following structure:
|
|
21
|
-
|
|
22
|
-
```
|
|
23
|
-
~/.brain/
|
|
24
|
-
├── index.json
|
|
25
|
-
├── associations.json
|
|
26
|
-
├── contexts.json
|
|
27
|
-
├── review-queue.json
|
|
28
|
-
├── professional/
|
|
29
|
-
│ └── _meta.json
|
|
30
|
-
├── personal/
|
|
31
|
-
│ └── _meta.json
|
|
32
|
-
├── social/
|
|
33
|
-
│ └── _meta.json
|
|
34
|
-
├── family/
|
|
35
|
-
│ └── _meta.json
|
|
36
|
-
├── _consolidated/
|
|
37
|
-
│ └── _meta.json
|
|
38
|
-
└── _archived/
|
|
39
|
-
└── index.json
|
|
40
|
-
```
|
|
41
|
-
|
|
42
|
-
### 3. Create index.json
|
|
43
|
-
|
|
44
|
-
```json
|
|
45
|
-
{
|
|
46
|
-
"version": 2,
|
|
47
|
-
"created": "<current ISO timestamp>",
|
|
48
|
-
"last_updated": "<current ISO timestamp>",
|
|
49
|
-
"memory_count": 0,
|
|
50
|
-
"memories": {},
|
|
51
|
-
"config": {
|
|
52
|
-
"max_depth": 6,
|
|
53
|
-
"consolidation_threshold": 0.3,
|
|
54
|
-
"decay_check_interval_days": 7,
|
|
55
|
-
"strength_boost_on_recall": 0.05,
|
|
56
|
-
"auto_consolidate": true,
|
|
57
|
-
"propagation_window_days": 7,
|
|
58
|
-
"association_config": {
|
|
59
|
-
"co_retrieval_boost": 0.10,
|
|
60
|
-
"link_decay_rate": 0.998,
|
|
61
|
-
"link_prune_threshold": 0.05,
|
|
62
|
-
"spreading_activation_depth": 2,
|
|
63
|
-
"spreading_activation_decay": 0.5
|
|
64
|
-
}
|
|
65
|
-
}
|
|
66
|
-
}
|
|
67
|
-
```
|
|
68
|
-
|
|
69
|
-
### 4. Create associations.json
|
|
70
|
-
|
|
71
|
-
The associative network stores weighted connections between memories — implementing spreading activation (like neurons activating linked memories) and Hebbian learning (memories that fire together wire together).
|
|
72
|
-
|
|
73
|
-
```json
|
|
74
|
-
{
|
|
75
|
-
"version": 1,
|
|
76
|
-
"edges": {}
|
|
77
|
-
}
|
|
78
|
-
```
|
|
79
|
-
|
|
80
|
-
### 5. Create contexts.json
|
|
81
|
-
|
|
82
|
-
Stores session-level context snapshots used for context-dependent recall — memories encoded in a similar context to the current one are scored higher.
|
|
83
|
-
|
|
84
|
-
```json
|
|
85
|
-
{
|
|
86
|
-
"version": 1,
|
|
87
|
-
"sessions": []
|
|
88
|
-
}
|
|
89
|
-
```
|
|
90
|
-
|
|
91
|
-
### 6. Create review-queue.json
|
|
92
|
-
|
|
93
|
-
Implements spaced repetition scheduling — surfaces memories for review at optimal intervals to maximize long-term retention.
|
|
94
|
-
|
|
95
|
-
```json
|
|
96
|
-
{
|
|
97
|
-
"version": 1,
|
|
98
|
-
"items": []
|
|
99
|
-
}
|
|
100
|
-
```
|
|
101
|
-
|
|
102
|
-
### 7. Create _archived/index.json
|
|
103
|
-
|
|
104
|
-
A searchable index of archived memories so they can be found and restored if needed.
|
|
105
|
-
|
|
106
|
-
```json
|
|
107
|
-
{
|
|
108
|
-
"version": 1,
|
|
109
|
-
"archived_count": 0,
|
|
110
|
-
"memories": {}
|
|
111
|
-
}
|
|
112
|
-
```
|
|
113
|
-
|
|
114
|
-
### 8. Create _meta.json for Each Top Category
|
|
115
|
-
|
|
116
|
-
For each top-level category (professional, personal, social, family, _consolidated), create a `_meta.json`:
|
|
117
|
-
|
|
118
|
-
```json
|
|
119
|
-
{
|
|
120
|
-
"category": "<category_name>",
|
|
121
|
-
"description": "<description from defaults>",
|
|
122
|
-
"created": "<current ISO timestamp>",
|
|
123
|
-
"memory_count": 0,
|
|
124
|
-
"subcategories": []
|
|
125
|
-
}
|
|
126
|
-
```
|
|
127
|
-
|
|
128
|
-
### 9. Ask User for Customization (Optional)
|
|
129
|
-
|
|
130
|
-
Ask the user:
|
|
131
|
-
- "Would you like to add any custom top-level categories beyond the defaults (professional, personal, social, family)?"
|
|
132
|
-
- "Do you have specific subcategories you'd like pre-created? (e.g., a company name under professional/companies/)"
|
|
133
|
-
|
|
134
|
-
If the user provides custom categories or subcategories, create them with appropriate `_meta.json` files.
|
|
135
|
-
|
|
136
|
-
### 10. Add .brain to .gitignore (Optional)
|
|
137
|
-
|
|
138
|
-
Ask the user if they want `~/.brain/` added to `.gitignore` (some users may want to track their memory in git, others may not).
|
|
139
|
-
|
|
140
|
-
### 11. Confirm
|
|
141
|
-
|
|
142
|
-
Print a summary of what was created, including the full tree structure. Inform the user of available commands:
|
|
143
|
-
|
|
144
|
-
- `/brain:memorize` — Store a new memory
|
|
145
|
-
- `/brain:remember` — Recall relevant memories
|
|
146
|
-
- `/brain:explore` — Browse the brain structure
|
|
147
|
-
- `/brain:consolidate` — Merge related memories
|
|
148
|
-
- `/brain:forget` — Decay or remove memories
|
|
149
|
-
- `/brain:sunshine` — Deep forensic erasure: trace and remove all references to a memory
|
|
150
|
-
- `/brain:sleep` — Overnight reorganization: restructure, consolidate, prune, and detect expertise areas
|
|
151
|
-
- `/brain:status` — View brain overview
|
|
152
|
-
- `/brain:review` — Spaced repetition review of memories due for reinforcement
|
|
153
|
-
|
package/commands/brain/review.md
DELETED
|
@@ -1,135 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
description: Spaced-repetition review session for memories due for reinforcement
|
|
3
|
-
argument-hint: "[scope]"
|
|
4
|
-
---
|
|
5
|
-
|
|
6
|
-
# /brain:review — Spaced Repetition Review
|
|
7
|
-
|
|
8
|
-
You are conducting a spaced repetition review session. This command surfaces memories that are due for review based on optimal spacing intervals, measures recall quality, and schedules the next review. Regular review sessions dramatically improve long-term retention.
|
|
9
|
-
|
|
10
|
-
**Scope:** $ARGUMENTS
|
|
11
|
-
|
|
12
|
-
## Overview
|
|
13
|
-
|
|
14
|
-
This implements a simplified SM-2 (SuperMemo 2) spaced repetition algorithm. Memories are scheduled for review at increasing intervals based on how well they are recalled. Well-recalled memories are reviewed less frequently; poorly-recalled memories are reviewed more often.
|
|
15
|
-
|
|
16
|
-
## Steps
|
|
17
|
-
|
|
18
|
-
### 1. Load Review Queue
|
|
19
|
-
|
|
20
|
-
Read `~/.brain/review-queue.json`. If it doesn't exist or is empty, generate it:
|
|
21
|
-
- Scan all memories in `index.json`
|
|
22
|
-
- For memories with `access_count > 0`, calculate initial review schedule
|
|
23
|
-
- For memories never recalled, add with `next_review` = now (immediate first review)
|
|
24
|
-
- If $ARGUMENTS specifies a category path, limit to that subtree
|
|
25
|
-
|
|
26
|
-
### 2. Find Due Memories
|
|
27
|
-
|
|
28
|
-
Filter the review queue for items where `next_review <= now`.
|
|
29
|
-
|
|
30
|
-
If no memories are due:
|
|
31
|
-
```
|
|
32
|
-
## No Memories Due for Review
|
|
33
|
-
|
|
34
|
-
Next review due: <soonest date>
|
|
35
|
-
Total in queue: <count>
|
|
36
|
-
|
|
37
|
-
Run /brain:status for a full overview.
|
|
38
|
-
```
|
|
39
|
-
|
|
40
|
-
### 3. Present Review Session
|
|
41
|
-
|
|
42
|
-
For each due memory (process up to 10 per session):
|
|
43
|
-
|
|
44
|
-
1. **Present the memory's title and path** (but NOT the full content initially):
|
|
45
|
-
```
|
|
46
|
-
### Review 1 of <N>
|
|
47
|
-
|
|
48
|
-
**Memory:** <title>
|
|
49
|
-
**Path:** ~/.brain/<path>
|
|
50
|
-
**Type:** <type> (<cognitive_type>) | **Last reviewed:** <date> | **Interval:** <days>d
|
|
51
|
-
**Confidence:** <confidence>
|
|
52
|
-
|
|
53
|
-
Can you recall what this memory is about? Try to remember before seeing the content.
|
|
54
|
-
```
|
|
55
|
-
|
|
56
|
-
2. **Reveal the full content** after the user responds (or on request):
|
|
57
|
-
```
|
|
58
|
-
<full memory content>
|
|
59
|
-
```
|
|
60
|
-
|
|
61
|
-
3. **Ask for recall quality** (1-5 scale):
|
|
62
|
-
- **5 — Perfect**: Recalled immediately and completely
|
|
63
|
-
- **4 — Good**: Recalled with minor effort
|
|
64
|
-
- **3 — Okay**: Recalled with significant effort
|
|
65
|
-
- **2 — Poor**: Could barely recall, needed heavy hints
|
|
66
|
-
- **1 — Failed**: Could not recall at all
|
|
67
|
-
|
|
68
|
-
### 4. Update Based on Recall Quality
|
|
69
|
-
|
|
70
|
-
For each reviewed memory, update using the SM-2 algorithm:
|
|
71
|
-
|
|
72
|
-
**Ease factor adjustment:**
|
|
73
|
-
```
|
|
74
|
-
new_ease = ease_factor + (0.1 - (5 - quality) * (0.08 + (5 - quality) * 0.02))
|
|
75
|
-
ease_factor = max(1.3, new_ease)
|
|
76
|
-
```
|
|
77
|
-
|
|
78
|
-
**Interval calculation:**
|
|
79
|
-
```
|
|
80
|
-
if quality >= 3: // Successful recall
|
|
81
|
-
if review_count == 0: interval = 1
|
|
82
|
-
elif review_count == 1: interval = 6
|
|
83
|
-
else: interval = previous_interval * ease_factor
|
|
84
|
-
else: // Failed recall
|
|
85
|
-
interval = 1 // Reset to 1 day
|
|
86
|
-
review_count = 0 // Reset review count
|
|
87
|
-
```
|
|
88
|
-
|
|
89
|
-
**Update memory:**
|
|
90
|
-
- `last_accessed` → current timestamp
|
|
91
|
-
- `access_count` → increment by 1
|
|
92
|
-
- `recall_history` → append current timestamp
|
|
93
|
-
- Apply spaced reinforcement to `strength` (same formula as /brain:remember)
|
|
94
|
-
- Improve `decay_rate` on successful recall (quality >= 3)
|
|
95
|
-
|
|
96
|
-
**Update review queue entry:**
|
|
97
|
-
```json
|
|
98
|
-
{
|
|
99
|
-
"memory_id": "<id>",
|
|
100
|
-
"next_review": "<now + interval days>",
|
|
101
|
-
"interval_days": <interval>,
|
|
102
|
-
"ease_factor": <ease_factor>,
|
|
103
|
-
"review_count": <review_count + 1>
|
|
104
|
-
}
|
|
105
|
-
```
|
|
106
|
-
|
|
107
|
-
### 5. Session Summary
|
|
108
|
-
|
|
109
|
-
After reviewing all due memories:
|
|
110
|
-
|
|
111
|
-
```
|
|
112
|
-
## Review Session Complete
|
|
113
|
-
|
|
114
|
-
Reviewed: <N> memories
|
|
115
|
-
Perfect (5): <count>
|
|
116
|
-
Good (4): <count>
|
|
117
|
-
Okay (3): <count>
|
|
118
|
-
Poor (2): <count>
|
|
119
|
-
Failed (1): <count>
|
|
120
|
-
|
|
121
|
-
Average recall quality: <avg>
|
|
122
|
-
Next review due: <soonest date>
|
|
123
|
-
Remaining in queue: <count>
|
|
124
|
-
|
|
125
|
-
Memories strengthened through review — keep it up!
|
|
126
|
-
```
|
|
127
|
-
|
|
128
|
-
## Rules
|
|
129
|
-
|
|
130
|
-
1. **Never skip the recall attempt** — always present the title first and let the user try to recall before revealing content
|
|
131
|
-
2. **Be encouraging** — spaced repetition is about building long-term retention, not testing
|
|
132
|
-
3. **Update everything** — update the memory file, index.json, review-queue.json, and associations.json (reinforce edges between co-reviewed memories)
|
|
133
|
-
4. **Respect scope** — if $ARGUMENTS specifies a category, only review memories in that subtree
|
|
134
|
-
5. **Session limit** — review at most 10 memories per session to avoid fatigue
|
|
135
|
-
6. **Failed recalls** — for quality 1-2, suggest the user re-read the memory and offer to update it if the information is outdated
|
|
@@ -1,342 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
description: Deep forensic erasure — trace and remove all references to a memory
|
|
3
|
-
argument-hint: "[target]"
|
|
4
|
-
---
|
|
5
|
-
|
|
6
|
-
# /brain:sunshine — Deep Forensic Memory Erasure
|
|
7
|
-
|
|
8
|
-
You are performing **deep forensic erasure** on a memory in the Brain Memory system. Like the procedure in *Eternal Sunshine of the Spotless Mind*, this command doesn't just delete a memory — it traces every ripple that memory left across the entire `~/.brain/` tree and surgically removes or repairs each one. When complete, it's as if the memory never existed.
|
|
9
|
-
|
|
10
|
-
Use this for erasing accidentally stored credentials, removing knowledge of a deprecated anti-pattern that leaked into other memories, or cleaning up after a fully reversed technical decision.
|
|
11
|
-
|
|
12
|
-
**Target:** $ARGUMENTS
|
|
13
|
-
|
|
14
|
-
## Flags
|
|
15
|
-
|
|
16
|
-
| Flag | Behavior |
|
|
17
|
-
|------|----------|
|
|
18
|
-
| *(default)* | Remove target + clean all direct references. Ask about derivatives individually |
|
|
19
|
-
| `--deep` | Also handle derivative memories and repair consolidated memories that lose sources |
|
|
20
|
-
| `--dry-run` | Show blast radius only — no changes are made |
|
|
21
|
-
| `--cascade` | With `--deep`, auto-remove derivative memories without asking |
|
|
22
|
-
| `--sensitive` | Overwrite file content with null bytes before deletion (for credentials, secrets) |
|
|
23
|
-
| `--no-trace` | Skip writing to `_erased.json` audit log |
|
|
24
|
-
| `--reason "<text>"` | Reason recorded in audit log entry |
|
|
25
|
-
|
|
26
|
-
## Steps
|
|
27
|
-
|
|
28
|
-
### 1. Parse Target and Flags
|
|
29
|
-
|
|
30
|
-
Extract:
|
|
31
|
-
- **Target identifier**: memory ID (e.g., `mem_20260215_a3f2c1`), title substring, or file path
|
|
32
|
-
- **Flags**: `--deep`, `--dry-run`, `--cascade`, `--sensitive`, `--no-trace`, `--reason`
|
|
33
|
-
|
|
34
|
-
If no target is provided, ask the user what memory they want to erase.
|
|
35
|
-
|
|
36
|
-
### 2. Locate Target Memory
|
|
37
|
-
|
|
38
|
-
Search for the target memory:
|
|
39
|
-
|
|
40
|
-
1. Read `~/.brain/index.json` and search `memories` by:
|
|
41
|
-
- Exact ID match
|
|
42
|
-
- Title substring match (case-insensitive)
|
|
43
|
-
- Path substring match
|
|
44
|
-
2. If not found in active memories, check `~/.brain/_archived/index.json`
|
|
45
|
-
3. If still not found, check `~/.brain/_erased.json` — if found there, report:
|
|
46
|
-
```
|
|
47
|
-
Memory was previously erased on <date>.
|
|
48
|
-
Reason: <reason or "unspecified">
|
|
49
|
-
No further action needed.
|
|
50
|
-
```
|
|
51
|
-
4. If not found anywhere, report and stop.
|
|
52
|
-
5. If multiple matches, present them and ask the user to pick one.
|
|
53
|
-
|
|
54
|
-
Once located, read the full memory file to capture its ID, title, path, tags, `related` array, `consolidated_from` array, and content.
|
|
55
|
-
|
|
56
|
-
### 3. Trace All References (Blast Radius Scan)
|
|
57
|
-
|
|
58
|
-
Scan the entire `~/.brain/` tree for every trace of the target memory. Track 8 reference types:
|
|
59
|
-
|
|
60
|
-
**3a. `related` arrays in other memories' frontmatter:**
|
|
61
|
-
Parse the YAML frontmatter of every `.md` memory file in `~/.brain/`. For each file whose `related` array contains the target ID, record:
|
|
62
|
-
- File path
|
|
63
|
-
- Current `related` array contents
|
|
64
|
-
|
|
65
|
-
**3b. Content body mentions:**
|
|
66
|
-
Search the Markdown body (below frontmatter) of all memory files for:
|
|
67
|
-
- The target memory ID (e.g., `mem_20260215_a3f2c1`)
|
|
68
|
-
- The target memory title (exact match)
|
|
69
|
-
Record each file path and the matching line.
|
|
70
|
-
|
|
71
|
-
**3c. `consolidated_from` arrays:**
|
|
72
|
-
Among all memory files with `type: consolidated`, check if their `consolidated_from` array contains the target ID. Record:
|
|
73
|
-
- File path
|
|
74
|
-
- Full `consolidated_from` array
|
|
75
|
-
- Number of other sources remaining
|
|
76
|
-
|
|
77
|
-
**3d. Association edges (`associations.json`):**
|
|
78
|
-
Read `~/.brain/associations.json`. Find all edges involving the target ID:
|
|
79
|
-
- Outgoing: `edges[target_id][*]`
|
|
80
|
-
- Incoming: `edges[*][target_id]`
|
|
81
|
-
Record each edge with its neighbor, weight, and origin.
|
|
82
|
-
|
|
83
|
-
**3e. Context sessions (`contexts.json`):**
|
|
84
|
-
Read `~/.brain/contexts.json`. Search all sessions for the target ID in:
|
|
85
|
-
- `memories_created` arrays
|
|
86
|
-
- `memories_recalled` arrays
|
|
87
|
-
Record each session timestamp and which array contained the reference.
|
|
88
|
-
|
|
89
|
-
**3f. Review queue (`review-queue.json`):**
|
|
90
|
-
Read `~/.brain/review-queue.json`. Check if any item has `memory_id` equal to the target ID.
|
|
91
|
-
|
|
92
|
-
**3g. Archive index (`_archived/index.json`):**
|
|
93
|
-
Read `~/.brain/_archived/index.json`. Check if the target ID exists as a key in `memories`.
|
|
94
|
-
|
|
95
|
-
**3h. Crystallization comments:**
|
|
96
|
-
Search all memory files for HTML comments matching the pattern:
|
|
97
|
-
```
|
|
98
|
-
<!-- Crystallized into <target_id> -->
|
|
99
|
-
```
|
|
100
|
-
This catches episodic memories that were crystallized into the target.
|
|
101
|
-
|
|
102
|
-
### 4. Identify Derivative Memories
|
|
103
|
-
|
|
104
|
-
Derivatives are memories that exist *because of* the target and may not make sense without it:
|
|
105
|
-
|
|
106
|
-
**4a. Sole crystallization derivatives:**
|
|
107
|
-
If the target is an episodic memory, search for semantic memories whose sole source is the target — identified by:
|
|
108
|
-
- Their `related` array contains the target ID
|
|
109
|
-
- A crystallization comment `<!-- Crystallized into <derivative_id> -->` exists in the target
|
|
110
|
-
- The derivative's creation was triggered by the target (check if the derivative has no other source memories in its `related` array besides the target)
|
|
111
|
-
|
|
112
|
-
**4b. Sole consolidation derivatives:**
|
|
113
|
-
If a consolidated memory's `consolidated_from` array contains the target ID and the target is its **only** remaining source (after removing the target, 0 sources remain), it's a sole derivative.
|
|
114
|
-
|
|
115
|
-
**4c. Chain following (with `--deep`):**
|
|
116
|
-
If `--deep` is set, recursively check each derivative for its own derivatives. Maintain a `visited` set to prevent infinite loops on circular references.
|
|
117
|
-
|
|
118
|
-
### 5. Visualize Blast Radius
|
|
119
|
-
|
|
120
|
-
Present the complete blast radius to the user:
|
|
121
|
-
|
|
122
|
-
```
|
|
123
|
-
## Blast Radius: "<title>" (<id>)
|
|
124
|
-
|
|
125
|
-
### TARGET (will be deleted)
|
|
126
|
-
<id> | <path> | <type> | strength: <strength> | salience: <salience>
|
|
127
|
-
|
|
128
|
-
### DIRECT REFERENCES (will be cleaned) — <N> found
|
|
129
|
-
[REL] <path.md> — related: [..., <target_id>, ...]
|
|
130
|
-
[BODY] <path.md> — "<matching line snippet>"
|
|
131
|
-
[CONS] <path.md> — consolidated_from: [..., <target_id>, ...] (<M> sources remain)
|
|
132
|
-
[EDGE] <target_id> <-> <other_id> (weight: <w>, origin: <origin>)
|
|
133
|
-
[CTX] Session <timestamp> — in <memories_created|memories_recalled>
|
|
134
|
-
[REV] Review queue entry (next_review: <date>)
|
|
135
|
-
[ARCH] Archive index entry
|
|
136
|
-
[CRYS] <path.md> — <!-- Crystallized into <target_id> -->
|
|
137
|
-
|
|
138
|
-
### DERIVATIVES (may cascade) — <N> found
|
|
139
|
-
<derivative_id> | <path> — sole <crystallization|consolidation> derivative of target
|
|
140
|
-
<explanation of why this is a derivative>
|
|
141
|
-
|
|
142
|
-
### CONSOLIDATED REPAIRS — <N> needed
|
|
143
|
-
<path.md> — consolidated_from shrinks from <before> to <after> sources
|
|
144
|
-
⚠️ <path.md> — will have only 1 source remaining (flagged for review)
|
|
145
|
-
|
|
146
|
-
### SUMMARY
|
|
147
|
-
Files to modify: <count>
|
|
148
|
-
References to clean: <count>
|
|
149
|
-
Derivatives found: <count>
|
|
150
|
-
Risk level: <low|medium|high>
|
|
151
|
-
```
|
|
152
|
-
|
|
153
|
-
**Risk level:**
|
|
154
|
-
- **Low**: <=3 references, no derivatives
|
|
155
|
-
- **Medium**: 4-10 references, or derivatives present
|
|
156
|
-
- **High**: >10 references, or target has salience >= 0.7
|
|
157
|
-
|
|
158
|
-
If `--dry-run` is set, stop here. Print "Dry run complete — no changes made." and exit.
|
|
159
|
-
|
|
160
|
-
### 6. Confirm with User
|
|
161
|
-
|
|
162
|
-
**Standard confirmation:**
|
|
163
|
-
```
|
|
164
|
-
Proceed with erasure? This will modify <N> files and remove <M> references.
|
|
165
|
-
[yes / no / select specific items]
|
|
166
|
-
```
|
|
167
|
-
|
|
168
|
-
**High-salience confirmation** (salience >= 0.7):
|
|
169
|
-
```
|
|
170
|
-
⚠️ HIGH-SALIENCE MEMORY (salience: <value>)
|
|
171
|
-
This memory was marked as significant. To confirm erasure, type the memory ID:
|
|
172
|
-
> <user must type the ID>
|
|
173
|
-
```
|
|
174
|
-
|
|
175
|
-
**Derivative handling** (without `--cascade`):
|
|
176
|
-
For each derivative found, ask individually:
|
|
177
|
-
```
|
|
178
|
-
Derivative: "<derivative_title>" (<derivative_id>)
|
|
179
|
-
This memory was <crystallized from|solely consolidated from> the target.
|
|
180
|
-
[delete] Remove this derivative too
|
|
181
|
-
[keep] Keep it (remove only the reference to target)
|
|
182
|
-
[skip] Skip — decide later
|
|
183
|
-
```
|
|
184
|
-
|
|
185
|
-
With `--cascade`, all derivatives are automatically included in the erasure.
|
|
186
|
-
|
|
187
|
-
### 7. Execute Erasure
|
|
188
|
-
|
|
189
|
-
Execute in this exact order (dependencies matter):
|
|
190
|
-
|
|
191
|
-
**7a. Handle derivatives first** (if `--deep` and user approved):
|
|
192
|
-
For each derivative marked for deletion, recursively apply steps 7b-7g. Process deepest derivatives first (reverse topological order) to avoid dangling references.
|
|
193
|
-
|
|
194
|
-
**7b. Repair consolidated memories** (if `--deep`):
|
|
195
|
-
For each consolidated memory that lists the target in `consolidated_from`:
|
|
196
|
-
- Remove the target ID from the `consolidated_from` array
|
|
197
|
-
- Remove the target ID from the `related` array
|
|
198
|
-
- If 0 sources remain: this was caught as a derivative in Step 4
|
|
199
|
-
- If 1 source remains: add a warning comment to the file:
|
|
200
|
-
```
|
|
201
|
-
<!-- WARNING: This consolidated memory now has only 1 source after erasure of <target_id>. Consider reviewing. -->
|
|
202
|
-
```
|
|
203
|
-
- Update the corresponding `index.json` entry
|
|
204
|
-
|
|
205
|
-
**7c. Clean all direct references:**
|
|
206
|
-
|
|
207
|
-
1. **`related` arrays**: For each memory file containing the target ID in its `related` array, parse the frontmatter, remove the target ID from the array, and write the file back. Leave empty arrays as `related: []`.
|
|
208
|
-
|
|
209
|
-
2. **Content body mentions**: For each memory file with body mentions of the target ID or title:
|
|
210
|
-
- Remove lines that are solely a reference to the target (e.g., `Related to the X decision (mem_20260215_a3f2c1)`)
|
|
211
|
-
- In mixed-content lines, remove just the target reference (ID or parenthetical mention)
|
|
212
|
-
- If a `## Connections` section becomes empty, remove the section header too
|
|
213
|
-
|
|
214
|
-
3. **Association edges**: Remove all edges involving the target from `associations.json`. Use the `removeEdgesForMemory()` utility from `index-manager.js`. Write the updated file.
|
|
215
|
-
|
|
216
|
-
4. **Context sessions**: In `contexts.json`, for each session containing the target ID:
|
|
217
|
-
- Remove the target ID from `memories_created` and `memories_recalled` arrays
|
|
218
|
-
- Do NOT delete the session itself (other memories may reference it)
|
|
219
|
-
|
|
220
|
-
5. **Review queue**: Remove the target's entry from `review-queue.json`. Use the `removeFromReviewQueue()` utility from `index-manager.js`. Write the updated file.
|
|
221
|
-
|
|
222
|
-
6. **Archive index**: If the target exists in `_archived/index.json`, remove its entry and decrement `archived_count`. Write the updated file.
|
|
223
|
-
|
|
224
|
-
7. **Crystallization comments**: For each memory file containing `<!-- Crystallized into <target_id> -->`, remove the comment line.
|
|
225
|
-
|
|
226
|
-
**7d. Remove from `index.json`:**
|
|
227
|
-
Remove the target memory from `index.json` using `removeMemory()` from `index-manager.js`. Write the updated file.
|
|
228
|
-
|
|
229
|
-
**7e. Update `_meta.json` files:**
|
|
230
|
-
For each directory in the target's path, read the `_meta.json` and decrement `memory_count`. Write the updated file.
|
|
231
|
-
|
|
232
|
-
**7f. Delete target file:**
|
|
233
|
-
- If `--sensitive`: first overwrite the file content with null bytes (same byte length as original), then delete
|
|
234
|
-
- Otherwise: delete the file directly
|
|
235
|
-
- Clean up empty parent directories (but never delete top-level category directories)
|
|
236
|
-
|
|
237
|
-
**7g. Remove archived copy:**
|
|
238
|
-
If an archived copy exists at `~/.brain/_archived/<original-path>`, delete it.
|
|
239
|
-
- If `--sensitive`: overwrite with null bytes before deletion
|
|
240
|
-
- Clean up empty directories in `_archived/`
|
|
241
|
-
|
|
242
|
-
### 8. Write Audit Log
|
|
243
|
-
|
|
244
|
-
Unless `--no-trace` is set, write or append to `~/.brain/_erased.json`:
|
|
245
|
-
|
|
246
|
-
```json
|
|
247
|
-
{
|
|
248
|
-
"version": 1,
|
|
249
|
-
"erasures": [
|
|
250
|
-
{
|
|
251
|
-
"erased_id": "<memory_id>",
|
|
252
|
-
"erased_date": "<ISO timestamp>",
|
|
253
|
-
"reason": "<user-provided reason or 'unspecified'>",
|
|
254
|
-
"references_cleaned": <count>,
|
|
255
|
-
"derivatives_removed": <count>,
|
|
256
|
-
"consolidated_repaired": <count>,
|
|
257
|
-
"flags_used": ["<flags that were active>"]
|
|
258
|
-
}
|
|
259
|
-
]
|
|
260
|
-
}
|
|
261
|
-
```
|
|
262
|
-
|
|
263
|
-
If the file already exists, read it, append the new entry to the `erasures` array, and write back.
|
|
264
|
-
|
|
265
|
-
**IMPORTANT**: The audit log intentionally omits the memory title, content, tags, path, or any identifying information. It proves an erasure happened for audit purposes without preserving what was erased.
|
|
266
|
-
|
|
267
|
-
### 9. Post-Erasure Integrity Check
|
|
268
|
-
|
|
269
|
-
After erasure, perform a quick integrity scan:
|
|
270
|
-
|
|
271
|
-
1. **Dangling references**: Grep all memory files for the erased ID. If any remain, report them as warnings.
|
|
272
|
-
2. **Orphaned associations**: Check `associations.json` for any edges pointing to the erased ID.
|
|
273
|
-
3. **Index consistency**: Verify `memory_count` in `index.json` matches the actual number of entries in `memories`.
|
|
274
|
-
4. **Empty directories**: Report any empty directories that may need cleanup.
|
|
275
|
-
|
|
276
|
-
If any issues are found:
|
|
277
|
-
```
|
|
278
|
-
⚠️ Post-erasure integrity issues:
|
|
279
|
-
- <description of issue>
|
|
280
|
-
|
|
281
|
-
These can be fixed by running /brain:sleep.
|
|
282
|
-
```
|
|
283
|
-
|
|
284
|
-
### 10. Confirm
|
|
285
|
-
|
|
286
|
-
Print a summary:
|
|
287
|
-
|
|
288
|
-
```
|
|
289
|
-
## Erasure Complete: "<title>"
|
|
290
|
-
|
|
291
|
-
Memory deleted: <id>
|
|
292
|
-
References cleaned: <count> across <file_count> files
|
|
293
|
-
Derivatives removed: <count>
|
|
294
|
-
Consolidated memories repaired: <count>
|
|
295
|
-
Audit log: <written to _erased.json | skipped (--no-trace)>
|
|
296
|
-
|
|
297
|
-
Brain stats: <total_memories> memories, average strength <avg>
|
|
298
|
-
|
|
299
|
-
The memory has been fully erased. All traces have been removed
|
|
300
|
-
from the associative network, context logs, review queue, and
|
|
301
|
-
cross-references in other memories.
|
|
302
|
-
```
|
|
303
|
-
|
|
304
|
-
## Edge Cases
|
|
305
|
-
|
|
306
|
-
1. **Memory already archived**: Still perform the full blast radius scan. The target may have references in active memories, associations, contexts, and the review queue even though it's in the archive. Clean all references, then remove the archived copy.
|
|
307
|
-
|
|
308
|
-
2. **Memory not found**: Check `_erased.json` first. If found there, report the previous erasure date and reason. If not found anywhere, report clearly and suggest checking the ID/title spelling.
|
|
309
|
-
|
|
310
|
-
3. **Circular references**: When following derivative chains with `--deep`, maintain a `visited` set. If a memory has already been visited, skip it and note the cycle.
|
|
311
|
-
|
|
312
|
-
4. **High-salience memories (salience >= 0.7)**: Require double confirmation — the user must type the memory ID to proceed. This prevents accidental erasure of important memories.
|
|
313
|
-
|
|
314
|
-
5. **Consolidated memory loses ALL sources**: This is caught as a sole consolidation derivative in Step 4. With `--deep`, it's removed. Without `--deep`, warn prominently:
|
|
315
|
-
```
|
|
316
|
-
⚠️ CRITICAL: "<consolidated_title>" will have ZERO sources after erasure.
|
|
317
|
-
This consolidated memory only existed because of the target.
|
|
318
|
-
Recommend: use --deep to handle this, or manually review.
|
|
319
|
-
```
|
|
320
|
-
|
|
321
|
-
6. **Consolidated memory left with 1 source**: Add a warning comment to the file and flag in the output. The memory is still valid but may benefit from review.
|
|
322
|
-
|
|
323
|
-
7. **Empty `related` arrays after cleanup**: Leave as `related: []`. Do not remove the field entirely — it maintains schema consistency.
|
|
324
|
-
|
|
325
|
-
8. **Memory referenced by memories outside `~/.brain/`**: This command only operates within `~/.brain/`. If external files (e.g., `CLAUDE.md`, project docs) reference the memory, note this limitation in the summary.
|
|
326
|
-
|
|
327
|
-
9. **Multiple memories matching a title substring**: Present all matches with their IDs, paths, and strengths. Ask the user to select the specific memory to erase.
|
|
328
|
-
|
|
329
|
-
10. **Target is itself a consolidated memory**: Its `consolidated_from` sources (if archived) are NOT affected — they remain in the archive. Only forward references are cleaned.
|
|
330
|
-
|
|
331
|
-
## Important Rules
|
|
332
|
-
|
|
333
|
-
1. **Always confirm before executing**. Never erase without explicit user approval. High-salience memories require typing the ID.
|
|
334
|
-
2. **Order matters**. Follow the execution order in Step 7 exactly — derivatives first, then repairs, then references, then index, then file deletion.
|
|
335
|
-
3. **Audit by default**. Always write to `_erased.json` unless `--no-trace` is explicitly set. The audit log contains no identifying information about the erased memory.
|
|
336
|
-
4. **No collateral damage**. Only remove references to the specific target. Never modify content unrelated to the target memory.
|
|
337
|
-
5. **Preserve other memories' integrity**. When editing other memories' frontmatter or content, preserve all other fields and content exactly.
|
|
338
|
-
6. **Sensitive data handling**. With `--sensitive`, overwrite file content before deletion to prevent filesystem-level recovery.
|
|
339
|
-
7. **Integrity check is mandatory**. Always run the post-erasure integrity check, even if no issues are expected.
|
|
340
|
-
8. **Recursive safety**. When processing derivatives with `--deep --cascade`, always maintain a `visited` set to prevent infinite loops.
|
|
341
|
-
9. **Never delete top-level category directories**. Even if they become empty after erasure, preserve `professional/`, `personal/`, `social/`, `family/`, `_consolidated/`, and `_archived/`.
|
|
342
|
-
10. **Context sessions are preserved**. Remove memory IDs from session arrays, but never delete the session entry itself.
|
package/commands/brain/unpin.md
DELETED
|
@@ -1,26 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
description: Remove a memory from the always-present tier
|
|
3
|
-
argument-hint: "[id|query]"
|
|
4
|
-
---
|
|
5
|
-
|
|
6
|
-
# /brain:unpin — Remove a Memory from the Always-Present Tier
|
|
7
|
-
|
|
8
|
-
You are unpinning a memory. It will no longer load automatically at session start and returns to normal recall + decay (an independent `stable` flag, if set, is left untouched).
|
|
9
|
-
|
|
10
|
-
**User input:** $ARGUMENTS
|
|
11
|
-
|
|
12
|
-
## Behavior
|
|
13
|
-
|
|
14
|
-
1. **Resolve the target:**
|
|
15
|
-
- If `$ARGUMENTS` is a memory ID (`mem_...`), use it directly.
|
|
16
|
-
- Otherwise inspect `~/.brain/pinned.json` (the list of current pins) or run `brain recall "$ARGUMENTS" --top 5`, and confirm which pin to remove.
|
|
17
|
-
|
|
18
|
-
2. **Unpin it:**
|
|
19
|
-
```bash
|
|
20
|
-
brain unpin <id>
|
|
21
|
-
```
|
|
22
|
-
|
|
23
|
-
3. Confirm:
|
|
24
|
-
```
|
|
25
|
-
📌 Unpinned <title> — no longer auto-loaded.
|
|
26
|
-
```
|