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/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 skillDir = path.join(skillsDest, `brain-${name}`);
102
+ const skillFolder = `brain-${name}`;
103
+ const skillDir = path.join(skillsDest, skillFolder);
74
104
  fs.mkdirSync(skillDir, { recursive: true });
75
- fs.copyFileSync(
76
- path.join(commandsSrc, file),
77
- path.join(skillDir, 'SKILL.md')
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 = path.join(targetDir, config.commandsSubdir);
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
- const skillsDir = path.join(targetDir, config.commandsSubdir);
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 = path.join(targetDir, config.commandsSubdir);
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
- .sort((a, b) => b.score - a.score);
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,