brain-memory 0.1.0-beta.3 → 0.1.0-beta.30

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.
Files changed (66) hide show
  1. package/CHANGELOG.md +319 -0
  2. package/README.md +379 -95
  3. package/SECURITY.md +61 -0
  4. package/assets/brand/README.md +28 -0
  5. package/assets/brand/icon-dark.svg +19 -0
  6. package/assets/brand/icon-light.svg +20 -0
  7. package/assets/brand/linkedin_cover.png +0 -0
  8. package/assets/brand/linkedin_cover_light.png +0 -0
  9. package/assets/brand/mark-dark.svg +19 -0
  10. package/assets/brand/mark-light.svg +20 -0
  11. package/assets/brand/png/icon-dark-1024.png +0 -0
  12. package/assets/brand/png/icon-dark-128.png +0 -0
  13. package/assets/brand/png/icon-dark-256.png +0 -0
  14. package/assets/brand/png/icon-dark-512.png +0 -0
  15. package/assets/brand/png/icon-dark-64.png +0 -0
  16. package/assets/brand/png/icon-light-1024.png +0 -0
  17. package/assets/brand/png/icon-light-128.png +0 -0
  18. package/assets/brand/png/icon-light-256.png +0 -0
  19. package/assets/brand/png/icon-light-512.png +0 -0
  20. package/assets/brand/png/icon-light-64.png +0 -0
  21. package/assets/brand/png/mark-dark-1024.png +0 -0
  22. package/assets/brand/png/mark-light-1024.png +0 -0
  23. package/assets/icon.png +0 -0
  24. package/assets/icon.svg +19 -0
  25. package/bin/brain.js +111 -0
  26. package/bin/cloud-sync.js +150 -0
  27. package/bin/forget.js +122 -0
  28. package/bin/install.js +229 -254
  29. package/bin/memorize.js +458 -0
  30. package/bin/pin.js +44 -0
  31. package/bin/recall.js +251 -0
  32. package/bin/reinforce.js +187 -0
  33. package/bin/session-start.js +298 -0
  34. package/bin/skill.js +67 -0
  35. package/bin/unpin.js +38 -0
  36. package/commands/brain/forget.md +245 -15
  37. package/commands/brain/memorize.md +76 -144
  38. package/commands/brain/pin.md +79 -0
  39. package/commands/brain/remember.md +48 -105
  40. package/commands/brain/skills.md +60 -0
  41. package/commands/brain/sleep.md +69 -28
  42. package/commands/brain/status.md +24 -10
  43. package/commands/brain/sync.md +386 -0
  44. package/package.json +22 -8
  45. package/prompts/antigravity.md +180 -0
  46. package/prompts/claude.md +124 -20
  47. package/prompts/openai.md +124 -20
  48. package/prompts/opencode.md +179 -0
  49. package/src/cloud-sync.js +534 -0
  50. package/src/crypto.js +130 -0
  51. package/src/export-import.js +200 -0
  52. package/src/git-sync.js +444 -0
  53. package/src/index-manager.js +219 -18
  54. package/src/installer.js +444 -0
  55. package/src/pinning.js +124 -0
  56. package/src/scorer.js +22 -9
  57. package/src/skills.js +208 -0
  58. package/src/tfidf.js +501 -0
  59. package/commands/brain/consolidate.md +0 -153
  60. package/commands/brain/explore.md +0 -79
  61. package/commands/brain/init.md +0 -157
  62. package/commands/brain/review.md +0 -130
  63. package/commands/brain/sunshine.md +0 -337
  64. package/hooks/session-end.md +0 -48
  65. package/hooks/session-start.md +0 -48
  66. package/prompts/gemini.md +0 -76
@@ -1,28 +1,88 @@
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');
11
+ const crypto = require('crypto');
10
12
 
11
- const DEFAULT_BRAIN_DIR = '.brain';
13
+ const DEFAULT_BRAIN_DIR = path.join(os.homedir(), '.brain');
12
14
  const INDEX_FILE = 'index.json';
13
15
  const ASSOCIATIONS_FILE = 'associations.json';
14
16
  const CONTEXTS_FILE = 'contexts.json';
15
17
  const REVIEW_QUEUE_FILE = 'review-queue.json';
16
18
  const ARCHIVE_INDEX_FILE = '_archived/index.json';
19
+ const SEARCH_INDEX_FILE = 'search-index.json';
20
+ const CONFIG_FILE = 'config.json';
21
+ const PINNED_FILE = 'pinned.json';
22
+ const SKILLS_INDEX_FILE = 'skills-index.json';
23
+
24
+ // CoALA Phase 0 — working-memory budget (token estimates, chars/4 heuristic).
25
+ // All values are conservative caps; the session-start aggregator never exceeds
26
+ // working_memory_budget_tokens and reports overflow rather than dropping silently.
27
+ const DEFAULT_CONFIG = {
28
+ working_memory_budget_tokens: 3000,
29
+ pin_budget_tokens: 1500,
30
+ skills_index_budget_tokens: 800,
31
+ recall_budget_tokens: 700,
32
+ };
33
+
34
+ /**
35
+ * Write data to a file atomically by writing to a temp file first,
36
+ * then renaming. Prevents corruption if the process crashes mid-write.
37
+ *
38
+ * @param {string} filePath - Target file path
39
+ * @param {string} data - Data to write
40
+ */
41
+ function atomicWriteSync(filePath, data) {
42
+ const tmpPath = filePath + '.tmp.' + crypto.randomBytes(4).toString('hex');
43
+ fs.writeFileSync(tmpPath, data);
44
+ fs.renameSync(tmpPath, filePath);
45
+ }
46
+
47
+ /**
48
+ * Validate that a target path is within the brain directory.
49
+ * Prevents path traversal attacks (e.g. categoryPath = '../../etc/passwd').
50
+ *
51
+ * @param {string} targetPath - The resolved path to validate
52
+ * @param {string} brainDir - The brain directory root
53
+ * @throws {Error} if targetPath is outside brainDir
54
+ */
55
+ function validateBrainPath(targetPath, brainDir) {
56
+ const resolved = path.resolve(targetPath);
57
+ const resolvedBrain = path.resolve(brainDir);
58
+ if (!resolved.startsWith(resolvedBrain + path.sep) && resolved !== resolvedBrain) {
59
+ throw new Error(`Path traversal detected: ${targetPath} is outside ${brainDir}`);
60
+ }
61
+ }
17
62
 
18
63
  /**
19
64
  * Resolve the brain directory path.
20
65
  *
21
- * @param {string} [projectRoot] - Project root directory (defaults to cwd)
22
- * @returns {string} Absolute path to .brain/
66
+ * Precedence: explicit `overrideBase` arg (tests / project-local brains) >
67
+ * the `BRAIN_DIR` environment variable (point your brain at any synced folder —
68
+ * Google Drive, Dropbox, iCloud, a git working copy, …) > the default `~/.brain`.
69
+ *
70
+ * `BRAIN_DIR` is the brain directory itself (the folder holding `index.json`),
71
+ * not a parent. A leading `~/` is expanded since env vars are not shell-expanded.
72
+ *
73
+ * @param {string} [overrideBase] - Override base directory (for testing)
74
+ * @returns {string} Absolute path to the brain directory
23
75
  */
24
- function getBrainDir(projectRoot) {
25
- return path.join(projectRoot || process.cwd(), DEFAULT_BRAIN_DIR);
76
+ function getBrainDir(overrideBase) {
77
+ if (overrideBase) return path.join(overrideBase, '.brain');
78
+ const env = process.env.BRAIN_DIR && process.env.BRAIN_DIR.trim();
79
+ if (env) {
80
+ const expanded = env === '~' || env.startsWith('~/')
81
+ ? path.join(os.homedir(), env.slice(1))
82
+ : env;
83
+ return path.resolve(expanded);
84
+ }
85
+ return DEFAULT_BRAIN_DIR;
26
86
  }
27
87
 
28
88
  /**
@@ -46,7 +106,7 @@ function readIndex(projectRoot) {
46
106
  function writeIndex(index, projectRoot) {
47
107
  const indexPath = path.join(getBrainDir(projectRoot), INDEX_FILE);
48
108
  index.last_updated = new Date().toISOString();
49
- fs.writeFileSync(indexPath, JSON.stringify(index, null, 2) + '\n');
109
+ atomicWriteSync(indexPath, JSON.stringify(index, null, 2) + '\n');
50
110
  }
51
111
 
52
112
  /**
@@ -106,27 +166,35 @@ function generateId() {
106
166
  /**
107
167
  * Read a _meta.json file from a brain subdirectory.
108
168
  *
109
- * @param {string} categoryPath - Relative path within .brain/
169
+ * @param {string} categoryPath - Relative path within ~/.brain/
110
170
  * @param {string} [projectRoot] - Project root directory
111
171
  * @returns {Object|null} Parsed meta or null
112
172
  */
113
173
  function readMeta(categoryPath, projectRoot) {
114
- const metaPath = path.join(getBrainDir(projectRoot), categoryPath, '_meta.json');
115
- if (!fs.existsSync(metaPath)) return null;
116
- return JSON.parse(fs.readFileSync(metaPath, 'utf-8'));
174
+ const brainDir = getBrainDir(projectRoot);
175
+ const metaPath = path.join(brainDir, categoryPath, '_meta.json');
176
+ validateBrainPath(metaPath, brainDir);
177
+ try {
178
+ return JSON.parse(fs.readFileSync(metaPath, 'utf-8'));
179
+ } catch (err) {
180
+ if (err.code === 'ENOENT') return null;
181
+ throw err;
182
+ }
117
183
  }
118
184
 
119
185
  /**
120
186
  * Write a _meta.json file to a brain subdirectory.
121
187
  *
122
- * @param {string} categoryPath - Relative path within .brain/
188
+ * @param {string} categoryPath - Relative path within ~/.brain/
123
189
  * @param {Object} meta - Meta object to write
124
190
  * @param {string} [projectRoot] - Project root directory
125
191
  */
126
192
  function writeMeta(categoryPath, meta, projectRoot) {
127
- const metaPath = path.join(getBrainDir(projectRoot), categoryPath, '_meta.json');
193
+ const brainDir = getBrainDir(projectRoot);
194
+ const metaPath = path.join(brainDir, categoryPath, '_meta.json');
195
+ validateBrainPath(metaPath, brainDir);
128
196
  fs.mkdirSync(path.dirname(metaPath), { recursive: true });
129
- fs.writeFileSync(metaPath, JSON.stringify(meta, null, 2) + '\n');
197
+ atomicWriteSync(metaPath, JSON.stringify(meta, null, 2) + '\n');
130
198
  }
131
199
 
132
200
  /**
@@ -167,7 +235,7 @@ function readAssociations(projectRoot) {
167
235
  */
168
236
  function writeAssociations(associations, projectRoot) {
169
237
  const filePath = path.join(getBrainDir(projectRoot), ASSOCIATIONS_FILE);
170
- fs.writeFileSync(filePath, JSON.stringify(associations, null, 2) + '\n');
238
+ atomicWriteSync(filePath, JSON.stringify(associations, null, 2) + '\n');
171
239
  }
172
240
 
173
241
  /**
@@ -273,7 +341,7 @@ function readContexts(projectRoot) {
273
341
  */
274
342
  function writeContexts(contexts, projectRoot) {
275
343
  const filePath = path.join(getBrainDir(projectRoot), CONTEXTS_FILE);
276
- fs.writeFileSync(filePath, JSON.stringify(contexts, null, 2) + '\n');
344
+ atomicWriteSync(filePath, JSON.stringify(contexts, null, 2) + '\n');
277
345
  }
278
346
 
279
347
  // --- Review Queue (Phase 4: Spaced Repetition) ---
@@ -298,7 +366,7 @@ function readReviewQueue(projectRoot) {
298
366
  */
299
367
  function writeReviewQueue(queue, projectRoot) {
300
368
  const filePath = path.join(getBrainDir(projectRoot), REVIEW_QUEUE_FILE);
301
- fs.writeFileSync(filePath, JSON.stringify(queue, null, 2) + '\n');
369
+ atomicWriteSync(filePath, JSON.stringify(queue, null, 2) + '\n');
302
370
  }
303
371
 
304
372
  // --- Archive Index (Phase 4: Archive Search) ---
@@ -324,7 +392,7 @@ function readArchiveIndex(projectRoot) {
324
392
  function writeArchiveIndex(archiveIndex, projectRoot) {
325
393
  const filePath = path.join(getBrainDir(projectRoot), ARCHIVE_INDEX_FILE);
326
394
  fs.mkdirSync(path.dirname(filePath), { recursive: true });
327
- fs.writeFileSync(filePath, JSON.stringify(archiveIndex, null, 2) + '\n');
395
+ atomicWriteSync(filePath, JSON.stringify(archiveIndex, null, 2) + '\n');
328
396
  }
329
397
 
330
398
  /**
@@ -370,8 +438,135 @@ function removeFromReviewQueue(queue, memoryId) {
370
438
  return queue;
371
439
  }
372
440
 
441
+ // --- Search Index (TF-IDF) ---
442
+
443
+ /**
444
+ * Read the TF-IDF search index.
445
+ *
446
+ * @param {string} [projectRoot] - Project root directory
447
+ * @returns {Object|null} Parsed search index or null
448
+ */
449
+ function readSearchIndex(projectRoot) {
450
+ const filePath = path.join(getBrainDir(projectRoot), SEARCH_INDEX_FILE);
451
+ try {
452
+ return JSON.parse(fs.readFileSync(filePath, 'utf-8'));
453
+ } catch (err) {
454
+ if (err.code === 'ENOENT') return null;
455
+ throw err;
456
+ }
457
+ }
458
+
459
+ /**
460
+ * Write the TF-IDF search index to disk.
461
+ *
462
+ * @param {Object} searchIndex - The search index object
463
+ * @param {string} [projectRoot] - Project root directory
464
+ */
465
+ function writeSearchIndex(searchIndex, projectRoot) {
466
+ const filePath = path.join(getBrainDir(projectRoot), SEARCH_INDEX_FILE);
467
+ atomicWriteSync(filePath, JSON.stringify(searchIndex, null, 2) + '\n');
468
+ }
469
+
470
+ // --- Config (CoALA Phase 0: working-memory budget) ---
471
+
472
+ /**
473
+ * Read the brain config, merged over safe defaults. Created lazily — a missing
474
+ * or unreadable config falls back to DEFAULT_CONFIG so session-start is robust.
475
+ *
476
+ * @param {string} [projectRoot] - Project root directory
477
+ * @returns {Object} Config with all budget keys guaranteed present
478
+ */
479
+ function readConfig(projectRoot) {
480
+ const filePath = path.join(getBrainDir(projectRoot), CONFIG_FILE);
481
+ let onDisk = {};
482
+ try {
483
+ onDisk = JSON.parse(fs.readFileSync(filePath, 'utf-8'));
484
+ } catch (_) {
485
+ // ENOENT (not yet created) or corrupt JSON → fall back to defaults.
486
+ // Budgets are non-critical; a broken config must not break startup.
487
+ onDisk = {};
488
+ }
489
+ return { ...DEFAULT_CONFIG, ...onDisk };
490
+ }
491
+
492
+ /**
493
+ * Write the brain config to disk atomically.
494
+ *
495
+ * @param {Object} config - The config object
496
+ * @param {string} [projectRoot] - Project root directory
497
+ */
498
+ function writeConfig(config, projectRoot) {
499
+ const filePath = path.join(getBrainDir(projectRoot), CONFIG_FILE);
500
+ atomicWriteSync(filePath, JSON.stringify(config, null, 2) + '\n');
501
+ }
502
+
503
+ // --- Pinned manifest (CoALA Phase 1: always-present semantic tier) ---
504
+
505
+ /**
506
+ * Read the pinned-memory manifest. Lets session-start load pins without
507
+ * scanning the whole index. Missing/corrupt → empty manifest.
508
+ *
509
+ * @param {string} [projectRoot] - Project root directory
510
+ * @returns {Object} { version, pins: [{ id, scope, priority, token_estimate }] }
511
+ */
512
+ function readPinned(projectRoot) {
513
+ const filePath = path.join(getBrainDir(projectRoot), PINNED_FILE);
514
+ try {
515
+ const data = JSON.parse(fs.readFileSync(filePath, 'utf-8'));
516
+ if (data && Array.isArray(data.pins)) return data;
517
+ } catch (_) { /* fall through */ }
518
+ return { version: 1, pins: [] };
519
+ }
520
+
521
+ /**
522
+ * Write the pinned-memory manifest to disk atomically.
523
+ *
524
+ * @param {Object} pinned - The pinned manifest
525
+ * @param {string} [projectRoot] - Project root directory
526
+ */
527
+ function writePinned(pinned, projectRoot) {
528
+ const filePath = path.join(getBrainDir(projectRoot), PINNED_FILE);
529
+ atomicWriteSync(filePath, JSON.stringify(pinned, null, 2) + '\n');
530
+ }
531
+
532
+ // --- Skills index (CoALA Phase 2: procedural progressive disclosure) ---
533
+
534
+ /**
535
+ * Read the lightweight skills index (the L0 advertised list). Missing/corrupt
536
+ * → empty index.
537
+ *
538
+ * @param {string} [projectRoot] - Project root directory
539
+ * @returns {Object} { version, skills: [{ name, description, triggers, path, strength, use_count, fail_count, last_used }] }
540
+ */
541
+ function readSkillsIndex(projectRoot) {
542
+ const filePath = path.join(getBrainDir(projectRoot), SKILLS_INDEX_FILE);
543
+ try {
544
+ const data = JSON.parse(fs.readFileSync(filePath, 'utf-8'));
545
+ if (data && Array.isArray(data.skills)) return data;
546
+ } catch (_) { /* fall through */ }
547
+ return { version: 1, skills: [] };
548
+ }
549
+
550
+ /**
551
+ * Write the skills index to disk atomically.
552
+ *
553
+ * @param {Object} skillsIndex - The skills index
554
+ * @param {string} [projectRoot] - Project root directory
555
+ */
556
+ function writeSkillsIndex(skillsIndex, projectRoot) {
557
+ const filePath = path.join(getBrainDir(projectRoot), SKILLS_INDEX_FILE);
558
+ atomicWriteSync(filePath, JSON.stringify(skillsIndex, null, 2) + '\n');
559
+ }
560
+
373
561
  module.exports = {
374
562
  getBrainDir,
563
+ DEFAULT_CONFIG,
564
+ readConfig,
565
+ writeConfig,
566
+ readPinned,
567
+ writePinned,
568
+ readSkillsIndex,
569
+ writeSkillsIndex,
375
570
  readIndex,
376
571
  writeIndex,
377
572
  addMemory,
@@ -395,7 +590,13 @@ module.exports = {
395
590
  writeReviewQueue,
396
591
  readArchiveIndex,
397
592
  writeArchiveIndex,
593
+ // Search Index (TF-IDF)
594
+ readSearchIndex,
595
+ writeSearchIndex,
398
596
  // Deep erasure utilities
399
597
  removeEdgesForMemory,
400
598
  removeFromReviewQueue,
599
+ // Security utilities
600
+ atomicWriteSync,
601
+ validateBrainPath,
401
602
  };