brain-memory 0.1.0-beta.1 → 0.1.0-beta.10

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.
@@ -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 searches the `.brain/` hierarchy, scores memories by relevance, strength, associative links, and context match, and returns the most useful memories — either individually or as a consolidated synthesis.
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. Parse the Query
9
+ ### 1. Determine Context
10
10
 
11
- Analyze $ARGUMENTS to determine:
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
- ### 3. Search the Brain
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
- Read `.brain/associations.json`. For each candidate memory scoring > 0.3 in initial relevance:
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
- This implements how the brain works: thinking about topic A naturally activates related topics B and C.
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
- ### 4. Score Candidates
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
- For each candidate memory, compute an **effective score** using the v4 formula:
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
- **Note:** If a memory lacks newer fields (spreading_bonus, context_match, salience), the formula renormalizes weights across the available terms. This ensures backward compatibility with v1 memories.
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
- ### 5. Decide Response Strategy
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 effective scores.
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 in active brain:**
91
- Search `.brain/_archived/` via the archive index (`_archived/index.json`). If archived matches are found with relevance > 0.3:
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
- ### 6. Reinforce Retrieved Memories (Spaced Reinforcement)
63
+ ### 5. Reinforce Retrieved Memories
101
64
 
102
- For every memory that was returned to the user (Cases A and B), apply spaced reinforcement:
65
+ After presenting results, run the reinforcement engine for all memories shown to the user:
103
66
 
104
- **Calculate spacing-aware boost:**
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
- Examples: 1 day gap = +0.05 (same as v1), 7 days = +0.08, 30 days = +0.10, cramming same day 20th recall = +0.02.
114
-
115
- **Update in both the memory file AND index.json:**
116
- - `last_accessed` → current timestamp
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
- Write the updated `associations.json`.
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
- ### 8. Present Results
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:** .brain/<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 ⚠️ if < 0.5>
92
+ **Confidence:** <confidence> <show warning if < 0.5>
141
93
 
142
94
  <memory content>
143
95
 
144
96
  ---
145
- *Memory reinforced — strength updated to <new_strength>, decay improved to <new_decay_rate>*
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>** (.brain/<path>) — score: <score>, confidence: <confidence>
157
- 2. **<title>** (.brain/<path>) — score: <score>, confidence: <confidence>
108
+ 1. **<title>** (~/.brain/<path>) — score: <score>
109
+ 2. **<title>** (~/.brain/<path>) — score: <score>
158
110
  ...
159
111
 
160
112
  ---
161
- *<N> memories reinforced, <M> association links strengthened*
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
  ```
@@ -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 `.brain/review-queue.json`. If it doesn't exist or is empty, generate it:
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:** .brain/<path>
44
+ **Path:** ~/.brain/<path>
45
45
  **Type:** <type> (<cognitive_type>) | **Last reviewed:** <date> | **Interval:** <days>d
46
46
  **Confidence:** <confidence>
47
47
 
@@ -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 `.brain/` hierarchy.
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 `.brain/index.json` to load all memories
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 `.brain/_archived/` and add them to `_archived/index.json`
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 `.brain/_archived/`, preserving directory structure
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.
@@ -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 `.brain/index.json` to get the full memory inventory. If `.brain/` doesn't exist, inform the user and suggest running `/brain:init`.
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
- - `.brain/associations.json` — for association network stats
13
- - `.brain/review-queue.json` — for review schedule info
14
- - `.brain/_archived/index.json` — for archive stats
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
- - **"Needs migration"** — Brain is v1 and needs upgrade. Suggest `/brain:sleep` to trigger migration.
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 `.brain/` tree and surgically removes or repairs each one. When complete, it's as if the memory never existed.
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 `.brain/index.json` and search `memories` by:
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 `.brain/_archived/index.json`
40
- 3. If still not found, check `.brain/_erased.json` — if found there, report:
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 `.brain/` tree for every trace of the target memory. Track 8 reference types:
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 `.brain/`. For each file whose `related` array contains the target ID, record:
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 `.brain/associations.json`. Find all edges involving the target ID:
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 `.brain/contexts.json`. Search all sessions for the target ID in:
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 `.brain/review-queue.json`. Check if any item has `memory_id` equal to the target ID.
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 `.brain/_archived/index.json`. Check if the target ID exists as a key in `memories`.
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 `.brain/_archived/<original-path>`, delete it.
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 `.brain/_erased.json`:
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 `.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.
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