brain-memory 0.4.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.
- package/CHANGELOG.md +99 -0
- package/README.md +4 -0
- package/SECURITY.md +17 -6
- package/bin/brain.js +24 -3
- 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 +4 -3
- 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 +2 -2
- 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/content-lint.js
CHANGED
|
@@ -11,6 +11,13 @@
|
|
|
11
11
|
* injection Text that tries to steer the agent against the user. Never
|
|
12
12
|
* downgraded — no legitimate memory says "ignore previous
|
|
13
13
|
* instructions" or pipes a download into a shell.
|
|
14
|
+
* authorization
|
|
15
|
+
* A claim that the agent may act without asking ("the user
|
|
16
|
+
* approved force-pushes", "no need to confirm deploys"). Never
|
|
17
|
+
* downgraded: a writer that invents permission is the failure
|
|
18
|
+
* this catches, and it happens without any attacker. Gated
|
|
19
|
+
* separately from injection by src/quarantine.js — even a
|
|
20
|
+
* user-origin claim needs the user's own words behind it.
|
|
14
21
|
* suspect Directive/imperative content. Downgraded to advisory for
|
|
15
22
|
* type:preference and cognitive_type:procedural memories, which
|
|
16
23
|
* legitimately contain instructions ("always use 2-space
|
|
@@ -20,7 +27,48 @@
|
|
|
20
27
|
* Pure and dependency-free; used at write time by bin/memorize.js.
|
|
21
28
|
*/
|
|
22
29
|
|
|
23
|
-
const SEVERITY_RANK = { none: 0, advisory: 1, suspect: 2,
|
|
30
|
+
const SEVERITY_RANK = { none: 0, advisory: 1, suspect: 2, authorization: 3, injection: 4 };
|
|
31
|
+
|
|
32
|
+
// secret_exfil pairs a transfer verb with a credential noun. Both must be
|
|
33
|
+
// standalone prose words: a verb that is a code literal or half of a compound
|
|
34
|
+
// (`upload`, upload-artifact, post-install) is a name, not an action, and a
|
|
35
|
+
// compound noun (password-reset, token_count) names a feature, not a secret.
|
|
36
|
+
// Without this, ordinary engineering notes ("the password-reset email", "set
|
|
37
|
+
// the destination to `upload`, then the API key…") quarantine as injections.
|
|
38
|
+
// `.env` is matched on its own: it starts with a non-word char, so a leading
|
|
39
|
+
// \b would require a word char before the dot and never match it bare.
|
|
40
|
+
const EXFIL_VERB = '(?<![`_\\-/.])\\b(?:send|post|upload|forward|exfiltrate|transmit|email)(?:s|ed|ing)?\\b(?![`_\\-/])';
|
|
41
|
+
const EXFIL_SECRET = '(?:(?<![`_\\-/])\\b(?:token|password|secret|api.?key|credential|private.?key)s?\\b(?![`_\\-])|(?<![\\w.])\\.env\\b)';
|
|
42
|
+
const EXFIL_GAP = '[^\\n.]{0,80}';
|
|
43
|
+
const SECRET_EXFIL_RE = new RegExp(
|
|
44
|
+
`${EXFIL_VERB}${EXFIL_GAP}${EXFIL_SECRET}|${EXFIL_SECRET}${EXFIL_GAP}${EXFIL_VERB}`,
|
|
45
|
+
'i'
|
|
46
|
+
);
|
|
47
|
+
|
|
48
|
+
// authorization_claim has three shapes, each anchored on who is granting or
|
|
49
|
+
// being granted — never on the bare words "approved"/"authorized", which
|
|
50
|
+
// ordinary notes about OAuth, RBAC and review workflows are full of:
|
|
51
|
+
// 1. a principal granted an *action* ("the user approved force-pushing");
|
|
52
|
+
// approving a design or a PR is a fact, not a permission, so an action
|
|
53
|
+
// verb must follow within the sentence;
|
|
54
|
+
// 2. the agent is told it may act ("you are allowed to", "Claude is
|
|
55
|
+
// permitted to");
|
|
56
|
+
// 3. confirmation is waived ("no need to ask", "pre-approved", "standing
|
|
57
|
+
// permission", "skip the confirmation").
|
|
58
|
+
const AUTHZ_GRANTOR = '\\b(?:the\\s+)?(?:user|owner|maintainer|admin(?:istrator)?|i|we)\\b';
|
|
59
|
+
const AUTHZ_GRANT = '(?:\\s+(?:has|have|had))?(?:\\s+(?:already|explicitly))?\\s+(?:approved|authori[sz]ed|okayed|ok\'d|signed\\s+off\\s+on|green-?lit|allowed|permitted)\\b';
|
|
60
|
+
const AUTHZ_ACTION = '\\b(?:force[\\s-]?push\\w*|push\\w*|deploy\\w*|delet\\w*|drop\\w*|merg\\w*|releas\\w*|publish\\w*|pay\\w*|send\\w*|email\\w*|transfer\\w*|run\\w*|execut\\w*|install\\w*|wip\\w*|rotat\\w*|revok\\w*|purchas\\w*|spend\\w*|skip\\w*|bypass\\w*|disabl\\w*|overwrit\\w*|rm\\b)';
|
|
61
|
+
const AUTHZ_AGENT = '\\b(?:you|the\\s+(?:agent|assistant|bot)|claude|codex|gemini|agents?)\\s+(?:are|is|have\\s+been|has\\s+been)(?:\\s+(?:now|always|explicitly))?\\s+(?:allowed|authori[sz]ed|permitted|cleared|granted\\s+(?:permission|access))\\b';
|
|
62
|
+
const AUTHZ_WAIVER = '\\b(?:no\\s+need\\s+to|(?:do\\s+not|don\'t|doesn\'t|does\\s+not)\\s+need\\s+to|without\\s+needing\\s+to)\\s+(?:ask|confirm|check\\s+with|get\\s+(?:approval|permission|sign-?off))\\b' +
|
|
63
|
+
// Predicate only, and not "pre-approved for": "deploys are pre-approved" is a
|
|
64
|
+
// permission; "pre-approved for a mortgage" and "pre-approved offers" are not.
|
|
65
|
+
'|\\b(?:is|are|was|were|be|been|now)\\s+pre-?(?:approved|authori[sz]ed)\\b(?!\\s+for\\b)' +
|
|
66
|
+
'|\\b(?:standing|blanket)\\s+(?:permission|approval|authori[sz]ation)\\b' +
|
|
67
|
+
'|\\bskip\\s+(?:the\\s+)?(?:confirmation|approval|permission)\\b';
|
|
68
|
+
const AUTHZ_RE = new RegExp(
|
|
69
|
+
`${AUTHZ_GRANTOR}${AUTHZ_GRANT}[^\\n.]{0,60}${AUTHZ_ACTION}|${AUTHZ_AGENT}|${AUTHZ_WAIVER}`,
|
|
70
|
+
'i'
|
|
71
|
+
);
|
|
24
72
|
|
|
25
73
|
// Each rule: name, base severity, and a matcher over the combined text.
|
|
26
74
|
// Patterns are case-insensitive; `m` where line-anchoring matters.
|
|
@@ -38,7 +86,12 @@ const RULES = [
|
|
|
38
86
|
{
|
|
39
87
|
rule: 'secret_exfil',
|
|
40
88
|
severity: 'injection',
|
|
41
|
-
re:
|
|
89
|
+
re: SECRET_EXFIL_RE,
|
|
90
|
+
},
|
|
91
|
+
{
|
|
92
|
+
rule: 'authorization_claim',
|
|
93
|
+
severity: 'authorization',
|
|
94
|
+
re: AUTHZ_RE,
|
|
42
95
|
},
|
|
43
96
|
{
|
|
44
97
|
rule: 'imperative_directive',
|
package/src/export-import.js
CHANGED
|
@@ -13,7 +13,7 @@ const path = require('path');
|
|
|
13
13
|
const { encrypt, decrypt } = require('./crypto');
|
|
14
14
|
|
|
15
15
|
// Directories inside ~/.brain/ to skip during export
|
|
16
|
-
const EXCLUDED = new Set(['.sync', '.DS_Store']);
|
|
16
|
+
const EXCLUDED = new Set(['.sync', '.local', '.DS_Store']);
|
|
17
17
|
|
|
18
18
|
/**
|
|
19
19
|
* Export the entire ~/.brain/ directory to a single file.
|
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
|
+
};
|