brain-memory 0.1.0-beta.8 → 0.1.0

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 (81) hide show
  1. package/CHANGELOG.md +555 -0
  2. package/README.md +411 -61
  3. package/SECURITY.md +100 -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/audit.js +93 -0
  26. package/bin/brain.js +132 -0
  27. package/bin/cloud-sync.js +150 -0
  28. package/bin/forget.js +163 -0
  29. package/bin/import.js +132 -0
  30. package/bin/install.js +63 -31
  31. package/bin/memorize.js +637 -0
  32. package/bin/pin.js +44 -0
  33. package/bin/recall.js +287 -0
  34. package/bin/reinforce.js +191 -0
  35. package/bin/restore.js +122 -0
  36. package/bin/session-start.js +337 -0
  37. package/bin/skill.js +67 -0
  38. package/bin/unpin.js +38 -0
  39. package/bin/verify.js +154 -0
  40. package/commands/brain/forget.md +243 -13
  41. package/commands/brain/import.md +125 -0
  42. package/commands/brain/memorize.md +95 -137
  43. package/commands/brain/pin.md +79 -0
  44. package/commands/brain/remember.md +53 -103
  45. package/commands/brain/skills.md +60 -0
  46. package/commands/brain/sleep.md +93 -6
  47. package/commands/brain/status.md +15 -6
  48. package/commands/brain/sync.md +181 -17
  49. package/commands/brain/verify.md +57 -0
  50. package/integrations/README.md +29 -0
  51. package/integrations/agentskills/brain-memory/SKILL.md +115 -0
  52. package/integrations/agentskills/brain-memory/scripts/session-start.mjs +34 -0
  53. package/package.json +20 -7
  54. package/prompts/antigravity.md +201 -0
  55. package/prompts/claude.md +107 -40
  56. package/prompts/copilot.md +203 -0
  57. package/prompts/kilo.md +202 -0
  58. package/prompts/openai.md +112 -45
  59. package/prompts/opencode.md +200 -0
  60. package/src/anomaly.js +260 -0
  61. package/src/audit.js +71 -0
  62. package/src/cloud-sync.js +672 -0
  63. package/src/content-lint.js +118 -0
  64. package/src/export-import.js +45 -7
  65. package/src/git-sync.js +170 -11
  66. package/src/harvest.js +562 -0
  67. package/src/index-manager.js +250 -11
  68. package/src/installer.js +250 -29
  69. package/src/pinning.js +146 -0
  70. package/src/provenance.js +79 -0
  71. package/src/quarantine.js +111 -0
  72. package/src/receipt.js +81 -0
  73. package/src/scorer.js +69 -12
  74. package/src/skills.js +208 -0
  75. package/src/tfidf.js +520 -0
  76. package/commands/brain/consolidate.md +0 -153
  77. package/commands/brain/explore.md +0 -79
  78. package/commands/brain/init.md +0 -149
  79. package/commands/brain/review.md +0 -130
  80. package/commands/brain/sunshine.md +0 -337
  81. package/prompts/gemini.md +0 -134
@@ -8,6 +8,7 @@
8
8
  const fs = require('fs');
9
9
  const path = require('path');
10
10
  const os = require('os');
11
+ const crypto = require('crypto');
11
12
 
12
13
  const DEFAULT_BRAIN_DIR = path.join(os.homedir(), '.brain');
13
14
  const INDEX_FILE = 'index.json';
@@ -15,15 +16,112 @@ const ASSOCIATIONS_FILE = 'associations.json';
15
16
  const CONTEXTS_FILE = 'contexts.json';
16
17
  const REVIEW_QUEUE_FILE = 'review-queue.json';
17
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
+ // ASI06 quarantine for low-trust writes: 'off' (never flag), 'flag'
33
+ // (recallable but marked + surfaced for verification — the default), or
34
+ // 'enforce' (excluded from recall/session-start until approved). Exclusion
35
+ // is evaluated at read time, so flipping the knob retroactively
36
+ // hides/reveals already-pending memories.
37
+ quarantine_mode: 'flag',
38
+ };
39
+
40
+ /**
41
+ * Write data to a file atomically by writing to a temp file first,
42
+ * then renaming. Prevents corruption if the process crashes mid-write.
43
+ *
44
+ * @param {string} filePath - Target file path
45
+ * @param {string} data - Data to write
46
+ */
47
+ function atomicWriteSync(filePath, data) {
48
+ const tmpPath = filePath + '.tmp.' + crypto.randomBytes(4).toString('hex');
49
+ fs.writeFileSync(tmpPath, data);
50
+ fs.renameSync(tmpPath, filePath);
51
+ }
52
+
53
+ /**
54
+ * Validate that a target path is within the brain directory.
55
+ * Prevents path traversal attacks (e.g. categoryPath = '../../etc/passwd').
56
+ *
57
+ * @param {string} targetPath - The resolved path to validate
58
+ * @param {string} brainDir - The brain directory root
59
+ * @throws {Error} if targetPath is outside brainDir
60
+ */
61
+ function validateBrainPath(targetPath, brainDir) {
62
+ const resolved = path.resolve(targetPath);
63
+ const resolvedBrain = path.resolve(brainDir);
64
+ if (!resolved.startsWith(resolvedBrain + path.sep) && resolved !== resolvedBrain) {
65
+ throw new Error(`Path traversal detected: ${targetPath} is outside ${brainDir}`);
66
+ }
67
+
68
+ // The string check above can be defeated by a symlink placed INSIDE the
69
+ // brain dir (e.g. ~/.brain/professional/x -> /etc): the lexical path stays
70
+ // inside while the write lands outside. Realpath the deepest existing
71
+ // ancestor and require it to stay under the realpath'd brain root. Both
72
+ // sides are realpath'd so a brain dir that is itself a symlink (BRAIN_DIR
73
+ // pointing into Dropbox/iCloud) remains fully supported.
74
+ let realBrain;
75
+ try {
76
+ realBrain = fs.realpathSync(resolvedBrain);
77
+ } catch (_) {
78
+ return; // brain dir doesn't exist yet (init paths) — nothing to escape from
79
+ }
80
+
81
+ // Refuse to write onto a path whose final component is itself a symlink —
82
+ // whether it dangles or resolves, a memory file must be a regular file.
83
+ let finalIsLink = false;
84
+ try {
85
+ finalIsLink = fs.lstatSync(resolved).isSymbolicLink();
86
+ } catch (_) { /* doesn't exist — fine */ }
87
+ if (finalIsLink) {
88
+ throw new Error(`Refusing to write through symlink: ${targetPath}`);
89
+ }
90
+
91
+ let probe = resolved;
92
+ while (!fs.existsSync(probe)) {
93
+ const parent = path.dirname(probe);
94
+ if (parent === probe) break;
95
+ probe = parent;
96
+ }
97
+ const realProbe = fs.realpathSync(probe);
98
+ if (!realProbe.startsWith(realBrain + path.sep) && realProbe !== realBrain) {
99
+ throw new Error(`Symlink escape detected: ${targetPath} resolves outside ${brainDir}`);
100
+ }
101
+ }
18
102
 
19
103
  /**
20
104
  * Resolve the brain directory path.
21
105
  *
106
+ * Precedence: explicit `overrideBase` arg (tests / project-local brains) >
107
+ * the `BRAIN_DIR` environment variable (point your brain at any synced folder —
108
+ * Google Drive, Dropbox, iCloud, a git working copy, …) > the default `~/.brain`.
109
+ *
110
+ * `BRAIN_DIR` is the brain directory itself (the folder holding `index.json`),
111
+ * not a parent. A leading `~/` is expanded since env vars are not shell-expanded.
112
+ *
22
113
  * @param {string} [overrideBase] - Override base directory (for testing)
23
- * @returns {string} Absolute path to ~/.brain/ (or overrideBase/.brain/ if provided)
114
+ * @returns {string} Absolute path to the brain directory
24
115
  */
25
116
  function getBrainDir(overrideBase) {
26
117
  if (overrideBase) return path.join(overrideBase, '.brain');
118
+ const env = process.env.BRAIN_DIR && process.env.BRAIN_DIR.trim();
119
+ if (env) {
120
+ const expanded = env === '~' || env.startsWith('~/')
121
+ ? path.join(os.homedir(), env.slice(1))
122
+ : env;
123
+ return path.resolve(expanded);
124
+ }
27
125
  return DEFAULT_BRAIN_DIR;
28
126
  }
29
127
 
@@ -48,7 +146,7 @@ function readIndex(projectRoot) {
48
146
  function writeIndex(index, projectRoot) {
49
147
  const indexPath = path.join(getBrainDir(projectRoot), INDEX_FILE);
50
148
  index.last_updated = new Date().toISOString();
51
- fs.writeFileSync(indexPath, JSON.stringify(index, null, 2) + '\n');
149
+ atomicWriteSync(indexPath, JSON.stringify(index, null, 2) + '\n');
52
150
  }
53
151
 
54
152
  /**
@@ -113,9 +211,15 @@ function generateId() {
113
211
  * @returns {Object|null} Parsed meta or null
114
212
  */
115
213
  function readMeta(categoryPath, projectRoot) {
116
- const metaPath = path.join(getBrainDir(projectRoot), categoryPath, '_meta.json');
117
- if (!fs.existsSync(metaPath)) return null;
118
- return JSON.parse(fs.readFileSync(metaPath, 'utf-8'));
214
+ const brainDir = getBrainDir(projectRoot);
215
+ const metaPath = path.join(brainDir, categoryPath, '_meta.json');
216
+ validateBrainPath(metaPath, brainDir);
217
+ try {
218
+ return JSON.parse(fs.readFileSync(metaPath, 'utf-8'));
219
+ } catch (err) {
220
+ if (err.code === 'ENOENT') return null;
221
+ throw err;
222
+ }
119
223
  }
120
224
 
121
225
  /**
@@ -126,9 +230,11 @@ function readMeta(categoryPath, projectRoot) {
126
230
  * @param {string} [projectRoot] - Project root directory
127
231
  */
128
232
  function writeMeta(categoryPath, meta, projectRoot) {
129
- const metaPath = path.join(getBrainDir(projectRoot), categoryPath, '_meta.json');
233
+ const brainDir = getBrainDir(projectRoot);
234
+ const metaPath = path.join(brainDir, categoryPath, '_meta.json');
235
+ validateBrainPath(metaPath, brainDir);
130
236
  fs.mkdirSync(path.dirname(metaPath), { recursive: true });
131
- fs.writeFileSync(metaPath, JSON.stringify(meta, null, 2) + '\n');
237
+ atomicWriteSync(metaPath, JSON.stringify(meta, null, 2) + '\n');
132
238
  }
133
239
 
134
240
  /**
@@ -169,7 +275,7 @@ function readAssociations(projectRoot) {
169
275
  */
170
276
  function writeAssociations(associations, projectRoot) {
171
277
  const filePath = path.join(getBrainDir(projectRoot), ASSOCIATIONS_FILE);
172
- fs.writeFileSync(filePath, JSON.stringify(associations, null, 2) + '\n');
278
+ atomicWriteSync(filePath, JSON.stringify(associations, null, 2) + '\n');
173
279
  }
174
280
 
175
281
  /**
@@ -275,7 +381,7 @@ function readContexts(projectRoot) {
275
381
  */
276
382
  function writeContexts(contexts, projectRoot) {
277
383
  const filePath = path.join(getBrainDir(projectRoot), CONTEXTS_FILE);
278
- fs.writeFileSync(filePath, JSON.stringify(contexts, null, 2) + '\n');
384
+ atomicWriteSync(filePath, JSON.stringify(contexts, null, 2) + '\n');
279
385
  }
280
386
 
281
387
  // --- Review Queue (Phase 4: Spaced Repetition) ---
@@ -300,7 +406,7 @@ function readReviewQueue(projectRoot) {
300
406
  */
301
407
  function writeReviewQueue(queue, projectRoot) {
302
408
  const filePath = path.join(getBrainDir(projectRoot), REVIEW_QUEUE_FILE);
303
- fs.writeFileSync(filePath, JSON.stringify(queue, null, 2) + '\n');
409
+ atomicWriteSync(filePath, JSON.stringify(queue, null, 2) + '\n');
304
410
  }
305
411
 
306
412
  // --- Archive Index (Phase 4: Archive Search) ---
@@ -326,7 +432,7 @@ function readArchiveIndex(projectRoot) {
326
432
  function writeArchiveIndex(archiveIndex, projectRoot) {
327
433
  const filePath = path.join(getBrainDir(projectRoot), ARCHIVE_INDEX_FILE);
328
434
  fs.mkdirSync(path.dirname(filePath), { recursive: true });
329
- fs.writeFileSync(filePath, JSON.stringify(archiveIndex, null, 2) + '\n');
435
+ atomicWriteSync(filePath, JSON.stringify(archiveIndex, null, 2) + '\n');
330
436
  }
331
437
 
332
438
  /**
@@ -372,8 +478,135 @@ function removeFromReviewQueue(queue, memoryId) {
372
478
  return queue;
373
479
  }
374
480
 
481
+ // --- Search Index (TF-IDF) ---
482
+
483
+ /**
484
+ * Read the TF-IDF search index.
485
+ *
486
+ * @param {string} [projectRoot] - Project root directory
487
+ * @returns {Object|null} Parsed search index or null
488
+ */
489
+ function readSearchIndex(projectRoot) {
490
+ const filePath = path.join(getBrainDir(projectRoot), SEARCH_INDEX_FILE);
491
+ try {
492
+ return JSON.parse(fs.readFileSync(filePath, 'utf-8'));
493
+ } catch (err) {
494
+ if (err.code === 'ENOENT') return null;
495
+ throw err;
496
+ }
497
+ }
498
+
499
+ /**
500
+ * Write the TF-IDF search index to disk.
501
+ *
502
+ * @param {Object} searchIndex - The search index object
503
+ * @param {string} [projectRoot] - Project root directory
504
+ */
505
+ function writeSearchIndex(searchIndex, projectRoot) {
506
+ const filePath = path.join(getBrainDir(projectRoot), SEARCH_INDEX_FILE);
507
+ atomicWriteSync(filePath, JSON.stringify(searchIndex, null, 2) + '\n');
508
+ }
509
+
510
+ // --- Config (CoALA Phase 0: working-memory budget) ---
511
+
512
+ /**
513
+ * Read the brain config, merged over safe defaults. Created lazily — a missing
514
+ * or unreadable config falls back to DEFAULT_CONFIG so session-start is robust.
515
+ *
516
+ * @param {string} [projectRoot] - Project root directory
517
+ * @returns {Object} Config with all budget keys guaranteed present
518
+ */
519
+ function readConfig(projectRoot) {
520
+ const filePath = path.join(getBrainDir(projectRoot), CONFIG_FILE);
521
+ let onDisk = {};
522
+ try {
523
+ onDisk = JSON.parse(fs.readFileSync(filePath, 'utf-8'));
524
+ } catch (_) {
525
+ // ENOENT (not yet created) or corrupt JSON → fall back to defaults.
526
+ // Budgets are non-critical; a broken config must not break startup.
527
+ onDisk = {};
528
+ }
529
+ return { ...DEFAULT_CONFIG, ...onDisk };
530
+ }
531
+
532
+ /**
533
+ * Write the brain config to disk atomically.
534
+ *
535
+ * @param {Object} config - The config object
536
+ * @param {string} [projectRoot] - Project root directory
537
+ */
538
+ function writeConfig(config, projectRoot) {
539
+ const filePath = path.join(getBrainDir(projectRoot), CONFIG_FILE);
540
+ atomicWriteSync(filePath, JSON.stringify(config, null, 2) + '\n');
541
+ }
542
+
543
+ // --- Pinned manifest (CoALA Phase 1: always-present semantic tier) ---
544
+
545
+ /**
546
+ * Read the pinned-memory manifest. Lets session-start load pins without
547
+ * scanning the whole index. Missing/corrupt → empty manifest.
548
+ *
549
+ * @param {string} [projectRoot] - Project root directory
550
+ * @returns {Object} { version, pins: [{ id, scope, priority, token_estimate }] }
551
+ */
552
+ function readPinned(projectRoot) {
553
+ const filePath = path.join(getBrainDir(projectRoot), PINNED_FILE);
554
+ try {
555
+ const data = JSON.parse(fs.readFileSync(filePath, 'utf-8'));
556
+ if (data && Array.isArray(data.pins)) return data;
557
+ } catch (_) { /* fall through */ }
558
+ return { version: 1, pins: [] };
559
+ }
560
+
561
+ /**
562
+ * Write the pinned-memory manifest to disk atomically.
563
+ *
564
+ * @param {Object} pinned - The pinned manifest
565
+ * @param {string} [projectRoot] - Project root directory
566
+ */
567
+ function writePinned(pinned, projectRoot) {
568
+ const filePath = path.join(getBrainDir(projectRoot), PINNED_FILE);
569
+ atomicWriteSync(filePath, JSON.stringify(pinned, null, 2) + '\n');
570
+ }
571
+
572
+ // --- Skills index (CoALA Phase 2: procedural progressive disclosure) ---
573
+
574
+ /**
575
+ * Read the lightweight skills index (the L0 advertised list). Missing/corrupt
576
+ * → empty index.
577
+ *
578
+ * @param {string} [projectRoot] - Project root directory
579
+ * @returns {Object} { version, skills: [{ name, description, triggers, path, strength, use_count, fail_count, last_used }] }
580
+ */
581
+ function readSkillsIndex(projectRoot) {
582
+ const filePath = path.join(getBrainDir(projectRoot), SKILLS_INDEX_FILE);
583
+ try {
584
+ const data = JSON.parse(fs.readFileSync(filePath, 'utf-8'));
585
+ if (data && Array.isArray(data.skills)) return data;
586
+ } catch (_) { /* fall through */ }
587
+ return { version: 1, skills: [] };
588
+ }
589
+
590
+ /**
591
+ * Write the skills index to disk atomically.
592
+ *
593
+ * @param {Object} skillsIndex - The skills index
594
+ * @param {string} [projectRoot] - Project root directory
595
+ */
596
+ function writeSkillsIndex(skillsIndex, projectRoot) {
597
+ const filePath = path.join(getBrainDir(projectRoot), SKILLS_INDEX_FILE);
598
+ atomicWriteSync(filePath, JSON.stringify(skillsIndex, null, 2) + '\n');
599
+ }
600
+
375
601
  module.exports = {
376
602
  getBrainDir,
603
+ DEFAULT_CONFIG,
604
+ readConfig,
605
+ writeConfig,
606
+ readPinned,
607
+ writePinned,
608
+ readSkillsIndex,
609
+ writeSkillsIndex,
377
610
  readIndex,
378
611
  writeIndex,
379
612
  addMemory,
@@ -397,7 +630,13 @@ module.exports = {
397
630
  writeReviewQueue,
398
631
  readArchiveIndex,
399
632
  writeArchiveIndex,
633
+ // Search Index (TF-IDF)
634
+ readSearchIndex,
635
+ writeSearchIndex,
400
636
  // Deep erasure utilities
401
637
  removeEdgesForMemory,
402
638
  removeFromReviewQueue,
639
+ // Security utilities
640
+ atomicWriteSync,
641
+ validateBrainPath,
403
642
  };