brain-memory 0.3.0 → 0.5.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.
Files changed (62) hide show
  1. package/CHANGELOG.md +153 -0
  2. package/README.md +4 -0
  3. package/SECURITY.md +61 -9
  4. package/bin/brain.js +24 -3
  5. package/bin/cloud-sync.js +49 -6
  6. package/bin/install.js +72 -14
  7. package/bin/memorize.js +50 -6
  8. package/bin/port.js +174 -0
  9. package/bin/recall.js +16 -6
  10. package/bin/reinforce.js +5 -0
  11. package/bin/session-start.js +30 -4
  12. package/bin/verify.js +42 -4
  13. package/commands/brain/memorize.md +8 -0
  14. package/commands/brain/sync.md +23 -0
  15. package/commands/brain/verify.md +10 -2
  16. package/hooks/citation-check.mjs +94 -0
  17. package/hooks/hooks.json +11 -0
  18. package/hooks/lib.mjs +6 -0
  19. package/hooks/prompt-recall.mjs +24 -3
  20. package/hooks/session-start.mjs +4 -2
  21. package/integrations/README.md +4 -0
  22. package/integrations/agentskills/brain-memory/SKILL.md +9 -5
  23. package/package.json +10 -5
  24. package/prompts/antigravity.md +4 -2
  25. package/prompts/claude.md +4 -2
  26. package/prompts/copilot.md +4 -2
  27. package/prompts/kilo.md +4 -2
  28. package/prompts/openai.md +4 -2
  29. package/prompts/opencode.md +4 -2
  30. package/src/adapters.js +240 -0
  31. package/src/anomaly.js +41 -1
  32. package/src/cloud-sync.js +123 -11
  33. package/src/content-lint.js +55 -2
  34. package/src/export-import.js +1 -1
  35. package/src/git-sync.js +1 -1
  36. package/src/index-manager.js +9 -5
  37. package/src/installer.js +35 -1
  38. package/src/pinning.js +20 -1
  39. package/src/provenance.js +34 -0
  40. package/src/quarantine.js +82 -5
  41. package/src/receipt.js +9 -4
  42. package/src/surfaced.js +188 -0
  43. package/store/CONTRACT.md +244 -0
  44. package/store/Dockerfile +24 -0
  45. package/store/README.md +43 -0
  46. package/store/SELF-HOSTING.md +200 -0
  47. package/store/bin/brain-store.js +189 -0
  48. package/store/conformance/conformance.test.js +341 -0
  49. package/store/conformance/helpers.js +199 -0
  50. package/store/deploy/Caddyfile +14 -0
  51. package/store/deploy/connector.Dockerfile +38 -0
  52. package/store/deploy/docker-compose.yml +83 -0
  53. package/store/deploy/env.example +19 -0
  54. package/store/lib/auth.js +174 -0
  55. package/store/lib/oidc.js +206 -0
  56. package/store/lib/storage.js +333 -0
  57. package/store/lib/tar.js +150 -0
  58. package/store/openapi.yaml +318 -0
  59. package/store/server.js +465 -0
  60. package/store/test/mock-issuer.js +104 -0
  61. package/store/test/oidc.test.js +222 -0
  62. package/store/test/store.test.js +445 -0
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 = { pinMemory, unpinMemory, estimateTokens, setFrontmatterFields };
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 'flag'):
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 && config.quarantine_mode) || 'flag';
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
- module.exports = { quarantineDecision, listPending, applyQuarantine, approveQuarantine };
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. User/agent-inferred, vetted, current,
19
- * standard receipts are byte-identical to the base format.
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 };
@@ -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
+ };