brain-memory 0.1.0-beta.7 → 0.1.0-beta.8

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 CHANGED
@@ -7,7 +7,7 @@ A hierarchical, file-system-based memory plugin for AI coding agents. Inspired b
7
7
  Works with **Claude Code**, **Gemini CLI**, and **OpenAI Codex CLI**.
8
8
 
9
9
  ```
10
- .brain/
10
+ ~/.brain/
11
11
  ├── professional/
12
12
  │ └── companies/
13
13
  │ └── acme-corp/
@@ -71,7 +71,7 @@ Auto-detects installed runtimes and refreshes commands + prompt sections. Target
71
71
  npx brain-memory@beta uninstall
72
72
  ```
73
73
 
74
- Removes commands and prompt sections. Your `.brain/` directory (memories) is preserved by default. Add `--delete-data` to remove it too. Use `--yes` to skip confirmation prompts.
74
+ Removes commands and prompt sections. Your `~/.brain/` directory (memories) is preserved by default. Add `--delete-data` to remove it too. Use `--yes` to skip confirmation prompts.
75
75
 
76
76
  ### Manual Install
77
77
 
@@ -101,7 +101,7 @@ Then append the contents of the corresponding prompt file to your agent's instru
101
101
 
102
102
  | Command | Description |
103
103
  |---------|-------------|
104
- | `/brain:init` | Initialize `.brain/` directory structure with default categories |
104
+ | `/brain:init` | Initialize `~/.brain/` directory structure with default categories |
105
105
  | `/brain:memorize [topic]` | Store memories from current session context |
106
106
  | `/brain:remember [query]` | Recall relevant memories with spreading activation and context matching |
107
107
  | `/brain:review [scope]` | Spaced repetition review session for due memories |
@@ -119,7 +119,7 @@ Brain Memory works automatically in the background — no commands needed for ba
119
119
 
120
120
  ### Session Start
121
121
 
122
- When a session begins and `.brain/` exists, the agent automatically:
122
+ When a session begins and `~/.brain/` exists, the agent automatically:
123
123
 
124
124
  1. Reads the brain index and loads the top 3-5 memories relevant to the current project
125
125
  2. Checks the review queue for memories due for spaced repetition
@@ -142,7 +142,7 @@ When a session ends, the agent evaluates whether significant decisions, learning
142
142
  Run /brain:memorize to capture them before this context is lost.
143
143
  ```
144
144
 
145
- The agent never auto-memorizes without user consent. Session context is always saved to `.brain/contexts.json` for context-dependent recall.
145
+ The agent never auto-memorizes without user consent. Session context is always saved to `~/.brain/contexts.json` for context-dependent recall.
146
146
 
147
147
  ## How It Works
148
148
 
@@ -282,7 +282,7 @@ The agent then decides the response strategy:
282
282
 
283
283
  ### Associative Network
284
284
 
285
- Memories are connected via weighted edges in `.brain/associations.json`:
285
+ Memories are connected via weighted edges in `~/.brain/associations.json`:
286
286
 
287
287
  ```json
288
288
  {
@@ -374,13 +374,19 @@ Each expertise area gets an `_expertise.md` profile documenting what you know we
374
374
 
375
375
  Failed recalls reset the interval to 1 day. Successful recalls extend the interval by the ease factor. This ensures you spend time on memories that need reinforcement, not ones you already know well.
376
376
 
377
+ ### Cross-Agent Memory Sharing
378
+
379
+ `~/.brain/` is a single global directory in the user's home folder. All memories are shared across every project and every supported agent automatically. A decision stored by Claude Code in one project is immediately available to Gemini CLI or Codex CLI in any other project — no configuration, no export, no per-project setup. The format is agent-agnostic: plain Markdown files with YAML frontmatter, readable by any tool.
380
+
381
+ To share memories across different machines, use `/brain:sync` (see below).
382
+
377
383
  ### Portable Sync
378
384
 
379
385
  `/brain:sync` provides two ways to sync memories across devices — no OAuth apps, no cloud provider setup.
380
386
 
381
- **Git remote** — Push/pull `.brain/` to any private Git repository. Works with GitHub, GitLab, Codeberg, or any self-hosted Git server. Uses your existing Git/SSH authentication — no additional credentials needed.
387
+ **Git remote** — Push/pull `~/.brain/` to any private Git repository. Works with GitHub, GitLab, Codeberg, or any self-hosted Git server. Uses your existing Git/SSH authentication — no additional credentials needed.
382
388
 
383
- **Export/Import** — Pack the entire `.brain/` into a single encrypted file for manual transfer via USB, email, or any file-sharing service.
389
+ **Export/Import** — Pack the entire `~/.brain/` into a single encrypted file for manual transfer via USB, email, or any file-sharing service.
384
390
 
385
391
  **Key features:**
386
392
  - **Manual push/pull** — No background watchers, no auto-sync. You control when data moves.
@@ -395,12 +401,12 @@ Failed recalls reset the interval to 1 day. Successful recalls extend the interv
395
401
 
396
402
  For one-off transfers, use `/brain:sync export` and `/brain:sync import <path>`.
397
403
 
398
- Sync state is stored locally in `.brain/.sync/` and is never pushed to the remote.
404
+ Sync state is stored locally in `~/.brain/.sync/` and is never pushed to the remote.
399
405
 
400
406
  ## File Structure
401
407
 
402
408
  ```
403
- .brain/
409
+ ~/.brain/
404
410
  ├── index.json # Memory inventory — fast lookup for all memories
405
411
  ├── associations.json # Weighted associative network between memories
406
412
  ├── contexts.json # Session context snapshots for context-dependent recall
@@ -439,7 +445,7 @@ Subdirectories are created **on demand** — the agent decides placement depth b
439
445
 
440
446
  ## Configuration
441
447
 
442
- Brain configuration lives in `.brain/index.json` under the `config` key:
448
+ Brain configuration lives in `~/.brain/index.json` under the `config` key:
443
449
 
444
450
  ```json
445
451
  {
package/bin/install.js CHANGED
@@ -3,6 +3,7 @@
3
3
  const readline = require('readline');
4
4
  const fs = require('fs');
5
5
  const path = require('path');
6
+ const os = require('os');
6
7
  const {
7
8
  RUNTIMES,
8
9
  installForRuntime,
@@ -114,7 +115,7 @@ async function runInstall(flags) {
114
115
  console.log('');
115
116
  const initBrain = await ask(
116
117
  rl,
117
- ' Initialize .brain/ directory in current project? (Y/n): '
118
+ ' Initialize ~/.brain/ directory? (Y/n): '
118
119
  );
119
120
 
120
121
  // Perform installation
@@ -130,9 +131,9 @@ async function runInstall(flags) {
130
131
  if (initBrain.trim().toLowerCase() !== 'n') {
131
132
  const result = initializeBrain();
132
133
  if (result.alreadyExists) {
133
- console.log('\n .brain/ already exists, skipping initialization.');
134
+ console.log('\n ~/.brain/ already exists, skipping initialization.');
134
135
  } else {
135
- console.log('\n .brain/ initialized successfully.');
136
+ console.log('\n ~/.brain/ initialized successfully.');
136
137
  console.log('');
137
138
  console.log(' Use /brain:sync to set up portable sync across devices.');
138
139
  }
@@ -265,30 +266,30 @@ async function runUninstall(flags) {
265
266
  }
266
267
 
267
268
  // Handle .brain/ data
268
- const brainDir = path.join(process.cwd(), '.brain');
269
+ const brainDir = path.join(os.homedir(), '.brain');
269
270
  if (fs.existsSync(brainDir)) {
270
271
  if (flags.has('delete-data')) {
271
272
  fs.rmSync(brainDir, { recursive: true, force: true });
272
- console.log('\n Deleted .brain/ directory.');
273
+ console.log('\n Deleted ~/.brain/ directory.');
273
274
  } else if (!flags.has('yes') && !flags.has('y')) {
274
275
  const rl = createRL();
275
276
  try {
276
277
  console.log('');
277
278
  const answer = await ask(
278
279
  rl,
279
- ' Delete .brain/ data directory? This removes all memories. (y/N): '
280
+ ' Delete ~/.brain/ data directory? This removes all memories. (y/N): '
280
281
  );
281
282
  if (answer.trim().toLowerCase() === 'y') {
282
283
  fs.rmSync(brainDir, { recursive: true, force: true });
283
- console.log(' Deleted .brain/ directory.');
284
+ console.log(' Deleted ~/.brain/ directory.');
284
285
  } else {
285
- console.log(' Kept .brain/ directory (your memories are preserved).');
286
+ console.log(' Kept ~/.brain/ directory (your memories are preserved).');
286
287
  }
287
288
  } finally {
288
289
  rl.close();
289
290
  }
290
291
  } else {
291
- console.log('\n Kept .brain/ directory (use --delete-data to remove memories).');
292
+ console.log('\n Kept ~/.brain/ directory (use --delete-data to remove memories).');
292
293
  }
293
294
  }
294
295
 
@@ -9,7 +9,7 @@ You are consolidating memories in the Brain Memory system. Consolidation combine
9
9
  ### 1. Determine Scope
10
10
 
11
11
  - If $ARGUMENTS specifies a category path, consolidate within that subtree
12
- - If $ARGUMENTS is empty, scan the entire `.brain/` for consolidation candidates
12
+ - If $ARGUMENTS is empty, scan the entire `~/.brain/` for consolidation candidates
13
13
  - If $ARGUMENTS is "auto", perform automatic consolidation based on thresholds
14
14
 
15
15
  ### 2. Find Consolidation Candidates
@@ -126,7 +126,7 @@ encoding_context:
126
126
 
127
127
  ### 7. Archive Source Memories
128
128
 
129
- Move the original source memory files to a `.brain/_archived/` directory (create if needed), preserving their paths as subdirectories. This keeps them recoverable and searchable via `/brain:remember`.
129
+ Move the original source memory files to a `~/.brain/_archived/` directory (create if needed), preserving their paths as subdirectories. This keeps them recoverable and searchable via `/brain:remember`.
130
130
 
131
131
  Update `index.json`:
132
132
  - Remove archived memory entries from `memories`
@@ -13,7 +13,7 @@ You are exploring the Brain Memory system's hierarchical structure. This gives t
13
13
 
14
14
  ### 2. Read Structure
15
15
 
16
- Read the directory structure of `.brain/` (or the specified subtree). For each directory, read its `_meta.json` to get metadata.
16
+ Read the directory structure of `~/.brain/` (or the specified subtree). For each directory, read its `_meta.json` to get metadata.
17
17
 
18
18
  ### 3. Display Tree View
19
19
 
@@ -24,7 +24,7 @@ Present the brain structure as a visual tree with statistics:
24
24
  Last updated: <timestamp>
25
25
  Total memories: <count>
26
26
 
27
- .brain/
27
+ ~/.brain/
28
28
  ├── professional/ (12 memories)
29
29
  │ ├── companies/ (8 memories)
30
30
  │ │ ├── acme-corp/ (5 memories)
@@ -64,8 +64,8 @@ The user must explicitly choose an action. Default to **archive** (safest).
64
64
  ### 5. Execute
65
65
 
66
66
  **Archive:**
67
- - Move memory files to `.brain/_archived/<original-path>/`
68
- - Add entry to `.brain/_archived/index.json` with all original metadata:
67
+ - Move memory files to `~/.brain/_archived/<original-path>/`
68
+ - Add entry to `~/.brain/_archived/index.json` with all original metadata:
69
69
  ```json
70
70
  {
71
71
  "<memory_id>": {
@@ -1,12 +1,12 @@
1
1
  # /brain:init — Initialize Brain Memory Structure
2
2
 
3
- 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.
3
+ 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.
4
4
 
5
5
  ## Steps
6
6
 
7
7
  ### 1. Check for Existing Brain
8
8
 
9
- Check if `.brain/` directory already exists in the current project root.
9
+ Check if `~/.brain/` directory already exists in the user's home directory.
10
10
 
11
11
  - If it exists, inform the user and ask if they want to reset or keep it.
12
12
  - If not, proceed with creation.
@@ -16,7 +16,7 @@ Check if `.brain/` directory already exists in the current project root.
16
16
  Create the following structure:
17
17
 
18
18
  ```
19
- .brain/
19
+ ~/.brain/
20
20
  ├── index.json
21
21
  ├── associations.json
22
22
  ├── contexts.json
@@ -131,7 +131,7 @@ If the user provides custom categories or subcategories, create them with approp
131
131
 
132
132
  ### 10. Add .brain to .gitignore (Optional)
133
133
 
134
- Ask the user if they want `.brain/` added to `.gitignore` (some users may want to track their memory in git, others may not).
134
+ Ask the user if they want `~/.brain/` added to `.gitignore` (some users may want to track their memory in git, others may not).
135
135
 
136
136
  ### 11. Confirm
137
137
 
@@ -1,6 +1,6 @@
1
1
  # /brain:memorize — Store a New Memory
2
2
 
3
- You are storing a new memory in the Brain Memory system. Memories are filed into the `.brain/` hierarchical directory structure based on their semantic content.
3
+ You are storing a new memory in the Brain Memory system. Memories are filed into the `~/.brain/` hierarchical directory structure based on their semantic content.
4
4
 
5
5
  **User input:** $ARGUMENTS
6
6
 
@@ -49,7 +49,7 @@ For each memory to store, determine:
49
49
 
50
50
  ### 3. Determine File Path (Categorization)
51
51
 
52
- Choose the most appropriate path in the `.brain/` hierarchy. This is the most critical step.
52
+ Choose the most appropriate path in the `~/.brain/` hierarchy. This is the most critical step.
53
53
 
54
54
  **Rules for path selection:**
55
55
  1. Start with the top-level category: `professional/`, `personal/`, `social/`, `family/`
@@ -118,12 +118,12 @@ encoding_context:
118
118
 
119
119
  ### 6. Update Index
120
120
 
121
- Read `.brain/index.json` and add an entry:
121
+ Read `~/.brain/index.json` and add an entry:
122
122
 
123
123
  ```json
124
124
  {
125
125
  "<memory_id>": {
126
- "path": "<relative path from .brain/>",
126
+ "path": "<relative path from ~/.brain/>",
127
127
  "title": "<short title>",
128
128
  "type": "<memory_type>",
129
129
  "cognitive_type": "<episodic|semantic|procedural>",
@@ -148,7 +148,7 @@ Increment `memory_count`. Update `last_updated`.
148
148
 
149
149
  ### 7. Update Associations
150
150
 
151
- Read `.brain/associations.json` and create edges for this memory:
151
+ Read `~/.brain/associations.json` and create edges for this memory:
152
152
 
153
153
  **A. Explicit `related` links:** For each ID in the `related` field, create an edge with weight 0.20 and origin `manual`.
154
154
 
@@ -1,6 +1,6 @@
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 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.
4
4
 
5
5
  **User query:** $ARGUMENTS
6
6
 
@@ -27,7 +27,7 @@ recall_context:
27
27
 
28
28
  ### 3. Search the Brain
29
29
 
30
- Read `.brain/index.json` to get the full memory inventory.
30
+ Read `~/.brain/index.json` to get the full memory inventory.
31
31
 
32
32
  **Search strategy (in order):**
33
33
 
@@ -40,7 +40,7 @@ Collect all candidate memories.
40
40
 
41
41
  ### 3.5. Spreading Activation
42
42
 
43
- Read `.brain/associations.json`. For each candidate memory scoring > 0.3 in initial relevance:
43
+ Read `~/.brain/associations.json`. For each candidate memory scoring > 0.3 in initial relevance:
44
44
  1. Traverse the association graph up to 2 hops
45
45
  2. For each reached memory: `spread_bonus = parent_score * link_weight * 0.5^hop`
46
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)
@@ -88,7 +88,7 @@ List the top 5-7 memories with titles, paths, types, and effective scores.
88
88
  Ask the user which ones they'd like to explore in detail.
89
89
 
90
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:
91
+ Search `~/.brain/_archived/` via the archive index (`_archived/index.json`). If archived matches are found with relevance > 0.3:
92
92
  - Present them with a note that they're archived
93
93
  - Offer to restore them (move back to active brain with strength +0.10)
94
94
 
@@ -134,7 +134,7 @@ Format the output clearly. Include confidence indicators for low-confidence memo
134
134
  ```
135
135
  ## Recalled Memory: <Title>
136
136
 
137
- **Path:** .brain/<path>
137
+ **Path:** ~/.brain/<path>
138
138
  **Strength:** <decayed_strength> (original: <base_strength>)
139
139
  **Type:** <type> (<cognitive_type>) | **Created:** <date> | **Recalled:** <access_count> times
140
140
  **Confidence:** <confidence> <show ⚠️ if < 0.5>
@@ -153,8 +153,8 @@ For consolidated responses (Case B):
153
153
  <consolidated narrative>
154
154
 
155
155
  ### Contributing Memories
156
- 1. **<title>** (.brain/<path>) — score: <score>, confidence: <confidence>
157
- 2. **<title>** (.brain/<path>) — score: <score>, confidence: <confidence>
156
+ 1. **<title>** (~/.brain/<path>) — score: <score>, confidence: <confidence>
157
+ 2. **<title>** (~/.brain/<path>) — score: <score>, confidence: <confidence>
158
158
  ...
159
159
 
160
160
  ---
@@ -166,7 +166,7 @@ For archived matches (Case D fallback):
166
166
  ```
167
167
  ## Found in Archive: <Title>
168
168
 
169
- **Path:** .brain/_archived/<path>
169
+ **Path:** ~/.brain/_archived/<path>
170
170
  **Original Strength:** <strength> | **Archived:** <date>
171
171
 
172
172
  <memory content summary>
@@ -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
 
@@ -24,7 +24,7 @@ During sleep, the hippocampus replays the day's events. Here, we scan and assess
24
24
 
25
25
  ### Steps
26
26
 
27
- 1. Read `.brain/index.json` to load all memories
27
+ 1. Read `~/.brain/index.json` to load all memories
28
28
  2. If $ARGUMENTS specifies a category path, limit scope to that subtree. Otherwise, process the entire brain.
29
29
  3. For **every** memory, compute the current decayed strength:
30
30
 
@@ -327,7 +327,7 @@ During deep sleep, the brain merges related experiences into generalized knowled
327
327
 
328
328
  5. For approved consolidations:
329
329
  - Write consolidated memory files using the standard format with `type: consolidated`
330
- - 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`
331
331
  - Transfer association edges from source memories to the consolidated memory in `associations.json`
332
332
  - Update `index.json` and `_meta.json` files
333
333
 
@@ -351,7 +351,7 @@ During sleep, the brain prunes weak synaptic connections to maintain efficiency.
351
351
  4. Get user approval (default: archive all)
352
352
 
353
353
  5. Execute:
354
- - Move to `.brain/_archived/`, preserving directory structure
354
+ - Move to `~/.brain/_archived/`, preserving directory structure
355
355
  - Add to `_archived/index.json` with original metadata
356
356
  - Remove from `index.json` and update `_meta.json` files
357
357
  - Remove association edges involving pruned memories from `associations.json`
@@ -6,13 +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
15
- - `.brain/.sync/config.json` — for git sync configuration
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
16
16
 
17
17
  ### 2. Compute Statistics
18
18
 
@@ -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
 
@@ -1,6 +1,6 @@
1
1
  # /brain:sync — Portable Sync
2
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.
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
4
 
5
5
  **CRITICAL RULES:**
6
6
  - NEVER auto-sync — always require explicit user action
@@ -15,7 +15,7 @@ Parse the user's input to determine the subcommand:
15
15
  - `push` → Commit and push local changes to remote
16
16
  - `pull` → Fetch and merge remote changes to local
17
17
  - `status` → Show sync state (ahead/behind)
18
- - `export [path]` → Export .brain/ to an encrypted single file
18
+ - `export [path]` → Export ~/.brain/ to an encrypted single file
19
19
  - `import <path>` → Import from an export file
20
20
  - `disconnect` → Remove sync configuration
21
21
 
@@ -28,9 +28,9 @@ If no subcommand is given, show available subcommands.
28
28
  ### Steps
29
29
 
30
30
  1. **Check prerequisites:**
31
- - Verify `.brain/` exists. If not, suggest `/brain:init` first.
31
+ - Verify `~/.brain/` exists. If not, suggest `/brain:init` first.
32
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.
33
+ - Check if sync is already configured (`~/.brain/.sync/config.json`). If so, ask if they want to reconfigure.
34
34
 
35
35
  2. **Get remote URL** (if not provided):
36
36
  - Ask for the Git remote URL (SSH or HTTPS).
@@ -46,7 +46,7 @@ If no subcommand is given, show available subcommands.
46
46
 
47
47
  4. **Initialize sync:**
48
48
  - Call `initSyncRepo()` and `configureRemote()` from `src/git-sync.js`.
49
- - Write config to `.brain/.sync/config.json` via `writeSyncConfig()`.
49
+ - Write config to `~/.brain/.sync/config.json` via `writeSyncConfig()`.
50
50
 
51
51
  5. **Show result:**
52
52
  ```
@@ -207,7 +207,7 @@ If no subcommand is given, show available subcommands.
207
207
 
208
208
  1. **Show current config** (remote URL).
209
209
  2. **Ask for confirmation:** "This will remove sync configuration. Your remote data will NOT be deleted."
210
- 3. **Remove `.brain/.sync/` directory.**
210
+ 3. **Remove `~/.brain/.sync/` directory.**
211
211
  4. **Confirm:** "✓ Sync disconnected. Remote repository is untouched."
212
212
 
213
213
  ---
@@ -217,6 +217,6 @@ If no subcommand is given, show available subcommands.
217
217
  - Git sync engine: `src/git-sync.js`
218
218
  - Export/import: `src/export-import.js`
219
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
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
222
  - All git operations use `execFileSync` — no npm dependencies
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "brain-memory",
3
- "version": "0.1.0-beta.7",
3
+ "version": "0.1.0-beta.8",
4
4
  "description": "A brain-inspired hierarchical memory system for AI coding agents. Deep nested file structure that mimics human memory with time-decay and strength-based recall.",
5
5
  "keywords": [
6
6
  "claude-code",
package/prompts/claude.md CHANGED
@@ -4,7 +4,7 @@ This project uses the **Brain Memory** plugin — a hierarchical, file-system-ba
4
4
 
5
5
  ## Memory Location
6
6
 
7
- All memories are stored in `.brain/` with a deep nested directory structure organized by life domains (professional, personal, social, family) with on-demand subcategories.
7
+ All memories are stored in a single global `~/.brain/` directory in the user's home folder, shared across all projects and all supported AI agents. The directory uses a deep nested structure organized by life domains (professional, personal, social, family) with on-demand subcategories.
8
8
 
9
9
  ## How It Works
10
10
 
@@ -37,7 +37,7 @@ Each memory is a Markdown file with YAML frontmatter containing: `id`, `type`, `
37
37
  | observation | 0.40 | 0.950 | Casual facts or notices |
38
38
 
39
39
  ### Associative Network
40
- Memories are connected via weighted edges in `.brain/associations.json`. When you recall memory A, **spreading activation** automatically surfaces related memories B and C — just like how the brain activates linked neurons. Links are strengthened through **Hebbian learning**: memories recalled together become more tightly connected over time.
40
+ Memories are connected via weighted edges in `~/.brain/associations.json`. When you recall memory A, **spreading activation** automatically surfaces related memories B and C — just like how the brain activates linked neurons. Links are strengthened through **Hebbian learning**: memories recalled together become more tightly connected over time.
41
41
 
42
42
  ### Context-Dependent Recall
43
43
  Memories store their encoding context (project, topics, task type). During recall, memories encoded in a similar context to the current session are scored higher — matching how human memory works better when recall context matches encoding context.
@@ -64,12 +64,12 @@ Memories store their encoding context (project, topics, task type). During recal
64
64
 
65
65
  **IMPORTANT: Perform these steps automatically at the beginning of every session.**
66
66
 
67
- If `.brain/index.json` exists in the current project:
67
+ If `~/.brain/index.json` exists:
68
68
 
69
69
  1. **Read the index** to understand the current brain state (memory count, categories)
70
70
  2. **Identify high-value memories** — the top 3-5 memories by effective strength that are relevant to the current project context
71
71
  3. **Silently internalize** these memories so you can reference them naturally during the session — do NOT dump memory contents
72
- 4. **Check review queue** — read `.brain/review-queue.json` if it exists for memories due for review
72
+ 4. **Check review queue** — read `~/.brain/review-queue.json` if it exists for memories due for review
73
73
  5. **Capture session context** — note the current project name, inferred topics, and task type for context-dependent recall
74
74
  6. **Output a brief status** (1-3 lines):
75
75
 
@@ -110,24 +110,24 @@ If the session contained meaningful content in any of these categories, suggest:
110
110
  - Do NOT auto-memorize without user consent
111
111
  - Do NOT prompt for trivial sessions (quick fixes, typo corrections, simple questions)
112
112
  - Only suggest when there is genuinely valuable context worth preserving
113
- - Always save session context to `.brain/contexts.json` regardless (append a session summary, keep last 20 entries)
113
+ - Always save session context to `~/.brain/contexts.json` regardless (append a session summary, keep last 20 entries)
114
114
 
115
115
  ## When Recalling Memories
116
116
 
117
117
  When the user asks you to "remember" something, or when context from past sessions would be helpful:
118
- 1. Check `.brain/index.json` for relevant memories
119
- 2. Load `.brain/associations.json` for spreading activation
118
+ 1. Check `~/.brain/index.json` for relevant memories
119
+ 2. Load `~/.brain/associations.json` for spreading activation
120
120
  3. Score by v4 formula: `0.38*relevance + 0.18*decayed_strength + 0.08*recency + 0.14*spreading_bonus + 0.14*context_match + 0.08*salience`
121
121
  4. Return strong individual matches or synthesize from multiple related memories
122
122
  5. Apply spaced reinforcement (spacing-aware boost) and improve decay rate
123
123
  6. Strengthen Hebbian links between co-retrieved memories
124
- 7. If no active matches, search the archive (`.brain/_archived/`)
124
+ 7. If no active matches, search the archive (`~/.brain/_archived/`)
125
125
 
126
126
  ## Portable Sync
127
127
 
128
128
  Brain memories can be synced across devices in two ways:
129
129
 
130
- 1. **Git remote** — Push/pull `.brain/` to any private Git repository (GitHub, GitLab, Codeberg, self-hosted). Run `/brain:sync setup <url>` to configure, then use `/brain:sync push` and `/brain:sync pull`.
131
- 2. **Export/Import** — Pack the entire `.brain/` into a single portable file for manual transfer. Run `/brain:sync export` and `/brain:sync import <path>`.
130
+ 1. **Git remote** — Push/pull `~/.brain/` to any private Git repository (GitHub, GitLab, Codeberg, self-hosted). Run `/brain:sync setup <url>` to configure, then use `/brain:sync push` and `/brain:sync pull`.
131
+ 2. **Export/Import** — Pack the entire `~/.brain/` into a single portable file for manual transfer. Run `/brain:sync export` and `/brain:sync import <path>`.
132
132
 
133
133
  Both methods support optional AES-256-GCM encryption. Sync is always manual — never automatic.
package/prompts/gemini.md CHANGED
@@ -4,7 +4,7 @@ This project uses the **Brain Memory** plugin — a hierarchical, file-system-ba
4
4
 
5
5
  ## Memory Location
6
6
 
7
- All memories are stored in `.brain/` with a deep nested directory structure organized by life domains (professional, personal, social, family) with on-demand subcategories.
7
+ All memories are stored in a single global `~/.brain/` directory in the user's home folder, shared across all projects and all supported AI agents. The directory uses a deep nested structure organized by life domains (professional, personal, social, family) with on-demand subcategories.
8
8
 
9
9
  ## How It Works
10
10
 
@@ -37,7 +37,7 @@ Each memory is a Markdown file with YAML frontmatter containing: `id`, `type`, `
37
37
  | observation | 0.40 | 0.950 | Casual facts or notices |
38
38
 
39
39
  ### Associative Network
40
- Memories are connected via weighted edges in `.brain/associations.json`. When you recall memory A, **spreading activation** automatically surfaces related memories B and C — just like how the brain activates linked neurons. Links are strengthened through **Hebbian learning**: memories recalled together become more tightly connected over time.
40
+ Memories are connected via weighted edges in `~/.brain/associations.json`. When you recall memory A, **spreading activation** automatically surfaces related memories B and C — just like how the brain activates linked neurons. Links are strengthened through **Hebbian learning**: memories recalled together become more tightly connected over time.
41
41
 
42
42
  ### Context-Dependent Recall
43
43
  Memories store their encoding context (project, topics, task type). During recall, memories encoded in a similar context to the current session are scored higher — matching how human memory works better when recall context matches encoding context.
@@ -65,12 +65,12 @@ Commands are available via `/brain:` prefix:
65
65
 
66
66
  **IMPORTANT: Perform these steps automatically at the beginning of every session.**
67
67
 
68
- If `.brain/index.json` exists in the current project:
68
+ If `~/.brain/index.json` exists:
69
69
 
70
70
  1. **Read the index** to understand the current brain state (memory count, categories)
71
71
  2. **Identify high-value memories** — the top 3-5 memories by effective strength that are relevant to the current project context
72
72
  3. **Silently internalize** these memories so you can reference them naturally during the session — do NOT dump memory contents
73
- 4. **Check review queue** — read `.brain/review-queue.json` if it exists for memories due for review
73
+ 4. **Check review queue** — read `~/.brain/review-queue.json` if it exists for memories due for review
74
74
  5. **Capture session context** — note the current project name, inferred topics, and task type for context-dependent recall
75
75
  6. **Output a brief status** (1-3 lines):
76
76
 
@@ -111,24 +111,24 @@ If the session contained meaningful content in any of these categories, suggest:
111
111
  - Do NOT auto-memorize without user consent
112
112
  - Do NOT prompt for trivial sessions (quick fixes, typo corrections, simple questions)
113
113
  - Only suggest when there is genuinely valuable context worth preserving
114
- - Always save session context to `.brain/contexts.json` regardless (append a session summary, keep last 20 entries)
114
+ - Always save session context to `~/.brain/contexts.json` regardless (append a session summary, keep last 20 entries)
115
115
 
116
116
  ## When Recalling Memories
117
117
 
118
118
  When the user asks you to "remember" something, or when context from past sessions would be helpful:
119
- 1. Check `.brain/index.json` for relevant memories
120
- 2. Load `.brain/associations.json` for spreading activation
119
+ 1. Check `~/.brain/index.json` for relevant memories
120
+ 2. Load `~/.brain/associations.json` for spreading activation
121
121
  3. Score by v4 formula: `0.38*relevance + 0.18*decayed_strength + 0.08*recency + 0.14*spreading_bonus + 0.14*context_match + 0.08*salience`
122
122
  4. Return strong individual matches or synthesize from multiple related memories
123
123
  5. Apply spaced reinforcement (spacing-aware boost) and improve decay rate
124
124
  6. Strengthen Hebbian links between co-retrieved memories
125
- 7. If no active matches, search the archive (`.brain/_archived/`)
125
+ 7. If no active matches, search the archive (`~/.brain/_archived/`)
126
126
 
127
127
  ## Portable Sync
128
128
 
129
129
  Brain memories can be synced across devices in two ways:
130
130
 
131
- 1. **Git remote** — Push/pull `.brain/` to any private Git repository (GitHub, GitLab, Codeberg, self-hosted). Run `/brain:sync setup <url>` to configure, then use `/brain:sync push` and `/brain:sync pull`.
132
- 2. **Export/Import** — Pack the entire `.brain/` into a single portable file for manual transfer. Run `/brain:sync export` and `/brain:sync import <path>`.
131
+ 1. **Git remote** — Push/pull `~/.brain/` to any private Git repository (GitHub, GitLab, Codeberg, self-hosted). Run `/brain:sync setup <url>` to configure, then use `/brain:sync push` and `/brain:sync pull`.
132
+ 2. **Export/Import** — Pack the entire `~/.brain/` into a single portable file for manual transfer. Run `/brain:sync export` and `/brain:sync import <path>`.
133
133
 
134
134
  Both methods support optional AES-256-GCM encryption. Sync is always manual — never automatic.
@@ -2,7 +2,7 @@
2
2
  * Brain Memory — Export / Import
3
3
  *
4
4
  * Single-file encrypted export/import for portable memory transfers.
5
- * Pack all .brain/ files into one JSON blob, optionally AES-256-GCM encrypt,
5
+ * Pack all ~/.brain/ files into one JSON blob, optionally AES-256-GCM encrypt,
6
6
  * and write a single .brain-export file. Import reverses the process.
7
7
  *
8
8
  * Zero external dependencies — uses only Node.js built-in fs and crypto.
@@ -12,20 +12,20 @@ const fs = require('fs');
12
12
  const path = require('path');
13
13
  const { encrypt, decrypt } = require('./crypto');
14
14
 
15
- // Directories inside .brain/ to skip during export
15
+ // Directories inside ~/.brain/ to skip during export
16
16
  const EXCLUDED = new Set(['.sync', '.DS_Store']);
17
17
 
18
18
  /**
19
- * Export the entire .brain/ directory to a single file.
19
+ * Export the entire ~/.brain/ directory to a single file.
20
20
  *
21
- * @param {string} brainDir - Absolute path to .brain/
21
+ * @param {string} brainDir - Absolute path to ~/.brain/
22
22
  * @param {string} outputPath - Destination file path
23
23
  * @param {string|null} [passphrase] - If provided, encrypt the export
24
24
  * @returns {{ fileCount: number, outputPath: string }}
25
25
  */
26
26
  function exportBrain(brainDir, outputPath, passphrase) {
27
27
  if (!fs.existsSync(brainDir)) {
28
- throw new Error('.brain/ directory not found. Run /brain:init first.');
28
+ throw new Error('~/.brain/ directory not found. Run /brain:init first.');
29
29
  }
30
30
 
31
31
  const files = {};
@@ -47,7 +47,7 @@ function exportBrain(brainDir, outputPath, passphrase) {
47
47
  * Recursively collect all files from brainDir into a flat { relativePath: content } map.
48
48
  *
49
49
  * @param {string} dir - Current directory to scan
50
- * @param {string} brainDir - Root .brain/ directory
50
+ * @param {string} brainDir - Root ~/.brain/ directory
51
51
  * @param {Object} files - Accumulator object
52
52
  */
53
53
  function collectFiles(dir, brainDir, files) {
@@ -69,10 +69,10 @@ function collectFiles(dir, brainDir, files) {
69
69
  }
70
70
 
71
71
  /**
72
- * Import memories from a .brain-export file into .brain/.
72
+ * Import memories from a .brain-export file into ~/.brain/.
73
73
  *
74
74
  * @param {string} inputPath - Path to the export file
75
- * @param {string} brainDir - Absolute path to .brain/
75
+ * @param {string} brainDir - Absolute path to ~/.brain/
76
76
  * @param {string|null} [passphrase] - Decryption passphrase (if the export is encrypted)
77
77
  * @param {Object} [options]
78
78
  * @param {string} [options.mode='overwrite'] - 'overwrite' replaces all files; 'merge' only imports newer files
@@ -142,7 +142,7 @@ function importBrain(inputPath, brainDir, passphrase, options = {}) {
142
142
  * Preview what an import would do without writing any files.
143
143
  *
144
144
  * @param {string} inputPath - Path to the export file
145
- * @param {string} brainDir - Absolute path to .brain/
145
+ * @param {string} brainDir - Absolute path to ~/.brain/
146
146
  * @param {string|null} [passphrase] - Decryption passphrase
147
147
  * @returns {{ totalFiles: number, newFiles: string[], existingFiles: string[], exportedAt: string }}
148
148
  */
package/src/git-sync.js CHANGED
@@ -1,8 +1,8 @@
1
1
  /**
2
2
  * Brain Memory — Git Sync Engine
3
3
  *
4
- * Push/pull .brain/ memories via any Git remote (GitHub, GitLab, Codeberg, etc.).
5
- * A hidden git repo lives at .brain/.sync/repo/ — the project's own git history
4
+ * Push/pull ~/.brain/ memories via any Git remote (GitHub, GitLab, Codeberg, etc.).
5
+ * A hidden git repo lives at ~/.brain/.sync/repo/ — the project's own git history
6
6
  * is never touched.
7
7
  *
8
8
  * Zero external dependencies — uses child_process.execFileSync to call the git binary.
@@ -17,7 +17,7 @@ const SYNC_DIR = '.sync';
17
17
  const REPO_DIR = 'repo';
18
18
  const CONFIG_FILE = 'config.json';
19
19
 
20
- // Files/dirs inside .brain/ that should NOT be synced
20
+ // Files/dirs inside ~/.brain/ that should NOT be synced
21
21
  const EXCLUDED = new Set(['.sync', '.DS_Store']);
22
22
 
23
23
  /**
@@ -37,7 +37,7 @@ function checkGitAvailable() {
37
37
  /**
38
38
  * Run a git command inside the sync repo.
39
39
  *
40
- * @param {string} repoDir - Absolute path to .brain/.sync/repo/
40
+ * @param {string} repoDir - Absolute path to ~/.brain/.sync/repo/
41
41
  * @param {string[]} args - Git arguments
42
42
  * @param {Object} [opts] - Extra execFileSync options
43
43
  * @returns {string} stdout (trimmed)
@@ -45,7 +45,7 @@ function checkGitAvailable() {
45
45
  function git(repoDir, args, opts = {}) {
46
46
  // Explicitly set GIT_DIR and GIT_WORK_TREE to prevent git from walking up
47
47
  // the directory tree and finding the parent project's .git directory.
48
- // Without this, if .brain/.sync/repo/.git doesn't exist yet (first push or
48
+ // Without this, if ~/.brain/.sync/repo/.git doesn't exist yet (first push or
49
49
  // failed init), git operations would silently affect the parent project repo.
50
50
  const env = {
51
51
  ...process.env,
@@ -64,7 +64,7 @@ function git(repoDir, args, opts = {}) {
64
64
  /**
65
65
  * Resolve paths for sync infrastructure.
66
66
  *
67
- * @param {string} brainDir - Absolute path to .brain/
67
+ * @param {string} brainDir - Absolute path to ~/.brain/
68
68
  * @returns {{ syncDir: string, repoDir: string, configPath: string }}
69
69
  */
70
70
  function resolvePaths(brainDir) {
@@ -75,9 +75,9 @@ function resolvePaths(brainDir) {
75
75
  }
76
76
 
77
77
  /**
78
- * Initialize a git repo inside .brain/.sync/repo/.
78
+ * Initialize a git repo inside ~/.brain/.sync/repo/.
79
79
  *
80
- * @param {string} brainDir - Absolute path to .brain/
80
+ * @param {string} brainDir - Absolute path to ~/.brain/
81
81
  * @returns {{ repoDir: string }} Created repo path
82
82
  */
83
83
  function initSyncRepo(brainDir) {
@@ -94,7 +94,7 @@ function initSyncRepo(brainDir) {
94
94
  /**
95
95
  * Configure (or update) the remote URL for the sync repo.
96
96
  *
97
- * @param {string} brainDir - Absolute path to .brain/
97
+ * @param {string} brainDir - Absolute path to ~/.brain/
98
98
  * @param {string} remoteUrl - Git remote URL (SSH or HTTPS)
99
99
  */
100
100
  function configureRemote(brainDir, remoteUrl) {
@@ -111,11 +111,11 @@ function configureRemote(brainDir, remoteUrl) {
111
111
  }
112
112
 
113
113
  /**
114
- * Copy .brain/ files into the sync repo, excluding .sync/.
114
+ * Copy ~/.brain/ files into the sync repo, excluding .sync/.
115
115
  * If encryption is enabled, files are encrypted before writing.
116
116
  *
117
- * @param {string} brainDir - Absolute path to .brain/
118
- * @param {string} repoDir - Absolute path to .brain/.sync/repo/
117
+ * @param {string} brainDir - Absolute path to ~/.brain/
118
+ * @param {string} repoDir - Absolute path to ~/.brain/.sync/repo/
119
119
  * @param {string|null} passphrase - Encryption passphrase or null
120
120
  */
121
121
  function copyBrainToRepo(brainDir, repoDir, passphrase) {
@@ -126,7 +126,7 @@ function copyBrainToRepo(brainDir, repoDir, passphrase) {
126
126
  fs.rmSync(path.join(repoDir, entry), { recursive: true, force: true });
127
127
  }
128
128
 
129
- // Recursively copy .brain/ → repo/
129
+ // Recursively copy ~/.brain/ → repo/
130
130
  copyDir(brainDir, repoDir, brainDir, passphrase);
131
131
  }
132
132
 
@@ -163,11 +163,11 @@ function copyDir(srcDir, destDir, brainDir, passphrase) {
163
163
  }
164
164
 
165
165
  /**
166
- * Copy files from the sync repo back into .brain/.
166
+ * Copy files from the sync repo back into ~/.brain/.
167
167
  * If encryption is enabled, files are decrypted after reading.
168
168
  *
169
- * @param {string} repoDir - Absolute path to .brain/.sync/repo/
170
- * @param {string} brainDir - Absolute path to .brain/
169
+ * @param {string} repoDir - Absolute path to ~/.brain/.sync/repo/
170
+ * @param {string} brainDir - Absolute path to ~/.brain/
171
171
  * @param {string|null} passphrase - Decryption passphrase or null
172
172
  */
173
173
  function copyRepoToBrain(repoDir, brainDir, passphrase) {
@@ -202,7 +202,7 @@ function copyRepoDir(srcDir, destDir, repoDir, passphrase) {
202
202
  /**
203
203
  * Get a summary of local vs remote sync status.
204
204
  *
205
- * @param {string} brainDir - Absolute path to .brain/
205
+ * @param {string} brainDir - Absolute path to ~/.brain/
206
206
  * @returns {{ configured: boolean, remote: string|null, branch: string|null, ahead: number, behind: number, lastPush: string|null }}
207
207
  */
208
208
  function getStatus(brainDir) {
@@ -244,9 +244,9 @@ function getStatus(brainDir) {
244
244
  }
245
245
 
246
246
  /**
247
- * Push .brain/ contents to the remote.
247
+ * Push ~/.brain/ contents to the remote.
248
248
  *
249
- * @param {string} brainDir - Absolute path to .brain/
249
+ * @param {string} brainDir - Absolute path to ~/.brain/
250
250
  * @param {string} [message] - Commit message (defaults to timestamp)
251
251
  * @param {string} [passphrase] - Encryption passphrase (if configured)
252
252
  * @returns {{ committed: boolean, pushed: boolean, message: string }}
@@ -302,9 +302,9 @@ function push(brainDir, message, passphrase) {
302
302
  }
303
303
 
304
304
  /**
305
- * Pull remote changes into .brain/.
305
+ * Pull remote changes into ~/.brain/.
306
306
  *
307
- * @param {string} brainDir - Absolute path to .brain/
307
+ * @param {string} brainDir - Absolute path to ~/.brain/
308
308
  * @param {string} [passphrase] - Decryption passphrase (if configured)
309
309
  * @returns {{ pulled: boolean, message: string }}
310
310
  */
@@ -329,7 +329,7 @@ function pull(brainDir, passphrase) {
329
329
  } catch (err) {
330
330
  // Could be first pull (nothing to pull), or merge conflict
331
331
  if (err.message && err.message.includes('Not possible to fast-forward')) {
332
- return { pulled: false, message: 'Merge conflict detected. Push your local changes first, or manually resolve in .brain/.sync/repo/' };
332
+ return { pulled: false, message: 'Merge conflict detected. Push your local changes first, or manually resolve in ~/.brain/.sync/repo/' };
333
333
  }
334
334
  // First clone — try to set up tracking
335
335
  try {
@@ -351,7 +351,7 @@ function pull(brainDir, passphrase) {
351
351
  }
352
352
 
353
353
  /**
354
- * Read sync config from .brain/.sync/config.json.
354
+ * Read sync config from ~/.brain/.sync/config.json.
355
355
  *
356
356
  * @param {string} configPath - Absolute path to config.json
357
357
  * @returns {Object|null}
@@ -365,7 +365,7 @@ function readConfig(configPath) {
365
365
  }
366
366
 
367
367
  /**
368
- * Write sync config to .brain/.sync/config.json.
368
+ * Write sync config to ~/.brain/.sync/config.json.
369
369
  *
370
370
  * @param {string} configPath - Absolute path to config.json
371
371
  * @param {Object} config
@@ -378,7 +378,7 @@ function writeConfig(configPath, config) {
378
378
  /**
379
379
  * Read the sync config for a brain directory.
380
380
  *
381
- * @param {string} brainDir - Absolute path to .brain/
381
+ * @param {string} brainDir - Absolute path to ~/.brain/
382
382
  * @returns {Object|null}
383
383
  */
384
384
  function getSyncConfig(brainDir) {
@@ -389,7 +389,7 @@ function getSyncConfig(brainDir) {
389
389
  /**
390
390
  * Write the sync config for a brain directory.
391
391
  *
392
- * @param {string} brainDir - Absolute path to .brain/
392
+ * @param {string} brainDir - Absolute path to ~/.brain/
393
393
  * @param {Object} config
394
394
  */
395
395
  function writeSyncConfig(brainDir, config) {
@@ -1,14 +1,15 @@
1
1
  /**
2
2
  * Brain Memory — Index Manager
3
3
  *
4
- * Utilities for reading, updating, and maintaining the .brain/index.json
4
+ * Utilities for reading, updating, and maintaining the ~/.brain/index.json
5
5
  * file. Used by hooks and external integrations.
6
6
  */
7
7
 
8
8
  const fs = require('fs');
9
9
  const path = require('path');
10
+ const os = require('os');
10
11
 
11
- const DEFAULT_BRAIN_DIR = '.brain';
12
+ const DEFAULT_BRAIN_DIR = path.join(os.homedir(), '.brain');
12
13
  const INDEX_FILE = 'index.json';
13
14
  const ASSOCIATIONS_FILE = 'associations.json';
14
15
  const CONTEXTS_FILE = 'contexts.json';
@@ -18,11 +19,12 @@ const ARCHIVE_INDEX_FILE = '_archived/index.json';
18
19
  /**
19
20
  * Resolve the brain directory path.
20
21
  *
21
- * @param {string} [projectRoot] - Project root directory (defaults to cwd)
22
- * @returns {string} Absolute path to .brain/
22
+ * @param {string} [overrideBase] - Override base directory (for testing)
23
+ * @returns {string} Absolute path to ~/.brain/ (or overrideBase/.brain/ if provided)
23
24
  */
24
- function getBrainDir(projectRoot) {
25
- return path.join(projectRoot || process.cwd(), DEFAULT_BRAIN_DIR);
25
+ function getBrainDir(overrideBase) {
26
+ if (overrideBase) return path.join(overrideBase, '.brain');
27
+ return DEFAULT_BRAIN_DIR;
26
28
  }
27
29
 
28
30
  /**
@@ -106,7 +108,7 @@ function generateId() {
106
108
  /**
107
109
  * Read a _meta.json file from a brain subdirectory.
108
110
  *
109
- * @param {string} categoryPath - Relative path within .brain/
111
+ * @param {string} categoryPath - Relative path within ~/.brain/
110
112
  * @param {string} [projectRoot] - Project root directory
111
113
  * @returns {Object|null} Parsed meta or null
112
114
  */
@@ -119,7 +121,7 @@ function readMeta(categoryPath, projectRoot) {
119
121
  /**
120
122
  * Write a _meta.json file to a brain subdirectory.
121
123
  *
122
- * @param {string} categoryPath - Relative path within .brain/
124
+ * @param {string} categoryPath - Relative path within ~/.brain/
123
125
  * @param {Object} meta - Meta object to write
124
126
  * @param {string} [projectRoot] - Project root directory
125
127
  */
package/src/installer.js CHANGED
@@ -210,8 +210,8 @@ function installForRuntime(runtime, scope) {
210
210
  injectPrompt(promptTarget, config.promptFile, config.promptSource);
211
211
  }
212
212
 
213
- function initializeBrain(projectDir) {
214
- const brainDir = path.join(projectDir || process.cwd(), '.brain');
213
+ function initializeBrain(overrideBase) {
214
+ const brainDir = path.join(overrideBase || os.homedir(), '.brain');
215
215
 
216
216
  if (fs.existsSync(brainDir)) {
217
217
  return { alreadyExists: true };