brain-memory 0.1.0-beta.3 → 0.1.0-beta.31
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/CHANGELOG.md +339 -0
- package/README.md +400 -94
- package/SECURITY.md +61 -0
- package/assets/brand/README.md +28 -0
- package/assets/brand/icon-dark.svg +19 -0
- package/assets/brand/icon-light.svg +20 -0
- package/assets/brand/linkedin_cover.png +0 -0
- package/assets/brand/linkedin_cover_light.png +0 -0
- package/assets/brand/mark-dark.svg +19 -0
- package/assets/brand/mark-light.svg +20 -0
- package/assets/brand/png/icon-dark-1024.png +0 -0
- package/assets/brand/png/icon-dark-128.png +0 -0
- package/assets/brand/png/icon-dark-256.png +0 -0
- package/assets/brand/png/icon-dark-512.png +0 -0
- package/assets/brand/png/icon-dark-64.png +0 -0
- package/assets/brand/png/icon-light-1024.png +0 -0
- package/assets/brand/png/icon-light-128.png +0 -0
- package/assets/brand/png/icon-light-256.png +0 -0
- package/assets/brand/png/icon-light-512.png +0 -0
- package/assets/brand/png/icon-light-64.png +0 -0
- package/assets/brand/png/mark-dark-1024.png +0 -0
- package/assets/brand/png/mark-light-1024.png +0 -0
- package/assets/icon.png +0 -0
- package/assets/icon.svg +19 -0
- package/bin/brain.js +111 -0
- package/bin/cloud-sync.js +150 -0
- package/bin/forget.js +122 -0
- package/bin/install.js +229 -254
- package/bin/memorize.js +458 -0
- package/bin/pin.js +44 -0
- package/bin/recall.js +259 -0
- package/bin/reinforce.js +187 -0
- package/bin/session-start.js +298 -0
- package/bin/skill.js +67 -0
- package/bin/unpin.js +38 -0
- package/commands/brain/forget.md +245 -15
- package/commands/brain/memorize.md +76 -144
- package/commands/brain/pin.md +79 -0
- package/commands/brain/remember.md +48 -105
- package/commands/brain/skills.md +60 -0
- package/commands/brain/sleep.md +69 -28
- package/commands/brain/status.md +24 -10
- package/commands/brain/sync.md +386 -0
- package/package.json +22 -8
- package/prompts/antigravity.md +180 -0
- package/prompts/claude.md +124 -20
- package/prompts/openai.md +124 -20
- package/prompts/opencode.md +179 -0
- package/src/cloud-sync.js +534 -0
- package/src/crypto.js +130 -0
- package/src/export-import.js +200 -0
- package/src/git-sync.js +444 -0
- package/src/index-manager.js +219 -18
- package/src/installer.js +444 -0
- package/src/pinning.js +124 -0
- package/src/scorer.js +45 -11
- package/src/skills.js +208 -0
- package/src/tfidf.js +520 -0
- package/commands/brain/consolidate.md +0 -153
- package/commands/brain/explore.md +0 -79
- package/commands/brain/init.md +0 -157
- package/commands/brain/review.md +0 -130
- package/commands/brain/sunshine.md +0 -337
- package/hooks/session-end.md +0 -48
- package/hooks/session-start.md +0 -48
- package/prompts/gemini.md +0 -76
package/src/index-manager.js
CHANGED
|
@@ -1,28 +1,88 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* Brain Memory — Index Manager
|
|
3
3
|
*
|
|
4
|
-
* Utilities for reading, updating, and maintaining the
|
|
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
|
-
*
|
|
22
|
-
*
|
|
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(
|
|
25
|
-
return path.join(
|
|
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
|
-
|
|
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
|
|
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
|
|
115
|
-
|
|
116
|
-
|
|
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
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
};
|