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.
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/
@@ -57,6 +57,22 @@ npx brain-memory --codex --global # OpenAI Codex CLI, global
57
57
  npx brain-memory --all --global # All runtimes, global
58
58
  ```
59
59
 
60
+ ### Update
61
+
62
+ ```bash
63
+ npx brain-memory@beta update
64
+ ```
65
+
66
+ Auto-detects installed runtimes and refreshes commands + prompt sections. Target specific runtimes with `--claude`, `--gemini`, `--openai`, or `--all`.
67
+
68
+ ### Uninstall
69
+
70
+ ```bash
71
+ npx brain-memory@beta uninstall
72
+ ```
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.
75
+
60
76
  ### Manual Install
61
77
 
62
78
  Copy the `commands/brain/` directory to your agent's commands folder:
@@ -85,7 +101,7 @@ Then append the contents of the corresponding prompt file to your agent's instru
85
101
 
86
102
  | Command | Description |
87
103
  |---------|-------------|
88
- | `/brain:init` | Initialize `.brain/` directory structure with default categories |
104
+ | `/brain:init` | Initialize `~/.brain/` directory structure with default categories |
89
105
  | `/brain:memorize [topic]` | Store memories from current session context |
90
106
  | `/brain:remember [query]` | Recall relevant memories with spreading activation and context matching |
91
107
  | `/brain:review [scope]` | Spaced repetition review session for due memories |
@@ -103,7 +119,7 @@ Brain Memory works automatically in the background — no commands needed for ba
103
119
 
104
120
  ### Session Start
105
121
 
106
- When a session begins and `.brain/` exists, the agent automatically:
122
+ When a session begins and `~/.brain/` exists, the agent automatically:
107
123
 
108
124
  1. Reads the brain index and loads the top 3-5 memories relevant to the current project
109
125
  2. Checks the review queue for memories due for spaced repetition
@@ -126,7 +142,7 @@ When a session ends, the agent evaluates whether significant decisions, learning
126
142
  Run /brain:memorize to capture them before this context is lost.
127
143
  ```
128
144
 
129
- 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.
130
146
 
131
147
  ## How It Works
132
148
 
@@ -266,7 +282,7 @@ The agent then decides the response strategy:
266
282
 
267
283
  ### Associative Network
268
284
 
269
- Memories are connected via weighted edges in `.brain/associations.json`:
285
+ Memories are connected via weighted edges in `~/.brain/associations.json`:
270
286
 
271
287
  ```json
272
288
  {
@@ -358,13 +374,19 @@ Each expertise area gets an `_expertise.md` profile documenting what you know we
358
374
 
359
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.
360
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
+
361
383
  ### Portable Sync
362
384
 
363
385
  `/brain:sync` provides two ways to sync memories across devices — no OAuth apps, no cloud provider setup.
364
386
 
365
- **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.
366
388
 
367
- **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.
368
390
 
369
391
  **Key features:**
370
392
  - **Manual push/pull** — No background watchers, no auto-sync. You control when data moves.
@@ -379,12 +401,12 @@ Failed recalls reset the interval to 1 day. Successful recalls extend the interv
379
401
 
380
402
  For one-off transfers, use `/brain:sync export` and `/brain:sync import <path>`.
381
403
 
382
- 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.
383
405
 
384
406
  ## File Structure
385
407
 
386
408
  ```
387
- .brain/
409
+ ~/.brain/
388
410
  ├── index.json # Memory inventory — fast lookup for all memories
389
411
  ├── associations.json # Weighted associative network between memories
390
412
  ├── contexts.json # Session context snapshots for context-dependent recall
@@ -423,7 +445,7 @@ Subdirectories are created **on demand** — the agent decides placement depth b
423
445
 
424
446
  ## Configuration
425
447
 
426
- Brain configuration lives in `.brain/index.json` under the `config` key:
448
+ Brain configuration lives in `~/.brain/index.json` under the `config` key:
427
449
 
428
450
  ```json
429
451
  {
package/bin/install.js CHANGED
@@ -1,10 +1,15 @@
1
1
  #!/usr/bin/env node
2
2
 
3
3
  const readline = require('readline');
4
+ const fs = require('fs');
5
+ const path = require('path');
6
+ const os = require('os');
4
7
  const {
5
8
  RUNTIMES,
6
9
  installForRuntime,
7
10
  initializeBrain,
11
+ detectInstallations,
12
+ uninstallForRuntime,
8
13
  } = require('../src/installer');
9
14
 
10
15
  function createRL() {
@@ -18,30 +23,50 @@ function ask(rl, question) {
18
23
  return new Promise((resolve) => rl.question(question, resolve));
19
24
  }
20
25
 
21
- async function main() {
22
- console.log(`
23
- ╔══════════════════════════════════════════════════════╗
24
- ║ ║
25
- ║ 🧠 Brain Memory — Installer ║
26
- ║ ║
27
- ║ Hierarchical memory system for AI coding agents ║
28
- ║ ║
29
- ╚══════════════════════════════════════════════════════╝
30
- `);
26
+ function parseArgs(argv) {
27
+ const args = argv.slice(2);
28
+ const subcommands = ['install', 'update', 'uninstall'];
29
+ let subcommand = 'install';
30
+ const flags = new Set();
31
31
 
32
- const args = process.argv.slice(2);
33
- const flags = new Set(args.map((a) => a.replace(/^--/, '')));
32
+ for (const arg of args) {
33
+ const clean = arg.replace(/^--/, '');
34
+ if (subcommands.includes(clean) && arg === clean) {
35
+ // positional subcommand (no --)
36
+ subcommand = clean;
37
+ } else if (clean === 'update') {
38
+ subcommand = 'update';
39
+ } else if (clean === 'uninstall') {
40
+ subcommand = 'uninstall';
41
+ } else {
42
+ flags.add(clean);
43
+ }
44
+ }
34
45
 
35
- let runtimes = [];
36
- let scope = null;
46
+ return { subcommand, flags };
47
+ }
37
48
 
38
- // Check for non-interactive flags
49
+ function resolveRuntimesFromFlags(flags) {
50
+ const runtimes = [];
39
51
  if (flags.has('claude')) runtimes.push('claude');
40
52
  if (flags.has('gemini')) runtimes.push('gemini');
41
53
  if (flags.has('openai') || flags.has('codex')) runtimes.push('openai');
42
- if (flags.has('all')) runtimes = ['claude', 'gemini', 'openai'];
43
- if (flags.has('global')) scope = 'global';
44
- if (flags.has('local')) scope = 'local';
54
+ if (flags.has('all')) return ['claude', 'gemini', 'openai'];
55
+ return runtimes;
56
+ }
57
+
58
+ function resolveScopeFromFlags(flags) {
59
+ if (flags.has('global')) return 'global';
60
+ if (flags.has('local')) return 'local';
61
+ return null;
62
+ }
63
+
64
+ // ---------------------------------------------------------------------------
65
+ // Install (original behavior, refactored from main)
66
+ // ---------------------------------------------------------------------------
67
+ async function runInstall(flags) {
68
+ let runtimes = resolveRuntimesFromFlags(flags);
69
+ let scope = resolveScopeFromFlags(flags);
45
70
 
46
71
  const rl = createRL();
47
72
 
@@ -90,7 +115,7 @@ async function main() {
90
115
  console.log('');
91
116
  const initBrain = await ask(
92
117
  rl,
93
- ' Initialize .brain/ directory in current project? (Y/n): '
118
+ ' Initialize ~/.brain/ directory? (Y/n): '
94
119
  );
95
120
 
96
121
  // Perform installation
@@ -106,12 +131,11 @@ async function main() {
106
131
  if (initBrain.trim().toLowerCase() !== 'n') {
107
132
  const result = initializeBrain();
108
133
  if (result.alreadyExists) {
109
- console.log('\n .brain/ already exists, skipping initialization.');
134
+ console.log('\n ~/.brain/ already exists, skipping initialization.');
110
135
  } else {
111
- console.log('\n .brain/ initialized successfully.');
136
+ console.log('\n ~/.brain/ initialized successfully.');
112
137
  console.log('');
113
- console.log(' ☁️ Cloud sync is available! Use /brain:sync login to connect');
114
- console.log(' Dropbox, Google Drive, or OneDrive for cross-device access.');
138
+ console.log(' Use /brain:sync to set up portable sync across devices.');
115
139
  }
116
140
  }
117
141
 
@@ -129,7 +153,7 @@ async function main() {
129
153
  /brain:sunshine Deep forensic memory erasure
130
154
  /brain:sleep Full maintenance cycle
131
155
  /brain:status Brain overview dashboard
132
- /brain:sync Cloud sync (Dropbox/Google Drive/OneDrive)
156
+ /brain:sync Sync memories via Git remote or export/import
133
157
 
134
158
  Get started by running /brain:init in your agent session.
135
159
  `);
@@ -138,7 +162,170 @@ async function main() {
138
162
  }
139
163
  }
140
164
 
165
+ // ---------------------------------------------------------------------------
166
+ // Update
167
+ // ---------------------------------------------------------------------------
168
+ async function runUpdate(flags) {
169
+ const pkg = JSON.parse(
170
+ fs.readFileSync(path.join(__dirname, '..', 'package.json'), 'utf-8')
171
+ );
172
+ const version = pkg.version;
173
+
174
+ console.log(' Detecting existing installations...\n');
175
+
176
+ let detections = detectInstallations();
177
+
178
+ // Filter by explicit flags if provided
179
+ const filterRuntimes = resolveRuntimesFromFlags(flags);
180
+ const filterScope = resolveScopeFromFlags(flags);
181
+ if (filterRuntimes.length > 0) {
182
+ detections = detections.filter((d) => filterRuntimes.includes(d.runtime));
183
+ }
184
+ if (filterScope) {
185
+ detections = detections.filter((d) => d.scope === filterScope);
186
+ }
187
+
188
+ if (detections.length === 0) {
189
+ console.log(' No existing brain-memory installations found.\n');
190
+ console.log(' To install, run: npx brain-memory@beta');
191
+ if (filterRuntimes.length > 0) {
192
+ console.log(` (Searched for: ${filterRuntimes.join(', ')})`);
193
+ }
194
+ return;
195
+ }
196
+
197
+ console.log(` Found ${detections.length} installation(s):\n`);
198
+ for (const d of detections) {
199
+ const parts = [];
200
+ if (d.commandsFound) parts.push('commands');
201
+ if (d.promptFound) parts.push('prompt');
202
+ console.log(` ${d.runtimeName} (${d.scope}) — ${parts.join(' + ')}`);
203
+ }
204
+
205
+ console.log('\n Updating...');
206
+ for (const d of detections) {
207
+ console.log(`\n Updating ${d.runtimeName} (${d.scope})...`);
208
+ installForRuntime(d.runtime, d.scope);
209
+ console.log(' Done!');
210
+ }
211
+
212
+ console.log(`\n ✓ Updated to v${version}\n`);
213
+ }
214
+
215
+ // ---------------------------------------------------------------------------
216
+ // Uninstall
217
+ // ---------------------------------------------------------------------------
218
+ async function runUninstall(flags) {
219
+ console.log(' Detecting existing installations...\n');
220
+
221
+ let detections = detectInstallations();
222
+
223
+ // Filter by explicit flags if provided
224
+ const filterRuntimes = resolveRuntimesFromFlags(flags);
225
+ const filterScope = resolveScopeFromFlags(flags);
226
+ if (filterRuntimes.length > 0) {
227
+ detections = detections.filter((d) => filterRuntimes.includes(d.runtime));
228
+ }
229
+ if (filterScope) {
230
+ detections = detections.filter((d) => d.scope === filterScope);
231
+ }
232
+
233
+ if (detections.length === 0) {
234
+ console.log(' No existing brain-memory installations found. Nothing to uninstall.\n');
235
+ return;
236
+ }
237
+
238
+ console.log(` Will remove ${detections.length} installation(s):\n`);
239
+ for (const d of detections) {
240
+ const parts = [];
241
+ if (d.commandsFound) parts.push('commands');
242
+ if (d.promptFound) parts.push('prompt section');
243
+ console.log(` ${d.runtimeName} (${d.scope}) — ${parts.join(' + ')}`);
244
+ }
245
+
246
+ // Confirm unless --yes
247
+ if (!flags.has('yes') && !flags.has('y')) {
248
+ const rl = createRL();
249
+ try {
250
+ console.log('');
251
+ const answer = await ask(rl, ' Proceed? (y/N): ');
252
+ if (answer.trim().toLowerCase() !== 'y') {
253
+ console.log('\n Cancelled.\n');
254
+ return;
255
+ }
256
+ } finally {
257
+ rl.close();
258
+ }
259
+ }
260
+
261
+ console.log('\n Uninstalling...');
262
+ for (const d of detections) {
263
+ console.log(`\n Removing ${d.runtimeName} (${d.scope})...`);
264
+ uninstallForRuntime(d.runtime, d.scope);
265
+ console.log(' Done!');
266
+ }
267
+
268
+ // Handle .brain/ data
269
+ const brainDir = path.join(os.homedir(), '.brain');
270
+ if (fs.existsSync(brainDir)) {
271
+ if (flags.has('delete-data')) {
272
+ fs.rmSync(brainDir, { recursive: true, force: true });
273
+ console.log('\n Deleted ~/.brain/ directory.');
274
+ } else if (!flags.has('yes') && !flags.has('y')) {
275
+ const rl = createRL();
276
+ try {
277
+ console.log('');
278
+ const answer = await ask(
279
+ rl,
280
+ ' Delete ~/.brain/ data directory? This removes all memories. (y/N): '
281
+ );
282
+ if (answer.trim().toLowerCase() === 'y') {
283
+ fs.rmSync(brainDir, { recursive: true, force: true });
284
+ console.log(' Deleted ~/.brain/ directory.');
285
+ } else {
286
+ console.log(' Kept ~/.brain/ directory (your memories are preserved).');
287
+ }
288
+ } finally {
289
+ rl.close();
290
+ }
291
+ } else {
292
+ console.log('\n Kept ~/.brain/ directory (use --delete-data to remove memories).');
293
+ }
294
+ }
295
+
296
+ console.log('\n ✓ Uninstall complete.\n');
297
+ }
298
+
299
+ // ---------------------------------------------------------------------------
300
+ // Main
301
+ // ---------------------------------------------------------------------------
302
+ async function main() {
303
+ console.log(`
304
+ ╔══════════════════════════════════════════════════════╗
305
+ ║ ║
306
+ ║ 🧠 Brain Memory — Installer ║
307
+ ║ ║
308
+ ║ Hierarchical memory system for AI coding agents ║
309
+ ║ ║
310
+ ╚══════════════════════════════════════════════════════╝
311
+ `);
312
+
313
+ const { subcommand, flags } = parseArgs(process.argv);
314
+
315
+ switch (subcommand) {
316
+ case 'update':
317
+ await runUpdate(flags);
318
+ break;
319
+ case 'uninstall':
320
+ await runUninstall(flags);
321
+ break;
322
+ default:
323
+ await runInstall(flags);
324
+ break;
325
+ }
326
+ }
327
+
141
328
  main().catch((err) => {
142
- console.error('Installation failed:', err.message);
329
+ console.error('Operation failed:', err.message);
143
330
  process.exit(1);
144
331
  });
@@ -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