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.
- package/CHANGELOG.md +319 -0
- package/README.md +379 -95
- 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 +251 -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 +22 -9
- package/src/skills.js +208 -0
- package/src/tfidf.js +501 -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/installer.js
ADDED
|
@@ -0,0 +1,444 @@
|
|
|
1
|
+
const fs = require('fs');
|
|
2
|
+
const path = require('path');
|
|
3
|
+
const os = require('os');
|
|
4
|
+
|
|
5
|
+
const { getBrainDir } = require('./index-manager');
|
|
6
|
+
|
|
7
|
+
const PACKAGE_ROOT = path.resolve(__dirname, '..');
|
|
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.
|
|
20
|
+
const RUNTIMES = {
|
|
21
|
+
claude: {
|
|
22
|
+
name: 'Claude Code',
|
|
23
|
+
globalDir: path.join(os.homedir(), '.claude'),
|
|
24
|
+
localDir: '.claude',
|
|
25
|
+
commandsSubdir: 'commands',
|
|
26
|
+
promptFile: 'CLAUDE.md',
|
|
27
|
+
promptSource: 'claude.md',
|
|
28
|
+
commandStyle: 'flat',
|
|
29
|
+
},
|
|
30
|
+
openai: {
|
|
31
|
+
name: 'OpenAI Codex CLI',
|
|
32
|
+
globalDir: path.join(os.homedir(), '.codex'),
|
|
33
|
+
localDir: '.codex',
|
|
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'),
|
|
38
|
+
promptFile: 'AGENTS.md',
|
|
39
|
+
promptSource: 'openai.md',
|
|
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,
|
|
57
|
+
},
|
|
58
|
+
opencode: {
|
|
59
|
+
name: 'OpenCode',
|
|
60
|
+
globalDir: path.join(os.homedir(), '.config', 'opencode'),
|
|
61
|
+
localDir: '.opencode',
|
|
62
|
+
commandsSubdir: 'commands',
|
|
63
|
+
promptFile: 'AGENTS.md',
|
|
64
|
+
promptSource: 'opencode.md',
|
|
65
|
+
commandStyle: 'flat',
|
|
66
|
+
},
|
|
67
|
+
};
|
|
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
|
+
|
|
77
|
+
const BRAIN_MARKER_START = '<!-- BRAIN-MEMORY-START -->';
|
|
78
|
+
const BRAIN_MARKER_END = '<!-- BRAIN-MEMORY-END -->';
|
|
79
|
+
|
|
80
|
+
function copyDir(src, dest, _depth = 0) {
|
|
81
|
+
if (_depth > 20) {
|
|
82
|
+
throw new Error(`copyDir: max depth (20) exceeded at ${src}`);
|
|
83
|
+
}
|
|
84
|
+
fs.mkdirSync(dest, { recursive: true });
|
|
85
|
+
const entries = fs.readdirSync(src, { withFileTypes: true });
|
|
86
|
+
for (const entry of entries) {
|
|
87
|
+
if (entry.isSymbolicLink()) continue;
|
|
88
|
+
const srcPath = path.join(src, entry.name);
|
|
89
|
+
const destPath = path.join(dest, entry.name);
|
|
90
|
+
if (entry.isDirectory()) {
|
|
91
|
+
copyDir(srcPath, destPath, _depth + 1);
|
|
92
|
+
} else {
|
|
93
|
+
fs.copyFileSync(srcPath, destPath);
|
|
94
|
+
}
|
|
95
|
+
}
|
|
96
|
+
}
|
|
97
|
+
|
|
98
|
+
function installSkills(commandsSrc, skillsDest, addName = false) {
|
|
99
|
+
const entries = fs.readdirSync(commandsSrc).filter((f) => f.endsWith('.md'));
|
|
100
|
+
for (const file of entries) {
|
|
101
|
+
const name = file.replace('.md', '');
|
|
102
|
+
const skillFolder = `brain-${name}`;
|
|
103
|
+
const skillDir = path.join(skillsDest, skillFolder);
|
|
104
|
+
fs.mkdirSync(skillDir, { recursive: true });
|
|
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`);
|
|
122
|
+
}
|
|
123
|
+
return `---\nname: ${name}\n---\n\n${content}`;
|
|
124
|
+
}
|
|
125
|
+
|
|
126
|
+
function injectPrompt(targetDir, promptFile, promptSource) {
|
|
127
|
+
const promptContent = fs.readFileSync(
|
|
128
|
+
path.join(PACKAGE_ROOT, 'prompts', promptSource),
|
|
129
|
+
'utf-8'
|
|
130
|
+
);
|
|
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 });
|
|
137
|
+
|
|
138
|
+
const wrappedContent = `\n${BRAIN_MARKER_START}\n${promptContent}\n${BRAIN_MARKER_END}\n`;
|
|
139
|
+
|
|
140
|
+
if (fs.existsSync(targetPath)) {
|
|
141
|
+
let existing = fs.readFileSync(targetPath, 'utf-8');
|
|
142
|
+
// Remove old brain section if present
|
|
143
|
+
const startIdx = existing.indexOf(BRAIN_MARKER_START);
|
|
144
|
+
const endIdx = existing.indexOf(BRAIN_MARKER_END);
|
|
145
|
+
if (startIdx !== -1 && endIdx !== -1) {
|
|
146
|
+
existing =
|
|
147
|
+
existing.substring(0, startIdx) +
|
|
148
|
+
existing.substring(endIdx + BRAIN_MARKER_END.length);
|
|
149
|
+
}
|
|
150
|
+
fs.writeFileSync(targetPath, existing.trimEnd() + '\n' + wrappedContent);
|
|
151
|
+
} else {
|
|
152
|
+
fs.writeFileSync(targetPath, wrappedContent.trim() + '\n');
|
|
153
|
+
}
|
|
154
|
+
}
|
|
155
|
+
|
|
156
|
+
function detectInstallations() {
|
|
157
|
+
const results = [];
|
|
158
|
+
for (const [runtime, config] of Object.entries(RUNTIMES)) {
|
|
159
|
+
for (const scope of ['global', 'local']) {
|
|
160
|
+
const targetDir = scope === 'global' ? config.globalDir : config.localDir;
|
|
161
|
+
const promptTarget = scope === 'global' ? config.globalDir : '.';
|
|
162
|
+
const promptPath = path.join(promptTarget, config.promptFile);
|
|
163
|
+
|
|
164
|
+
// Check for command files/dirs
|
|
165
|
+
let commandsFound = false;
|
|
166
|
+
if (config.commandStyle === 'skills') {
|
|
167
|
+
const skillsDir = skillsDestFor(config, scope);
|
|
168
|
+
commandsFound = fs.existsSync(skillsDir) &&
|
|
169
|
+
fs.readdirSync(skillsDir).some(
|
|
170
|
+
(d) => d.startsWith('brain-') &&
|
|
171
|
+
fs.existsSync(path.join(skillsDir, d, 'SKILL.md'))
|
|
172
|
+
);
|
|
173
|
+
} else {
|
|
174
|
+
const commandsDir = path.join(targetDir, config.commandsSubdir, 'brain');
|
|
175
|
+
commandsFound = fs.existsSync(commandsDir) &&
|
|
176
|
+
fs.readdirSync(commandsDir).some((f) => f.endsWith('.md'));
|
|
177
|
+
}
|
|
178
|
+
|
|
179
|
+
// Check for prompt markers
|
|
180
|
+
let promptFound = false;
|
|
181
|
+
if (fs.existsSync(promptPath)) {
|
|
182
|
+
const content = fs.readFileSync(promptPath, 'utf-8');
|
|
183
|
+
promptFound = content.includes(BRAIN_MARKER_START) && content.includes(BRAIN_MARKER_END);
|
|
184
|
+
}
|
|
185
|
+
|
|
186
|
+
if (commandsFound || promptFound) {
|
|
187
|
+
results.push({
|
|
188
|
+
runtime,
|
|
189
|
+
scope,
|
|
190
|
+
runtimeName: config.name,
|
|
191
|
+
commandsFound,
|
|
192
|
+
promptFound,
|
|
193
|
+
targetDir,
|
|
194
|
+
promptPath,
|
|
195
|
+
});
|
|
196
|
+
}
|
|
197
|
+
}
|
|
198
|
+
}
|
|
199
|
+
return results;
|
|
200
|
+
}
|
|
201
|
+
|
|
202
|
+
function removePromptSection(promptPath) {
|
|
203
|
+
if (!fs.existsSync(promptPath)) {
|
|
204
|
+
return { removed: false, reason: 'file-not-found' };
|
|
205
|
+
}
|
|
206
|
+
|
|
207
|
+
const content = fs.readFileSync(promptPath, 'utf-8');
|
|
208
|
+
const startIdx = content.indexOf(BRAIN_MARKER_START);
|
|
209
|
+
const endIdx = content.indexOf(BRAIN_MARKER_END);
|
|
210
|
+
|
|
211
|
+
if (startIdx === -1 || endIdx === -1) {
|
|
212
|
+
return { removed: false, reason: 'no-markers' };
|
|
213
|
+
}
|
|
214
|
+
|
|
215
|
+
const before = content.substring(0, startIdx);
|
|
216
|
+
const after = content.substring(endIdx + BRAIN_MARKER_END.length);
|
|
217
|
+
const remaining = (before + after).trim();
|
|
218
|
+
|
|
219
|
+
if (remaining.length === 0) {
|
|
220
|
+
fs.unlinkSync(promptPath);
|
|
221
|
+
return { removed: true, fileDeleted: true };
|
|
222
|
+
}
|
|
223
|
+
|
|
224
|
+
fs.writeFileSync(promptPath, remaining + '\n');
|
|
225
|
+
return { removed: true, fileDeleted: false };
|
|
226
|
+
}
|
|
227
|
+
|
|
228
|
+
function removeCommands(targetDir, config, scope = 'global') {
|
|
229
|
+
const removed = [];
|
|
230
|
+
|
|
231
|
+
if (config.commandStyle === 'skills') {
|
|
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);
|
|
236
|
+
if (fs.existsSync(skillsDir)) {
|
|
237
|
+
const entries = fs.readdirSync(skillsDir).filter((d) => d.startsWith('brain-'));
|
|
238
|
+
for (const entry of entries) {
|
|
239
|
+
const fullPath = path.join(skillsDir, entry);
|
|
240
|
+
fs.rmSync(fullPath, { recursive: true, force: true });
|
|
241
|
+
removed.push(fullPath);
|
|
242
|
+
}
|
|
243
|
+
}
|
|
244
|
+
} else {
|
|
245
|
+
const commandsDir = path.join(targetDir, config.commandsSubdir, 'brain');
|
|
246
|
+
if (fs.existsSync(commandsDir)) {
|
|
247
|
+
removed.push(commandsDir);
|
|
248
|
+
fs.rmSync(commandsDir, { recursive: true, force: true });
|
|
249
|
+
}
|
|
250
|
+
}
|
|
251
|
+
|
|
252
|
+
return removed;
|
|
253
|
+
}
|
|
254
|
+
|
|
255
|
+
function uninstallForRuntime(runtime, scope) {
|
|
256
|
+
if (!Object.keys(RUNTIMES).includes(runtime)) {
|
|
257
|
+
throw new Error(`Unknown runtime: ${runtime}. Valid: ${Object.keys(RUNTIMES).join(', ')}`);
|
|
258
|
+
}
|
|
259
|
+
if (scope !== 'global' && scope !== 'local') {
|
|
260
|
+
throw new Error(`Invalid scope: ${scope}. Must be 'global' or 'local'.`);
|
|
261
|
+
}
|
|
262
|
+
const config = RUNTIMES[runtime];
|
|
263
|
+
const targetDir = scope === 'global' ? config.globalDir : config.localDir;
|
|
264
|
+
const promptTarget = scope === 'global' ? config.globalDir : '.';
|
|
265
|
+
const promptPath = path.join(promptTarget, config.promptFile);
|
|
266
|
+
|
|
267
|
+
const removedCommands = removeCommands(targetDir, config, scope);
|
|
268
|
+
const promptResult = removePromptSection(promptPath);
|
|
269
|
+
|
|
270
|
+
return { removedCommands, promptResult };
|
|
271
|
+
}
|
|
272
|
+
|
|
273
|
+
function installForRuntime(runtime, scope) {
|
|
274
|
+
if (!Object.keys(RUNTIMES).includes(runtime)) {
|
|
275
|
+
throw new Error(`Unknown runtime: ${runtime}. Valid: ${Object.keys(RUNTIMES).join(', ')}`);
|
|
276
|
+
}
|
|
277
|
+
if (scope !== 'global' && scope !== 'local') {
|
|
278
|
+
throw new Error(`Invalid scope: ${scope}. Must be 'global' or 'local'.`);
|
|
279
|
+
}
|
|
280
|
+
const config = RUNTIMES[runtime];
|
|
281
|
+
const targetDir = scope === 'global' ? config.globalDir : config.localDir;
|
|
282
|
+
const commandsSrc = path.join(PACKAGE_ROOT, 'commands', 'brain');
|
|
283
|
+
|
|
284
|
+
if (config.commandStyle === 'skills') {
|
|
285
|
+
const skillsDest = skillsDestFor(config, scope);
|
|
286
|
+
// Clear stale brain-* skill dirs first so renamed/removed commands don't
|
|
287
|
+
// linger across upgrades (e.g. brain-skill → brain-skills).
|
|
288
|
+
if (fs.existsSync(skillsDest)) {
|
|
289
|
+
for (const entry of fs.readdirSync(skillsDest)) {
|
|
290
|
+
if (entry.startsWith('brain-')) {
|
|
291
|
+
fs.rmSync(path.join(skillsDest, entry), { recursive: true, force: true });
|
|
292
|
+
}
|
|
293
|
+
}
|
|
294
|
+
}
|
|
295
|
+
installSkills(commandsSrc, skillsDest, config.skillName);
|
|
296
|
+
} else {
|
|
297
|
+
const commandsDest = path.join(targetDir, config.commandsSubdir, 'brain');
|
|
298
|
+
// Wipe the brain command dir before copying so renamed/removed commands
|
|
299
|
+
// don't linger across upgrades. This is critical on case-insensitive
|
|
300
|
+
// filesystems: a leftover skill.md (== SKILL.md) makes Claude Code treat
|
|
301
|
+
// the whole dir as one skill and hides every /brain:* command.
|
|
302
|
+
fs.rmSync(commandsDest, { recursive: true, force: true });
|
|
303
|
+
copyDir(commandsSrc, commandsDest);
|
|
304
|
+
}
|
|
305
|
+
|
|
306
|
+
const promptTarget = scope === 'global' ? config.globalDir : '.';
|
|
307
|
+
injectPrompt(promptTarget, config.promptFile, config.promptSource);
|
|
308
|
+
}
|
|
309
|
+
|
|
310
|
+
function initializeBrain(overrideBase) {
|
|
311
|
+
// Honors $BRAIN_DIR (via getBrainDir) so a fresh brain is created wherever the
|
|
312
|
+
// user points it — e.g. inside a Google Drive / Dropbox / iCloud synced folder.
|
|
313
|
+
const brainDir = overrideBase ? path.join(overrideBase, '.brain') : getBrainDir();
|
|
314
|
+
|
|
315
|
+
if (fs.existsSync(brainDir)) {
|
|
316
|
+
return { alreadyExists: true };
|
|
317
|
+
}
|
|
318
|
+
|
|
319
|
+
const now = new Date().toISOString();
|
|
320
|
+
|
|
321
|
+
// Create directories
|
|
322
|
+
const categories = ['professional', 'personal', 'social', 'family', '_consolidated', '_archived'];
|
|
323
|
+
for (const cat of categories) {
|
|
324
|
+
fs.mkdirSync(path.join(brainDir, cat), { recursive: true });
|
|
325
|
+
}
|
|
326
|
+
|
|
327
|
+
// Create index.json
|
|
328
|
+
const index = {
|
|
329
|
+
version: 2,
|
|
330
|
+
created: now,
|
|
331
|
+
last_updated: now,
|
|
332
|
+
memory_count: 0,
|
|
333
|
+
memories: {},
|
|
334
|
+
config: {
|
|
335
|
+
max_depth: 6,
|
|
336
|
+
consolidation_threshold: 0.3,
|
|
337
|
+
decay_check_interval_days: 7,
|
|
338
|
+
strength_boost_on_recall: 0.05,
|
|
339
|
+
auto_consolidate: true,
|
|
340
|
+
propagation_window_days: 7,
|
|
341
|
+
association_config: {
|
|
342
|
+
co_retrieval_boost: 0.10,
|
|
343
|
+
link_decay_rate: 0.998,
|
|
344
|
+
link_prune_threshold: 0.05,
|
|
345
|
+
spreading_activation_depth: 2,
|
|
346
|
+
spreading_activation_decay: 0.5,
|
|
347
|
+
},
|
|
348
|
+
},
|
|
349
|
+
};
|
|
350
|
+
fs.writeFileSync(
|
|
351
|
+
path.join(brainDir, 'index.json'),
|
|
352
|
+
JSON.stringify(index, null, 2) + '\n'
|
|
353
|
+
);
|
|
354
|
+
|
|
355
|
+
// Create associations.json
|
|
356
|
+
fs.writeFileSync(
|
|
357
|
+
path.join(brainDir, 'associations.json'),
|
|
358
|
+
JSON.stringify({ version: 1, edges: {} }, null, 2) + '\n'
|
|
359
|
+
);
|
|
360
|
+
|
|
361
|
+
// Create contexts.json
|
|
362
|
+
fs.writeFileSync(
|
|
363
|
+
path.join(brainDir, 'contexts.json'),
|
|
364
|
+
JSON.stringify({ version: 1, sessions: [] }, null, 2) + '\n'
|
|
365
|
+
);
|
|
366
|
+
|
|
367
|
+
// Create review-queue.json
|
|
368
|
+
fs.writeFileSync(
|
|
369
|
+
path.join(brainDir, 'review-queue.json'),
|
|
370
|
+
JSON.stringify({ version: 1, items: [] }, null, 2) + '\n'
|
|
371
|
+
);
|
|
372
|
+
|
|
373
|
+
// Create _archived/index.json
|
|
374
|
+
fs.writeFileSync(
|
|
375
|
+
path.join(brainDir, '_archived', 'index.json'),
|
|
376
|
+
JSON.stringify({ version: 1, archived_count: 0, memories: {} }, null, 2) + '\n'
|
|
377
|
+
);
|
|
378
|
+
|
|
379
|
+
// Create search-index.json (TF-IDF)
|
|
380
|
+
fs.writeFileSync(
|
|
381
|
+
path.join(brainDir, 'search-index.json'),
|
|
382
|
+
JSON.stringify({ version: 1, doc_count: 0, documents: {}, df: {} }, null, 2) + '\n'
|
|
383
|
+
);
|
|
384
|
+
|
|
385
|
+
// Load category descriptions from template
|
|
386
|
+
const templatePath = path.join(PACKAGE_ROOT, 'templates', 'default-categories.json');
|
|
387
|
+
let template = { top_categories: [] };
|
|
388
|
+
if (fs.existsSync(templatePath)) {
|
|
389
|
+
template = JSON.parse(fs.readFileSync(templatePath, 'utf-8'));
|
|
390
|
+
}
|
|
391
|
+
|
|
392
|
+
// Create _meta.json for each category
|
|
393
|
+
const mainCategories = ['professional', 'personal', 'social', 'family'];
|
|
394
|
+
for (const cat of mainCategories) {
|
|
395
|
+
const templateCat = template.top_categories.find((c) => c.name === cat) || {};
|
|
396
|
+
const meta = {
|
|
397
|
+
category: cat,
|
|
398
|
+
description: templateCat.description || cat,
|
|
399
|
+
created: now,
|
|
400
|
+
memory_count: 0,
|
|
401
|
+
subcategories: [],
|
|
402
|
+
};
|
|
403
|
+
fs.writeFileSync(
|
|
404
|
+
path.join(brainDir, cat, '_meta.json'),
|
|
405
|
+
JSON.stringify(meta, null, 2) + '\n'
|
|
406
|
+
);
|
|
407
|
+
}
|
|
408
|
+
|
|
409
|
+
// Create _meta.json for special directories
|
|
410
|
+
for (const special of ['_consolidated', '_archived']) {
|
|
411
|
+
const meta = {
|
|
412
|
+
category: special,
|
|
413
|
+
description:
|
|
414
|
+
special === '_consolidated'
|
|
415
|
+
? 'Merged memories from consolidation operations'
|
|
416
|
+
: 'Archived memories preserved for recovery',
|
|
417
|
+
created: now,
|
|
418
|
+
memory_count: 0,
|
|
419
|
+
subcategories: [],
|
|
420
|
+
};
|
|
421
|
+
fs.writeFileSync(
|
|
422
|
+
path.join(brainDir, special, '_meta.json'),
|
|
423
|
+
JSON.stringify(meta, null, 2) + '\n'
|
|
424
|
+
);
|
|
425
|
+
}
|
|
426
|
+
|
|
427
|
+
return { alreadyExists: false, brainDir };
|
|
428
|
+
}
|
|
429
|
+
|
|
430
|
+
module.exports = {
|
|
431
|
+
RUNTIMES,
|
|
432
|
+
BRAIN_MARKER_START,
|
|
433
|
+
BRAIN_MARKER_END,
|
|
434
|
+
PACKAGE_ROOT,
|
|
435
|
+
copyDir,
|
|
436
|
+
installSkills,
|
|
437
|
+
injectPrompt,
|
|
438
|
+
installForRuntime,
|
|
439
|
+
initializeBrain,
|
|
440
|
+
detectInstallations,
|
|
441
|
+
removePromptSection,
|
|
442
|
+
removeCommands,
|
|
443
|
+
uninstallForRuntime,
|
|
444
|
+
};
|
package/src/pinning.js
ADDED
|
@@ -0,0 +1,124 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Brain Memory — Pinning (CoALA Phase 1)
|
|
3
|
+
*
|
|
4
|
+
* Pin/unpin a memory into the always-present semantic tier. Pinning is the fix
|
|
5
|
+
* for the core reliability hole: a durable convention/preference must apply
|
|
6
|
+
* every session regardless of recall score. A pinned memory is implicitly
|
|
7
|
+
* decay-exempt (the scorer treats pinned || stable as exempt).
|
|
8
|
+
*
|
|
9
|
+
* The index entry is the source of truth read by recall/session-start; the
|
|
10
|
+
* memory file's frontmatter is kept in sync for human-readability and git.
|
|
11
|
+
*/
|
|
12
|
+
|
|
13
|
+
const fs = require('fs');
|
|
14
|
+
const path = require('path');
|
|
15
|
+
|
|
16
|
+
const {
|
|
17
|
+
getBrainDir,
|
|
18
|
+
readIndex,
|
|
19
|
+
writeIndex,
|
|
20
|
+
readPinned,
|
|
21
|
+
writePinned,
|
|
22
|
+
} = require('./index-manager');
|
|
23
|
+
|
|
24
|
+
/** chars/4 token estimate; falls back to the title line for older entries. */
|
|
25
|
+
function estimateTokens(entry) {
|
|
26
|
+
if (entry && typeof entry.token_estimate === 'number') return entry.token_estimate;
|
|
27
|
+
return Math.ceil((((entry && entry.title) || '').length + 8) / 4);
|
|
28
|
+
}
|
|
29
|
+
|
|
30
|
+
/**
|
|
31
|
+
* Update-or-insert scalar YAML frontmatter fields in a memory file (best effort;
|
|
32
|
+
* the index entry remains the source of truth if the file is unreadable).
|
|
33
|
+
*/
|
|
34
|
+
function setFrontmatterFields(brainDir, memPath, fields) {
|
|
35
|
+
const fullPath = path.join(brainDir, memPath);
|
|
36
|
+
let content;
|
|
37
|
+
try { content = fs.readFileSync(fullPath, 'utf-8'); } catch (_) { return; }
|
|
38
|
+
|
|
39
|
+
const first = content.indexOf('---');
|
|
40
|
+
const second = content.indexOf('---', first + 3);
|
|
41
|
+
if (first === -1 || second === -1) return;
|
|
42
|
+
|
|
43
|
+
let fm = content.slice(first + 3, second);
|
|
44
|
+
const inserts = [];
|
|
45
|
+
for (const [key, value] of Object.entries(fields)) {
|
|
46
|
+
const formatted = typeof value === 'string' ? `"${value}"` : String(value);
|
|
47
|
+
const re = new RegExp(`^(${key}:\\s*).*$`, 'm');
|
|
48
|
+
if (re.test(fm)) fm = fm.replace(re, `$1${formatted}`);
|
|
49
|
+
else inserts.push(`${key}: ${formatted}\n`);
|
|
50
|
+
}
|
|
51
|
+
if (inserts.length) fm = fm.replace(/\s*$/, '\n') + inserts.join('');
|
|
52
|
+
|
|
53
|
+
content = content.slice(0, first + 3) + fm + content.slice(second);
|
|
54
|
+
fs.writeFileSync(fullPath, content);
|
|
55
|
+
}
|
|
56
|
+
|
|
57
|
+
/**
|
|
58
|
+
* Pin a memory (always-loaded). Sets pinned/pin_scope/pin_priority on the index
|
|
59
|
+
* entry + frontmatter and records it in pinned.json.
|
|
60
|
+
*
|
|
61
|
+
* @param {string} [projectRoot] - Filesystem root (undefined = real ~/.brain)
|
|
62
|
+
* @param {string} id - Memory ID
|
|
63
|
+
* @param {Object} [opts] - { scope = "global"|"project:<name>", priority = 0 }
|
|
64
|
+
* @returns {Object} Result or { error }
|
|
65
|
+
*/
|
|
66
|
+
function pinMemory(projectRoot, id, opts = {}) {
|
|
67
|
+
const scope = opts.scope || 'global';
|
|
68
|
+
const priority = Number.isFinite(opts.priority) ? opts.priority : 0;
|
|
69
|
+
|
|
70
|
+
const index = readIndex(projectRoot);
|
|
71
|
+
if (!index || !index.memories || !index.memories[id]) {
|
|
72
|
+
return { error: `Memory not found: ${id}` };
|
|
73
|
+
}
|
|
74
|
+
|
|
75
|
+
const entry = index.memories[id];
|
|
76
|
+
entry.pinned = true;
|
|
77
|
+
entry.pin_scope = scope;
|
|
78
|
+
entry.pin_priority = priority;
|
|
79
|
+
writeIndex(index, projectRoot);
|
|
80
|
+
|
|
81
|
+
setFrontmatterFields(getBrainDir(projectRoot), entry.path, {
|
|
82
|
+
pinned: true,
|
|
83
|
+
pin_scope: scope,
|
|
84
|
+
pin_priority: priority,
|
|
85
|
+
});
|
|
86
|
+
|
|
87
|
+
const pinned = readPinned(projectRoot);
|
|
88
|
+
pinned.pins = pinned.pins.filter((p) => p.id !== id);
|
|
89
|
+
pinned.pins.push({ id, scope, priority, token_estimate: estimateTokens(entry) });
|
|
90
|
+
writePinned(pinned, projectRoot);
|
|
91
|
+
|
|
92
|
+
return { id, pinned: true, scope, priority };
|
|
93
|
+
}
|
|
94
|
+
|
|
95
|
+
/**
|
|
96
|
+
* Unpin a memory. Clears the pinned flag and removes it from pinned.json. Leaves
|
|
97
|
+
* an independent `stable` flag untouched.
|
|
98
|
+
*
|
|
99
|
+
* @param {string} [projectRoot] - Filesystem root (undefined = real ~/.brain)
|
|
100
|
+
* @param {string} id - Memory ID
|
|
101
|
+
* @returns {Object} Result or { error }
|
|
102
|
+
*/
|
|
103
|
+
function unpinMemory(projectRoot, id) {
|
|
104
|
+
const index = readIndex(projectRoot);
|
|
105
|
+
if (!index || !index.memories || !index.memories[id]) {
|
|
106
|
+
return { error: `Memory not found: ${id}` };
|
|
107
|
+
}
|
|
108
|
+
|
|
109
|
+
const entry = index.memories[id];
|
|
110
|
+
const wasPinned = !!entry.pinned;
|
|
111
|
+
entry.pinned = false;
|
|
112
|
+
writeIndex(index, projectRoot);
|
|
113
|
+
|
|
114
|
+
setFrontmatterFields(getBrainDir(projectRoot), entry.path, { pinned: false });
|
|
115
|
+
|
|
116
|
+
const pinned = readPinned(projectRoot);
|
|
117
|
+
const before = pinned.pins.length;
|
|
118
|
+
pinned.pins = pinned.pins.filter((p) => p.id !== id);
|
|
119
|
+
writePinned(pinned, projectRoot);
|
|
120
|
+
|
|
121
|
+
return { id, pinned: false, was_pinned: wasPinned, removed: before !== pinned.pins.length };
|
|
122
|
+
}
|
|
123
|
+
|
|
124
|
+
module.exports = { pinMemory, unpinMemory, estimateTokens, setFrontmatterFields };
|
package/src/scorer.js
CHANGED
|
@@ -13,9 +13,12 @@
|
|
|
13
13
|
* @param {number} baseStrength - Original strength (0.0-1.0)
|
|
14
14
|
* @param {number} decayRate - Daily decay factor (e.g., 0.995)
|
|
15
15
|
* @param {string|Date} lastAccessed - ISO timestamp of last access
|
|
16
|
+
* @param {boolean} [exempt=false] - CoALA Phase 1: pinned/stable memories are
|
|
17
|
+
* decay-exempt — their strength never fades (semantic "stable" property).
|
|
16
18
|
* @returns {number} Effective strength after decay
|
|
17
19
|
*/
|
|
18
|
-
function computeDecayedStrength(baseStrength, decayRate, lastAccessed) {
|
|
20
|
+
function computeDecayedStrength(baseStrength, decayRate, lastAccessed, exempt = false) {
|
|
21
|
+
if (exempt) return baseStrength;
|
|
19
22
|
const lastDate = new Date(lastAccessed);
|
|
20
23
|
const now = new Date();
|
|
21
24
|
const daysElapsed = (now - lastDate) / (1000 * 60 * 60 * 24);
|
|
@@ -290,6 +293,8 @@ function improveDecayRate(decayRate) {
|
|
|
290
293
|
* @returns {number} Consolidated strength (capped at 1.0)
|
|
291
294
|
*/
|
|
292
295
|
function computeConsolidatedStrength(sourceStrengths) {
|
|
296
|
+
// No sources to consolidate — Math.max(...[]) is -Infinity, so guard explicitly.
|
|
297
|
+
if (!Array.isArray(sourceStrengths) || sourceStrengths.length === 0) return 0;
|
|
293
298
|
const maxStrength = Math.max(...sourceStrengths);
|
|
294
299
|
return Math.min(1.0, maxStrength + 0.15);
|
|
295
300
|
}
|
|
@@ -360,15 +365,21 @@ function computeSpreadingActivationBatch(scoredMemories, associations, maxDepth
|
|
|
360
365
|
* @returns {Object[]} Scored and sorted memories (highest first)
|
|
361
366
|
*/
|
|
362
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
|
+
|
|
363
373
|
// First pass: compute base scores
|
|
364
374
|
const scored = memories.map((mem) => {
|
|
365
|
-
const decayedStrength = computeDecayedStrength(
|
|
375
|
+
const decayedStrength = fin(computeDecayedStrength(
|
|
366
376
|
mem.strength,
|
|
367
377
|
mem.decay_rate,
|
|
368
|
-
mem.last_accessed
|
|
369
|
-
|
|
370
|
-
|
|
371
|
-
const
|
|
378
|
+
mem.last_accessed,
|
|
379
|
+
!!(mem.stable || mem.pinned) // pinned ⇒ implicitly stable (decay-exempt)
|
|
380
|
+
));
|
|
381
|
+
const recencyBonus = fin(computeRecencyBonus(mem.last_accessed));
|
|
382
|
+
const relevance = fin(relevanceFn(mem));
|
|
372
383
|
|
|
373
384
|
return {
|
|
374
385
|
...mem,
|
|
@@ -414,12 +425,12 @@ function rankMemories(memories, relevanceFn, options = {}) {
|
|
|
414
425
|
if (mem.context_match > 0) extras.contextMatch = mem.context_match;
|
|
415
426
|
if (mem.salience != null) extras.salience = mem.salience;
|
|
416
427
|
|
|
417
|
-
const score = computeRecallScore(
|
|
428
|
+
const score = fin(computeRecallScore(
|
|
418
429
|
mem.relevance,
|
|
419
430
|
mem.decayed_strength,
|
|
420
431
|
mem.recency_bonus,
|
|
421
432
|
extras
|
|
422
|
-
);
|
|
433
|
+
));
|
|
423
434
|
|
|
424
435
|
return {
|
|
425
436
|
...mem,
|
|
@@ -431,7 +442,9 @@ function rankMemories(memories, relevanceFn, options = {}) {
|
|
|
431
442
|
score: Math.round(score * 1000) / 1000,
|
|
432
443
|
};
|
|
433
444
|
})
|
|
434
|
-
|
|
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));
|
|
435
448
|
}
|
|
436
449
|
|
|
437
450
|
module.exports = {
|