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

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
@@ -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:
@@ -95,7 +111,7 @@ Then append the contents of the corresponding prompt file to your agent's instru
95
111
  | `/brain:sunshine [target]` | Deep forensic erasure — trace and remove all references |
96
112
  | `/brain:sleep [scope]` | Full maintenance cycle — 9 neuroscience-inspired phases |
97
113
  | `/brain:status` | Dashboard with brain health metrics and recommendations |
98
- | `/brain:sync [subcommand]` | Cloud sync — push/pull memories to Dropbox, Google Drive, or OneDrive |
114
+ | `/brain:sync [subcommand]` | Sync memories via Git remote or export/import for portability |
99
115
 
100
116
  ## Session Lifecycle
101
117
 
@@ -358,24 +374,28 @@ 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
 
361
- ### Cloud Sync
377
+ ### Portable Sync
362
378
 
363
- `/brain:sync` lets you push and pull your `.brain/` memories to a cloud provider for cross-device access. Supports **Dropbox**, **Google Drive**, and **OneDrive** with zero npm dependencies (uses Node.js 18+ built-in `fetch`).
379
+ `/brain:sync` provides two ways to sync memories across devices — no OAuth apps, no cloud provider setup.
380
+
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.
382
+
383
+ **Export/Import** — Pack the entire `.brain/` into a single encrypted file for manual transfer via USB, email, or any file-sharing service.
364
384
 
365
385
  **Key features:**
366
386
  - **Manual push/pull** — No background watchers, no auto-sync. You control when data moves.
367
- - **Three-way diff** — Compares local state, remote state, and last-known sync state to detect changes and conflicts.
368
- - **Conflict resolution** — When the same file is modified locally and remotely, sync detects the conflict and lets you choose: keep local, keep remote, or keep both.
369
- - **Optional encryption** — AES-256-GCM encryption with a user-provided passphrase. When enabled, all files are encrypted before upload and decrypted after download. The cloud provider only ever sees opaque bytes.
370
- - **OAuth2 authentication** — PKCE authorization code flow with a Device Code Flow fallback for headless/SSH environments. Users register their own OAuth app with the provider and supply their client ID.
387
+ - **Optional encryption** — AES-256-GCM encryption with a user-provided passphrase. When enabled, all files are encrypted before committing or exporting.
388
+ - **Merge mode** — Import supports merge mode (only import newer files) or overwrite mode.
389
+ - **Zero dependencies** — Uses Node.js built-in `crypto` and the system `git` binary.
371
390
 
372
391
  **Setup:**
373
- 1. Register an OAuth app with your chosen provider (Dropbox / Google Drive / OneDrive)
374
- 2. Run `/brain:sync login <provider>` and provide your client ID
375
- 3. Authorize in the browser (or enter the device code for headless environments)
376
- 4. Use `/brain:sync push` and `/brain:sync pull` to keep memories in sync
392
+ 1. Create a private Git repo (e.g., `gh repo create brain-data --private`)
393
+ 2. Run `/brain:sync setup git@github.com:you/brain-data.git`
394
+ 3. Use `/brain:sync push` and `/brain:sync pull` to keep memories in sync
395
+
396
+ For one-off transfers, use `/brain:sync export` and `/brain:sync import <path>`.
377
397
 
378
- Sync state is stored locally in `.brain/.sync/` and is never uploaded to the cloud.
398
+ Sync state is stored locally in `.brain/.sync/` and is never pushed to the remote.
379
399
 
380
400
  ## File Structure
381
401
 
@@ -410,10 +430,9 @@ Sync state is stored locally in `.brain/.sync/` and is never uploaded to the clo
410
430
  ├── _archived/ # Decayed memories (recoverable + searchable)
411
431
  │ ├── _meta.json
412
432
  │ └── index.json # Searchable archive index
413
- └── .sync/ # Cloud sync state (never synced, local only)
414
- ├── config.json # Provider, client ID, encryption flag
415
- ├── credentials.enc # AES-256-GCM encrypted OAuth tokens
416
- └── sync-state.json # Per-file revisions, cursor, conflicts
433
+ └── .sync/ # Sync state (local only, never pushed)
434
+ ├── config.json # Remote URL, encryption flag
435
+ └── repo/ # Hidden git repo for sync
417
436
  ```
418
437
 
419
438
  Subdirectories are created **on demand** — the agent decides placement depth based on how specific the memory is. A generic career thought lands in `professional/`, but a specific deployment incident goes to `professional/companies/acme/projects/alpha/`.
package/bin/install.js CHANGED
@@ -1,10 +1,14 @@
1
1
  #!/usr/bin/env node
2
2
 
3
3
  const readline = require('readline');
4
+ const fs = require('fs');
5
+ const path = require('path');
4
6
  const {
5
7
  RUNTIMES,
6
8
  installForRuntime,
7
9
  initializeBrain,
10
+ detectInstallations,
11
+ uninstallForRuntime,
8
12
  } = require('../src/installer');
9
13
 
10
14
  function createRL() {
@@ -18,30 +22,50 @@ function ask(rl, question) {
18
22
  return new Promise((resolve) => rl.question(question, resolve));
19
23
  }
20
24
 
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
- `);
25
+ function parseArgs(argv) {
26
+ const args = argv.slice(2);
27
+ const subcommands = ['install', 'update', 'uninstall'];
28
+ let subcommand = 'install';
29
+ const flags = new Set();
31
30
 
32
- const args = process.argv.slice(2);
33
- const flags = new Set(args.map((a) => a.replace(/^--/, '')));
31
+ for (const arg of args) {
32
+ const clean = arg.replace(/^--/, '');
33
+ if (subcommands.includes(clean) && arg === clean) {
34
+ // positional subcommand (no --)
35
+ subcommand = clean;
36
+ } else if (clean === 'update') {
37
+ subcommand = 'update';
38
+ } else if (clean === 'uninstall') {
39
+ subcommand = 'uninstall';
40
+ } else {
41
+ flags.add(clean);
42
+ }
43
+ }
34
44
 
35
- let runtimes = [];
36
- let scope = null;
45
+ return { subcommand, flags };
46
+ }
37
47
 
38
- // Check for non-interactive flags
48
+ function resolveRuntimesFromFlags(flags) {
49
+ const runtimes = [];
39
50
  if (flags.has('claude')) runtimes.push('claude');
40
51
  if (flags.has('gemini')) runtimes.push('gemini');
41
52
  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';
53
+ if (flags.has('all')) return ['claude', 'gemini', 'openai'];
54
+ return runtimes;
55
+ }
56
+
57
+ function resolveScopeFromFlags(flags) {
58
+ if (flags.has('global')) return 'global';
59
+ if (flags.has('local')) return 'local';
60
+ return null;
61
+ }
62
+
63
+ // ---------------------------------------------------------------------------
64
+ // Install (original behavior, refactored from main)
65
+ // ---------------------------------------------------------------------------
66
+ async function runInstall(flags) {
67
+ let runtimes = resolveRuntimesFromFlags(flags);
68
+ let scope = resolveScopeFromFlags(flags);
45
69
 
46
70
  const rl = createRL();
47
71
 
@@ -110,8 +134,7 @@ async function main() {
110
134
  } else {
111
135
  console.log('\n .brain/ initialized successfully.');
112
136
  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.');
137
+ console.log(' Use /brain:sync to set up portable sync across devices.');
115
138
  }
116
139
  }
117
140
 
@@ -129,7 +152,7 @@ async function main() {
129
152
  /brain:sunshine Deep forensic memory erasure
130
153
  /brain:sleep Full maintenance cycle
131
154
  /brain:status Brain overview dashboard
132
- /brain:sync Cloud sync (Dropbox/Google Drive/OneDrive)
155
+ /brain:sync Sync memories via Git remote or export/import
133
156
 
134
157
  Get started by running /brain:init in your agent session.
135
158
  `);
@@ -138,7 +161,170 @@ async function main() {
138
161
  }
139
162
  }
140
163
 
164
+ // ---------------------------------------------------------------------------
165
+ // Update
166
+ // ---------------------------------------------------------------------------
167
+ async function runUpdate(flags) {
168
+ const pkg = JSON.parse(
169
+ fs.readFileSync(path.join(__dirname, '..', 'package.json'), 'utf-8')
170
+ );
171
+ const version = pkg.version;
172
+
173
+ console.log(' Detecting existing installations...\n');
174
+
175
+ let detections = detectInstallations();
176
+
177
+ // Filter by explicit flags if provided
178
+ const filterRuntimes = resolveRuntimesFromFlags(flags);
179
+ const filterScope = resolveScopeFromFlags(flags);
180
+ if (filterRuntimes.length > 0) {
181
+ detections = detections.filter((d) => filterRuntimes.includes(d.runtime));
182
+ }
183
+ if (filterScope) {
184
+ detections = detections.filter((d) => d.scope === filterScope);
185
+ }
186
+
187
+ if (detections.length === 0) {
188
+ console.log(' No existing brain-memory installations found.\n');
189
+ console.log(' To install, run: npx brain-memory@beta');
190
+ if (filterRuntimes.length > 0) {
191
+ console.log(` (Searched for: ${filterRuntimes.join(', ')})`);
192
+ }
193
+ return;
194
+ }
195
+
196
+ console.log(` Found ${detections.length} installation(s):\n`);
197
+ for (const d of detections) {
198
+ const parts = [];
199
+ if (d.commandsFound) parts.push('commands');
200
+ if (d.promptFound) parts.push('prompt');
201
+ console.log(` ${d.runtimeName} (${d.scope}) — ${parts.join(' + ')}`);
202
+ }
203
+
204
+ console.log('\n Updating...');
205
+ for (const d of detections) {
206
+ console.log(`\n Updating ${d.runtimeName} (${d.scope})...`);
207
+ installForRuntime(d.runtime, d.scope);
208
+ console.log(' Done!');
209
+ }
210
+
211
+ console.log(`\n ✓ Updated to v${version}\n`);
212
+ }
213
+
214
+ // ---------------------------------------------------------------------------
215
+ // Uninstall
216
+ // ---------------------------------------------------------------------------
217
+ async function runUninstall(flags) {
218
+ console.log(' Detecting existing installations...\n');
219
+
220
+ let detections = detectInstallations();
221
+
222
+ // Filter by explicit flags if provided
223
+ const filterRuntimes = resolveRuntimesFromFlags(flags);
224
+ const filterScope = resolveScopeFromFlags(flags);
225
+ if (filterRuntimes.length > 0) {
226
+ detections = detections.filter((d) => filterRuntimes.includes(d.runtime));
227
+ }
228
+ if (filterScope) {
229
+ detections = detections.filter((d) => d.scope === filterScope);
230
+ }
231
+
232
+ if (detections.length === 0) {
233
+ console.log(' No existing brain-memory installations found. Nothing to uninstall.\n');
234
+ return;
235
+ }
236
+
237
+ console.log(` Will remove ${detections.length} installation(s):\n`);
238
+ for (const d of detections) {
239
+ const parts = [];
240
+ if (d.commandsFound) parts.push('commands');
241
+ if (d.promptFound) parts.push('prompt section');
242
+ console.log(` ${d.runtimeName} (${d.scope}) — ${parts.join(' + ')}`);
243
+ }
244
+
245
+ // Confirm unless --yes
246
+ if (!flags.has('yes') && !flags.has('y')) {
247
+ const rl = createRL();
248
+ try {
249
+ console.log('');
250
+ const answer = await ask(rl, ' Proceed? (y/N): ');
251
+ if (answer.trim().toLowerCase() !== 'y') {
252
+ console.log('\n Cancelled.\n');
253
+ return;
254
+ }
255
+ } finally {
256
+ rl.close();
257
+ }
258
+ }
259
+
260
+ console.log('\n Uninstalling...');
261
+ for (const d of detections) {
262
+ console.log(`\n Removing ${d.runtimeName} (${d.scope})...`);
263
+ uninstallForRuntime(d.runtime, d.scope);
264
+ console.log(' Done!');
265
+ }
266
+
267
+ // Handle .brain/ data
268
+ const brainDir = path.join(process.cwd(), '.brain');
269
+ if (fs.existsSync(brainDir)) {
270
+ if (flags.has('delete-data')) {
271
+ fs.rmSync(brainDir, { recursive: true, force: true });
272
+ console.log('\n Deleted .brain/ directory.');
273
+ } else if (!flags.has('yes') && !flags.has('y')) {
274
+ const rl = createRL();
275
+ try {
276
+ console.log('');
277
+ const answer = await ask(
278
+ rl,
279
+ ' Delete .brain/ data directory? This removes all memories. (y/N): '
280
+ );
281
+ if (answer.trim().toLowerCase() === 'y') {
282
+ fs.rmSync(brainDir, { recursive: true, force: true });
283
+ console.log(' Deleted .brain/ directory.');
284
+ } else {
285
+ console.log(' Kept .brain/ directory (your memories are preserved).');
286
+ }
287
+ } finally {
288
+ rl.close();
289
+ }
290
+ } else {
291
+ console.log('\n Kept .brain/ directory (use --delete-data to remove memories).');
292
+ }
293
+ }
294
+
295
+ console.log('\n ✓ Uninstall complete.\n');
296
+ }
297
+
298
+ // ---------------------------------------------------------------------------
299
+ // Main
300
+ // ---------------------------------------------------------------------------
301
+ async function main() {
302
+ console.log(`
303
+ ╔══════════════════════════════════════════════════════╗
304
+ ║ ║
305
+ ║ 🧠 Brain Memory — Installer ║
306
+ ║ ║
307
+ ║ Hierarchical memory system for AI coding agents ║
308
+ ║ ║
309
+ ╚══════════════════════════════════════════════════════╝
310
+ `);
311
+
312
+ const { subcommand, flags } = parseArgs(process.argv);
313
+
314
+ switch (subcommand) {
315
+ case 'update':
316
+ await runUpdate(flags);
317
+ break;
318
+ case 'uninstall':
319
+ await runUninstall(flags);
320
+ break;
321
+ default:
322
+ await runInstall(flags);
323
+ break;
324
+ }
325
+ }
326
+
141
327
  main().catch((err) => {
142
- console.error('Installation failed:', err.message);
328
+ console.error('Operation failed:', err.message);
143
329
  process.exit(1);
144
330
  });
@@ -12,8 +12,7 @@ Also read (if they exist):
12
12
  - `.brain/associations.json` — for association network stats
13
13
  - `.brain/review-queue.json` — for review schedule info
14
14
  - `.brain/_archived/index.json` — for archive stats
15
- - `.brain/.sync/config.json` — for cloud sync configuration
16
- - `.brain/.sync/sync-state.json` — for sync state and pending changes
15
+ - `.brain/.sync/config.json` — for git sync configuration
17
16
 
18
17
  ### 2. Compute Statistics
19
18
 
@@ -107,12 +106,13 @@ Calculate aggregate stats:
107
106
  + <title> (<path>) — <date>
108
107
  ...
109
108
 
110
- ## Cloud Sync
111
- Provider: <provider or "not configured">
112
- Encryption: <enabled/disabled>
113
- Last Sync: <timestamp or "never">
114
- Pending Changes: <count> files modified since last sync
115
- Conflicts: <count>
109
+ ## Sync
110
+ Remote: <remote URL or "not configured">
111
+ Encryption: <enabled/disabled>
112
+ Last Push: <timestamp or "never">
113
+ Last Pull: <timestamp or "never">
114
+ Ahead: <count> commits
115
+ Behind: <count> commits
116
116
  ```
117
117
 
118
118
  ### 4. Health Check
@@ -128,6 +128,5 @@ Analyze the brain's health and provide recommendations:
128
128
  - **"Needs sleep"** — Multiple flat clusters detected, OR many memories in moderate/weak tiers, OR no `_expertise.md` profiles exist despite having 10+ memories. Suggest `/brain:sleep`
129
129
  - **"Low confidence"** — More than 30% of memories have confidence < 0.5. Suggest reviewing and validating uncertain memories.
130
130
  - **"Review overdue"** — More than 10 memories are past their review date. Suggest `/brain:review`
131
- - **"Sync available"** — Cloud sync is not configured. Suggest `/brain:sync login` for cross-device access.
132
- - **"Sync stale"** — Last sync was more than 7 days ago. Suggest `/brain:sync push` or `/brain:sync pull`.
133
- - **"Sync conflicts"** — Unresolved sync conflicts exist. Suggest `/brain:sync resolve`.
131
+ - **"Sync available"** — Git sync is not configured. Suggest `/brain:sync setup` for cross-device access.
132
+ - **"Sync stale"** — Last push was more than 7 days ago. Suggest `/brain:sync push`.