brain-memory 0.1.0-beta.24 → 0.1.0-beta.27
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 +264 -0
- package/README.md +101 -21
- package/SECURITY.md +61 -0
- package/assets/icon.png +0 -0
- package/assets/icon.svg +18 -26
- package/bin/brain.js +1 -1
- package/bin/forget.js +120 -0
- package/bin/install.js +16 -14
- package/bin/memorize.js +6 -1
- package/bin/recall.js +27 -3
- package/bin/session-start.js +2 -1
- package/commands/brain/status.md +1 -1
- package/package.json +3 -1
- package/prompts/{gemini.md → antigravity.md} +19 -19
- package/prompts/claude.md +2 -2
- package/prompts/openai.md +10 -10
- package/prompts/opencode.md +2 -2
- package/src/installer.js +73 -21
- package/src/scorer.js +14 -7
- package/src/tfidf.js +69 -0
package/src/installer.js
CHANGED
|
@@ -6,6 +6,17 @@ const { getBrainDir } = require('./index-manager');
|
|
|
6
6
|
|
|
7
7
|
const PACKAGE_ROOT = path.resolve(__dirname, '..');
|
|
8
8
|
|
|
9
|
+
// Local-first integration targets, current as of mid-2026. The hosted MCP
|
|
10
|
+
// connector (Brain Cloud) is the universal path for everything else (Claude.ai,
|
|
11
|
+
// ChatGPT, mobile, Antigravity/Gemini-Enterprise via remote MCP); these are the
|
|
12
|
+
// CLIs where a native install adds the ambient zero-config loop MCP can't.
|
|
13
|
+
//
|
|
14
|
+
// `skillsGlobalDir`/`skillsLocalDir` decouple where skills land from where the
|
|
15
|
+
// prompt lands (Codex prompts go to ~/.codex/AGENTS.md but skills go to the
|
|
16
|
+
// cross-tool ~/.agents/skills/). `skillName: true` injects the `name:`
|
|
17
|
+
// frontmatter that Codex/Antigravity require to match the skill folder.
|
|
18
|
+
//
|
|
19
|
+
// Gemini CLI was retired 2026-06-18 (absorbed into Antigravity) and is removed.
|
|
9
20
|
const RUNTIMES = {
|
|
10
21
|
claude: {
|
|
11
22
|
name: 'Claude Code',
|
|
@@ -16,23 +27,33 @@ const RUNTIMES = {
|
|
|
16
27
|
promptSource: 'claude.md',
|
|
17
28
|
commandStyle: 'flat',
|
|
18
29
|
},
|
|
19
|
-
gemini: {
|
|
20
|
-
name: 'Gemini CLI',
|
|
21
|
-
globalDir: path.join(os.homedir(), '.gemini'),
|
|
22
|
-
localDir: '.gemini',
|
|
23
|
-
commandsSubdir: 'commands',
|
|
24
|
-
promptFile: 'GEMINI.md',
|
|
25
|
-
promptSource: 'gemini.md',
|
|
26
|
-
commandStyle: 'flat',
|
|
27
|
-
},
|
|
28
30
|
openai: {
|
|
29
31
|
name: 'OpenAI Codex CLI',
|
|
30
32
|
globalDir: path.join(os.homedir(), '.codex'),
|
|
31
33
|
localDir: '.codex',
|
|
32
34
|
commandsSubdir: 'skills',
|
|
35
|
+
// Codex reads skills from the cross-tool ~/.agents/skills/, NOT ~/.codex/skills/.
|
|
36
|
+
skillsGlobalDir: path.join(os.homedir(), '.agents', 'skills'),
|
|
37
|
+
skillsLocalDir: path.join('.agents', 'skills'),
|
|
33
38
|
promptFile: 'AGENTS.md',
|
|
34
39
|
promptSource: 'openai.md',
|
|
35
40
|
commandStyle: 'skills',
|
|
41
|
+
skillName: true,
|
|
42
|
+
},
|
|
43
|
+
antigravity: {
|
|
44
|
+
name: 'Google Antigravity',
|
|
45
|
+
// NB: Antigravity reuses ~/.gemini/ and reads GEMINI.md globally + Markdown
|
|
46
|
+
// SKILL.md skills under ~/.gemini/skills/. These paths are community-sourced
|
|
47
|
+
// (official docs are JS SPAs) — VERIFY against a live Antigravity install.
|
|
48
|
+
globalDir: path.join(os.homedir(), '.gemini'),
|
|
49
|
+
localDir: '.',
|
|
50
|
+
commandsSubdir: 'skills',
|
|
51
|
+
skillsGlobalDir: path.join(os.homedir(), '.gemini', 'skills'),
|
|
52
|
+
skillsLocalDir: path.join('.agents', 'skills'),
|
|
53
|
+
promptFile: 'GEMINI.md',
|
|
54
|
+
promptSource: 'antigravity.md',
|
|
55
|
+
commandStyle: 'skills',
|
|
56
|
+
skillName: true,
|
|
36
57
|
},
|
|
37
58
|
opencode: {
|
|
38
59
|
name: 'OpenCode',
|
|
@@ -45,6 +66,14 @@ const RUNTIMES = {
|
|
|
45
66
|
},
|
|
46
67
|
};
|
|
47
68
|
|
|
69
|
+
/** Where skills install for a runtime+scope (decoupled from the prompt target). */
|
|
70
|
+
function skillsDestFor(config, scope) {
|
|
71
|
+
if (scope === 'global') {
|
|
72
|
+
return config.skillsGlobalDir || path.join(config.globalDir, config.commandsSubdir);
|
|
73
|
+
}
|
|
74
|
+
return config.skillsLocalDir || path.join(config.localDir, config.commandsSubdir);
|
|
75
|
+
}
|
|
76
|
+
|
|
48
77
|
const BRAIN_MARKER_START = '<!-- BRAIN-MEMORY-START -->';
|
|
49
78
|
const BRAIN_MARKER_END = '<!-- BRAIN-MEMORY-END -->';
|
|
50
79
|
|
|
@@ -66,17 +95,32 @@ function copyDir(src, dest, _depth = 0) {
|
|
|
66
95
|
}
|
|
67
96
|
}
|
|
68
97
|
|
|
69
|
-
function installSkills(commandsSrc, skillsDest) {
|
|
98
|
+
function installSkills(commandsSrc, skillsDest, addName = false) {
|
|
70
99
|
const entries = fs.readdirSync(commandsSrc).filter((f) => f.endsWith('.md'));
|
|
71
100
|
for (const file of entries) {
|
|
72
101
|
const name = file.replace('.md', '');
|
|
73
|
-
const
|
|
102
|
+
const skillFolder = `brain-${name}`;
|
|
103
|
+
const skillDir = path.join(skillsDest, skillFolder);
|
|
74
104
|
fs.mkdirSync(skillDir, { recursive: true });
|
|
75
|
-
fs.
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
105
|
+
let content = fs.readFileSync(path.join(commandsSrc, file), 'utf-8');
|
|
106
|
+
if (addName) content = ensureSkillName(content, skillFolder);
|
|
107
|
+
fs.writeFileSync(path.join(skillDir, 'SKILL.md'), content);
|
|
108
|
+
}
|
|
109
|
+
}
|
|
110
|
+
|
|
111
|
+
/**
|
|
112
|
+
* Codex and Antigravity require a `name:` frontmatter field that matches the
|
|
113
|
+
* skill folder. The source command files only carry `description:`, so inject
|
|
114
|
+
* `name:` as the first frontmatter field (idempotent — skips if already present).
|
|
115
|
+
*/
|
|
116
|
+
function ensureSkillName(content, name) {
|
|
117
|
+
if (/^---\s*\n/.test(content)) {
|
|
118
|
+
const end = content.indexOf('\n---', 3);
|
|
119
|
+
const block = end !== -1 ? content.slice(0, end) : content;
|
|
120
|
+
if (/^\s*name\s*:/m.test(block)) return content;
|
|
121
|
+
return content.replace(/^---\s*\n/, `---\nname: ${name}\n`);
|
|
79
122
|
}
|
|
123
|
+
return `---\nname: ${name}\n---\n\n${content}`;
|
|
80
124
|
}
|
|
81
125
|
|
|
82
126
|
function injectPrompt(targetDir, promptFile, promptSource) {
|
|
@@ -85,6 +129,11 @@ function injectPrompt(targetDir, promptFile, promptSource) {
|
|
|
85
129
|
'utf-8'
|
|
86
130
|
);
|
|
87
131
|
const targetPath = path.join(targetDir, promptFile);
|
|
132
|
+
// Ensure the prompt dir exists. Previously this was created as a side-effect
|
|
133
|
+
// of installing commands/skills into the same dir; now that skills can land
|
|
134
|
+
// elsewhere (e.g. Codex skills → ~/.agents/skills), the prompt dir (~/.codex)
|
|
135
|
+
// must be created explicitly.
|
|
136
|
+
fs.mkdirSync(targetDir, { recursive: true });
|
|
88
137
|
|
|
89
138
|
const wrappedContent = `\n${BRAIN_MARKER_START}\n${promptContent}\n${BRAIN_MARKER_END}\n`;
|
|
90
139
|
|
|
@@ -115,7 +164,7 @@ function detectInstallations() {
|
|
|
115
164
|
// Check for command files/dirs
|
|
116
165
|
let commandsFound = false;
|
|
117
166
|
if (config.commandStyle === 'skills') {
|
|
118
|
-
const skillsDir =
|
|
167
|
+
const skillsDir = skillsDestFor(config, scope);
|
|
119
168
|
commandsFound = fs.existsSync(skillsDir) &&
|
|
120
169
|
fs.readdirSync(skillsDir).some(
|
|
121
170
|
(d) => d.startsWith('brain-') &&
|
|
@@ -176,11 +225,14 @@ function removePromptSection(promptPath) {
|
|
|
176
225
|
return { removed: true, fileDeleted: false };
|
|
177
226
|
}
|
|
178
227
|
|
|
179
|
-
function removeCommands(targetDir, config) {
|
|
228
|
+
function removeCommands(targetDir, config, scope = 'global') {
|
|
180
229
|
const removed = [];
|
|
181
230
|
|
|
182
231
|
if (config.commandStyle === 'skills') {
|
|
183
|
-
|
|
232
|
+
// Honor an explicit skills override; otherwise resolve relative to the
|
|
233
|
+
// passed targetDir (so callers that pass a custom targetDir still work).
|
|
234
|
+
const override = scope === 'global' ? config.skillsGlobalDir : config.skillsLocalDir;
|
|
235
|
+
const skillsDir = override || path.join(targetDir, config.commandsSubdir);
|
|
184
236
|
if (fs.existsSync(skillsDir)) {
|
|
185
237
|
const entries = fs.readdirSync(skillsDir).filter((d) => d.startsWith('brain-'));
|
|
186
238
|
for (const entry of entries) {
|
|
@@ -212,7 +264,7 @@ function uninstallForRuntime(runtime, scope) {
|
|
|
212
264
|
const promptTarget = scope === 'global' ? config.globalDir : '.';
|
|
213
265
|
const promptPath = path.join(promptTarget, config.promptFile);
|
|
214
266
|
|
|
215
|
-
const removedCommands = removeCommands(targetDir, config);
|
|
267
|
+
const removedCommands = removeCommands(targetDir, config, scope);
|
|
216
268
|
const promptResult = removePromptSection(promptPath);
|
|
217
269
|
|
|
218
270
|
return { removedCommands, promptResult };
|
|
@@ -230,7 +282,7 @@ function installForRuntime(runtime, scope) {
|
|
|
230
282
|
const commandsSrc = path.join(PACKAGE_ROOT, 'commands', 'brain');
|
|
231
283
|
|
|
232
284
|
if (config.commandStyle === 'skills') {
|
|
233
|
-
const skillsDest =
|
|
285
|
+
const skillsDest = skillsDestFor(config, scope);
|
|
234
286
|
// Clear stale brain-* skill dirs first so renamed/removed commands don't
|
|
235
287
|
// linger across upgrades (e.g. brain-skill → brain-skills).
|
|
236
288
|
if (fs.existsSync(skillsDest)) {
|
|
@@ -240,7 +292,7 @@ function installForRuntime(runtime, scope) {
|
|
|
240
292
|
}
|
|
241
293
|
}
|
|
242
294
|
}
|
|
243
|
-
installSkills(commandsSrc, skillsDest);
|
|
295
|
+
installSkills(commandsSrc, skillsDest, config.skillName);
|
|
244
296
|
} else {
|
|
245
297
|
const commandsDest = path.join(targetDir, config.commandsSubdir, 'brain');
|
|
246
298
|
// Wipe the brain command dir before copying so renamed/removed commands
|
package/src/scorer.js
CHANGED
|
@@ -365,16 +365,21 @@ function computeSpreadingActivationBatch(scoredMemories, associations, maxDepth
|
|
|
365
365
|
* @returns {Object[]} Scored and sorted memories (highest first)
|
|
366
366
|
*/
|
|
367
367
|
function rankMemories(memories, relevanceFn, options = {}) {
|
|
368
|
+
// Guard every term against NaN (e.g. a missing/invalid last_accessed or
|
|
369
|
+
// strength) — a single NaN score sorts non-deterministically and can outrank
|
|
370
|
+
// valid results.
|
|
371
|
+
const fin = (x) => (Number.isFinite(x) ? x : 0);
|
|
372
|
+
|
|
368
373
|
// First pass: compute base scores
|
|
369
374
|
const scored = memories.map((mem) => {
|
|
370
|
-
const decayedStrength = computeDecayedStrength(
|
|
375
|
+
const decayedStrength = fin(computeDecayedStrength(
|
|
371
376
|
mem.strength,
|
|
372
377
|
mem.decay_rate,
|
|
373
378
|
mem.last_accessed,
|
|
374
379
|
!!(mem.stable || mem.pinned) // pinned ⇒ implicitly stable (decay-exempt)
|
|
375
|
-
);
|
|
376
|
-
const recencyBonus = computeRecencyBonus(mem.last_accessed);
|
|
377
|
-
const relevance = relevanceFn(mem);
|
|
380
|
+
));
|
|
381
|
+
const recencyBonus = fin(computeRecencyBonus(mem.last_accessed));
|
|
382
|
+
const relevance = fin(relevanceFn(mem));
|
|
378
383
|
|
|
379
384
|
return {
|
|
380
385
|
...mem,
|
|
@@ -420,12 +425,12 @@ function rankMemories(memories, relevanceFn, options = {}) {
|
|
|
420
425
|
if (mem.context_match > 0) extras.contextMatch = mem.context_match;
|
|
421
426
|
if (mem.salience != null) extras.salience = mem.salience;
|
|
422
427
|
|
|
423
|
-
const score = computeRecallScore(
|
|
428
|
+
const score = fin(computeRecallScore(
|
|
424
429
|
mem.relevance,
|
|
425
430
|
mem.decayed_strength,
|
|
426
431
|
mem.recency_bonus,
|
|
427
432
|
extras
|
|
428
|
-
);
|
|
433
|
+
));
|
|
429
434
|
|
|
430
435
|
return {
|
|
431
436
|
...mem,
|
|
@@ -437,7 +442,9 @@ function rankMemories(memories, relevanceFn, options = {}) {
|
|
|
437
442
|
score: Math.round(score * 1000) / 1000,
|
|
438
443
|
};
|
|
439
444
|
})
|
|
440
|
-
|
|
445
|
+
// Deterministic order: score desc, then id asc to break ties (scores are
|
|
446
|
+
// rounded to 3dp, which manufactures ties at scale).
|
|
447
|
+
.sort((a, b) => (b.score - a.score) || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
|
|
441
448
|
}
|
|
442
449
|
|
|
443
450
|
module.exports = {
|
package/src/tfidf.js
CHANGED
|
@@ -348,6 +348,74 @@ function search(searchIndex, query) {
|
|
|
348
348
|
return scores;
|
|
349
349
|
}
|
|
350
350
|
|
|
351
|
+
/**
|
|
352
|
+
* BM25 relevance scoring for a query against all indexed memories.
|
|
353
|
+
*
|
|
354
|
+
* Fixes two TF-IDF-cosine weaknesses that buried long, detailed memories under
|
|
355
|
+
* short distractors: BM25 SATURATES term frequency (k1) and normalizes document
|
|
356
|
+
* length GENTLY (b), instead of dividing TF by full length and cosine by full
|
|
357
|
+
* magnitude (which penalized the richer oracle memories for being longer). The
|
|
358
|
+
* field weighting baked into the index (title 3x, tags 2x via buildMemoryText)
|
|
359
|
+
* is preserved. Scores are normalized to 0..1 by the top score so they blend
|
|
360
|
+
* cleanly into the scorer's recall formula (which expects relevance in [0,1]).
|
|
361
|
+
*
|
|
362
|
+
* @param {Object} searchIndex - The search index
|
|
363
|
+
* @param {string} query - The search query
|
|
364
|
+
* @param {Object} [opts] - { k1 = 1.5, b = 0.75 }
|
|
365
|
+
* @returns {Object} Map of memoryId → normalized relevance score (0.0-1.0)
|
|
366
|
+
*/
|
|
367
|
+
function bm25Search(searchIndex, query, opts = {}) {
|
|
368
|
+
if (!searchIndex || searchIndex.doc_count === 0) return {};
|
|
369
|
+
|
|
370
|
+
const queryTokens = tokenize(query);
|
|
371
|
+
if (queryTokens.length === 0) return {};
|
|
372
|
+
|
|
373
|
+
const k1 = opts.k1 != null ? opts.k1 : 1.5;
|
|
374
|
+
const b = opts.b != null ? opts.b : 0.75;
|
|
375
|
+
const N = searchIndex.doc_count;
|
|
376
|
+
|
|
377
|
+
// Average document length (for length normalization).
|
|
378
|
+
let totalLen = 0;
|
|
379
|
+
for (const d of Object.values(searchIndex.documents)) totalLen += d.length || 0;
|
|
380
|
+
const avgdl = N > 0 ? totalLen / N : 0;
|
|
381
|
+
|
|
382
|
+
// BM25 IDF per (deduped) query term, floored at 0 so a term present in nearly
|
|
383
|
+
// every document can't contribute a negative score.
|
|
384
|
+
const qTerms = [...new Set(queryTokens)];
|
|
385
|
+
const idf = {};
|
|
386
|
+
for (const t of qTerms) {
|
|
387
|
+
const df = searchIndex.df[t] || 0;
|
|
388
|
+
idf[t] = Math.max(0, Math.log(1 + (N - df + 0.5) / (df + 0.5)));
|
|
389
|
+
}
|
|
390
|
+
|
|
391
|
+
const raw = {};
|
|
392
|
+
let maxScore = 0;
|
|
393
|
+
for (const [memoryId, doc] of Object.entries(searchIndex.documents)) {
|
|
394
|
+
const dl = doc.length || 0;
|
|
395
|
+
let score = 0;
|
|
396
|
+
for (const t of qTerms) {
|
|
397
|
+
const f = doc.tf[t] || 0;
|
|
398
|
+
if (f === 0) continue;
|
|
399
|
+
const denom = f + k1 * (1 - b + b * (avgdl > 0 ? dl / avgdl : 0));
|
|
400
|
+
score += idf[t] * (f * (k1 + 1)) / denom;
|
|
401
|
+
}
|
|
402
|
+
if (score > 0) {
|
|
403
|
+
raw[memoryId] = score;
|
|
404
|
+
if (score > maxScore) maxScore = score;
|
|
405
|
+
}
|
|
406
|
+
}
|
|
407
|
+
|
|
408
|
+
// Normalize to 0..1 by the top score — preserves ranking and keeps the [0,1]
|
|
409
|
+
// contract the recall scorer's relevance blend expects.
|
|
410
|
+
const scores = {};
|
|
411
|
+
if (maxScore > 0) {
|
|
412
|
+
for (const [id, s] of Object.entries(raw)) {
|
|
413
|
+
scores[id] = Math.round((s / maxScore) * 1000) / 1000;
|
|
414
|
+
}
|
|
415
|
+
}
|
|
416
|
+
return scores;
|
|
417
|
+
}
|
|
418
|
+
|
|
351
419
|
/**
|
|
352
420
|
* Rebuild the entire search index from memory files on disk.
|
|
353
421
|
*
|
|
@@ -401,6 +469,7 @@ module.exports = {
|
|
|
401
469
|
removeDocument,
|
|
402
470
|
computeIdf,
|
|
403
471
|
search,
|
|
472
|
+
bm25Search,
|
|
404
473
|
rebuildIndex,
|
|
405
474
|
// Constants
|
|
406
475
|
SEARCH_INDEX_FILE,
|