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 +35 -16
- package/bin/install.js +208 -22
- package/commands/brain/status.md +10 -11
- package/commands/brain/sync.md +126 -124
- package/package.json +2 -2
- package/prompts/claude.md +8 -3
- package/prompts/gemini.md +8 -3
- package/prompts/openai.md +8 -3
- package/src/{sync/crypto-utils.js → crypto.js} +4 -91
- package/src/export-import.js +185 -0
- package/src/git-sync.js +413 -0
- package/src/installer.js +108 -0
- package/src/sync/oauth.js +0 -430
- package/src/sync/provider.js +0 -144
- package/src/sync/providers/dropbox.js +0 -288
- package/src/sync/providers/google-drive.js +0 -496
- package/src/sync/providers/onedrive.js +0 -308
- package/src/sync/sync-engine.js +0 -774
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]` |
|
|
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
|
-
###
|
|
377
|
+
### Portable Sync
|
|
362
378
|
|
|
363
|
-
`/brain:sync`
|
|
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
|
-
- **
|
|
368
|
-
- **
|
|
369
|
-
- **
|
|
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.
|
|
374
|
-
2. Run `/brain:sync
|
|
375
|
-
3.
|
|
376
|
-
|
|
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
|
|
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/ #
|
|
414
|
-
├── config.json #
|
|
415
|
-
|
|
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
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
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
|
|
33
|
-
|
|
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
|
-
|
|
36
|
-
|
|
45
|
+
return { subcommand, flags };
|
|
46
|
+
}
|
|
37
47
|
|
|
38
|
-
|
|
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'))
|
|
43
|
-
|
|
44
|
-
|
|
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('
|
|
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
|
|
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('
|
|
328
|
+
console.error('Operation failed:', err.message);
|
|
143
329
|
process.exit(1);
|
|
144
330
|
});
|
package/commands/brain/status.md
CHANGED
|
@@ -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
|
|
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
|
-
##
|
|
111
|
-
|
|
112
|
-
Encryption:
|
|
113
|
-
Last
|
|
114
|
-
|
|
115
|
-
|
|
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"** —
|
|
132
|
-
- **"Sync stale"** — Last
|
|
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`.
|