brain-memory 0.1.0-beta.6 → 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.
@@ -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.6",
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,16 +37,26 @@ 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)
44
44
  */
45
45
  function git(repoDir, args, opts = {}) {
46
+ // Explicitly set GIT_DIR and GIT_WORK_TREE to prevent git from walking up
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
49
+ // failed init), git operations would silently affect the parent project repo.
50
+ const env = {
51
+ ...process.env,
52
+ GIT_DIR: path.join(repoDir, '.git'),
53
+ GIT_WORK_TREE: repoDir,
54
+ };
46
55
  return execFileSync('git', args, {
47
56
  cwd: repoDir,
48
57
  stdio: 'pipe',
49
58
  encoding: 'utf8',
59
+ env,
50
60
  ...opts,
51
61
  }).trim();
52
62
  }
@@ -54,7 +64,7 @@ function git(repoDir, args, opts = {}) {
54
64
  /**
55
65
  * Resolve paths for sync infrastructure.
56
66
  *
57
- * @param {string} brainDir - Absolute path to .brain/
67
+ * @param {string} brainDir - Absolute path to ~/.brain/
58
68
  * @returns {{ syncDir: string, repoDir: string, configPath: string }}
59
69
  */
60
70
  function resolvePaths(brainDir) {
@@ -65,9 +75,9 @@ function resolvePaths(brainDir) {
65
75
  }
66
76
 
67
77
  /**
68
- * Initialize a git repo inside .brain/.sync/repo/.
78
+ * Initialize a git repo inside ~/.brain/.sync/repo/.
69
79
  *
70
- * @param {string} brainDir - Absolute path to .brain/
80
+ * @param {string} brainDir - Absolute path to ~/.brain/
71
81
  * @returns {{ repoDir: string }} Created repo path
72
82
  */
73
83
  function initSyncRepo(brainDir) {
@@ -84,7 +94,7 @@ function initSyncRepo(brainDir) {
84
94
  /**
85
95
  * Configure (or update) the remote URL for the sync repo.
86
96
  *
87
- * @param {string} brainDir - Absolute path to .brain/
97
+ * @param {string} brainDir - Absolute path to ~/.brain/
88
98
  * @param {string} remoteUrl - Git remote URL (SSH or HTTPS)
89
99
  */
90
100
  function configureRemote(brainDir, remoteUrl) {
@@ -101,11 +111,11 @@ function configureRemote(brainDir, remoteUrl) {
101
111
  }
102
112
 
103
113
  /**
104
- * Copy .brain/ files into the sync repo, excluding .sync/.
114
+ * Copy ~/.brain/ files into the sync repo, excluding .sync/.
105
115
  * If encryption is enabled, files are encrypted before writing.
106
116
  *
107
- * @param {string} brainDir - Absolute path to .brain/
108
- * @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/
109
119
  * @param {string|null} passphrase - Encryption passphrase or null
110
120
  */
111
121
  function copyBrainToRepo(brainDir, repoDir, passphrase) {
@@ -116,7 +126,7 @@ function copyBrainToRepo(brainDir, repoDir, passphrase) {
116
126
  fs.rmSync(path.join(repoDir, entry), { recursive: true, force: true });
117
127
  }
118
128
 
119
- // Recursively copy .brain/ → repo/
129
+ // Recursively copy ~/.brain/ → repo/
120
130
  copyDir(brainDir, repoDir, brainDir, passphrase);
121
131
  }
122
132
 
@@ -153,11 +163,11 @@ function copyDir(srcDir, destDir, brainDir, passphrase) {
153
163
  }
154
164
 
155
165
  /**
156
- * Copy files from the sync repo back into .brain/.
166
+ * Copy files from the sync repo back into ~/.brain/.
157
167
  * If encryption is enabled, files are decrypted after reading.
158
168
  *
159
- * @param {string} repoDir - Absolute path to .brain/.sync/repo/
160
- * @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/
161
171
  * @param {string|null} passphrase - Decryption passphrase or null
162
172
  */
163
173
  function copyRepoToBrain(repoDir, brainDir, passphrase) {
@@ -192,7 +202,7 @@ function copyRepoDir(srcDir, destDir, repoDir, passphrase) {
192
202
  /**
193
203
  * Get a summary of local vs remote sync status.
194
204
  *
195
- * @param {string} brainDir - Absolute path to .brain/
205
+ * @param {string} brainDir - Absolute path to ~/.brain/
196
206
  * @returns {{ configured: boolean, remote: string|null, branch: string|null, ahead: number, behind: number, lastPush: string|null }}
197
207
  */
198
208
  function getStatus(brainDir) {
@@ -234,9 +244,9 @@ function getStatus(brainDir) {
234
244
  }
235
245
 
236
246
  /**
237
- * Push .brain/ contents to the remote.
247
+ * Push ~/.brain/ contents to the remote.
238
248
  *
239
- * @param {string} brainDir - Absolute path to .brain/
249
+ * @param {string} brainDir - Absolute path to ~/.brain/
240
250
  * @param {string} [message] - Commit message (defaults to timestamp)
241
251
  * @param {string} [passphrase] - Encryption passphrase (if configured)
242
252
  * @returns {{ committed: boolean, pushed: boolean, message: string }}
@@ -292,9 +302,9 @@ function push(brainDir, message, passphrase) {
292
302
  }
293
303
 
294
304
  /**
295
- * Pull remote changes into .brain/.
305
+ * Pull remote changes into ~/.brain/.
296
306
  *
297
- * @param {string} brainDir - Absolute path to .brain/
307
+ * @param {string} brainDir - Absolute path to ~/.brain/
298
308
  * @param {string} [passphrase] - Decryption passphrase (if configured)
299
309
  * @returns {{ pulled: boolean, message: string }}
300
310
  */
@@ -319,7 +329,7 @@ function pull(brainDir, passphrase) {
319
329
  } catch (err) {
320
330
  // Could be first pull (nothing to pull), or merge conflict
321
331
  if (err.message && err.message.includes('Not possible to fast-forward')) {
322
- 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/' };
323
333
  }
324
334
  // First clone — try to set up tracking
325
335
  try {
@@ -341,7 +351,7 @@ function pull(brainDir, passphrase) {
341
351
  }
342
352
 
343
353
  /**
344
- * Read sync config from .brain/.sync/config.json.
354
+ * Read sync config from ~/.brain/.sync/config.json.
345
355
  *
346
356
  * @param {string} configPath - Absolute path to config.json
347
357
  * @returns {Object|null}
@@ -355,7 +365,7 @@ function readConfig(configPath) {
355
365
  }
356
366
 
357
367
  /**
358
- * Write sync config to .brain/.sync/config.json.
368
+ * Write sync config to ~/.brain/.sync/config.json.
359
369
  *
360
370
  * @param {string} configPath - Absolute path to config.json
361
371
  * @param {Object} config
@@ -368,7 +378,7 @@ function writeConfig(configPath, config) {
368
378
  /**
369
379
  * Read the sync config for a brain directory.
370
380
  *
371
- * @param {string} brainDir - Absolute path to .brain/
381
+ * @param {string} brainDir - Absolute path to ~/.brain/
372
382
  * @returns {Object|null}
373
383
  */
374
384
  function getSyncConfig(brainDir) {
@@ -379,7 +389,7 @@ function getSyncConfig(brainDir) {
379
389
  /**
380
390
  * Write the sync config for a brain directory.
381
391
  *
382
- * @param {string} brainDir - Absolute path to .brain/
392
+ * @param {string} brainDir - Absolute path to ~/.brain/
383
393
  * @param {Object} config
384
394
  */
385
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
  */