brain-memory 0.4.0 → 0.5.1
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 +132 -0
- package/README.md +4 -0
- package/SECURITY.md +17 -6
- package/bin/brain.js +24 -3
- package/bin/cloud-sync.js +65 -7
- package/bin/install.js +72 -14
- package/bin/memorize.js +50 -6
- package/bin/port.js +174 -0
- package/bin/recall.js +16 -6
- package/bin/reinforce.js +5 -0
- package/bin/session-start.js +30 -4
- package/bin/verify.js +42 -4
- package/commands/brain/memorize.md +8 -0
- package/commands/brain/verify.md +10 -2
- package/hooks/citation-check.mjs +94 -0
- package/hooks/hooks.json +11 -0
- package/hooks/lib.mjs +6 -0
- package/hooks/prompt-recall.mjs +24 -3
- package/hooks/session-start.mjs +4 -2
- package/integrations/README.md +4 -0
- package/integrations/agentskills/brain-memory/SKILL.md +9 -5
- package/package.json +5 -4
- package/prompts/antigravity.md +4 -2
- package/prompts/claude.md +4 -2
- package/prompts/copilot.md +4 -2
- package/prompts/kilo.md +4 -2
- package/prompts/openai.md +4 -2
- package/prompts/opencode.md +4 -2
- package/src/adapters.js +240 -0
- package/src/anomaly.js +41 -1
- package/src/cloud-sync.js +162 -27
- package/src/content-lint.js +55 -2
- package/src/export-import.js +1 -1
- package/src/git-sync.js +1 -1
- package/src/index-manager.js +9 -5
- package/src/installer.js +35 -1
- package/src/pinning.js +20 -1
- package/src/provenance.js +34 -0
- package/src/quarantine.js +82 -5
- package/src/receipt.js +9 -4
- package/src/surfaced.js +188 -0
- package/store/conformance/helpers.js +70 -16
- package/store/test/oidc.test.js +13 -8
package/src/git-sync.js
CHANGED
|
@@ -20,7 +20,7 @@ const CONFIG_FILE = 'config.json';
|
|
|
20
20
|
// Files/dirs inside ~/.brain/ that should NOT be synced. `.cloud` holds Brain
|
|
21
21
|
// Cloud OAuth tokens and pre-restore backups — credentials must never be
|
|
22
22
|
// committed to a git remote.
|
|
23
|
-
const EXCLUDED = new Set(['.sync', '.cloud', '.DS_Store']);
|
|
23
|
+
const EXCLUDED = new Set(['.sync', '.cloud', '.local', '.DS_Store']);
|
|
24
24
|
|
|
25
25
|
/**
|
|
26
26
|
* Check whether `git` is available on PATH.
|
package/src/index-manager.js
CHANGED
|
@@ -38,11 +38,15 @@ const DEFAULT_CONFIG = {
|
|
|
38
38
|
// here or approves them one by one with `brain verify approve`.
|
|
39
39
|
sensitive_topics: false,
|
|
40
40
|
// ASI06 quarantine for low-trust writes: 'off' (never flag), 'flag'
|
|
41
|
-
// (recallable but marked + surfaced for verification
|
|
42
|
-
//
|
|
43
|
-
// is evaluated at read time, so flipping the knob retroactively
|
|
44
|
-
// hides/reveals already-pending memories.
|
|
45
|
-
|
|
41
|
+
// (recallable but marked + surfaced for verification), or 'enforce'
|
|
42
|
+
// (excluded from recall/session-start until approved — the default).
|
|
43
|
+
// Exclusion is evaluated at read time, so flipping the knob retroactively
|
|
44
|
+
// hides/reveals already-pending memories. src/quarantine.js owns the
|
|
45
|
+
// default; keep the two in step.
|
|
46
|
+
quarantine_mode: 'enforce',
|
|
47
|
+
// Most low-trust (tool-output / external) memories one recall result set
|
|
48
|
+
// may hold, approved or not. See capLowTrust in src/provenance.js.
|
|
49
|
+
recall_low_trust_max: 1,
|
|
46
50
|
};
|
|
47
51
|
|
|
48
52
|
/**
|
package/src/installer.js
CHANGED
|
@@ -260,7 +260,7 @@ function removeInstructionsEntry(configPath, entry) {
|
|
|
260
260
|
// host); here the placeholder is expanded to this package's root.
|
|
261
261
|
// ---------------------------------------------------------------------------
|
|
262
262
|
|
|
263
|
-
const HOOK_SCRIPT_RE = /[\\/]hooks[\\/](session-start|prompt-recall|session-end)\.mjs"?$/;
|
|
263
|
+
const HOOK_SCRIPT_RE = /[\\/]hooks[\\/](session-start|prompt-recall|citation-check|session-end)\.mjs"?$/;
|
|
264
264
|
|
|
265
265
|
function isBrainHook(hook) {
|
|
266
266
|
return Boolean(hook) && typeof hook.command === 'string' && HOOK_SCRIPT_RE.test(hook.command);
|
|
@@ -658,6 +658,39 @@ function initializeBrain(overrideBase) {
|
|
|
658
658
|
return { alreadyExists: false, brainDir };
|
|
659
659
|
}
|
|
660
660
|
|
|
661
|
+
// ---------------------------------------------------------------------------
|
|
662
|
+
// Fragile-install detection. A global install made under a per-version Node
|
|
663
|
+
// manager puts `brain` in that ONE version's bin dir. The command then
|
|
664
|
+
// vanishes whenever the default version moves (a `22` alias drifting to a
|
|
665
|
+
// newer 22.x is enough), and it is invisible to any shell that does not load
|
|
666
|
+
// the manager — agent hooks, GUI-launched agents, non-interactive shells. The
|
|
667
|
+
// failure is silent and intermittent: agents just fall back to hand-editing
|
|
668
|
+
// memory files. Volta and `n` are absent on purpose — Volta shims global
|
|
669
|
+
// packages across versions and `n` installs into a fixed /usr/local prefix.
|
|
670
|
+
// ---------------------------------------------------------------------------
|
|
671
|
+
const VERSION_MANAGERS = [
|
|
672
|
+
{ manager: 'nvm', re: /\/\.?nvm\/versions\/node\/([^/]+)\// },
|
|
673
|
+
// nvm-windows: %APPDATA%\nvm\v22.16.0\node_modules\…
|
|
674
|
+
{ manager: 'nvm', re: /\/nvm\/(v\d+\.\d+\.\d+)\/node_modules\// },
|
|
675
|
+
{ manager: 'fnm', re: /\/\.?fnm\/node-versions\/([^/]+)\// },
|
|
676
|
+
{ manager: 'asdf', re: /\/\.asdf\/installs\/nodejs\/([^/]+)\// },
|
|
677
|
+
{ manager: 'mise', re: /\/mise\/installs\/node\/([^/]+)\// },
|
|
678
|
+
{ manager: 'nodenv', re: /\/\.nodenv\/versions\/([^/]+)\// },
|
|
679
|
+
];
|
|
680
|
+
|
|
681
|
+
/**
|
|
682
|
+
* @param {string} [packageRoot] - Where this package is installed
|
|
683
|
+
* @returns {{ manager: string, version: string } | null}
|
|
684
|
+
*/
|
|
685
|
+
function detectVersionManager(packageRoot = PACKAGE_ROOT) {
|
|
686
|
+
const p = `${String(packageRoot).replace(/\\/g, '/')}/`;
|
|
687
|
+
for (const { manager, re } of VERSION_MANAGERS) {
|
|
688
|
+
const m = p.match(re);
|
|
689
|
+
if (m) return { manager, version: m[1] };
|
|
690
|
+
}
|
|
691
|
+
return null;
|
|
692
|
+
}
|
|
693
|
+
|
|
661
694
|
module.exports = {
|
|
662
695
|
RUNTIMES,
|
|
663
696
|
BRAIN_MARKER_START,
|
|
@@ -680,4 +713,5 @@ module.exports = {
|
|
|
680
713
|
installHooks,
|
|
681
714
|
uninstallHooks,
|
|
682
715
|
hooksInstalled,
|
|
716
|
+
detectVersionManager,
|
|
683
717
|
};
|
package/src/pinning.js
CHANGED
|
@@ -77,6 +77,18 @@ function setFrontmatterFields(brainDir, memPath, fields, opts = {}) {
|
|
|
77
77
|
* @param {Object} [opts] - { scope = "global"|"project:<name>", priority = 0 }
|
|
78
78
|
* @returns {Object} Result or { error }
|
|
79
79
|
*/
|
|
80
|
+
/**
|
|
81
|
+
* Whether a memory carrying an authorization claim (src/content-lint.js) may
|
|
82
|
+
* be pinned. Only a user-origin claim qualifies, and only once it is backed by
|
|
83
|
+
* the user's own words (`authorized_by`) or a human approved it in
|
|
84
|
+
* `brain verify` — anything else would load a permission into every session on
|
|
85
|
+
* the writer's say-so.
|
|
86
|
+
*/
|
|
87
|
+
function authorizationPinnable(entry) {
|
|
88
|
+
if (!entry || !entry.authorization) return true;
|
|
89
|
+
return entry.origin === 'user' && Boolean(entry.authorized_by || entry.vetted);
|
|
90
|
+
}
|
|
91
|
+
|
|
80
92
|
function pinMemory(projectRoot, id, opts = {}) {
|
|
81
93
|
const scope = opts.scope || 'global';
|
|
82
94
|
const priority = Number.isFinite(opts.priority) ? opts.priority : 0;
|
|
@@ -95,6 +107,12 @@ function pinMemory(projectRoot, id, opts = {}) {
|
|
|
95
107
|
error: `Memory is pending verification — approve it first: brain verify approve ${id}`,
|
|
96
108
|
};
|
|
97
109
|
}
|
|
110
|
+
if (!authorizationPinnable(entry)) {
|
|
111
|
+
return {
|
|
112
|
+
error: `Memory grants the agent a permission and is not backed by the user — ` +
|
|
113
|
+
`only a user-origin claim with authorized_by, or one approved in brain verify, can be pinned: ${id}`,
|
|
114
|
+
};
|
|
115
|
+
}
|
|
98
116
|
entry.pinned = true;
|
|
99
117
|
entry.pin_scope = scope;
|
|
100
118
|
entry.pin_priority = priority;
|
|
@@ -143,4 +161,5 @@ function unpinMemory(projectRoot, id) {
|
|
|
143
161
|
return { id, pinned: false, was_pinned: wasPinned, removed: before !== pinned.pins.length };
|
|
144
162
|
}
|
|
145
163
|
|
|
146
|
-
module.exports = {
|
|
164
|
+
module.exports = {
|
|
165
|
+
authorizationPinnable, pinMemory, unpinMemory, estimateTokens, setFrontmatterFields };
|
package/src/provenance.js
CHANGED
|
@@ -70,7 +70,41 @@ function isLowTrust(origin) {
|
|
|
70
70
|
return LOW_TRUST_ORIGINS.has(origin);
|
|
71
71
|
}
|
|
72
72
|
|
|
73
|
+
// Default number of low-trust memories one result set may hold. Down-weighting
|
|
74
|
+
// alone leaves a poisoned memory in the context window whenever it is the best
|
|
75
|
+
// lexical match; bounding its *occupancy* does not depend on outranking it.
|
|
76
|
+
const DEFAULT_LOW_TRUST_MAX = 1;
|
|
77
|
+
|
|
78
|
+
/**
|
|
79
|
+
* Take the top `top` of a ranked list while holding at most `max` low-trust
|
|
80
|
+
* memories. Low-trust memories past the cap are skipped (the next trusted one
|
|
81
|
+
* takes the slot) and counted, so the caller can report the suppression
|
|
82
|
+
* rather than hide it.
|
|
83
|
+
*
|
|
84
|
+
* @param {Object[]} ranked - Best first; each with `origin`
|
|
85
|
+
* @param {number} top - Result size
|
|
86
|
+
* @param {number} [max] - Low-trust ceiling (config `recall_low_trust_max`)
|
|
87
|
+
* @returns {{ kept: Object[], suppressed: number }}
|
|
88
|
+
*/
|
|
89
|
+
function capLowTrust(ranked, top, max = DEFAULT_LOW_TRUST_MAX) {
|
|
90
|
+
const ceiling = Number.isInteger(max) && max >= 0 ? max : DEFAULT_LOW_TRUST_MAX;
|
|
91
|
+
const kept = [];
|
|
92
|
+
let lowTrust = 0;
|
|
93
|
+
let suppressed = 0;
|
|
94
|
+
for (const mem of ranked) {
|
|
95
|
+
if (kept.length >= top) break;
|
|
96
|
+
if (isLowTrust(mem.origin)) {
|
|
97
|
+
if (lowTrust >= ceiling) { suppressed++; continue; }
|
|
98
|
+
lowTrust++;
|
|
99
|
+
}
|
|
100
|
+
kept.push(mem);
|
|
101
|
+
}
|
|
102
|
+
return { kept, suppressed };
|
|
103
|
+
}
|
|
104
|
+
|
|
73
105
|
module.exports = {
|
|
106
|
+
DEFAULT_LOW_TRUST_MAX,
|
|
107
|
+
capLowTrust,
|
|
74
108
|
ORIGIN_POLICY,
|
|
75
109
|
DEFAULT_ORIGIN,
|
|
76
110
|
PRUNE_EXEMPT_SALIENCE,
|
package/src/quarantine.js
CHANGED
|
@@ -10,7 +10,7 @@
|
|
|
10
10
|
* Naming: the SM-2 spaced-repetition queue owns "review" (review-queue.json,
|
|
11
11
|
* due_for_review). This subsystem is quarantine / verify / pending_verification.
|
|
12
12
|
*
|
|
13
|
-
* Modes (config.json `quarantine_mode`, default '
|
|
13
|
+
* Modes (config.json `quarantine_mode`, default 'enforce'):
|
|
14
14
|
* off Nothing is flagged; existing flags persist inertly.
|
|
15
15
|
* flag Flagged memories stay recallable, marked (⊘ unverified receipts,
|
|
16
16
|
* quarantine_pending in results, session-start count).
|
|
@@ -18,6 +18,11 @@
|
|
|
18
18
|
* approved. Evaluated at read time, so flipping the knob
|
|
19
19
|
* retroactively hides/reveals already-pending items.
|
|
20
20
|
*
|
|
21
|
+
* Exclusion is the default because down-weighting is not a defense: a
|
|
22
|
+
* poisoned memory that is merely ranked lower still reaches the context
|
|
23
|
+
* window whenever it is the best lexical match for the query. Only keeping it
|
|
24
|
+
* out of the candidate pool removes it.
|
|
25
|
+
*
|
|
21
26
|
* Approval clears the flag only — origin, write-time clamps, and the recall
|
|
22
27
|
* trust factor all stay. `vetted: true` records that a human/agent looked, and
|
|
23
28
|
* stops `brain audit` from re-proposing the memory.
|
|
@@ -25,6 +30,34 @@
|
|
|
25
30
|
|
|
26
31
|
const { isLowTrust } = require('./provenance');
|
|
27
32
|
const { setFrontmatterFields } = require('./pinning');
|
|
33
|
+
const { SENSITIVE_OPT_OUT_REASON } = require('./sensitivity');
|
|
34
|
+
|
|
35
|
+
const QUARANTINE_MODES = new Set(['off', 'flag', 'enforce']);
|
|
36
|
+
const DEFAULT_QUARANTINE_MODE = 'enforce';
|
|
37
|
+
|
|
38
|
+
/**
|
|
39
|
+
* The effective quarantine mode. An unknown value falls back to the default
|
|
40
|
+
* rather than to 'off' — a typo in config.json must never disable the defense.
|
|
41
|
+
*/
|
|
42
|
+
function quarantineMode(config) {
|
|
43
|
+
const mode = config && config.quarantine_mode;
|
|
44
|
+
return QUARANTINE_MODES.has(mode) ? mode : DEFAULT_QUARANTINE_MODE;
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
/** True when pending-verification memories are hidden from recall. */
|
|
48
|
+
function hidesPending(config) {
|
|
49
|
+
return quarantineMode(config) === 'enforce';
|
|
50
|
+
}
|
|
51
|
+
|
|
52
|
+
/** True when the lint result carries an authorization claim. */
|
|
53
|
+
function isAuthorizationClaim(lintResult) {
|
|
54
|
+
return ((lintResult && lintResult.flags) || []).some((f) => f.severity === 'authorization');
|
|
55
|
+
}
|
|
56
|
+
|
|
57
|
+
/** `authorized_by` counts as backing only with a non-empty quote of the user. */
|
|
58
|
+
function hasBacking(authorizedBy) {
|
|
59
|
+
return Boolean(authorizedBy && typeof authorizedBy.quote === 'string' && authorizedBy.quote.trim());
|
|
60
|
+
}
|
|
28
61
|
|
|
29
62
|
/**
|
|
30
63
|
* Decide whether a write should be quarantined.
|
|
@@ -33,12 +66,18 @@ const { setFrontmatterFields } = require('./pinning');
|
|
|
33
66
|
* - agent-inferred: flagged only on injection-severity lint — the default
|
|
34
67
|
* agent write path stays friction-free.
|
|
35
68
|
* - user: never auto-flagged (lint is still recorded in the audit trail).
|
|
69
|
+
* - An authorization claim (lint severity `authorization`) is the exception
|
|
70
|
+
* to both: from any origin but `user` it is flagged `authz:unbacked`, and a
|
|
71
|
+
* `user` one is flagged `authz:no-source` unless the caller passed the
|
|
72
|
+
* user's own words in `authorized_by.quote`. Origin is asserted by the
|
|
73
|
+
* writer, and a writer inventing permission is exactly the failure this
|
|
74
|
+
* guards — so the claim needs evidence, not a label.
|
|
36
75
|
*
|
|
37
|
-
* @param {Object} opts - { origin, lintResult, config }
|
|
76
|
+
* @param {Object} opts - { origin, lintResult, config, authorizedBy }
|
|
38
77
|
* @returns {{ quarantined: boolean, reasons: string[] }}
|
|
39
78
|
*/
|
|
40
|
-
function quarantineDecision({ origin, lintResult, config }) {
|
|
41
|
-
const mode = (config
|
|
79
|
+
function quarantineDecision({ origin, lintResult, config, authorizedBy }) {
|
|
80
|
+
const mode = quarantineMode(config);
|
|
42
81
|
if (mode === 'off') return { quarantined: false, reasons: [] };
|
|
43
82
|
|
|
44
83
|
const reasons = [];
|
|
@@ -53,6 +92,10 @@ function quarantineDecision({ origin, lintResult, config }) {
|
|
|
53
92
|
else if (f.severity === 'suspect' && isLowTrust(origin)) reasons.push(`lint:${f.rule}`);
|
|
54
93
|
}
|
|
55
94
|
}
|
|
95
|
+
if (isAuthorizationClaim(lintResult)) {
|
|
96
|
+
if (origin !== 'user') reasons.push('authz:unbacked');
|
|
97
|
+
else if (!hasBacking(authorizedBy)) reasons.push('authz:no-source');
|
|
98
|
+
}
|
|
56
99
|
|
|
57
100
|
return { quarantined: reasons.length > 0, reasons };
|
|
58
101
|
}
|
|
@@ -108,4 +151,38 @@ function approveQuarantine(brainDir, index, id, now) {
|
|
|
108
151
|
return { id, vetted: true };
|
|
109
152
|
}
|
|
110
153
|
|
|
111
|
-
|
|
154
|
+
/**
|
|
155
|
+
* Put an approved memory back into pending verification — the undo for a
|
|
156
|
+
* mistaken approve. Re-flags it and strips vetted/vetted_at, so `brain audit`
|
|
157
|
+
* is free to propose it again. Approval dropped the original reasons, so they
|
|
158
|
+
* are rebuilt: the origin reason (when low-trust), the consent reason (when the
|
|
159
|
+
* memory is sensitive and the user has not opted in), plus `requeued`.
|
|
160
|
+
*
|
|
161
|
+
* Clearing `vetted` is also what withdraws per-item consent: a sensitive
|
|
162
|
+
* memory goes back to hidden, because isSensitiveHidden() keys on it.
|
|
163
|
+
*
|
|
164
|
+
* A pinned memory is refused rather than silently unpinned: pending memories
|
|
165
|
+
* can never be pinned, and dropping an always-apply constraint is the user's
|
|
166
|
+
* call. A supersession the approval released is NOT reverted — the caller
|
|
167
|
+
* surfaces it. Caller writes the index.
|
|
168
|
+
*/
|
|
169
|
+
function requeueQuarantine(brainDir, index, id, now, config) {
|
|
170
|
+
const entry = index.memories[id];
|
|
171
|
+
if (!entry) return { error: `Memory not found: ${id}` };
|
|
172
|
+
if (entry.quarantined) return { error: `Memory is already pending verification: ${id}` };
|
|
173
|
+
if (entry.pinned) return { error: `Memory is pinned — unpin it first (a pending memory can never be pinned): ${id}` };
|
|
174
|
+
const optedOut = entry.sensitivity === 'sensitive' && !(config && config.sensitive_topics === true);
|
|
175
|
+
const reasons = [
|
|
176
|
+
...(isLowTrust(entry.origin) ? [`origin:${entry.origin}`] : []),
|
|
177
|
+
...(optedOut ? [SENSITIVE_OPT_OUT_REASON] : []),
|
|
178
|
+
'requeued',
|
|
179
|
+
];
|
|
180
|
+
delete entry.vetted;
|
|
181
|
+
delete entry.vetted_at;
|
|
182
|
+
setFrontmatterFields(brainDir, entry.path, { vetted: null, vetted_at: null });
|
|
183
|
+
return applyQuarantine(brainDir, index, id, reasons, now);
|
|
184
|
+
}
|
|
185
|
+
|
|
186
|
+
module.exports = {
|
|
187
|
+
DEFAULT_QUARANTINE_MODE, quarantineMode, hidesPending,
|
|
188
|
+
isAuthorizationClaim, hasBacking, quarantineDecision, listPending, applyQuarantine, approveQuarantine, requeueQuarantine };
|
package/src/receipt.js
CHANGED
|
@@ -15,8 +15,10 @@
|
|
|
15
15
|
* Memories pending verification (quarantined — see src/quarantine.js) carry a
|
|
16
16
|
* further "⊘ unverified" segment, and memories whose validity window has closed
|
|
17
17
|
* (see src/temporal.js) a "⌛ expired" one, and sensitive-topic memories (see
|
|
18
|
-
* src/sensitivity.js) a "⚠ sensitive" one
|
|
19
|
-
*
|
|
18
|
+
* src/sensitivity.js) a "⚠ sensitive" one, and memories that grant the agent a
|
|
19
|
+
* permission (see src/content-lint.js) a "⚠ authorization" one. User/agent-
|
|
20
|
+
* inferred, vetted, current, standard receipts are byte-identical to the base
|
|
21
|
+
* format.
|
|
20
22
|
*
|
|
21
23
|
* Age is derived from the memory's `created` timestamp (falling back to
|
|
22
24
|
* `last_accessed`; omitted entirely when neither parses):
|
|
@@ -82,10 +84,13 @@ function receiptFor(memoryLike, nowFn) {
|
|
|
82
84
|
// Consent: a sensitive-topic memory stays visibly marked even after the user
|
|
83
85
|
// opted in or approved it, so the agent knows to handle it with care.
|
|
84
86
|
const sensitive = mem.sensitivity === 'sensitive' ? ', ⚠ sensitive' : '';
|
|
87
|
+
// A permission recalled from memory is a claim about the past, never
|
|
88
|
+
// consent for the action in front of the agent now.
|
|
89
|
+
const authz = mem.authorization ? ', ⚠ authorization' : '';
|
|
85
90
|
|
|
86
91
|
return age
|
|
87
|
-
? `◉ memory: "${title}" (${type}, ${age}${trust}${pending}${expired}${sensitive})`
|
|
88
|
-
: `◉ memory: "${title}" (${type}${trust}${pending}${expired}${sensitive})`;
|
|
92
|
+
? `◉ memory: "${title}" (${type}, ${age}${trust}${pending}${expired}${sensitive}${authz})`
|
|
93
|
+
: `◉ memory: "${title}" (${type}${trust}${pending}${expired}${sensitive}${authz})`;
|
|
89
94
|
}
|
|
90
95
|
|
|
91
96
|
module.exports = { receiptFor, ageLabel };
|
package/src/surfaced.js
ADDED
|
@@ -0,0 +1,188 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Brain Memory — Surfaced Ledger (citation lock)
|
|
3
|
+
*
|
|
4
|
+
* A receipt line (`◉ memory: "<title>" (…)`) tells the user a memory shaped an
|
|
5
|
+
* answer. src/receipt.js guarantees the engine mints it; this module checks
|
|
6
|
+
* the other half — that the agent only cites memories brain actually showed
|
|
7
|
+
* it. Every read path (recall, session-start, prompt-recall) records what it
|
|
8
|
+
* surfaced; `brain reinforce` records what was used; the Stop hook compares
|
|
9
|
+
* the receipts in the final reply against the ledger.
|
|
10
|
+
*
|
|
11
|
+
* Device-local by design: `.local/` is excluded from git sync, cloud sync,
|
|
12
|
+
* export and restore. What one machine's session saw says nothing about
|
|
13
|
+
* another's, and the ledger is telemetry, not memory.
|
|
14
|
+
*
|
|
15
|
+
* Bounded: past MAX_LINES the file is trimmed to its newest KEEP_LINES. Every
|
|
16
|
+
* write is best-effort — a full disk must never break recall.
|
|
17
|
+
*/
|
|
18
|
+
|
|
19
|
+
const fs = require('fs');
|
|
20
|
+
const path = require('path');
|
|
21
|
+
|
|
22
|
+
const LOCAL_DIR = '.local';
|
|
23
|
+
const LEDGER_FILE = 'surfaced.jsonl';
|
|
24
|
+
const MAX_LINES = 4000;
|
|
25
|
+
const KEEP_LINES = 2000;
|
|
26
|
+
// Receipts in a reply are matched against memories surfaced this session, or
|
|
27
|
+
// in this window when the reader could not name its session (a bare CLI call).
|
|
28
|
+
const UNSCOPED_WINDOW_MS = 12 * 3600 * 1000;
|
|
29
|
+
|
|
30
|
+
// Titles are not escaped in receipts (src/receipt.js), so match lazily up to
|
|
31
|
+
// the `" (` that opens the type segment.
|
|
32
|
+
const RECEIPT_RE = /◉ memory: "(.*?)" \(/g;
|
|
33
|
+
|
|
34
|
+
function ledgerPath(brainDir) {
|
|
35
|
+
return path.join(brainDir, LOCAL_DIR, LEDGER_FILE);
|
|
36
|
+
}
|
|
37
|
+
|
|
38
|
+
/** The session id a CLI process can see, or null. Hooks pass theirs in. */
|
|
39
|
+
function envSession(env = process.env) {
|
|
40
|
+
return env.BRAIN_SESSION_ID || env.CLAUDE_SESSION_ID || env.CODEX_SESSION_ID || null;
|
|
41
|
+
}
|
|
42
|
+
|
|
43
|
+
function append(brainDir, entries) {
|
|
44
|
+
if (!entries.length) return;
|
|
45
|
+
try {
|
|
46
|
+
const file = ledgerPath(brainDir);
|
|
47
|
+
fs.mkdirSync(path.dirname(file), { recursive: true });
|
|
48
|
+
fs.appendFileSync(file, entries.map((e) => JSON.stringify(e)).join('\n') + '\n');
|
|
49
|
+
trim(file);
|
|
50
|
+
} catch (_) {
|
|
51
|
+
// Telemetry only — never fail the read path that called us.
|
|
52
|
+
}
|
|
53
|
+
}
|
|
54
|
+
|
|
55
|
+
function trim(file) {
|
|
56
|
+
const lines = fs.readFileSync(file, 'utf-8').split('\n').filter(Boolean);
|
|
57
|
+
if (lines.length <= MAX_LINES) return;
|
|
58
|
+
fs.writeFileSync(file, lines.slice(-KEEP_LINES).join('\n') + '\n');
|
|
59
|
+
}
|
|
60
|
+
|
|
61
|
+
/**
|
|
62
|
+
* Record memories a read path put in front of the agent.
|
|
63
|
+
*
|
|
64
|
+
* @param {string} brainDir
|
|
65
|
+
* @param {Object} opts - { session, source, results: [{id, title, receipt}], now }
|
|
66
|
+
*/
|
|
67
|
+
function recordSurfaced(brainDir, { session, source, results, now }) {
|
|
68
|
+
const ts = now || new Date().toISOString();
|
|
69
|
+
append(brainDir, (results || []).filter((r) => r && r.id).map((r) => ({
|
|
70
|
+
ts, kind: 'surfaced', session: session || null, source, id: r.id, title: receiptTitle(r.receipt) ?? r.title,
|
|
71
|
+
})));
|
|
72
|
+
}
|
|
73
|
+
|
|
74
|
+
/** Record memories the agent reported using (`brain reinforce`). */
|
|
75
|
+
function recordUsed(brainDir, { session, ids, now }) {
|
|
76
|
+
const ts = now || new Date().toISOString();
|
|
77
|
+
append(brainDir, (ids || []).map((id) => ({ ts, kind: 'used', session: session || null, id })));
|
|
78
|
+
}
|
|
79
|
+
|
|
80
|
+
/** Record a reply that cited memories brain never surfaced. */
|
|
81
|
+
function recordViolation(brainDir, { session, titles, now }) {
|
|
82
|
+
append(brainDir, [{ ts: now || new Date().toISOString(), kind: 'violation', session: session || null, titles }]);
|
|
83
|
+
}
|
|
84
|
+
|
|
85
|
+
/** Mark a session's violations as shown to the agent. */
|
|
86
|
+
function recordAck(brainDir, { session, now }) {
|
|
87
|
+
append(brainDir, [{ ts: now || new Date().toISOString(), kind: 'ack', session: session || null }]);
|
|
88
|
+
}
|
|
89
|
+
|
|
90
|
+
function readLedger(brainDir) {
|
|
91
|
+
try {
|
|
92
|
+
return fs.readFileSync(ledgerPath(brainDir), 'utf-8').split('\n').filter(Boolean).map((line) => {
|
|
93
|
+
try { return JSON.parse(line); } catch (_) { return null; }
|
|
94
|
+
}).filter(Boolean);
|
|
95
|
+
} catch (_) {
|
|
96
|
+
return [];
|
|
97
|
+
}
|
|
98
|
+
}
|
|
99
|
+
|
|
100
|
+
/** The title inside a receipt line; null when it is not one. */
|
|
101
|
+
function receiptTitle(receipt) {
|
|
102
|
+
if (typeof receipt !== 'string') return null;
|
|
103
|
+
RECEIPT_RE.lastIndex = 0;
|
|
104
|
+
const m = RECEIPT_RE.exec(receipt);
|
|
105
|
+
return m ? m[1] : null;
|
|
106
|
+
}
|
|
107
|
+
|
|
108
|
+
/** Every receipt title cited in a reply. */
|
|
109
|
+
function citedTitles(text) {
|
|
110
|
+
const titles = [];
|
|
111
|
+
if (typeof text !== 'string') return titles;
|
|
112
|
+
RECEIPT_RE.lastIndex = 0;
|
|
113
|
+
let m;
|
|
114
|
+
while ((m = RECEIPT_RE.exec(text)) !== null) titles.push(m[1]);
|
|
115
|
+
return titles;
|
|
116
|
+
}
|
|
117
|
+
|
|
118
|
+
/**
|
|
119
|
+
* Compare the receipts in a reply against what was surfaced to this session.
|
|
120
|
+
*
|
|
121
|
+
* @param {string} brainDir
|
|
122
|
+
* @param {Object} opts - { session, text, nowMs }
|
|
123
|
+
* @returns {{ cited: string[], unsurfaced: string[] }}
|
|
124
|
+
*/
|
|
125
|
+
function checkCitations(brainDir, { session, text, nowMs }) {
|
|
126
|
+
const cited = citedTitles(text);
|
|
127
|
+
if (!cited.length) return { cited, unsurfaced: [] };
|
|
128
|
+
const now = nowMs ?? Date.now();
|
|
129
|
+
const seen = new Set();
|
|
130
|
+
for (const e of readLedger(brainDir)) {
|
|
131
|
+
if (e.kind !== 'surfaced') continue;
|
|
132
|
+
const sameSession = session && e.session === session;
|
|
133
|
+
const unscoped = !e.session && now - Date.parse(e.ts) <= UNSCOPED_WINDOW_MS;
|
|
134
|
+
if (sameSession || unscoped) seen.add(e.title);
|
|
135
|
+
}
|
|
136
|
+
return { cited, unsurfaced: [...new Set(cited.filter((t) => !seen.has(t)))] };
|
|
137
|
+
}
|
|
138
|
+
|
|
139
|
+
/** Violations recorded for a session since its last ack. */
|
|
140
|
+
function pendingViolations(brainDir, session) {
|
|
141
|
+
if (!session) return [];
|
|
142
|
+
let pending = [];
|
|
143
|
+
for (const e of readLedger(brainDir)) {
|
|
144
|
+
if (e.session !== session) continue;
|
|
145
|
+
if (e.kind === 'ack') pending = [];
|
|
146
|
+
else if (e.kind === 'violation') pending.push(...(e.titles || []));
|
|
147
|
+
}
|
|
148
|
+
return [...new Set(pending)];
|
|
149
|
+
}
|
|
150
|
+
|
|
151
|
+
/**
|
|
152
|
+
* Surfaced vs used over a window — how much of what brain injects the agent
|
|
153
|
+
* actually relies on. A low ratio means injection is mostly noise.
|
|
154
|
+
*/
|
|
155
|
+
function usageSummary(brainDir, { sinceMs }) {
|
|
156
|
+
let surfaced = 0;
|
|
157
|
+
let used = 0;
|
|
158
|
+
const surfacedIds = new Set();
|
|
159
|
+
const usedIds = new Set();
|
|
160
|
+
for (const e of readLedger(brainDir)) {
|
|
161
|
+
if (Date.parse(e.ts) < sinceMs) continue;
|
|
162
|
+
if (e.kind === 'surfaced') { surfaced++; surfacedIds.add(e.id); }
|
|
163
|
+
else if (e.kind === 'used') { used++; usedIds.add(e.id); }
|
|
164
|
+
}
|
|
165
|
+
const usedOfSurfaced = [...usedIds].filter((id) => surfacedIds.has(id)).length;
|
|
166
|
+
return {
|
|
167
|
+
surfaced,
|
|
168
|
+
used,
|
|
169
|
+
distinct_surfaced: surfacedIds.size,
|
|
170
|
+
distinct_used_of_surfaced: usedOfSurfaced,
|
|
171
|
+
use_rate: surfacedIds.size ? Math.round((usedOfSurfaced / surfacedIds.size) * 1000) / 1000 : null,
|
|
172
|
+
};
|
|
173
|
+
}
|
|
174
|
+
|
|
175
|
+
module.exports = {
|
|
176
|
+
LOCAL_DIR,
|
|
177
|
+
envSession,
|
|
178
|
+
recordSurfaced,
|
|
179
|
+
recordUsed,
|
|
180
|
+
recordViolation,
|
|
181
|
+
recordAck,
|
|
182
|
+
readLedger,
|
|
183
|
+
receiptTitle,
|
|
184
|
+
citedTitles,
|
|
185
|
+
checkCitations,
|
|
186
|
+
pendingViolations,
|
|
187
|
+
usageSummary,
|
|
188
|
+
};
|
|
@@ -8,6 +8,8 @@
|
|
|
8
8
|
|
|
9
9
|
const crypto = require('crypto');
|
|
10
10
|
const fs = require('fs');
|
|
11
|
+
const http = require('http');
|
|
12
|
+
const https = require('https');
|
|
11
13
|
const os = require('os');
|
|
12
14
|
const path = require('path');
|
|
13
15
|
const zlib = require('zlib');
|
|
@@ -65,20 +67,77 @@ function sha256(buf) {
|
|
|
65
67
|
|
|
66
68
|
// -- a thin client -----------------------------------------------------------
|
|
67
69
|
|
|
70
|
+
/**
|
|
71
|
+
* One HTTP request on a socket of its own, closed when the response ends.
|
|
72
|
+
*
|
|
73
|
+
* Deliberately not `fetch`: fetch keeps connections alive in a pool, and on
|
|
74
|
+
* Node 18 a pooled socket to a server that has just been shut down could keep a
|
|
75
|
+
* finished test process from exiting, which hung CI. With `agent: false` and
|
|
76
|
+
* `Connection: close` nothing outlives the request, on any Node version.
|
|
77
|
+
*
|
|
78
|
+
* @returns {Promise<{status: number, headers: {get: (name: string) => string|null}, body: Buffer}>}
|
|
79
|
+
*/
|
|
80
|
+
function rawRequest(method, url, { headers, body } = {}) {
|
|
81
|
+
return new Promise((resolve, reject) => {
|
|
82
|
+
const target = new URL(url);
|
|
83
|
+
const mod = target.protocol === 'https:' ? https : http;
|
|
84
|
+
const req = mod.request(target, {
|
|
85
|
+
method,
|
|
86
|
+
agent: false,
|
|
87
|
+
headers: {
|
|
88
|
+
Connection: 'close',
|
|
89
|
+
...(headers || {}),
|
|
90
|
+
...(body != null ? { 'Content-Length': Buffer.byteLength(body) } : {}),
|
|
91
|
+
},
|
|
92
|
+
}, (res) => {
|
|
93
|
+
const chunks = [];
|
|
94
|
+
res.on('data', (chunk) => chunks.push(chunk));
|
|
95
|
+
res.on('error', reject);
|
|
96
|
+
res.on('end', () => resolve({
|
|
97
|
+
status: res.statusCode,
|
|
98
|
+
headers: {
|
|
99
|
+
get(name) {
|
|
100
|
+
const value = res.headers[String(name).toLowerCase()];
|
|
101
|
+
if (value == null) return null;
|
|
102
|
+
return Array.isArray(value) ? value.join(', ') : value;
|
|
103
|
+
},
|
|
104
|
+
},
|
|
105
|
+
body: Buffer.concat(chunks),
|
|
106
|
+
}));
|
|
107
|
+
});
|
|
108
|
+
req.on('error', reject);
|
|
109
|
+
req.setTimeout(30000, () => req.destroy(new Error(`${method} ${url} timed out`)));
|
|
110
|
+
req.end(body != null ? body : undefined);
|
|
111
|
+
});
|
|
112
|
+
}
|
|
113
|
+
|
|
114
|
+
function parseBody(buf) {
|
|
115
|
+
const text = buf.toString('utf8');
|
|
116
|
+
try { return text ? JSON.parse(text) : null; } catch { return text; }
|
|
117
|
+
}
|
|
118
|
+
|
|
119
|
+
/** The subset of `fetch` the OIDC verifier uses, without a connection pool. */
|
|
120
|
+
async function plainFetch(url, opts = {}) {
|
|
121
|
+
const res = await rawRequest(opts.method || 'GET', String(url), { headers: opts.headers, body: opts.body });
|
|
122
|
+
return {
|
|
123
|
+
ok: res.status >= 200 && res.status < 300,
|
|
124
|
+
status: res.status,
|
|
125
|
+
headers: res.headers,
|
|
126
|
+
json: async () => JSON.parse(res.body.toString('utf8')),
|
|
127
|
+
text: async () => res.body.toString('utf8'),
|
|
128
|
+
};
|
|
129
|
+
}
|
|
130
|
+
|
|
68
131
|
function client(baseUrl, token) {
|
|
69
132
|
const base = baseUrl.replace(/\/$/, '');
|
|
70
133
|
const auth = token ? { Authorization: `Bearer ${token}` } : {};
|
|
71
134
|
|
|
72
135
|
async function json(method, pathname, body, headers) {
|
|
73
|
-
const res = await
|
|
74
|
-
method,
|
|
136
|
+
const res = await rawRequest(method, base + pathname, {
|
|
75
137
|
headers: { ...auth, ...(body ? { 'Content-Type': 'application/json' } : {}), ...(headers || {}) },
|
|
76
138
|
body: body ? JSON.stringify(body) : undefined,
|
|
77
139
|
});
|
|
78
|
-
|
|
79
|
-
let data = null;
|
|
80
|
-
try { data = text ? JSON.parse(text) : null; } catch { data = text; }
|
|
81
|
-
return { status: res.status, headers: res.headers, data };
|
|
140
|
+
return { status: res.status, headers: res.headers, data: parseBody(res.body) };
|
|
82
141
|
}
|
|
83
142
|
|
|
84
143
|
async function upload(brainId, archive, { headers, query, field } = {}) {
|
|
@@ -89,23 +148,18 @@ function client(baseUrl, token) {
|
|
|
89
148
|
'Content-Type: application/gzip\r\n\r\n'
|
|
90
149
|
);
|
|
91
150
|
const tail = Buffer.from(`\r\n--${boundary}--\r\n`);
|
|
92
|
-
const res = await
|
|
93
|
-
method: 'PUT',
|
|
151
|
+
const res = await rawRequest('PUT', `${base}/api/brains/${brainId}/sync${query || ''}`, {
|
|
94
152
|
headers: { ...auth, 'Content-Type': `multipart/form-data; boundary=${boundary}`, ...(headers || {}) },
|
|
95
153
|
body: Buffer.concat([head, archive, tail]),
|
|
96
154
|
});
|
|
97
|
-
|
|
98
|
-
let data = null;
|
|
99
|
-
try { data = text ? JSON.parse(text) : null; } catch { data = text; }
|
|
100
|
-
return { status: res.status, headers: res.headers, data };
|
|
155
|
+
return { status: res.status, headers: res.headers, data: parseBody(res.body) };
|
|
101
156
|
}
|
|
102
157
|
|
|
103
158
|
async function download(brainId, { headers, query } = {}) {
|
|
104
|
-
const res = await
|
|
159
|
+
const res = await rawRequest('GET', `${base}/api/brains/${brainId}/sync${query || ''}`, {
|
|
105
160
|
headers: { ...auth, ...(headers || {}) },
|
|
106
161
|
});
|
|
107
|
-
|
|
108
|
-
return { status: res.status, headers: res.headers, body };
|
|
162
|
+
return { status: res.status, headers: res.headers, body: res.body };
|
|
109
163
|
}
|
|
110
164
|
|
|
111
165
|
return { json, upload, download };
|
|
@@ -142,4 +196,4 @@ async function startReferenceStore(options = {}) {
|
|
|
142
196
|
};
|
|
143
197
|
}
|
|
144
198
|
|
|
145
|
-
module.exports = { makeArchive, sampleArchive, sha256, client, startReferenceStore };
|
|
199
|
+
module.exports = { makeArchive, sampleArchive, sha256, client, plainFetch, startReferenceStore };
|