brain-memory 0.1.0-beta.1 → 0.1.0-beta.11
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 +158 -54
- package/assets/icon.png +0 -0
- package/bin/install.js +200 -230
- package/bin/recall.js +211 -0
- package/bin/reinforce.js +179 -0
- package/commands/brain/consolidate.md +2 -2
- package/commands/brain/explore.md +2 -2
- package/commands/brain/forget.md +2 -2
- package/commands/brain/init.md +4 -12
- package/commands/brain/memorize.md +64 -21
- package/commands/brain/remember.md +43 -105
- package/commands/brain/review.md +2 -2
- package/commands/brain/sleep.md +4 -23
- package/commands/brain/status.md +15 -5
- package/commands/brain/sunshine.md +13 -13
- package/commands/brain/sync.md +222 -0
- package/package.json +16 -5
- package/prompts/claude.md +122 -12
- package/prompts/gemini.md +122 -12
- package/prompts/openai.md +120 -10
- package/src/crypto.js +130 -0
- package/src/export-import.js +185 -0
- package/src/git-sync.js +444 -0
- package/src/index-manager.js +94 -18
- package/src/installer.js +361 -0
- package/src/tfidf.js +408 -0
- package/hooks/session-end.md +0 -48
- package/hooks/session-start.md +0 -48
|
@@ -1,22 +1,14 @@
|
|
|
1
1
|
# /brain:remember — Recall Relevant Memories
|
|
2
2
|
|
|
3
|
-
You are recalling memories from the Brain Memory system. This command
|
|
3
|
+
You are recalling memories from the Brain Memory system. This command uses the **deterministic recall engine** (`brain-recall`) to score and rank memories, then presents the results.
|
|
4
4
|
|
|
5
5
|
**User query:** $ARGUMENTS
|
|
6
6
|
|
|
7
7
|
## Steps
|
|
8
8
|
|
|
9
|
-
### 1.
|
|
9
|
+
### 1. Determine Context
|
|
10
10
|
|
|
11
|
-
|
|
12
|
-
- **Keywords**: Extract key terms and concepts
|
|
13
|
-
- **Category hints**: Does the query suggest a specific life domain? (professional, personal, social, family)
|
|
14
|
-
- **Time hints**: Is the user asking about recent or old memories?
|
|
15
|
-
- **Intent**: Are they looking for a specific memory, a pattern, or general knowledge?
|
|
16
|
-
|
|
17
|
-
### 2. Capture Recall Context
|
|
18
|
-
|
|
19
|
-
Determine the current session context for context-dependent matching:
|
|
11
|
+
Identify the current session context:
|
|
20
12
|
|
|
21
13
|
```yaml
|
|
22
14
|
recall_context:
|
|
@@ -25,51 +17,30 @@ recall_context:
|
|
|
25
17
|
task_type: <debugging|implementing|designing|reviewing|discussing|learning>
|
|
26
18
|
```
|
|
27
19
|
|
|
28
|
-
###
|
|
29
|
-
|
|
30
|
-
Read `.brain/index.json` to get the full memory inventory.
|
|
31
|
-
|
|
32
|
-
**Search strategy (in order):**
|
|
33
|
-
|
|
34
|
-
1. **Category-first**: If the query clearly maps to a category, traverse that subtree first
|
|
35
|
-
2. **Tag matching**: Match query keywords against memory tags
|
|
36
|
-
3. **Title matching**: Match against memory titles in the index
|
|
37
|
-
4. **Full-text search**: If index matching yields few results, read memory files in relevant categories and search content
|
|
38
|
-
|
|
39
|
-
Collect all candidate memories.
|
|
40
|
-
|
|
41
|
-
### 3.5. Spreading Activation
|
|
20
|
+
### 2. Run the Recall Engine
|
|
42
21
|
|
|
43
|
-
|
|
44
|
-
1. Traverse the association graph up to 2 hops
|
|
45
|
-
2. For each reached memory: `spread_bonus = parent_score * link_weight * 0.5^hop`
|
|
46
|
-
3. Memories NOT in the initial candidates but reached via spreading activation with bonus >= 0.05 are **added** to the candidate pool (they were "reminded" by association)
|
|
22
|
+
Execute the recall CLI to get deterministically scored results:
|
|
47
23
|
|
|
48
|
-
|
|
24
|
+
```bash
|
|
25
|
+
node <brain-memory-install-path>/bin/recall.js "$ARGUMENTS" \
|
|
26
|
+
--project "<project>" \
|
|
27
|
+
--task "<task_type>" \
|
|
28
|
+
--topics "<topic1,topic2>" \
|
|
29
|
+
--top 10
|
|
30
|
+
```
|
|
49
31
|
|
|
50
|
-
|
|
32
|
+
If the brain-memory package is installed globally, use:
|
|
33
|
+
```bash
|
|
34
|
+
brain-recall "$ARGUMENTS" --project "<project>" --task "<task_type>" --top 10
|
|
35
|
+
```
|
|
51
36
|
|
|
52
|
-
|
|
37
|
+
The engine computes **TF-IDF relevance** (cosine similarity between query and memory content), then combines it with decayed strength, recency, spreading activation, context match, and salience using the v4 formula. All scoring is deterministic — same query always produces the same ranking.
|
|
53
38
|
|
|
54
|
-
|
|
55
|
-
days_elapsed = (now - last_accessed) / (1000 * 60 * 60 * 24)
|
|
56
|
-
decayed_strength = strength * (decay_rate ^ days_elapsed)
|
|
57
|
-
recency_bonus = max(0, 1 - (days_elapsed / 365))
|
|
58
|
-
spreading_bonus = <computed in step 3.5, 0 if not reached via associations>
|
|
59
|
-
context_match = 0.3*(project matches) + 0.4*jaccard(topics) + 0.3*(task_type matches)
|
|
60
|
-
salience_bonus = salience (from memory frontmatter, default 0.5)
|
|
61
|
-
|
|
62
|
-
effective_score = 0.38 * relevance
|
|
63
|
-
+ 0.18 * decayed_strength
|
|
64
|
-
+ 0.08 * recency_bonus
|
|
65
|
-
+ 0.14 * spreading_bonus
|
|
66
|
-
+ 0.14 * context_match
|
|
67
|
-
+ 0.08 * salience_bonus
|
|
68
|
-
```
|
|
39
|
+
### 3. Read Top Memories
|
|
69
40
|
|
|
70
|
-
|
|
41
|
+
Parse the JSON output. For the top results (score > 0.3), read the actual memory files from `~/.brain/<path>` to get full content.
|
|
71
42
|
|
|
72
|
-
###
|
|
43
|
+
### 4. Decide Response Strategy
|
|
73
44
|
|
|
74
45
|
Based on the scored results:
|
|
75
46
|
|
|
@@ -81,68 +52,49 @@ Read all candidate memory files and synthesize a **consolidated response** that:
|
|
|
81
52
|
- Weaves together insights from all relevant memories
|
|
82
53
|
- Notes which memories contributed (by ID and title)
|
|
83
54
|
- Highlights patterns or evolution across memories
|
|
84
|
-
- Presents the most current/relevant information prominently
|
|
85
55
|
|
|
86
56
|
**Case C — Many weak matches (>5 candidates, all scores < 0.4):**
|
|
87
|
-
List the top 5-7 memories with titles, paths, types, and
|
|
57
|
+
List the top 5-7 memories with titles, paths, types, and scores.
|
|
88
58
|
Ask the user which ones they'd like to explore in detail.
|
|
89
59
|
|
|
90
|
-
**Case D — No matches
|
|
91
|
-
Search
|
|
92
|
-
- Present them with a note that they're archived
|
|
93
|
-
- Offer to restore them (move back to active brain with strength +0.10)
|
|
94
|
-
|
|
95
|
-
If still no matches, inform the user and suggest:
|
|
96
|
-
- Trying different keywords
|
|
97
|
-
- Exploring the brain structure with `/brain:explore`
|
|
98
|
-
- Storing new memories with `/brain:memorize`
|
|
60
|
+
**Case D — No matches:**
|
|
61
|
+
Search `~/.brain/_archived/` via the archive index. If archived matches found, present them and offer to restore. Otherwise suggest different keywords or `/brain:explore`.
|
|
99
62
|
|
|
100
|
-
###
|
|
63
|
+
### 5. Reinforce Retrieved Memories
|
|
101
64
|
|
|
102
|
-
|
|
65
|
+
After presenting results, run the reinforcement engine for all memories shown to the user:
|
|
103
66
|
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
daysSinceLastAccess = (now - last_accessed) / (1000 * 60 * 60 * 24)
|
|
107
|
-
recallCount = access_count (or len(recall_history))
|
|
108
|
-
spacingMultiplier = min(3.0, 1.0 + log2(1 + daysSinceLastAccess))
|
|
109
|
-
diminishingFactor = 1.0 / (1.0 + 0.1 * recallCount)
|
|
110
|
-
boost = 0.05 * spacingMultiplier * diminishingFactor
|
|
67
|
+
```bash
|
|
68
|
+
node <brain-memory-install-path>/bin/reinforce.js <mem_id1> <mem_id2> ...
|
|
111
69
|
```
|
|
112
70
|
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
- `access_count` → increment by 1
|
|
118
|
-
- `recall_history` → append current timestamp
|
|
119
|
-
- `strength` → min(1.0, strength + boost)
|
|
120
|
-
- `decay_rate` → improved via: `decay_rate + 0.10 * (0.999 - decay_rate)` (memories become progressively more forgetting-resistant)
|
|
121
|
-
|
|
122
|
-
### 7. Hebbian Co-Retrieval Learning
|
|
123
|
-
|
|
124
|
-
When multiple memories are returned together (Case B), strengthen their mutual association edges in `associations.json`:
|
|
125
|
-
- For each pair of retrieved memories, call `reinforceEdge()` with origin `co_retrieval`
|
|
126
|
-
- This implements "neurons that fire together wire together" — memories recalled in the same context become more tightly linked over time
|
|
71
|
+
Or if globally installed:
|
|
72
|
+
```bash
|
|
73
|
+
brain-reinforce <mem_id1> <mem_id2> ...
|
|
74
|
+
```
|
|
127
75
|
|
|
128
|
-
|
|
76
|
+
This deterministically applies:
|
|
77
|
+
- **Spaced reinforcement** — strength boost based on time since last access
|
|
78
|
+
- **Decay rate improvement** — memories become more forgetting-resistant
|
|
79
|
+
- **Hebbian co-retrieval** — strengthens association edges between all returned memories
|
|
129
80
|
|
|
130
|
-
###
|
|
81
|
+
### 6. Present Results
|
|
131
82
|
|
|
132
83
|
Format the output clearly. Include confidence indicators for low-confidence memories.
|
|
133
84
|
|
|
134
85
|
```
|
|
135
86
|
## Recalled Memory: <Title>
|
|
136
87
|
|
|
137
|
-
**Path:**
|
|
88
|
+
**Path:** ~/.brain/<path>
|
|
138
89
|
**Strength:** <decayed_strength> (original: <base_strength>)
|
|
90
|
+
**Score:** <score> (relevance: <relevance>, context: <context_match>)
|
|
139
91
|
**Type:** <type> (<cognitive_type>) | **Created:** <date> | **Recalled:** <access_count> times
|
|
140
|
-
**Confidence:** <confidence> <show
|
|
92
|
+
**Confidence:** <confidence> <show warning if < 0.5>
|
|
141
93
|
|
|
142
94
|
<memory content>
|
|
143
95
|
|
|
144
96
|
---
|
|
145
|
-
*Memory reinforced — strength updated
|
|
97
|
+
*Memory reinforced — strength updated, decay improved*
|
|
146
98
|
```
|
|
147
99
|
|
|
148
100
|
For consolidated responses (Case B):
|
|
@@ -153,24 +105,10 @@ For consolidated responses (Case B):
|
|
|
153
105
|
<consolidated narrative>
|
|
154
106
|
|
|
155
107
|
### Contributing Memories
|
|
156
|
-
1. **<title>** (
|
|
157
|
-
2. **<title>** (
|
|
108
|
+
1. **<title>** (~/.brain/<path>) — score: <score>
|
|
109
|
+
2. **<title>** (~/.brain/<path>) — score: <score>
|
|
158
110
|
...
|
|
159
111
|
|
|
160
112
|
---
|
|
161
|
-
*<N> memories reinforced,
|
|
162
|
-
```
|
|
163
|
-
|
|
164
|
-
For archived matches (Case D fallback):
|
|
165
|
-
|
|
166
|
-
```
|
|
167
|
-
## Found in Archive: <Title>
|
|
168
|
-
|
|
169
|
-
**Path:** .brain/_archived/<path>
|
|
170
|
-
**Original Strength:** <strength> | **Archived:** <date>
|
|
171
|
-
|
|
172
|
-
<memory content summary>
|
|
173
|
-
|
|
174
|
-
---
|
|
175
|
-
*Would you like to restore this memory to active brain?*
|
|
113
|
+
*<N> memories reinforced, association links strengthened*
|
|
176
114
|
```
|
package/commands/brain/review.md
CHANGED
|
@@ -12,7 +12,7 @@ This implements a simplified SM-2 (SuperMemo 2) spaced repetition algorithm. Mem
|
|
|
12
12
|
|
|
13
13
|
### 1. Load Review Queue
|
|
14
14
|
|
|
15
|
-
Read
|
|
15
|
+
Read `~/.brain/review-queue.json`. If it doesn't exist or is empty, generate it:
|
|
16
16
|
- Scan all memories in `index.json`
|
|
17
17
|
- For memories with `access_count > 0`, calculate initial review schedule
|
|
18
18
|
- For memories never recalled, add with `next_review` = now (immediate first review)
|
|
@@ -41,7 +41,7 @@ For each due memory (process up to 10 per session):
|
|
|
41
41
|
### Review 1 of <N>
|
|
42
42
|
|
|
43
43
|
**Memory:** <title>
|
|
44
|
-
**Path:**
|
|
44
|
+
**Path:** ~/.brain/<path>
|
|
45
45
|
**Type:** <type> (<cognitive_type>) | **Last reviewed:** <date> | **Interval:** <days>d
|
|
46
46
|
**Confidence:** <confidence>
|
|
47
47
|
|
package/commands/brain/sleep.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# /brain:sleep — Overnight Memory Reorganization
|
|
2
2
|
|
|
3
|
-
You are performing a **sleep cycle** on the Brain Memory system. Just like the human brain during sleep — where the hippocampus replays recent experiences and the neocortex reorganizes them into long-term structured knowledge — this command restructures, consolidates, prunes, and deepens the
|
|
3
|
+
You are performing a **sleep cycle** on the Brain Memory system. Just like the human brain during sleep — where the hippocampus replays recent experiences and the neocortex reorganizes them into long-term structured knowledge — this command restructures, consolidates, prunes, and deepens the `~/.brain/` hierarchy.
|
|
4
4
|
|
|
5
5
|
**Scope:** $ARGUMENTS
|
|
6
6
|
|
|
@@ -18,31 +18,13 @@ Sleep performs nine phases, mimicking real neuroscience:
|
|
|
18
18
|
8. **REM Dreaming** — Discover creative cross-domain associations via analogical reasoning
|
|
19
19
|
9. **Expertise Detection** — Identify dense knowledge areas and generate expertise profiles
|
|
20
20
|
|
|
21
|
-
### Migration Phase (Phase 0)
|
|
22
|
-
|
|
23
|
-
If the brain's `index.json` has `version: 1` (pre-v2), run migration first:
|
|
24
|
-
|
|
25
|
-
1. Create `associations.json` from existing `related` fields — for each memory with `related` entries, create edges with weight 0.20 and origin `manual`
|
|
26
|
-
2. Auto-discover associations: for any two memories sharing 2+ tags, create edges with weight 0.10 and origin `tag_overlap`
|
|
27
|
-
3. Create `contexts.json` with `{"version": 1, "sessions": []}`
|
|
28
|
-
4. Create `review-queue.json` with `{"version": 1, "items": []}`
|
|
29
|
-
5. Create `_archived/index.json` if not present with `{"version": 1, "archived_count": 0, "memories": {}}`
|
|
30
|
-
6. For each memory: backfill `recall_history` from `access_count` (if `access_count > 0`, set `recall_history: [last_accessed]`; otherwise `recall_history: []`)
|
|
31
|
-
7. Set defaults for missing fields: `cognitive_type: "semantic"`, `salience: 0.5`, `confidence: 0.8`
|
|
32
|
-
8. Update both memory files (frontmatter) and `index.json` entries
|
|
33
|
-
9. Set `index.json` version to 2
|
|
34
|
-
|
|
35
|
-
Present migration summary, then proceed to Phase 1.
|
|
36
|
-
|
|
37
|
-
---
|
|
38
|
-
|
|
39
21
|
## Phase 1: Replay (Hippocampal Scan)
|
|
40
22
|
|
|
41
23
|
During sleep, the hippocampus replays the day's events. Here, we scan and assess the full brain state.
|
|
42
24
|
|
|
43
25
|
### Steps
|
|
44
26
|
|
|
45
|
-
1. Read
|
|
27
|
+
1. Read `~/.brain/index.json` to load all memories
|
|
46
28
|
2. If $ARGUMENTS specifies a category path, limit scope to that subtree. Otherwise, process the entire brain.
|
|
47
29
|
3. For **every** memory, compute the current decayed strength:
|
|
48
30
|
|
|
@@ -345,7 +327,7 @@ During deep sleep, the brain merges related experiences into generalized knowled
|
|
|
345
327
|
|
|
346
328
|
5. For approved consolidations:
|
|
347
329
|
- Write consolidated memory files using the standard format with `type: consolidated`
|
|
348
|
-
- Archive source memories to
|
|
330
|
+
- Archive source memories to `~/.brain/_archived/` and add them to `_archived/index.json`
|
|
349
331
|
- Transfer association edges from source memories to the consolidated memory in `associations.json`
|
|
350
332
|
- Update `index.json` and `_meta.json` files
|
|
351
333
|
|
|
@@ -369,7 +351,7 @@ During sleep, the brain prunes weak synaptic connections to maintain efficiency.
|
|
|
369
351
|
4. Get user approval (default: archive all)
|
|
370
352
|
|
|
371
353
|
5. Execute:
|
|
372
|
-
- Move to
|
|
354
|
+
- Move to `~/.brain/_archived/`, preserving directory structure
|
|
373
355
|
- Add to `_archived/index.json` with original metadata
|
|
374
356
|
- Remove from `index.json` and update `_meta.json` files
|
|
375
357
|
- Remove association edges involving pruned memories from `associations.json`
|
|
@@ -532,4 +514,3 @@ After all phases complete, present a comprehensive sleep report:
|
|
|
532
514
|
7. **Idempotent expertise** — if `_expertise.md` already exists, update it rather than creating a duplicate.
|
|
533
515
|
8. **Skip empty phases** — if there's nothing to do in a phase (e.g., no flat clusters to reorganize), briefly note it and move on.
|
|
534
516
|
9. **Salience protection** — never auto-prune memories with salience >= 0.7.
|
|
535
|
-
10. **Run migration** — if `index.json` version is 1, run Phase 0 migration before proceeding.
|
package/commands/brain/status.md
CHANGED
|
@@ -6,12 +6,13 @@ You are displaying a comprehensive overview of the Brain Memory system's current
|
|
|
6
6
|
|
|
7
7
|
### 1. Read Brain State
|
|
8
8
|
|
|
9
|
-
Read
|
|
9
|
+
Read `~/.brain/index.json` to get the full memory inventory. If `~/.brain/` doesn't exist, inform the user and suggest running `/brain:init`.
|
|
10
10
|
|
|
11
11
|
Also read (if they exist):
|
|
12
|
-
-
|
|
13
|
-
-
|
|
14
|
-
-
|
|
12
|
+
- `~/.brain/associations.json` — for association network stats
|
|
13
|
+
- `~/.brain/review-queue.json` — for review schedule info
|
|
14
|
+
- `~/.brain/_archived/index.json` — for archive stats
|
|
15
|
+
- `~/.brain/.sync/config.json` — for git sync configuration
|
|
15
16
|
|
|
16
17
|
### 2. Compute Statistics
|
|
17
18
|
|
|
@@ -104,6 +105,14 @@ Calculate aggregate stats:
|
|
|
104
105
|
+ <title> (<path>) — <date>
|
|
105
106
|
+ <title> (<path>) — <date>
|
|
106
107
|
...
|
|
108
|
+
|
|
109
|
+
## Sync
|
|
110
|
+
Remote: <remote URL or "not configured">
|
|
111
|
+
Encryption: <enabled/disabled>
|
|
112
|
+
Last Push: <timestamp or "never">
|
|
113
|
+
Last Pull: <timestamp or "never">
|
|
114
|
+
Ahead: <count> commits
|
|
115
|
+
Behind: <count> commits
|
|
107
116
|
```
|
|
108
117
|
|
|
109
118
|
### 4. Health Check
|
|
@@ -119,4 +128,5 @@ Analyze the brain's health and provide recommendations:
|
|
|
119
128
|
- **"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`
|
|
120
129
|
- **"Low confidence"** — More than 30% of memories have confidence < 0.5. Suggest reviewing and validating uncertain memories.
|
|
121
130
|
- **"Review overdue"** — More than 10 memories are past their review date. Suggest `/brain:review`
|
|
122
|
-
- **"
|
|
131
|
+
- **"Sync available"** — Git sync is not configured. Suggest `/brain:sync setup` for cross-device access.
|
|
132
|
+
- **"Sync stale"** — Last push was more than 7 days ago. Suggest `/brain:sync push`.
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# /brain:sunshine — Deep Forensic Memory Erasure
|
|
2
2
|
|
|
3
|
-
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
|
|
3
|
+
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.
|
|
4
4
|
|
|
5
5
|
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.
|
|
6
6
|
|
|
@@ -32,12 +32,12 @@ If no target is provided, ask the user what memory they want to erase.
|
|
|
32
32
|
|
|
33
33
|
Search for the target memory:
|
|
34
34
|
|
|
35
|
-
1. Read
|
|
35
|
+
1. Read `~/.brain/index.json` and search `memories` by:
|
|
36
36
|
- Exact ID match
|
|
37
37
|
- Title substring match (case-insensitive)
|
|
38
38
|
- Path substring match
|
|
39
|
-
2. If not found in active memories, check
|
|
40
|
-
3. If still not found, check
|
|
39
|
+
2. If not found in active memories, check `~/.brain/_archived/index.json`
|
|
40
|
+
3. If still not found, check `~/.brain/_erased.json` — if found there, report:
|
|
41
41
|
```
|
|
42
42
|
Memory was previously erased on <date>.
|
|
43
43
|
Reason: <reason or "unspecified">
|
|
@@ -50,10 +50,10 @@ Once located, read the full memory file to capture its ID, title, path, tags, `r
|
|
|
50
50
|
|
|
51
51
|
### 3. Trace All References (Blast Radius Scan)
|
|
52
52
|
|
|
53
|
-
Scan the entire
|
|
53
|
+
Scan the entire `~/.brain/` tree for every trace of the target memory. Track 8 reference types:
|
|
54
54
|
|
|
55
55
|
**3a. `related` arrays in other memories' frontmatter:**
|
|
56
|
-
Parse the YAML frontmatter of every `.md` memory file in
|
|
56
|
+
Parse the YAML frontmatter of every `.md` memory file in `~/.brain/`. For each file whose `related` array contains the target ID, record:
|
|
57
57
|
- File path
|
|
58
58
|
- Current `related` array contents
|
|
59
59
|
|
|
@@ -70,22 +70,22 @@ Among all memory files with `type: consolidated`, check if their `consolidated_f
|
|
|
70
70
|
- Number of other sources remaining
|
|
71
71
|
|
|
72
72
|
**3d. Association edges (`associations.json`):**
|
|
73
|
-
Read
|
|
73
|
+
Read `~/.brain/associations.json`. Find all edges involving the target ID:
|
|
74
74
|
- Outgoing: `edges[target_id][*]`
|
|
75
75
|
- Incoming: `edges[*][target_id]`
|
|
76
76
|
Record each edge with its neighbor, weight, and origin.
|
|
77
77
|
|
|
78
78
|
**3e. Context sessions (`contexts.json`):**
|
|
79
|
-
Read
|
|
79
|
+
Read `~/.brain/contexts.json`. Search all sessions for the target ID in:
|
|
80
80
|
- `memories_created` arrays
|
|
81
81
|
- `memories_recalled` arrays
|
|
82
82
|
Record each session timestamp and which array contained the reference.
|
|
83
83
|
|
|
84
84
|
**3f. Review queue (`review-queue.json`):**
|
|
85
|
-
Read
|
|
85
|
+
Read `~/.brain/review-queue.json`. Check if any item has `memory_id` equal to the target ID.
|
|
86
86
|
|
|
87
87
|
**3g. Archive index (`_archived/index.json`):**
|
|
88
|
-
Read
|
|
88
|
+
Read `~/.brain/_archived/index.json`. Check if the target ID exists as a key in `memories`.
|
|
89
89
|
|
|
90
90
|
**3h. Crystallization comments:**
|
|
91
91
|
Search all memory files for HTML comments matching the pattern:
|
|
@@ -230,13 +230,13 @@ For each directory in the target's path, read the `_meta.json` and decrement `me
|
|
|
230
230
|
- Clean up empty parent directories (but never delete top-level category directories)
|
|
231
231
|
|
|
232
232
|
**7g. Remove archived copy:**
|
|
233
|
-
If an archived copy exists at
|
|
233
|
+
If an archived copy exists at `~/.brain/_archived/<original-path>`, delete it.
|
|
234
234
|
- If `--sensitive`: overwrite with null bytes before deletion
|
|
235
235
|
- Clean up empty directories in `_archived/`
|
|
236
236
|
|
|
237
237
|
### 8. Write Audit Log
|
|
238
238
|
|
|
239
|
-
Unless `--no-trace` is set, write or append to
|
|
239
|
+
Unless `--no-trace` is set, write or append to `~/.brain/_erased.json`:
|
|
240
240
|
|
|
241
241
|
```json
|
|
242
242
|
{
|
|
@@ -317,7 +317,7 @@ Print a summary:
|
|
|
317
317
|
|
|
318
318
|
7. **Empty `related` arrays after cleanup**: Leave as `related: []`. Do not remove the field entirely — it maintains schema consistency.
|
|
319
319
|
|
|
320
|
-
8. **Memory referenced by memories outside
|
|
320
|
+
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.
|
|
321
321
|
|
|
322
322
|
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.
|
|
323
323
|
|
|
@@ -0,0 +1,222 @@
|
|
|
1
|
+
# /brain:sync — Portable Sync
|
|
2
|
+
|
|
3
|
+
You are managing synchronization for the Brain Memory system. This enables manual push/pull of `~/.brain/` memories via any Git remote, plus encrypted single-file export/import for portable transfers.
|
|
4
|
+
|
|
5
|
+
**CRITICAL RULES:**
|
|
6
|
+
- NEVER auto-sync — always require explicit user action
|
|
7
|
+
- NEVER silently overwrite files — always show a preview first
|
|
8
|
+
- NEVER display passphrases or secrets in output
|
|
9
|
+
- ALWAYS show what will change before executing push/pull/import
|
|
10
|
+
|
|
11
|
+
## Subcommands
|
|
12
|
+
|
|
13
|
+
Parse the user's input to determine the subcommand:
|
|
14
|
+
- `setup <url>` → Configure a Git remote for sync
|
|
15
|
+
- `push` → Commit and push local changes to remote
|
|
16
|
+
- `pull` → Fetch and merge remote changes to local
|
|
17
|
+
- `status` → Show sync state (ahead/behind)
|
|
18
|
+
- `export [path]` → Export ~/.brain/ to an encrypted single file
|
|
19
|
+
- `import <path>` → Import from an export file
|
|
20
|
+
- `disconnect` → Remove sync configuration
|
|
21
|
+
|
|
22
|
+
If no subcommand is given, show available subcommands.
|
|
23
|
+
|
|
24
|
+
---
|
|
25
|
+
|
|
26
|
+
## `/brain:sync setup <url>`
|
|
27
|
+
|
|
28
|
+
### Steps
|
|
29
|
+
|
|
30
|
+
1. **Check prerequisites:**
|
|
31
|
+
- Verify `~/.brain/` exists. If not, suggest `/brain:init` first.
|
|
32
|
+
- Verify `git` is available (`checkGitAvailable()` from `src/git-sync.js`).
|
|
33
|
+
- Check if sync is already configured (`~/.brain/.sync/config.json`). If so, ask if they want to reconfigure.
|
|
34
|
+
|
|
35
|
+
2. **Get remote URL** (if not provided):
|
|
36
|
+
- Ask for the Git remote URL (SSH or HTTPS).
|
|
37
|
+
- Auto-detect `gh` CLI: if available, offer to create a private repo with `gh repo create brain-data --private`.
|
|
38
|
+
- Examples:
|
|
39
|
+
- `git@github.com:user/brain-data.git`
|
|
40
|
+
- `https://github.com/user/brain-data.git`
|
|
41
|
+
- `git@gitlab.com:user/brain-data.git`
|
|
42
|
+
|
|
43
|
+
3. **Ask about encryption** (optional):
|
|
44
|
+
- "Would you like to encrypt memories before pushing? (recommended for sensitive data)"
|
|
45
|
+
- If yes, ask for a passphrase (will be needed on every push/pull and on other devices).
|
|
46
|
+
|
|
47
|
+
4. **Initialize sync:**
|
|
48
|
+
- Call `initSyncRepo()` and `configureRemote()` from `src/git-sync.js`.
|
|
49
|
+
- Write config to `~/.brain/.sync/config.json` via `writeSyncConfig()`.
|
|
50
|
+
|
|
51
|
+
5. **Show result:**
|
|
52
|
+
```
|
|
53
|
+
✓ Git sync configured!
|
|
54
|
+
Remote: <remote-url>
|
|
55
|
+
Branch: main
|
|
56
|
+
Encryption: <enabled/disabled>
|
|
57
|
+
|
|
58
|
+
Use /brain:sync push to upload your memories.
|
|
59
|
+
Use /brain:sync pull to download from remote.
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
---
|
|
63
|
+
|
|
64
|
+
## `/brain:sync push`
|
|
65
|
+
|
|
66
|
+
### Steps
|
|
67
|
+
|
|
68
|
+
1. **Check sync is configured.** If not, suggest `/brain:sync setup`.
|
|
69
|
+
|
|
70
|
+
2. **Preview changes:**
|
|
71
|
+
- Call `getStatus()` from `src/git-sync.js`.
|
|
72
|
+
- Display summary:
|
|
73
|
+
```
|
|
74
|
+
📤 Push Preview:
|
|
75
|
+
Remote: <remote-url>
|
|
76
|
+
Status: <ahead> commits ahead, <behind> behind
|
|
77
|
+
```
|
|
78
|
+
- If behind > 0, warn: "Remote has newer changes. Consider pulling first."
|
|
79
|
+
|
|
80
|
+
3. **Ask for confirmation** before proceeding.
|
|
81
|
+
|
|
82
|
+
4. **Execute push:**
|
|
83
|
+
- If encryption is enabled, ask for passphrase.
|
|
84
|
+
- Call `push()` from `src/git-sync.js`.
|
|
85
|
+
- Show result:
|
|
86
|
+
```
|
|
87
|
+
✓ Push complete!
|
|
88
|
+
Committed: <message>
|
|
89
|
+
Remote: <remote-url>
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
---
|
|
93
|
+
|
|
94
|
+
## `/brain:sync pull`
|
|
95
|
+
|
|
96
|
+
### Steps
|
|
97
|
+
|
|
98
|
+
1. **Check sync is configured.**
|
|
99
|
+
|
|
100
|
+
2. **Preview:**
|
|
101
|
+
- Call `getStatus()` to show ahead/behind count.
|
|
102
|
+
```
|
|
103
|
+
📥 Pull Preview:
|
|
104
|
+
Remote: <remote-url>
|
|
105
|
+
Status: <behind> new commits to pull
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
3. **Ask for confirmation.**
|
|
109
|
+
|
|
110
|
+
4. **Execute pull:**
|
|
111
|
+
- If encryption is enabled, ask for passphrase.
|
|
112
|
+
- Call `pull()` from `src/git-sync.js`.
|
|
113
|
+
- Show result:
|
|
114
|
+
```
|
|
115
|
+
✓ Pull complete!
|
|
116
|
+
Updated <count> files from remote.
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
---
|
|
120
|
+
|
|
121
|
+
## `/brain:sync status`
|
|
122
|
+
|
|
123
|
+
### Steps
|
|
124
|
+
|
|
125
|
+
1. **Read sync config** using `getSyncConfig()` from `src/git-sync.js`.
|
|
126
|
+
|
|
127
|
+
2. **Display dashboard:**
|
|
128
|
+
```
|
|
129
|
+
🔄 Sync Status
|
|
130
|
+
─────────────────────
|
|
131
|
+
Remote: <remote-url or "not configured">
|
|
132
|
+
Branch: <branch>
|
|
133
|
+
Encryption: <enabled/disabled>
|
|
134
|
+
Last Push: <timestamp or "never">
|
|
135
|
+
Last Pull: <timestamp or "never">
|
|
136
|
+
Ahead: <count> commits
|
|
137
|
+
Behind: <count> commits
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
---
|
|
141
|
+
|
|
142
|
+
## `/brain:sync export [path]`
|
|
143
|
+
|
|
144
|
+
### Steps
|
|
145
|
+
|
|
146
|
+
1. **Determine output path:**
|
|
147
|
+
- Default: `.brain-export` in the current directory.
|
|
148
|
+
- User can specify a custom path.
|
|
149
|
+
|
|
150
|
+
2. **Ask about encryption:**
|
|
151
|
+
- "Would you like to encrypt the export? (recommended)"
|
|
152
|
+
- If yes, ask for a passphrase.
|
|
153
|
+
|
|
154
|
+
3. **Execute export:**
|
|
155
|
+
- Call `exportBrain()` from `src/export-import.js`.
|
|
156
|
+
- Show result:
|
|
157
|
+
```
|
|
158
|
+
✓ Brain exported!
|
|
159
|
+
File: <output-path>
|
|
160
|
+
Memories: <count> files packed
|
|
161
|
+
Encrypted: <yes/no>
|
|
162
|
+
Size: <file-size>
|
|
163
|
+
|
|
164
|
+
Transfer this file to another machine and run /brain:sync import <path>
|
|
165
|
+
```
|
|
166
|
+
|
|
167
|
+
---
|
|
168
|
+
|
|
169
|
+
## `/brain:sync import <path>`
|
|
170
|
+
|
|
171
|
+
### Steps
|
|
172
|
+
|
|
173
|
+
1. **Preview the import:**
|
|
174
|
+
- Call `previewImport()` from `src/export-import.js`.
|
|
175
|
+
- Display:
|
|
176
|
+
```
|
|
177
|
+
📦 Import Preview:
|
|
178
|
+
File: <path>
|
|
179
|
+
Exported at: <date>
|
|
180
|
+
Total files: <count>
|
|
181
|
+
New: <count> (will be created)
|
|
182
|
+
Existing: <count> (will be overwritten)
|
|
183
|
+
```
|
|
184
|
+
|
|
185
|
+
2. **Ask for import mode:**
|
|
186
|
+
- **Overwrite** (default): Replace all matching files with the imported versions.
|
|
187
|
+
- **Merge**: Only import files newer than local versions.
|
|
188
|
+
|
|
189
|
+
3. **If encrypted, ask for passphrase.**
|
|
190
|
+
|
|
191
|
+
4. **Ask for confirmation.**
|
|
192
|
+
|
|
193
|
+
5. **Execute import:**
|
|
194
|
+
- Call `importBrain()` from `src/export-import.js`.
|
|
195
|
+
- Show result:
|
|
196
|
+
```
|
|
197
|
+
✓ Import complete!
|
|
198
|
+
Imported: <count> files
|
|
199
|
+
Skipped: <count> (merge mode, local was newer)
|
|
200
|
+
```
|
|
201
|
+
|
|
202
|
+
---
|
|
203
|
+
|
|
204
|
+
## `/brain:sync disconnect`
|
|
205
|
+
|
|
206
|
+
### Steps
|
|
207
|
+
|
|
208
|
+
1. **Show current config** (remote URL).
|
|
209
|
+
2. **Ask for confirmation:** "This will remove sync configuration. Your remote data will NOT be deleted."
|
|
210
|
+
3. **Remove `~/.brain/.sync/` directory.**
|
|
211
|
+
4. **Confirm:** "✓ Sync disconnected. Remote repository is untouched."
|
|
212
|
+
|
|
213
|
+
---
|
|
214
|
+
|
|
215
|
+
## Key Implementation Notes
|
|
216
|
+
|
|
217
|
+
- Git sync engine: `src/git-sync.js`
|
|
218
|
+
- Export/import: `src/export-import.js`
|
|
219
|
+
- Crypto utilities: `src/crypto.js`
|
|
220
|
+
- Sync config stored in `~/.brain/.sync/config.json` (local only)
|
|
221
|
+
- Hidden git repo at `~/.brain/.sync/repo/` — never interferes with the project's own git
|
|
222
|
+
- All git operations use `execFileSync` — no npm dependencies
|