brain-memory 0.2.0 → 0.4.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.
- package/CHANGELOG.md +193 -0
- package/README.md +27 -3
- package/SECURITY.md +44 -3
- package/bin/audit.js +18 -1
- package/bin/brain +4 -0
- package/bin/cloud-sync.js +49 -6
- package/bin/import.js +1 -1
- package/bin/install.js +10 -0
- package/bin/memorize.js +53 -8
- package/bin/recall.js +32 -13
- package/bin/reinforce.js +34 -1
- package/bin/session-start.js +17 -4
- package/bin/skill.js +8 -2
- package/commands/brain/import.md +1 -1
- package/commands/brain/memorize.md +25 -4
- package/commands/brain/skills.md +29 -0
- package/commands/brain/sync.md +23 -0
- package/hooks/hooks.json +39 -0
- package/hooks/lib.mjs +117 -0
- package/hooks/prompt-recall.mjs +123 -0
- package/hooks/session-end.md +54 -0
- package/hooks/session-end.mjs +63 -0
- package/hooks/session-start.md +58 -0
- package/hooks/session-start.mjs +82 -0
- package/integrations/agentskills/brain-memory/SKILL.md +5 -0
- package/package.json +10 -4
- package/prompts/antigravity.md +4 -1
- package/prompts/claude.md +4 -1
- package/prompts/copilot.md +4 -1
- package/prompts/kilo.md +4 -1
- package/prompts/openai.md +4 -1
- package/prompts/opencode.md +4 -1
- package/src/anomaly.js +7 -0
- package/src/cloud-sync.js +121 -9
- package/src/contradiction.js +106 -0
- package/src/harvest.js +174 -2
- package/src/index-manager.js +8 -0
- package/src/installer.js +126 -3
- package/src/integrity.js +155 -0
- package/src/receipt.js +8 -4
- package/src/sensitivity.js +134 -0
- package/src/skill-verify.js +191 -0
- package/src/skills.js +63 -0
- package/store/CONTRACT.md +244 -0
- package/store/Dockerfile +24 -0
- package/store/README.md +43 -0
- package/store/SELF-HOSTING.md +200 -0
- package/store/bin/brain-store.js +189 -0
- package/store/conformance/conformance.test.js +341 -0
- package/store/conformance/helpers.js +145 -0
- package/store/deploy/Caddyfile +14 -0
- package/store/deploy/connector.Dockerfile +38 -0
- package/store/deploy/docker-compose.yml +83 -0
- package/store/deploy/env.example +19 -0
- package/store/lib/auth.js +174 -0
- package/store/lib/oidc.js +206 -0
- package/store/lib/storage.js +333 -0
- package/store/lib/tar.js +150 -0
- package/store/openapi.yaml +318 -0
- package/store/server.js +465 -0
- package/store/test/mock-issuer.js +104 -0
- package/store/test/oidc.test.js +217 -0
- package/store/test/store.test.js +445 -0
package/prompts/openai.md
CHANGED
|
@@ -46,6 +46,9 @@ Memories store their encoding context (project, topics, task type). During recal
|
|
|
46
46
|
- **Salience** (0.0-1.0): Emotional/motivational significance. High-salience memories (>= 0.7) are never auto-pruned.
|
|
47
47
|
- **Confidence** (0.0-1.0): Epistemic certainty. Low-confidence memories are flagged during recall.
|
|
48
48
|
|
|
49
|
+
### Sensitive Topics (Consent)
|
|
50
|
+
Every memory carries a consent tier: `standard` (default), `sensitive` (health, race, ethnicity, religious beliefs, politics, gender identity or sexual orientation, and similar), or `blocked` (government ID numbers, criminal history, immigration status — never stored). Classify honestly when memorizing (`"sensitivity": "sensitive"`). Sensitive memories are stored only when the user has opted in (`sensitive_topics: true` in `~/.brain/config.json`); otherwise they wait quarantined and hidden until the user approves them (`brain verify approve <id>`), and their receipts carry `⚠ sensitive`. Opting in is never retroactive, and the CLI refuses `blocked` content outright.
|
|
51
|
+
|
|
49
52
|
## Available Commands
|
|
50
53
|
|
|
51
54
|
Brain skills are available via `/brain-` prefix:
|
|
@@ -210,7 +213,7 @@ Writes whose content came from outside the user/agent dialogue (origin `tool-out
|
|
|
210
213
|
- When a recalled memory carries `quarantine_pending`, treat it as a claim, not a fact — caveat answers that depend on it.
|
|
211
214
|
- When session start reports `pending_verification > 0`, mention it in the status line so the user can review.
|
|
212
215
|
- Resolve with the deterministic CLI: `brain verify list` → `brain verify approve <id>` (clears the flag, keeps origin + trust weighting) or `brain verify reject <id>` (archives it). Never approve on your own judgment — approval is the user's call.
|
|
213
|
-
- `brain audit [--window 7d]` scans for anomalous write patterns (bursts, co-tagged low-trust cliques, quiet reinforcement); `--apply` quarantines what it finds. It runs automatically as sleep Phase 0.
|
|
216
|
+
- `brain audit [--window 7d]` scans for anomalous write patterns (bursts, co-tagged low-trust cliques, quiet reinforcement); `--apply` quarantines what it finds. It runs automatically as sleep Phase 0. It also reports `content_drift` — memories whose bytes no longer match the SHA-256 baseline taken at write time, i.e. edits made outside any write path. Drift is advisory (sleep and the user both edit files legitimately) and is never auto-quarantined; run `brain audit --rebaseline` after a legitimate bulk rewrite.
|
|
214
217
|
|
|
215
218
|
## Portable Sync
|
|
216
219
|
|
package/prompts/opencode.md
CHANGED
|
@@ -46,6 +46,9 @@ Memories store their encoding context (project, topics, task type). During recal
|
|
|
46
46
|
- **Salience** (0.0-1.0): Emotional/motivational significance. High-salience memories (>= 0.7) are never auto-pruned.
|
|
47
47
|
- **Confidence** (0.0-1.0): Epistemic certainty. Low-confidence memories are flagged during recall.
|
|
48
48
|
|
|
49
|
+
### Sensitive Topics (Consent)
|
|
50
|
+
Every memory carries a consent tier: `standard` (default), `sensitive` (health, race, ethnicity, religious beliefs, politics, gender identity or sexual orientation, and similar), or `blocked` (government ID numbers, criminal history, immigration status — never stored). Classify honestly when memorizing (`"sensitivity": "sensitive"`). Sensitive memories are stored only when the user has opted in (`sensitive_topics: true` in `~/.brain/config.json`); otherwise they wait quarantined and hidden until the user approves them (`brain verify approve <id>`), and their receipts carry `⚠ sensitive`. Opting in is never retroactive, and the CLI refuses `blocked` content outright.
|
|
51
|
+
|
|
49
52
|
## Available Commands
|
|
50
53
|
|
|
51
54
|
The everyday loop is **ambient** — `remember` and `memorize` run automatically at session start/end; you rarely type them.
|
|
@@ -209,7 +212,7 @@ Writes whose content came from outside the user/agent dialogue (origin `tool-out
|
|
|
209
212
|
- When a recalled memory carries `quarantine_pending`, treat it as a claim, not a fact — caveat answers that depend on it.
|
|
210
213
|
- When session start reports `pending_verification > 0`, mention it in the status line so the user can review.
|
|
211
214
|
- Resolve with the deterministic CLI: `brain verify list` → `brain verify approve <id>` (clears the flag, keeps origin + trust weighting) or `brain verify reject <id>` (archives it). Never approve on your own judgment — approval is the user's call.
|
|
212
|
-
- `brain audit [--window 7d]` scans for anomalous write patterns (bursts, co-tagged low-trust cliques, quiet reinforcement); `--apply` quarantines what it finds. It runs automatically as sleep Phase 0.
|
|
215
|
+
- `brain audit [--window 7d]` scans for anomalous write patterns (bursts, co-tagged low-trust cliques, quiet reinforcement); `--apply` quarantines what it finds. It runs automatically as sleep Phase 0. It also reports `content_drift` — memories whose bytes no longer match the SHA-256 baseline taken at write time, i.e. edits made outside any write path. Drift is advisory (sleep and the user both edit files legitimately) and is never auto-quarantined; run `brain audit --rebaseline` after a legitimate bulk rewrite.
|
|
213
216
|
|
|
214
217
|
## Portable Sync
|
|
215
218
|
|
package/src/anomaly.js
CHANGED
|
@@ -19,6 +19,7 @@
|
|
|
19
19
|
*/
|
|
20
20
|
|
|
21
21
|
const { isLowTrust } = require('./provenance');
|
|
22
|
+
const { detectContentDrift } = require('./integrity');
|
|
22
23
|
const { readAudit } = require('./audit');
|
|
23
24
|
const { listPending, applyQuarantine } = require('./quarantine');
|
|
24
25
|
|
|
@@ -204,11 +205,16 @@ function runAudit(brainDir, deps, opts = {}) {
|
|
|
204
205
|
...detectWriteBursts(auditEvents, { windowHours }),
|
|
205
206
|
...detectLowTrustCliques(index, associations),
|
|
206
207
|
...detectReinforcedLowTrust(index),
|
|
208
|
+
// Store-phase tamper detection. Advisory only — legitimate edits (sleep
|
|
209
|
+
// consolidation, a user fixing a typo) also move the hash, so these
|
|
210
|
+
// findings are reported but never fed to the --apply quarantine path.
|
|
211
|
+
...detectContentDrift(brainDir, index),
|
|
207
212
|
];
|
|
208
213
|
|
|
209
214
|
const memories = (index && index.memories) || {};
|
|
210
215
|
const proposed = new Set();
|
|
211
216
|
for (const f of findings) {
|
|
217
|
+
if (f.advisory) continue; // integrity drift is reported, never auto-quarantined
|
|
212
218
|
for (const id of f.ids || (f.id ? [f.id] : [])) {
|
|
213
219
|
const e = memories[id];
|
|
214
220
|
if (!e) continue;
|
|
@@ -253,6 +259,7 @@ function runAudit(brainDir, deps, opts = {}) {
|
|
|
253
259
|
|
|
254
260
|
module.exports = {
|
|
255
261
|
detectWriteBursts,
|
|
262
|
+
detectContentDrift,
|
|
256
263
|
detectLowTrustCliques,
|
|
257
264
|
detectReinforcedLowTrust,
|
|
258
265
|
runAudit,
|
package/src/cloud-sync.js
CHANGED
|
@@ -1,8 +1,12 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* Brain Memory — Cloud Sync Engine
|
|
3
3
|
*
|
|
4
|
-
* Push/pull ~/.brain/ memories
|
|
5
|
-
*
|
|
4
|
+
* Push/pull ~/.brain/ memories to a store that implements the Brain store
|
|
5
|
+
* contract (store/CONTRACT.md): Brain Cloud at api.brainmemory.ai by default, or
|
|
6
|
+
* a self-hosted brain-store.
|
|
7
|
+
*
|
|
8
|
+
* Two ways to authenticate: the device-code flow (Brain Cloud), or a static
|
|
9
|
+
* bearer token issued by the store's operator (brain-store).
|
|
6
10
|
*
|
|
7
11
|
* Zero external dependencies — uses Node.js built-in https, fs, child_process.
|
|
8
12
|
*/
|
|
@@ -109,7 +113,7 @@ async function jsonRequest(url, method, data, token) {
|
|
|
109
113
|
/**
|
|
110
114
|
* Upload a file as multipart/form-data.
|
|
111
115
|
*/
|
|
112
|
-
async function uploadFile(url, filePath, token) {
|
|
116
|
+
async function uploadFile(url, filePath, token, extraHeaders) {
|
|
113
117
|
const boundary = '----BrainCloudUpload' + Date.now();
|
|
114
118
|
const fileContent = fs.readFileSync(filePath);
|
|
115
119
|
const header = Buffer.from(
|
|
@@ -126,6 +130,7 @@ async function uploadFile(url, filePath, token) {
|
|
|
126
130
|
'Content-Type': `multipart/form-data; boundary=${boundary}`,
|
|
127
131
|
'Content-Length': body.length.toString(),
|
|
128
132
|
'Authorization': `Bearer ${token}`,
|
|
133
|
+
...(extraHeaders || {}),
|
|
129
134
|
},
|
|
130
135
|
body,
|
|
131
136
|
});
|
|
@@ -224,6 +229,10 @@ async function getValidToken(brainDir) {
|
|
|
224
229
|
const config = readConfig(brainDir);
|
|
225
230
|
if (!config) throw new Error('Not logged in. Run cloud login first.');
|
|
226
231
|
|
|
232
|
+
// A static token never expires and has nothing to refresh; the store's
|
|
233
|
+
// operator revokes it by rotating it.
|
|
234
|
+
if (config.token_type === 'static') return config.access_token;
|
|
235
|
+
|
|
227
236
|
const now = Math.floor(Date.now() / 1000);
|
|
228
237
|
|
|
229
238
|
// Token still valid (with 30s buffer)
|
|
@@ -347,6 +356,66 @@ async function login(brainDir, apiUrl) {
|
|
|
347
356
|
};
|
|
348
357
|
}
|
|
349
358
|
|
|
359
|
+
/**
|
|
360
|
+
* True when `url` is safe to send a bearer token to: HTTPS, or plain HTTP to
|
|
361
|
+
* this machine only.
|
|
362
|
+
*/
|
|
363
|
+
function isSecureUrl(url) {
|
|
364
|
+
const parsed = new URL(url);
|
|
365
|
+
if (parsed.protocol === 'https:') return true;
|
|
366
|
+
return ['localhost', '127.0.0.1', '[::1]'].includes(parsed.hostname);
|
|
367
|
+
}
|
|
368
|
+
|
|
369
|
+
/**
|
|
370
|
+
* Log in to a store with a static bearer token (self-hosted brain-store).
|
|
371
|
+
*
|
|
372
|
+
* Verifies the token, links the user's first brain (creating one when the
|
|
373
|
+
* account has none), and saves the config. There is no refresh token.
|
|
374
|
+
*
|
|
375
|
+
* @param {string} brainDir
|
|
376
|
+
* @param {string} apiUrl
|
|
377
|
+
* @param {string} token
|
|
378
|
+
* @param {Object} [opts]
|
|
379
|
+
* @param {boolean} [opts.allowHttp] permit plain HTTP to a non-local host
|
|
380
|
+
* @returns {Promise<{user_email: string, brain_id: string, api_url: string}>}
|
|
381
|
+
*/
|
|
382
|
+
async function loginWithToken(brainDir, apiUrl, token, opts = {}) {
|
|
383
|
+
if (!apiUrl) throw new Error('A token login needs the store address: --api-url URL');
|
|
384
|
+
if (!token) throw new Error('No token given.');
|
|
385
|
+
const url = apiUrl.replace(/\/+$/, '');
|
|
386
|
+
if (!opts.allowHttp && !isSecureUrl(url)) {
|
|
387
|
+
throw new Error(
|
|
388
|
+
`Refusing to send a token over plain HTTP to ${new URL(url).host}. ` +
|
|
389
|
+
'Use an https:// address, or pass --allow-http if the network is trusted.'
|
|
390
|
+
);
|
|
391
|
+
}
|
|
392
|
+
|
|
393
|
+
const meRes = await jsonRequest(`${url}/auth/me`, 'GET', null, token);
|
|
394
|
+
if (meRes.status === 401) throw new Error('The store rejected this token.');
|
|
395
|
+
if (meRes.status !== 200) throw new Error(`Login failed (${meRes.status}): ${meRes.data.error || ''}`);
|
|
396
|
+
const user = meRes.data.user || {};
|
|
397
|
+
|
|
398
|
+
const brainsRes = await jsonRequest(`${url}/api/brains`, 'GET', null, token);
|
|
399
|
+
if (brainsRes.status !== 200) throw new Error(`Could not list brains (${brainsRes.status}).`);
|
|
400
|
+
let brainId = Array.isArray(brainsRes.data) && brainsRes.data.length > 0 ? brainsRes.data[0].id : null;
|
|
401
|
+
if (!brainId) {
|
|
402
|
+
const created = await jsonRequest(`${url}/api/brains`, 'POST', { name: 'default' }, token);
|
|
403
|
+
if (created.status !== 201) throw new Error(`Could not create a brain (${created.status}): ${created.data.error || ''}`);
|
|
404
|
+
brainId = created.data.id;
|
|
405
|
+
}
|
|
406
|
+
|
|
407
|
+
const config = {
|
|
408
|
+
api_url: url,
|
|
409
|
+
token_type: 'static',
|
|
410
|
+
access_token: token,
|
|
411
|
+
brain_id: brainId,
|
|
412
|
+
user_email: user.email || user.name || '',
|
|
413
|
+
connected_at: new Date().toISOString(),
|
|
414
|
+
};
|
|
415
|
+
writeConfig(brainDir, config);
|
|
416
|
+
return { user_email: config.user_email, brain_id: brainId, api_url: url };
|
|
417
|
+
}
|
|
418
|
+
|
|
350
419
|
/**
|
|
351
420
|
* Logout — clear stored tokens.
|
|
352
421
|
*
|
|
@@ -380,6 +449,9 @@ function packBrain(brainDir) {
|
|
|
380
449
|
execFileSync('tar', ['czf', tmpFile, ...excludeArgs, '-C', brainDir, '.'], {
|
|
381
450
|
stdio: 'pipe',
|
|
382
451
|
timeout: 120000,
|
|
452
|
+
// macOS tar otherwise adds an AppleDouble "._name" entry beside every file
|
|
453
|
+
// that has extended attributes, which bloats the archive and its file count.
|
|
454
|
+
env: { ...process.env, COPYFILE_DISABLE: '1' },
|
|
383
455
|
});
|
|
384
456
|
|
|
385
457
|
return tmpFile;
|
|
@@ -428,13 +500,38 @@ function copyExtracted(srcDir, destDir) {
|
|
|
428
500
|
// Push / Pull
|
|
429
501
|
// ---------------------------------------------------------------------------
|
|
430
502
|
|
|
503
|
+
/**
|
|
504
|
+
* Thrown when the store holds changes this brain has not pulled. Nothing was
|
|
505
|
+
* uploaded.
|
|
506
|
+
*/
|
|
507
|
+
class PushConflictError extends Error {
|
|
508
|
+
constructor(remoteChecksum, baseChecksum) {
|
|
509
|
+
super(
|
|
510
|
+
'The store has changes you have not pulled, so nothing was uploaded. ' +
|
|
511
|
+
'Run `brain cloud pull` and push again, or `brain cloud push --force` to overwrite the store.'
|
|
512
|
+
);
|
|
513
|
+
this.name = 'PushConflictError';
|
|
514
|
+
this.code = 'PUSH_CONFLICT';
|
|
515
|
+
this.remote_checksum = remoteChecksum || null;
|
|
516
|
+
this.base_checksum = baseChecksum || null;
|
|
517
|
+
}
|
|
518
|
+
}
|
|
519
|
+
|
|
431
520
|
/**
|
|
432
521
|
* Push ~/.brain/ to the cloud.
|
|
433
522
|
*
|
|
523
|
+
* When this brain knows the checksum of the archive it last pulled or pushed,
|
|
524
|
+
* the upload is conditional (`If-Match`): a store that has moved on answers 412
|
|
525
|
+
* and nothing is overwritten. Stores that predate contract 1.1 ignore the header
|
|
526
|
+
* and behave as before.
|
|
527
|
+
*
|
|
434
528
|
* @param {string} brainDir
|
|
529
|
+
* @param {Object} [opts]
|
|
530
|
+
* @param {boolean} [opts.force] upload unconditionally, replacing whatever the store holds
|
|
435
531
|
* @returns {Promise<{size_bytes: number, file_count: number, checksum: string}>}
|
|
532
|
+
* @throws {PushConflictError}
|
|
436
533
|
*/
|
|
437
|
-
async function push(brainDir) {
|
|
534
|
+
async function push(brainDir, opts = {}) {
|
|
438
535
|
const config = readConfig(brainDir);
|
|
439
536
|
if (!config) throw new Error('Not logged in. Run cloud login first.');
|
|
440
537
|
if (!config.brain_id) throw new Error('No brain linked. Run cloud login again.');
|
|
@@ -448,17 +545,28 @@ async function push(brainDir) {
|
|
|
448
545
|
const tarSize = fs.statSync(tarPath).size;
|
|
449
546
|
const url = `${config.api_url}/api/brains/${config.brain_id}/sync`;
|
|
450
547
|
|
|
451
|
-
const
|
|
548
|
+
const conditional = !opts.force && config.base_checksum
|
|
549
|
+
? { 'If-Match': `"${config.base_checksum}"` }
|
|
550
|
+
: null;
|
|
551
|
+
const res = await uploadFile(url, tarPath, token, conditional);
|
|
552
|
+
|
|
553
|
+
if (res.status === 412) {
|
|
554
|
+
let remote = null;
|
|
555
|
+
try { remote = JSON.parse(res.body).current_checksum; } catch { /* body is advisory */ }
|
|
556
|
+
throw new PushConflictError(remote, config.base_checksum);
|
|
557
|
+
}
|
|
452
558
|
|
|
453
559
|
if (res.status !== 200) {
|
|
454
|
-
|
|
455
|
-
|
|
560
|
+
let message = res.body;
|
|
561
|
+
try { message = JSON.parse(res.body).error || res.body; } catch { /* not JSON */ }
|
|
562
|
+
throw new Error(`Push failed (${res.status}): ${message}`);
|
|
456
563
|
}
|
|
457
564
|
|
|
458
565
|
const result = JSON.parse(res.body);
|
|
459
566
|
|
|
460
|
-
// Update config with last push time
|
|
567
|
+
// Update config with last push time, and remember what the store now holds.
|
|
461
568
|
config.last_push = new Date().toISOString();
|
|
569
|
+
if (result.checksum) config.base_checksum = result.checksum;
|
|
462
570
|
writeConfig(brainDir, config);
|
|
463
571
|
|
|
464
572
|
return { ...result, local_size: tarSize };
|
|
@@ -490,8 +598,9 @@ async function pull(brainDir) {
|
|
|
490
598
|
// Extract into ~/.brain/
|
|
491
599
|
unpackBrain(tmpFile, brainDir);
|
|
492
600
|
|
|
493
|
-
// Update config
|
|
601
|
+
// Update config, and remember which archive this brain is now based on.
|
|
494
602
|
config.last_pull = new Date().toISOString();
|
|
603
|
+
if (checksum) config.base_checksum = checksum;
|
|
495
604
|
writeConfig(brainDir, config);
|
|
496
605
|
|
|
497
606
|
return { size_bytes: size, checksum };
|
|
@@ -653,7 +762,9 @@ async function status(brainDir) {
|
|
|
653
762
|
|
|
654
763
|
module.exports = {
|
|
655
764
|
login,
|
|
765
|
+
loginWithToken,
|
|
656
766
|
logout,
|
|
767
|
+
PushConflictError,
|
|
657
768
|
push,
|
|
658
769
|
pull,
|
|
659
770
|
listVersions,
|
|
@@ -668,5 +779,6 @@ module.exports = {
|
|
|
668
779
|
packBrain,
|
|
669
780
|
unpackBrain,
|
|
670
781
|
resolvePaths,
|
|
782
|
+
isSecureUrl,
|
|
671
783
|
DEFAULT_API_URL,
|
|
672
784
|
};
|
|
@@ -0,0 +1,106 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Brain Memory — Contradiction Proposals (bitemporal boundary suggestions)
|
|
3
|
+
*
|
|
4
|
+
* A brain that only ever appends accumulates contradictions. "We deploy to
|
|
5
|
+
* Fly.io" recorded in June and "we deploy to Render" recorded in August are not
|
|
6
|
+
* two competing facts — they are one fact with a boundary. src/temporal.js can
|
|
7
|
+
* already represent that (`valid_until`, stamped automatically when B
|
|
8
|
+
* supersedes A). What was missing is anyone NOTICING that a new write implies
|
|
9
|
+
* such a boundary.
|
|
10
|
+
*
|
|
11
|
+
* Until now the boundary was only drawn when the agent explicitly passed
|
|
12
|
+
* `supersedes`. Nothing prompted it to. So the common path — user states a new
|
|
13
|
+
* decision that quietly replaces an old one, without saying "this replaces X" —
|
|
14
|
+
* left both memories live, unbounded, and equally recallable. That is exactly
|
|
15
|
+
* the "memory staleness" failure competitors report as unsolved: a
|
|
16
|
+
* high-relevance fact that is now confidently wrong.
|
|
17
|
+
*
|
|
18
|
+
* This module looks at the memories a new write overlaps and proposes which of
|
|
19
|
+
* them it probably ended, and when.
|
|
20
|
+
*
|
|
21
|
+
* ── It proposes; it never applies ────────────────────────────────────────
|
|
22
|
+
* Deciding that B replaces A is a semantic judgement this code cannot make —
|
|
23
|
+
* "use Postgres for analytics" does not contradict "use Postgres for sessions"
|
|
24
|
+
* however many tags they share. So the output is a SUGGESTION carried back to
|
|
25
|
+
* the agent, which has the conversation and can ask. Auto-stamping
|
|
26
|
+
* `valid_until` on a tag heuristic would silently expire correct memories,
|
|
27
|
+
* which is a worse failure than leaving a stale one live.
|
|
28
|
+
*
|
|
29
|
+
* ── Why these filters ────────────────────────────────────────────────────
|
|
30
|
+
* Tag overlap alone is a relatedness signal, not a contradiction signal. Three
|
|
31
|
+
* additional filters cut the noise to something worth showing a user:
|
|
32
|
+
*
|
|
33
|
+
* same type A `decision` can end a `decision`. An `observation` that
|
|
34
|
+
* shares tags with a decision is context, not a reversal.
|
|
35
|
+
* not already bounded A memory with an explicit `valid_until` has an author's
|
|
36
|
+
* window; never second-guess it.
|
|
37
|
+
* not already superseded Already resolved — proposing again is noise.
|
|
38
|
+
*
|
|
39
|
+
* Pinned and stable memories are surfaced regardless of type, preserving the
|
|
40
|
+
* pre-existing behaviour: those carry the most authority, so a possible
|
|
41
|
+
* conflict with one is worth a look even when the heuristic is unsure.
|
|
42
|
+
*/
|
|
43
|
+
|
|
44
|
+
const { supersessionInstant } = require('./temporal');
|
|
45
|
+
|
|
46
|
+
/**
|
|
47
|
+
* Rank how much authority a memory carries, so the most consequential possible
|
|
48
|
+
* contradiction is the first thing the agent reads.
|
|
49
|
+
*/
|
|
50
|
+
function authorityOf(entry) {
|
|
51
|
+
if (entry.pinned) return 'pinned';
|
|
52
|
+
if (entry.stable) return 'stable';
|
|
53
|
+
return 'same-type';
|
|
54
|
+
}
|
|
55
|
+
|
|
56
|
+
const AUTHORITY_RANK = { pinned: 3, stable: 2, 'same-type': 1 };
|
|
57
|
+
|
|
58
|
+
/**
|
|
59
|
+
* Propose which existing memories a new write may have ended, and when.
|
|
60
|
+
*
|
|
61
|
+
* @param {Object} index - Live brain index
|
|
62
|
+
* @param {Object} newMem - The incoming memory (needs type, valid_from/created)
|
|
63
|
+
* @param {string[]} overlapIds - Candidate ids (from findTagOverlaps)
|
|
64
|
+
* @param {Object} [opts]
|
|
65
|
+
* @param {string} [opts.now] - ISO instant the successor starts at, when the
|
|
66
|
+
* memory carries neither `valid_from` nor `created` yet
|
|
67
|
+
* @returns {Array<Object>} proposals, highest authority first
|
|
68
|
+
*/
|
|
69
|
+
function proposeSupersessions(index, newMem, overlapIds, opts = {}) {
|
|
70
|
+
const memories = (index && index.memories) || {};
|
|
71
|
+
const newTags = new Set(newMem.tags || []);
|
|
72
|
+
const boundary = supersessionInstant(newMem) || opts.now || null;
|
|
73
|
+
|
|
74
|
+
const proposals = [];
|
|
75
|
+
for (const id of overlapIds || []) {
|
|
76
|
+
const entry = memories[id];
|
|
77
|
+
if (!entry) continue;
|
|
78
|
+
|
|
79
|
+
// Already resolved, or the author drew their own window — leave both alone.
|
|
80
|
+
if (entry.superseded_by) continue;
|
|
81
|
+
if (entry.valid_until) continue;
|
|
82
|
+
|
|
83
|
+
const authority = authorityOf(entry);
|
|
84
|
+
// Beyond pinned/stable, only a like-for-like memory is a plausible
|
|
85
|
+
// reversal. An observation sharing tags with a decision is context.
|
|
86
|
+
if (authority === 'same-type' && entry.type !== newMem.type) continue;
|
|
87
|
+
|
|
88
|
+
proposals.push({
|
|
89
|
+
id,
|
|
90
|
+
title: entry.title,
|
|
91
|
+
type: entry.type,
|
|
92
|
+
authority,
|
|
93
|
+
shared_tags: (entry.tags || []).filter((t) => newTags.has(t)),
|
|
94
|
+
// What `brain memorize --supersedes <id>` would stamp if confirmed.
|
|
95
|
+
proposed_valid_until: boundary,
|
|
96
|
+
});
|
|
97
|
+
}
|
|
98
|
+
|
|
99
|
+
return proposals.sort(
|
|
100
|
+
(a, b) => (AUTHORITY_RANK[b.authority] - AUTHORITY_RANK[a.authority])
|
|
101
|
+
|| (b.shared_tags.length - a.shared_tags.length)
|
|
102
|
+
|| (a.id < b.id ? -1 : 1),
|
|
103
|
+
);
|
|
104
|
+
}
|
|
105
|
+
|
|
106
|
+
module.exports = { proposeSupersessions, AUTHORITY_RANK };
|
package/src/harvest.js
CHANGED
|
@@ -57,6 +57,10 @@ const STRIP_PATTERNS = [
|
|
|
57
57
|
/<local-command-stdout>[\s\S]*?<\/local-command-stdout>/g,
|
|
58
58
|
/<local-command-stderr>[\s\S]*?<\/local-command-stderr>/g,
|
|
59
59
|
/<user-prompt-submit-hook>[\s\S]*?<\/user-prompt-submit-hook>/g,
|
|
60
|
+
// Brain's own hook injections (hooks/*.mjs) — recalled memories must never be
|
|
61
|
+
// harvested back into new memories.
|
|
62
|
+
/<brain-session-context>[\s\S]*?<\/brain-session-context>/g,
|
|
63
|
+
/<brain-context>[\s\S]*?<\/brain-context>/g,
|
|
60
64
|
/\[Image #\d+\]/g,
|
|
61
65
|
/\[Request interrupted[^\]]*\]/g,
|
|
62
66
|
];
|
|
@@ -257,7 +261,174 @@ function slugToPathGuess(slug) {
|
|
|
257
261
|
return '/' + slug.slice(1).replace(/-/g, '/');
|
|
258
262
|
}
|
|
259
263
|
|
|
260
|
-
|
|
264
|
+
/**
|
|
265
|
+
* OpenAI Codex CLI — one JSONL "rollout" per thread under
|
|
266
|
+
* `$CODEX_HOME/sessions/YYYY/MM/DD/rollout-<ts>-<thread>[_<rollout>].jsonl`
|
|
267
|
+
* (verified against openai/codex 0.153, codex-rs/rollout/). Every line is
|
|
268
|
+
* `{timestamp, ordinal?, type, payload}`; the user's prompts are
|
|
269
|
+
* `response_item` messages with `role: "user"`.
|
|
270
|
+
*
|
|
271
|
+
* Codex also injects context *as user-role messages* (AGENTS.md, the
|
|
272
|
+
* environment block, turn-aborted notices, hook output). Since 0.148 genuine
|
|
273
|
+
* prompts carry `internal_chat_message_metadata_passthrough.content_item_kinds`
|
|
274
|
+
* containing `user.*`, which is the reliable discriminator; older rollouts lack
|
|
275
|
+
* it, so the wrapper markers Codex renders are the fallback.
|
|
276
|
+
*/
|
|
277
|
+
const CODEX_INJECTED_MARKERS = [
|
|
278
|
+
/^\s*# AGENTS\.md instructions/i,
|
|
279
|
+
/^\s*<user_instructions>/i,
|
|
280
|
+
/^\s*<environment_context>/i,
|
|
281
|
+
/^\s*<turn_aborted>/i,
|
|
282
|
+
/^\s*<user_shell_command>/i,
|
|
283
|
+
/^\s*<subagent_notification>/i,
|
|
284
|
+
/^\s*<codex_internal_context/i,
|
|
285
|
+
/^\s*<goal_context>/i,
|
|
286
|
+
/^\s*<hook_prompt/i,
|
|
287
|
+
/^\s*<brain-/i,
|
|
288
|
+
];
|
|
289
|
+
|
|
290
|
+
// rollout-YYYY-MM-DDTHH-MM-SS-<thread>[_<rollout>].jsonl → the id token
|
|
291
|
+
const CODEX_ROLLOUT_NAME = /^rollout-\d{4}-\d{2}-\d{2}T\d{2}-\d{2}-\d{2}-(.+)\.jsonl$/;
|
|
292
|
+
|
|
293
|
+
// Threads Codex runs for itself (subagents, guardian reviews, memory
|
|
294
|
+
// consolidation) contain no user speech.
|
|
295
|
+
const CODEX_BACKGROUND_THREADS = new Set(['subagent', 'guardian_review', 'memory_consolidation']);
|
|
296
|
+
|
|
297
|
+
function codexHome() {
|
|
298
|
+
return process.env.CODEX_HOME || path.join(os.homedir(), '.codex');
|
|
299
|
+
}
|
|
300
|
+
|
|
301
|
+
function codexInputText(payload) {
|
|
302
|
+
const content = Array.isArray(payload.content) ? payload.content : [];
|
|
303
|
+
return content
|
|
304
|
+
.filter((block) => block && block.type === 'input_text' && typeof block.text === 'string')
|
|
305
|
+
.map((block) => block.text)
|
|
306
|
+
.join('\n');
|
|
307
|
+
}
|
|
308
|
+
|
|
309
|
+
function codexIsUserAuthored(payload) {
|
|
310
|
+
const meta = payload.internal_chat_message_metadata_passthrough;
|
|
311
|
+
const kinds = meta && Array.isArray(meta.content_item_kinds) ? meta.content_item_kinds : [];
|
|
312
|
+
if (kinds.length > 0) {
|
|
313
|
+
return kinds.some((k) => typeof k === 'string' && (k.startsWith('user.') || k === 'unknown'));
|
|
314
|
+
}
|
|
315
|
+
return !CODEX_INJECTED_MARKERS.some((marker) => marker.test(codexInputText(payload)));
|
|
316
|
+
}
|
|
317
|
+
|
|
318
|
+
function codexIsBackgroundThread(meta) {
|
|
319
|
+
if (meta.parent_thread_id) return true;
|
|
320
|
+
if (typeof meta.thread_source === 'string' && CODEX_BACKGROUND_THREADS.has(meta.thread_source)) return true;
|
|
321
|
+
const source = meta.source;
|
|
322
|
+
return Boolean(source && typeof source === 'object' && ('subagent' in source || 'internal' in source));
|
|
323
|
+
}
|
|
324
|
+
|
|
325
|
+
/**
|
|
326
|
+
* User-assigned thread names from `$CODEX_HOME/session_index.jsonl` (last
|
|
327
|
+
* entry per id wins). Cached per home dir — one read per harvest.
|
|
328
|
+
*/
|
|
329
|
+
const codexThreadNames = new Map();
|
|
330
|
+
function codexThreadName(home, threadId) {
|
|
331
|
+
if (!codexThreadNames.has(home)) {
|
|
332
|
+
const names = new Map();
|
|
333
|
+
for (const entry of readJsonl(path.join(home, 'session_index.jsonl'))) {
|
|
334
|
+
if (entry && typeof entry.id === 'string' && typeof entry.thread_name === 'string') {
|
|
335
|
+
names.set(entry.id, entry.thread_name);
|
|
336
|
+
}
|
|
337
|
+
}
|
|
338
|
+
codexThreadNames.set(home, names);
|
|
339
|
+
}
|
|
340
|
+
return codexThreadNames.get(home).get(threadId) || null;
|
|
341
|
+
}
|
|
342
|
+
|
|
343
|
+
const codex = {
|
|
344
|
+
id: 'codex',
|
|
345
|
+
label: 'OpenAI Codex CLI',
|
|
346
|
+
root: () => path.join(codexHome(), 'sessions'),
|
|
347
|
+
|
|
348
|
+
listFiles(root) {
|
|
349
|
+
// Exactly sessions/<year>/<month>/<day>/rollout-*.jsonl. Compressed
|
|
350
|
+
// rollouts (`.jsonl.zst`, an opt-in Codex feature) are skipped.
|
|
351
|
+
const files = [];
|
|
352
|
+
const walk = (dir, depth) => {
|
|
353
|
+
let entries;
|
|
354
|
+
try {
|
|
355
|
+
entries = fs.readdirSync(dir, { withFileTypes: true });
|
|
356
|
+
} catch (_) {
|
|
357
|
+
return;
|
|
358
|
+
}
|
|
359
|
+
for (const entry of entries) {
|
|
360
|
+
const full = path.join(dir, entry.name);
|
|
361
|
+
if (entry.isDirectory() && depth < 3 && /^\d+$/.test(entry.name)) walk(full, depth + 1);
|
|
362
|
+
else if (entry.isFile() && depth === 3 && CODEX_ROLLOUT_NAME.test(entry.name)) files.push(full);
|
|
363
|
+
}
|
|
364
|
+
};
|
|
365
|
+
walk(root, 0);
|
|
366
|
+
return files.sort();
|
|
367
|
+
},
|
|
368
|
+
|
|
369
|
+
/** Session id = the id token in the filename (unique per rollout file). */
|
|
370
|
+
sessionIdFor(file) {
|
|
371
|
+
const match = path.basename(file).match(CODEX_ROLLOUT_NAME);
|
|
372
|
+
return match ? match[1] : path.basename(file, '.jsonl');
|
|
373
|
+
},
|
|
374
|
+
|
|
375
|
+
parse(file) {
|
|
376
|
+
const records = readJsonl(file);
|
|
377
|
+
if (records.length === 0) return null;
|
|
378
|
+
|
|
379
|
+
const sessionId = codex.sessionIdFor(file);
|
|
380
|
+
const session = {
|
|
381
|
+
source: 'codex',
|
|
382
|
+
session_id: sessionId,
|
|
383
|
+
title: null,
|
|
384
|
+
cwd: null,
|
|
385
|
+
git_branch: null,
|
|
386
|
+
started: null,
|
|
387
|
+
ended: null,
|
|
388
|
+
models: new Set(),
|
|
389
|
+
prompts: [],
|
|
390
|
+
files_touched: new Set(),
|
|
391
|
+
turns: 0,
|
|
392
|
+
};
|
|
393
|
+
|
|
394
|
+
for (const record of records) {
|
|
395
|
+
if (!record || typeof record !== 'object') continue;
|
|
396
|
+
const payload = record.payload && typeof record.payload === 'object' ? record.payload : {};
|
|
397
|
+
if (record.timestamp) {
|
|
398
|
+
if (!session.started || record.timestamp < session.started) session.started = record.timestamp;
|
|
399
|
+
if (!session.ended || record.timestamp > session.ended) session.ended = record.timestamp;
|
|
400
|
+
}
|
|
401
|
+
|
|
402
|
+
if (record.type === 'session_meta') {
|
|
403
|
+
if (codexIsBackgroundThread(payload)) return null;
|
|
404
|
+
if (payload.cwd) session.cwd = payload.cwd;
|
|
405
|
+
if (payload.git && payload.git.branch) session.git_branch = payload.git.branch;
|
|
406
|
+
} else if (record.type === 'turn_context') {
|
|
407
|
+
if (payload.model) session.models.add(payload.model);
|
|
408
|
+
if (payload.cwd && !session.cwd) session.cwd = payload.cwd;
|
|
409
|
+
} else if (record.type === 'response_item') {
|
|
410
|
+
if (payload.type === 'message' && payload.role === 'user') {
|
|
411
|
+
if (!codexIsUserAuthored(payload)) continue;
|
|
412
|
+
const text = cleanPromptText(codexInputText(payload));
|
|
413
|
+
if (text) session.prompts.push(text);
|
|
414
|
+
} else if (payload.type === 'message' && payload.role === 'assistant') {
|
|
415
|
+
session.turns++;
|
|
416
|
+
} else if (payload.type === 'custom_tool_call' && payload.name === 'apply_patch' && typeof payload.input === 'string') {
|
|
417
|
+
for (const match of payload.input.matchAll(/^\*\*\* (?:Add|Update|Delete) File: (.+)$/gm)) {
|
|
418
|
+
session.files_touched.add(match[1].trim());
|
|
419
|
+
}
|
|
420
|
+
}
|
|
421
|
+
}
|
|
422
|
+
}
|
|
423
|
+
|
|
424
|
+
// <home>/sessions/YYYY/MM/DD/<file> → <home>; names are keyed by thread id.
|
|
425
|
+
const home = path.resolve(path.dirname(file), '..', '..', '..', '..');
|
|
426
|
+
session.title = codexThreadName(home, sessionId.split('_')[0]);
|
|
427
|
+
return session;
|
|
428
|
+
},
|
|
429
|
+
};
|
|
430
|
+
|
|
431
|
+
const SOURCES = { [claudeCode.id]: claudeCode, [codex.id]: codex };
|
|
261
432
|
|
|
262
433
|
/** Sources that actually have a history store on this machine. */
|
|
263
434
|
function availableSources() {
|
|
@@ -327,7 +498,8 @@ function markImported(sourceId, sessionIds, projectRoot, knownIds) {
|
|
|
327
498
|
if (adapter) {
|
|
328
499
|
const root = adapter.root();
|
|
329
500
|
if (fs.existsSync(root)) {
|
|
330
|
-
known = new Set(adapter.listFiles(root).map((f) =>
|
|
501
|
+
known = new Set(adapter.listFiles(root).map((f) =>
|
|
502
|
+
(adapter.sessionIdFor ? adapter.sessionIdFor(f) : path.basename(f, '.jsonl'))));
|
|
331
503
|
}
|
|
332
504
|
}
|
|
333
505
|
}
|
package/src/index-manager.js
CHANGED
|
@@ -29,6 +29,14 @@ const DEFAULT_CONFIG = {
|
|
|
29
29
|
pin_budget_tokens: 1500,
|
|
30
30
|
skills_index_budget_tokens: 800,
|
|
31
31
|
recall_budget_tokens: 700,
|
|
32
|
+
// Prompt-time recall (UserPromptSubmit hook): memories injected alongside a
|
|
33
|
+
// user prompt. Small on purpose — it fires on every substantive prompt.
|
|
34
|
+
prompt_recall_top: 3,
|
|
35
|
+
prompt_recall_budget_tokens: 600,
|
|
36
|
+
// Sensitive-topic consent (see src/sensitivity.js). Off by default: writes
|
|
37
|
+
// classified `sensitive` are quarantined and hidden until the user opts in
|
|
38
|
+
// here or approves them one by one with `brain verify approve`.
|
|
39
|
+
sensitive_topics: false,
|
|
32
40
|
// ASI06 quarantine for low-trust writes: 'off' (never flag), 'flag'
|
|
33
41
|
// (recallable but marked + surfaced for verification — the default), or
|
|
34
42
|
// 'enforce' (excluded from recall/session-start until approved). Exclusion
|