brain-memory 0.1.0 → 0.3.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 +216 -0
- package/README.md +34 -5
- package/bin/audit.js +18 -1
- package/bin/brain +4 -0
- package/bin/forget.js +10 -1
- package/bin/import.js +1 -1
- package/bin/install.js +10 -0
- package/bin/memorize.js +99 -21
- package/bin/recall.js +64 -13
- package/bin/reinforce.js +34 -1
- package/bin/session-start.js +32 -4
- package/bin/skill.js +8 -2
- package/bin/verify.js +35 -3
- package/commands/brain/import.md +1 -1
- package/commands/brain/memorize.md +45 -4
- package/commands/brain/remember.md +10 -1
- package/commands/brain/skills.md +29 -0
- package/commands/brain/sleep.md +1 -1
- package/commands/brain/verify.md +6 -0
- package/hooks/hooks.json +39 -0
- package/hooks/lib.mjs +117 -0
- package/hooks/prompt-recall.mjs +123 -0
- package/hooks/session-end.md +54 -0
- package/hooks/session-end.mjs +63 -0
- package/hooks/session-start.md +58 -0
- package/hooks/session-start.mjs +82 -0
- package/integrations/agentskills/brain-memory/SKILL.md +5 -0
- package/package.json +5 -3
- package/prompts/antigravity.md +26 -2
- package/prompts/claude.md +26 -2
- package/prompts/copilot.md +26 -2
- package/prompts/kilo.md +26 -2
- package/prompts/openai.md +26 -2
- package/prompts/opencode.md +26 -2
- package/src/anomaly.js +7 -0
- package/src/contradiction.js +106 -0
- package/src/harvest.js +174 -2
- package/src/index-manager.js +8 -0
- package/src/installer.js +126 -3
- package/src/integrity.js +155 -0
- package/src/receipt.js +14 -4
- package/src/scorer.js +75 -7
- package/src/sensitivity.js +134 -0
- package/src/skill-verify.js +191 -0
- package/src/skills.js +63 -0
- package/src/temporal.js +228 -0
package/src/receipt.js
CHANGED
|
@@ -13,8 +13,10 @@
|
|
|
13
13
|
* trailing warning segment so a poisoned-source memory is visibly marked
|
|
14
14
|
* wherever its receipt appears: ◉ memory: "<title>" (<type>, <age>, ⚠ external)
|
|
15
15
|
* Memories pending verification (quarantined — see src/quarantine.js) carry a
|
|
16
|
-
* further "⊘ unverified" segment
|
|
17
|
-
*
|
|
16
|
+
* further "⊘ unverified" segment, and memories whose validity window has closed
|
|
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
20
|
*
|
|
19
21
|
* Age is derived from the memory's `created` timestamp (falling back to
|
|
20
22
|
* `last_accessed`; omitted entirely when neither parses):
|
|
@@ -25,6 +27,7 @@
|
|
|
25
27
|
*/
|
|
26
28
|
|
|
27
29
|
const { isLowTrust } = require('./provenance');
|
|
30
|
+
const { temporalState } = require('./temporal');
|
|
28
31
|
|
|
29
32
|
const MS_PER_DAY = 24 * 60 * 60 * 1000;
|
|
30
33
|
const DAYS_PER_MONTH = 30.44; // mean Gregorian month
|
|
@@ -72,10 +75,17 @@ function receiptFor(memoryLike, nowFn) {
|
|
|
72
75
|
// Pending verification (quarantine flag mode): the receipt is the visible
|
|
73
76
|
// channel, so an unverified memory is marked wherever it fires.
|
|
74
77
|
const pending = mem.quarantined ? ', ⊘ unverified' : '';
|
|
78
|
+
// Bitemporal: the fact's validity window has closed. A stale memory can
|
|
79
|
+
// still be the right answer ("that was true until March") — but it must
|
|
80
|
+
// never look current, so the marker rides along with the receipt.
|
|
81
|
+
const expired = temporalState(mem, now.getTime()) === 'expired' ? ', ⌛ expired' : '';
|
|
82
|
+
// Consent: a sensitive-topic memory stays visibly marked even after the user
|
|
83
|
+
// opted in or approved it, so the agent knows to handle it with care.
|
|
84
|
+
const sensitive = mem.sensitivity === 'sensitive' ? ', ⚠ sensitive' : '';
|
|
75
85
|
|
|
76
86
|
return age
|
|
77
|
-
? `◉ memory: "${title}" (${type}, ${age}${trust}${pending})`
|
|
78
|
-
: `◉ memory: "${title}" (${type}${trust}${pending})`;
|
|
87
|
+
? `◉ memory: "${title}" (${type}, ${age}${trust}${pending}${expired}${sensitive})`
|
|
88
|
+
: `◉ memory: "${title}" (${type}${trust}${pending}${expired}${sensitive})`;
|
|
79
89
|
}
|
|
80
90
|
|
|
81
91
|
module.exports = { receiptFor, ageLabel };
|
package/src/scorer.js
CHANGED
|
@@ -8,6 +8,12 @@
|
|
|
8
8
|
*/
|
|
9
9
|
|
|
10
10
|
const { trustFactor } = require('./provenance');
|
|
11
|
+
const {
|
|
12
|
+
EXPIRED_PENALTY,
|
|
13
|
+
parseInstant,
|
|
14
|
+
temporalState,
|
|
15
|
+
validityOf,
|
|
16
|
+
} = require('./temporal');
|
|
11
17
|
|
|
12
18
|
// Temporal invalidation: multiplier applied to a memory that a newer one has
|
|
13
19
|
// explicitly superseded. Low enough that the successor reliably outranks it,
|
|
@@ -378,6 +384,36 @@ function computeSpreadingActivationBatch(scoredMemories, associations, maxDepth
|
|
|
378
384
|
* recall of low-relevance neighbors is a feature, not noise).
|
|
379
385
|
* @returns {Object[]} Scored and sorted memories (highest first)
|
|
380
386
|
*/
|
|
387
|
+
/**
|
|
388
|
+
* Recall multiplier for a memory's temporal standing (1 = current).
|
|
389
|
+
*
|
|
390
|
+
* Default mode demotes anything a successor replaced or whose validity window
|
|
391
|
+
* has elapsed. In valid-time travel (`asOf`) the question changes: a memory
|
|
392
|
+
* still inside its window *was* current at that instant, so the supersession
|
|
393
|
+
* demotion is lifted — the fact that it was later replaced is exactly what the
|
|
394
|
+
* query is looking past.
|
|
395
|
+
*
|
|
396
|
+
* The one case that keeps its demotion under asOf is a memory superseded
|
|
397
|
+
* before validity windows existed (`superseded_by` with no `valid_until`):
|
|
398
|
+
* nothing records when it stopped being true, so assuming it was still current
|
|
399
|
+
* would be a guess. Legacy data stays conservative.
|
|
400
|
+
*
|
|
401
|
+
* @param {Object} mem - Memory or index entry
|
|
402
|
+
* @param {Object} ctx - { asOf: number|null, evaluatedAt: number }
|
|
403
|
+
* @returns {number} Multiplier in (0, 1]
|
|
404
|
+
*/
|
|
405
|
+
function temporalPenaltyFor(mem, { asOf = null, evaluatedAt = Date.now() } = {}) {
|
|
406
|
+
if (asOf != null) {
|
|
407
|
+
const supersededWithoutWindow = mem.superseded_by && validityOf(mem).until == null;
|
|
408
|
+
return supersededWithoutWindow ? SUPERSEDED_PENALTY : 1;
|
|
409
|
+
}
|
|
410
|
+
|
|
411
|
+
let penalty = 1;
|
|
412
|
+
if (mem.superseded_by) penalty = SUPERSEDED_PENALTY;
|
|
413
|
+
if (temporalState(mem, evaluatedAt) === 'expired') penalty = Math.min(penalty, EXPIRED_PENALTY);
|
|
414
|
+
return penalty;
|
|
415
|
+
}
|
|
416
|
+
|
|
381
417
|
function rankMemories(memories, relevanceFn, options = {}) {
|
|
382
418
|
// Guard every term against NaN (e.g. a missing/invalid last_accessed or
|
|
383
419
|
// strength) — a single NaN score sorts non-deterministically and can outrank
|
|
@@ -447,10 +483,35 @@ function rankMemories(memories, relevanceFn, options = {}) {
|
|
|
447
483
|
// Relevance floor: gate BEFORE final scoring so strength/salience can't
|
|
448
484
|
// carry an unrelated memory into the results (uses raw, unrounded terms).
|
|
449
485
|
const floor = options.relevanceFloor;
|
|
450
|
-
const
|
|
486
|
+
const relevanceGated = floor != null
|
|
451
487
|
? scored.filter((mem) => mem.relevance >= floor || mem.spreading_bonus >= floor)
|
|
452
488
|
: scored;
|
|
453
489
|
|
|
490
|
+
// Bitemporal gates. Both are point-in-time *filters*, not demotions: an
|
|
491
|
+
// as-of query asks what the world looked like at an instant, and a memory
|
|
492
|
+
// outside that instant is not a weaker answer — it is not an answer.
|
|
493
|
+
// asOf (valid time) — the fact was true then
|
|
494
|
+
// asKnownOf (record time) — the brain had recorded it by then
|
|
495
|
+
// Passing both reconstructs what the brain believed, and when.
|
|
496
|
+
const asOf = parseInstant(options.asOf);
|
|
497
|
+
const asKnownOf = parseInstant(options.asKnownOf);
|
|
498
|
+
let gated = relevanceGated;
|
|
499
|
+
if (asOf != null) {
|
|
500
|
+
gated = gated.filter((mem) => temporalState(mem, asOf) === 'current');
|
|
501
|
+
}
|
|
502
|
+
if (asKnownOf != null) {
|
|
503
|
+
gated = gated.filter((mem) => {
|
|
504
|
+
const recorded = parseInstant(mem.created);
|
|
505
|
+
// A memory with no parseable record time can't be proven to post-date
|
|
506
|
+
// the cutoff, so it stays — dropping it would silently lose legacy data.
|
|
507
|
+
return recorded == null || recorded <= asKnownOf;
|
|
508
|
+
});
|
|
509
|
+
}
|
|
510
|
+
|
|
511
|
+
// The instant "current" is judged against: the as-of instant in valid-time
|
|
512
|
+
// travel, otherwise now.
|
|
513
|
+
const evaluatedAt = asOf != null ? asOf : Date.now();
|
|
514
|
+
|
|
454
515
|
// Final score
|
|
455
516
|
return gated
|
|
456
517
|
.map((mem) => {
|
|
@@ -463,21 +524,25 @@ function rankMemories(memories, relevanceFn, options = {}) {
|
|
|
463
524
|
// volume, not relevance — a clearly more relevant low-trust memory can
|
|
464
525
|
// still win, but it can't win on bulk. Missing origin weighs as the
|
|
465
526
|
// memorize default, so legacy memories keep their relative order.
|
|
466
|
-
// Temporal invalidation
|
|
467
|
-
// (
|
|
468
|
-
//
|
|
469
|
-
//
|
|
470
|
-
|
|
527
|
+
// Temporal invalidation. Two signals say "no longer current": an explicit
|
|
528
|
+
// successor (`superseded_by`) and an elapsed validity window
|
|
529
|
+
// (`valid_until`). Take the strongest single penalty, never the product —
|
|
530
|
+
// a memory carrying both is one stale fact, not two. Demote, don't drop:
|
|
531
|
+
// the successor wins, but "this was true until X" stays answerable.
|
|
532
|
+
const temporalPenalty = temporalPenaltyFor(mem, { asOf, evaluatedAt });
|
|
471
533
|
|
|
472
534
|
const score = fin(computeRecallScore(
|
|
473
535
|
mem.relevance,
|
|
474
536
|
mem.decayed_strength,
|
|
475
537
|
mem.recency_bonus,
|
|
476
538
|
extras
|
|
477
|
-
)) * trustFactor(mem.origin) *
|
|
539
|
+
)) * trustFactor(mem.origin) * temporalPenalty;
|
|
478
540
|
|
|
479
541
|
return {
|
|
480
542
|
...mem,
|
|
543
|
+
// Standing at the instant this ranking was judged against, so callers
|
|
544
|
+
// can flag a stale fact without re-deriving the window.
|
|
545
|
+
temporal_state: temporalState(mem, evaluatedAt),
|
|
481
546
|
decayed_strength: Math.round(mem.decayed_strength * 1000) / 1000,
|
|
482
547
|
recency_bonus: Math.round(mem.recency_bonus * 1000) / 1000,
|
|
483
548
|
relevance: Math.round(mem.relevance * 1000) / 1000,
|
|
@@ -506,4 +571,7 @@ module.exports = {
|
|
|
506
571
|
computeContextMatch,
|
|
507
572
|
computeSpacedBoost,
|
|
508
573
|
improveDecayRate,
|
|
574
|
+
// Bitemporal validity (see src/temporal.js)
|
|
575
|
+
temporalPenaltyFor,
|
|
576
|
+
SUPERSEDED_PENALTY,
|
|
509
577
|
};
|
|
@@ -0,0 +1,134 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Brain Memory — Sensitive-topic consent (per-fragment)
|
|
3
|
+
*
|
|
4
|
+
* Three tiers, deliberately matching the vocabulary of the largest deployed
|
|
5
|
+
* consent model for assistant memory (Anthropic's, Aug 2026) so a brain is
|
|
6
|
+
* interoperable with it rather than inventing a bespoke schema:
|
|
7
|
+
*
|
|
8
|
+
* standard Stored normally. The default.
|
|
9
|
+
* sensitive Health, race, ethnicity, religious beliefs, politics, gender
|
|
10
|
+
* identity and similar. Excluded from storage unless the user has
|
|
11
|
+
* opted in (`sensitive_topics: true` in ~/.brain/config.json) —
|
|
12
|
+
* until then the write lands quarantined (`sensitive_opt_out`) and
|
|
13
|
+
* is hidden from recall and session-start. `brain verify approve`
|
|
14
|
+
* is per-item consent and lifts the exclusion for that memory.
|
|
15
|
+
* Never retroactive: opting in never rewrites what was refused.
|
|
16
|
+
* blocked Government / national ID numbers, criminal history, immigration
|
|
17
|
+
* status. Refused at write time whatever the toggle says.
|
|
18
|
+
*
|
|
19
|
+
* The agent classifies (it read the conversation); the patterns here are a
|
|
20
|
+
* backstop for the two tiers that must never depend on a caller's honesty.
|
|
21
|
+
* They are narrow on purpose: a false "blocked" refuses a write the user asked
|
|
22
|
+
* for, so only unambiguous identifiers and phrases qualify, and the sensitive
|
|
23
|
+
* backstop flags rather than blocks. Nothing here is PII detection.
|
|
24
|
+
*/
|
|
25
|
+
|
|
26
|
+
const SENSITIVITY_LEVELS = ['standard', 'sensitive', 'blocked'];
|
|
27
|
+
const DEFAULT_SENSITIVITY = 'standard';
|
|
28
|
+
const SENSITIVE_OPT_OUT_REASON = 'sensitive_opt_out';
|
|
29
|
+
|
|
30
|
+
/** Category → description, as published. Kept as data so docs and prompts can cite it. */
|
|
31
|
+
const SENSITIVE_CATEGORIES = {
|
|
32
|
+
health: 'physical or mental health, conditions, medication, treatment',
|
|
33
|
+
race: 'race',
|
|
34
|
+
ethnicity: 'ethnicity or national origin',
|
|
35
|
+
religion: 'religious or philosophical beliefs',
|
|
36
|
+
politics: 'political opinions or affiliation',
|
|
37
|
+
gender_identity: 'gender identity or sexual orientation',
|
|
38
|
+
};
|
|
39
|
+
|
|
40
|
+
const BLOCKED_CATEGORIES = {
|
|
41
|
+
government_id: 'social-security, passport, national-ID, tax or similar identification numbers',
|
|
42
|
+
criminal_history: 'criminal history, charges, convictions',
|
|
43
|
+
immigration_status: 'immigration or visa status',
|
|
44
|
+
};
|
|
45
|
+
|
|
46
|
+
// --- Backstop patterns ---
|
|
47
|
+
|
|
48
|
+
const BLOCKED_RULES = [
|
|
49
|
+
// Structured identifiers: a US SSN, or an ID-word within a few tokens of a
|
|
50
|
+
// 6-12 digit run (passport/national/tax IDs vary by country; the word makes
|
|
51
|
+
// the digits unambiguous).
|
|
52
|
+
{ category: 'government_id', re: /\b\d{3}-\d{2}-\d{4}\b/ },
|
|
53
|
+
{
|
|
54
|
+
category: 'government_id',
|
|
55
|
+
re: /\b(?:ssn|social\s+security|passport|national\s+id|tax\s+id|citizen\s+service|bsn|nino|sin)\b(?:\s+(?:number|no\.?|#))?[^\n\d]{0,20}\d(?:[\s-]?\d){5,11}\b/i,
|
|
56
|
+
},
|
|
57
|
+
{ category: 'criminal_history', re: /\b(?:criminal\s+(?:record|history|charges?)|convicted\s+of|felony\s+conviction|misdemeanou?r\s+conviction|was\s+arrested\s+for|serv(?:ed|ing)\s+(?:time|a\s+sentence))\b/i },
|
|
58
|
+
{ category: 'immigration_status', re: /\b(?:immigration\s+status|visa\s+status|undocumented\s+immigrant|asylum\s+(?:seeker|claim|status)|deportation\s+order|green\s+card\s+(?:status|application)|overstayed\s+(?:a|the|my|their)\s+visa)\b/i },
|
|
59
|
+
];
|
|
60
|
+
|
|
61
|
+
const SENSITIVE_RULES = [
|
|
62
|
+
{ category: 'health', re: /\b(?:diagnos(?:ed|is)\s+with|my\s+(?:therapist|psychiatrist|oncologist|medication|diagnosis)|(?:takes?|taking|prescribed)\s+(?:antidepressants?|insulin|chemotherapy|adhd\s+medication)|mental\s+health\s+(?:condition|history|diagnosis)|(?:has|have|had)\s+(?:cancer|diabetes|epilepsy|hiv|depression|bipolar|schizophrenia|ptsd|anorexia|bulimia))\b/i },
|
|
63
|
+
{ category: 'race', re: /\b(?:racial\s+(?:identity|background)|(?:identif(?:y|ies)\s+as|is|am)\s+(?:black|white|asian|latino|latina|latinx|hispanic|indigenous|native\s+american|mixed[- ]race))\b/i },
|
|
64
|
+
{ category: 'ethnicity', re: /\b(?:ethnic(?:ity|\s+background)|(?:is|am|are)\s+(?:of\s+)?(?:kurdish|turkish|arab|jewish|romani|han\s+chinese|tamil|uyghur|persian|armenian|pashtun)\s*(?:descent|origin|heritage)?)\b/i },
|
|
65
|
+
{ category: 'religion', re: /\b(?:religious\s+(?:beliefs?|affiliation|background)|(?:is|am|are)\s+(?:a\s+)?(?:practi[sc]ing\s+)?(?:muslim|christian|catholic|protestant|jewish|hindu|buddhist|sikh|atheist|agnostic)\b|converted\s+to\s+(?:islam|christianity|judaism|buddhism|hinduism)|attends?\s+(?:church|mosque|synagogue|temple)\s+(?:every|weekly|regularly))/i },
|
|
66
|
+
{ category: 'politics', re: /\b(?:political\s+(?:views?|affiliation|opinions?|party)|vot(?:ed|es|ing)\s+(?:for|against)\s+(?:the\s+)?[A-Z][\w-]+|(?:is|am|are)\s+(?:a\s+)?(?:registered\s+)?(?:democrat|republican|conservative|liberal|socialist|libertarian|green\s+party\s+member)|member\s+of\s+(?:the\s+)?\w+\s+party)\b/i },
|
|
67
|
+
{ category: 'gender_identity', re: /\b(?:gender\s+identity|(?:is|am|are|identif(?:y|ies)\s+as)\s+(?:transgender|trans|non-?binary|genderfluid|genderqueer|gay|lesbian|bisexual|queer|asexual|pansexual)|sexual\s+orientation|came\s+out\s+as)\b/i },
|
|
68
|
+
];
|
|
69
|
+
|
|
70
|
+
function textOf(mem) {
|
|
71
|
+
return `${(mem && mem.title) || ''}\n${(mem && mem.content) || ''}`;
|
|
72
|
+
}
|
|
73
|
+
|
|
74
|
+
/**
|
|
75
|
+
* Backstop classification of a memory's text.
|
|
76
|
+
*
|
|
77
|
+
* @param {Object} mem - { title, content }
|
|
78
|
+
* @returns {{ level: string, categories: string[] }}
|
|
79
|
+
*/
|
|
80
|
+
function classifySensitivity(mem) {
|
|
81
|
+
const text = textOf(mem);
|
|
82
|
+
const blocked = BLOCKED_RULES.filter((r) => r.re.test(text)).map((r) => r.category);
|
|
83
|
+
if (blocked.length > 0) return { level: 'blocked', categories: [...new Set(blocked)] };
|
|
84
|
+
const sensitive = SENSITIVE_RULES.filter((r) => r.re.test(text)).map((r) => r.category);
|
|
85
|
+
if (sensitive.length > 0) return { level: 'sensitive', categories: [...new Set(sensitive)] };
|
|
86
|
+
return { level: 'standard', categories: [] };
|
|
87
|
+
}
|
|
88
|
+
|
|
89
|
+
/**
|
|
90
|
+
* Resolve the final sensitivity of a write and what to do with it.
|
|
91
|
+
*
|
|
92
|
+
* The caller's label can only raise the level (an agent may not call a match
|
|
93
|
+
* for "criminal record" `standard`), and the backstop can only raise it too.
|
|
94
|
+
*
|
|
95
|
+
* @param {Object} mem - { title, content, sensitivity? }
|
|
96
|
+
* @param {Object} config - brain config (sensitive_topics)
|
|
97
|
+
* @returns {{ level, categories, action: 'store'|'quarantine'|'refuse', requested, error? }}
|
|
98
|
+
*/
|
|
99
|
+
function sensitivityDecision(mem, config) {
|
|
100
|
+
const requested = mem && mem.sensitivity != null ? String(mem.sensitivity) : null;
|
|
101
|
+
if (requested != null && !SENSITIVITY_LEVELS.includes(requested)) {
|
|
102
|
+
return { error: `Unknown sensitivity "${requested}" (expected one of: ${SENSITIVITY_LEVELS.join(', ')})` };
|
|
103
|
+
}
|
|
104
|
+
const detected = classifySensitivity(mem);
|
|
105
|
+
const rank = (l) => SENSITIVITY_LEVELS.indexOf(l);
|
|
106
|
+
const level = rank(detected.level) > rank(requested || DEFAULT_SENSITIVITY) ? detected.level : (requested || DEFAULT_SENSITIVITY);
|
|
107
|
+
|
|
108
|
+
let action = 'store';
|
|
109
|
+
if (level === 'blocked') action = 'refuse';
|
|
110
|
+
else if (level === 'sensitive' && !(config && config.sensitive_topics === true)) action = 'quarantine';
|
|
111
|
+
|
|
112
|
+
return { level, categories: detected.categories, action, requested };
|
|
113
|
+
}
|
|
114
|
+
|
|
115
|
+
/**
|
|
116
|
+
* Read-side gate: a sensitive memory is hidden from recall and session-start
|
|
117
|
+
* unless the user opted in globally or approved this one (`vetted`).
|
|
118
|
+
*/
|
|
119
|
+
function isSensitiveHidden(entry, config) {
|
|
120
|
+
if (!entry || entry.sensitivity !== 'sensitive') return false;
|
|
121
|
+
if (config && config.sensitive_topics === true) return false;
|
|
122
|
+
return !entry.vetted;
|
|
123
|
+
}
|
|
124
|
+
|
|
125
|
+
module.exports = {
|
|
126
|
+
SENSITIVITY_LEVELS,
|
|
127
|
+
DEFAULT_SENSITIVITY,
|
|
128
|
+
SENSITIVE_OPT_OUT_REASON,
|
|
129
|
+
SENSITIVE_CATEGORIES,
|
|
130
|
+
BLOCKED_CATEGORIES,
|
|
131
|
+
classifySensitivity,
|
|
132
|
+
sensitivityDecision,
|
|
133
|
+
isSensitiveHidden,
|
|
134
|
+
};
|
|
@@ -0,0 +1,191 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Brain Memory — Skill Verification (Skill-DisCo, arXiv:2606.26669)
|
|
3
|
+
*
|
|
4
|
+
* A crystallized skill is a claim: "this is how this repo does migrations."
|
|
5
|
+
* Today that claim is only ever tested by *using* it — `brain skill use
|
|
6
|
+
* --failed` demotes one that misfires, so a bad skill decays out of the L0
|
|
7
|
+
* index eventually. Eventually is the problem: the skill is advertised to
|
|
8
|
+
* every session until enough failures accumulate, and the first few failures
|
|
9
|
+
* are paid by the user.
|
|
10
|
+
*
|
|
11
|
+
* The Skill-DisCo result is that procedural memory should compile to something
|
|
12
|
+
* **checkable offline** — verifiable without running the agent. This module is
|
|
13
|
+
* that check: a skill may declare preconditions, and `brain skill verify`
|
|
14
|
+
* answers whether they still hold in the current working directory.
|
|
15
|
+
*
|
|
16
|
+
* The value is drift detection. A skill distilled six months ago against a repo
|
|
17
|
+
* whose `migrations/` folder has since been renamed is not weakly-supported —
|
|
18
|
+
* it is *wrong*, and it will confidently misdirect the next session that
|
|
19
|
+
* matches its triggers. A precondition check catches that in milliseconds.
|
|
20
|
+
*
|
|
21
|
+
* ── Why declarative checks and not a shell command ───────────────────────
|
|
22
|
+
* The obvious design is `verify: npm run migrate:check`. It is also a loaded
|
|
23
|
+
* gun pointed at the rest of this codebase.
|
|
24
|
+
*
|
|
25
|
+
* Skills are crystallized automatically from experience (sleep Phase 4b), they
|
|
26
|
+
* sync between machines, and they can be imported from other people. A `verify`
|
|
27
|
+
* field holding arbitrary shell would mean a memory file that executes code —
|
|
28
|
+
* turning every one of Brain's poisoning defenses into theatre, because the
|
|
29
|
+
* payload would no longer need to persuade the agent of anything. It would just
|
|
30
|
+
* need to be run. `curl … | bash` in a synced skill is precisely the OWASP
|
|
31
|
+
* ASI06 scenario with the hard part removed.
|
|
32
|
+
*
|
|
33
|
+
* So checks are DECLARATIVE and READ-ONLY. Every check type below inspects
|
|
34
|
+
* state; none of them execute anything, and there is deliberately no escape
|
|
35
|
+
* hatch. A skill can ask "does `migrations/` exist?" It cannot ask the machine
|
|
36
|
+
* to run something and trust the exit code.
|
|
37
|
+
*
|
|
38
|
+
* ── Check types ──────────────────────────────────────────────────────────
|
|
39
|
+
* { file_exists: "migrations/" }
|
|
40
|
+
* { file_absent: "config/legacy.yml" }
|
|
41
|
+
* { file_contains: { path: "package.json", text: "\"migrate\"" } }
|
|
42
|
+
* { command_available: "psql" } — PATH lookup only, never executed
|
|
43
|
+
* { env_set: "DATABASE_URL" } — presence only, value never read
|
|
44
|
+
*/
|
|
45
|
+
|
|
46
|
+
const fs = require('fs');
|
|
47
|
+
const path = require('path');
|
|
48
|
+
|
|
49
|
+
// A contains-check reads a file into memory; cap it so a skill pointed at a
|
|
50
|
+
// multi-gigabyte artifact degrades to a failed check instead of an OOM.
|
|
51
|
+
const MAX_CONTAINS_BYTES = 2 * 1024 * 1024;
|
|
52
|
+
|
|
53
|
+
const CHECK_TYPES = ['file_exists', 'file_absent', 'file_contains', 'command_available', 'env_set'];
|
|
54
|
+
|
|
55
|
+
/**
|
|
56
|
+
* Resolve a skill-declared path inside the working directory.
|
|
57
|
+
*
|
|
58
|
+
* Skills sync between machines and can be imported from other people, so a
|
|
59
|
+
* declared path is untrusted input. Anything that escapes the working
|
|
60
|
+
* directory — `../`, an absolute path, a symlink pointing out — resolves to
|
|
61
|
+
* null and fails the check, so a skill can never be used to probe for files
|
|
62
|
+
* elsewhere on the disk.
|
|
63
|
+
*
|
|
64
|
+
* @param {string} cwd - Directory the checks run against
|
|
65
|
+
* @param {string} rel - Skill-declared path
|
|
66
|
+
* @returns {string|null} Absolute path, or null when it escapes `cwd`
|
|
67
|
+
*/
|
|
68
|
+
function resolveInside(cwd, rel) {
|
|
69
|
+
if (typeof rel !== 'string' || rel.length === 0) return null;
|
|
70
|
+
if (path.isAbsolute(rel)) return null;
|
|
71
|
+
const base = fs.realpathSync.native ? path.resolve(cwd) : path.resolve(cwd);
|
|
72
|
+
const target = path.resolve(base, rel);
|
|
73
|
+
const withSep = base.endsWith(path.sep) ? base : base + path.sep;
|
|
74
|
+
if (target !== base && !target.startsWith(withSep)) return null;
|
|
75
|
+
return target;
|
|
76
|
+
}
|
|
77
|
+
|
|
78
|
+
/** Is `name` an executable on PATH? Resolves only — never runs it. */
|
|
79
|
+
function onPath(name) {
|
|
80
|
+
if (typeof name !== 'string' || !/^[A-Za-z0-9._-]+$/.test(name)) return false;
|
|
81
|
+
const dirs = (process.env.PATH || '').split(path.delimiter).filter(Boolean);
|
|
82
|
+
// Windows resolves commands through PATHEXT (`node` on PATH is node.exe);
|
|
83
|
+
// POSIX has no equivalent, so the bare name is the only candidate there.
|
|
84
|
+
const exts = process.platform === 'win32'
|
|
85
|
+
? ['', ...(process.env.PATHEXT || '.COM;.EXE;.BAT;.CMD').split(';').filter(Boolean)]
|
|
86
|
+
: [''];
|
|
87
|
+
for (const dir of dirs) {
|
|
88
|
+
for (const ext of exts) {
|
|
89
|
+
try {
|
|
90
|
+
fs.accessSync(path.join(dir, name + ext), fs.constants.X_OK);
|
|
91
|
+
return true;
|
|
92
|
+
} catch { /* keep looking */ }
|
|
93
|
+
}
|
|
94
|
+
}
|
|
95
|
+
return false;
|
|
96
|
+
}
|
|
97
|
+
|
|
98
|
+
/**
|
|
99
|
+
* Evaluate one declarative check.
|
|
100
|
+
*
|
|
101
|
+
* @param {Object} check - Single-key object, e.g. { file_exists: "migrations/" }
|
|
102
|
+
* @param {string} cwd
|
|
103
|
+
* @returns {{ check: string, target: string, ok: boolean, detail?: string }}
|
|
104
|
+
*/
|
|
105
|
+
function runCheck(check, cwd) {
|
|
106
|
+
if (!check || typeof check !== 'object') {
|
|
107
|
+
return { check: 'malformed', target: '', ok: false, detail: 'check is not an object' };
|
|
108
|
+
}
|
|
109
|
+
const kind = Object.keys(check).find((k) => CHECK_TYPES.includes(k));
|
|
110
|
+
if (!kind) {
|
|
111
|
+
return {
|
|
112
|
+
check: 'unknown',
|
|
113
|
+
target: String(Object.keys(check)[0] || ''),
|
|
114
|
+
ok: false,
|
|
115
|
+
detail: `unsupported check; expected one of ${CHECK_TYPES.join(', ')}`,
|
|
116
|
+
};
|
|
117
|
+
}
|
|
118
|
+
|
|
119
|
+
const value = check[kind];
|
|
120
|
+
|
|
121
|
+
if (kind === 'env_set') {
|
|
122
|
+
const ok = typeof value === 'string' && Boolean(process.env[value]);
|
|
123
|
+
// Presence only. The value is never read, so a check can't exfiltrate a
|
|
124
|
+
// secret into a result payload that later gets synced.
|
|
125
|
+
return { check: kind, target: String(value), ok };
|
|
126
|
+
}
|
|
127
|
+
|
|
128
|
+
if (kind === 'command_available') {
|
|
129
|
+
return { check: kind, target: String(value), ok: onPath(value) };
|
|
130
|
+
}
|
|
131
|
+
|
|
132
|
+
if (kind === 'file_exists' || kind === 'file_absent') {
|
|
133
|
+
const abs = resolveInside(cwd, value);
|
|
134
|
+
if (abs === null) {
|
|
135
|
+
return { check: kind, target: String(value), ok: false, detail: 'path escapes the working directory' };
|
|
136
|
+
}
|
|
137
|
+
const exists = fs.existsSync(abs);
|
|
138
|
+
return { check: kind, target: String(value), ok: kind === 'file_exists' ? exists : !exists };
|
|
139
|
+
}
|
|
140
|
+
|
|
141
|
+
// file_contains
|
|
142
|
+
const spec = value && typeof value === 'object' ? value : {};
|
|
143
|
+
const abs = resolveInside(cwd, spec.path);
|
|
144
|
+
if (abs === null) {
|
|
145
|
+
return { check: kind, target: String(spec.path || ''), ok: false, detail: 'path escapes the working directory' };
|
|
146
|
+
}
|
|
147
|
+
if (typeof spec.text !== 'string' || spec.text.length === 0) {
|
|
148
|
+
return { check: kind, target: String(spec.path || ''), ok: false, detail: 'missing `text`' };
|
|
149
|
+
}
|
|
150
|
+
try {
|
|
151
|
+
const stat = fs.statSync(abs);
|
|
152
|
+
if (stat.size > MAX_CONTAINS_BYTES) {
|
|
153
|
+
return { check: kind, target: spec.path, ok: false, detail: 'file too large to scan' };
|
|
154
|
+
}
|
|
155
|
+
return { check: kind, target: spec.path, ok: fs.readFileSync(abs, 'utf-8').includes(spec.text) };
|
|
156
|
+
} catch {
|
|
157
|
+
return { check: kind, target: String(spec.path || ''), ok: false, detail: 'unreadable' };
|
|
158
|
+
}
|
|
159
|
+
}
|
|
160
|
+
|
|
161
|
+
/**
|
|
162
|
+
* Run every check a skill declares.
|
|
163
|
+
*
|
|
164
|
+
* A skill with no `verify` block is `unverifiable` — not passing and not
|
|
165
|
+
* failing. Most skills are prose and always will be; treating an absent block
|
|
166
|
+
* as failure would demote the whole library on the first verification sweep.
|
|
167
|
+
*
|
|
168
|
+
* @param {Object} skill - Skill record (needs `verify` array)
|
|
169
|
+
* @param {Object} [opts]
|
|
170
|
+
* @param {string} [opts.cwd=process.cwd()]
|
|
171
|
+
* @returns {{ status: 'passed'|'failed'|'unverifiable', checks: Object[], passed: number, total: number }}
|
|
172
|
+
*/
|
|
173
|
+
function verifySkill(skill, opts = {}) {
|
|
174
|
+
const cwd = opts.cwd || process.cwd();
|
|
175
|
+
const declared = (skill && skill.verify) || null;
|
|
176
|
+
|
|
177
|
+
if (!Array.isArray(declared) || declared.length === 0) {
|
|
178
|
+
return { status: 'unverifiable', checks: [], passed: 0, total: 0 };
|
|
179
|
+
}
|
|
180
|
+
|
|
181
|
+
const checks = declared.map((c) => runCheck(c, cwd));
|
|
182
|
+
const passed = checks.filter((c) => c.ok).length;
|
|
183
|
+
return {
|
|
184
|
+
status: passed === checks.length ? 'passed' : 'failed',
|
|
185
|
+
checks,
|
|
186
|
+
passed,
|
|
187
|
+
total: checks.length,
|
|
188
|
+
};
|
|
189
|
+
}
|
|
190
|
+
|
|
191
|
+
module.exports = { verifySkill, runCheck, resolveInside, onPath, CHECK_TYPES, MAX_CONTAINS_BYTES };
|
package/src/skills.js
CHANGED
|
@@ -22,6 +22,7 @@ const {
|
|
|
22
22
|
atomicWriteSync,
|
|
23
23
|
} = require('./index-manager');
|
|
24
24
|
const { setFrontmatterFields } = require('./pinning');
|
|
25
|
+
const { verifySkill } = require('./skill-verify');
|
|
25
26
|
|
|
26
27
|
const SKILLS_DIR = '_skills';
|
|
27
28
|
const DEFAULT_STRENGTH = 0.6;
|
|
@@ -83,6 +84,10 @@ function addSkill(projectRoot, skill) {
|
|
|
83
84
|
use_count: 0,
|
|
84
85
|
fail_count: 0,
|
|
85
86
|
last_used: null,
|
|
87
|
+
// Declarative, read-only preconditions (src/skill-verify.js). Only set when
|
|
88
|
+
// present, so prose-only skills stay lean and are reported `unverifiable`
|
|
89
|
+
// rather than failing a check they never claimed to support.
|
|
90
|
+
...(Array.isArray(skill.verify) && skill.verify.length ? { verify: skill.verify } : {}),
|
|
86
91
|
};
|
|
87
92
|
atomicWriteSync(path.join(dir, 'SKILL.md'), buildSkillFile({ ...record, body: skill.body }));
|
|
88
93
|
|
|
@@ -116,6 +121,63 @@ function showSkill(projectRoot, name) {
|
|
|
116
121
|
}
|
|
117
122
|
}
|
|
118
123
|
|
|
124
|
+
/**
|
|
125
|
+
* Check a skill's declared preconditions against the current working directory.
|
|
126
|
+
*
|
|
127
|
+
* Answers "does this skill still describe reality?" without running the agent
|
|
128
|
+
* — the offline-checkable half of procedural memory (Skill-DisCo,
|
|
129
|
+
* arXiv:2606.26669). A skill distilled against a repo layout that has since
|
|
130
|
+
* changed is not weakly-supported, it is wrong, and it will keep being
|
|
131
|
+
* advertised to every matching session until enough real failures accumulate.
|
|
132
|
+
*
|
|
133
|
+
* A failed verification demotes exactly like a failed use, because the user
|
|
134
|
+
* pays the same price either way. A *passing* verification does NOT strengthen:
|
|
135
|
+
* preconditions holding says the skill is still applicable, not that following
|
|
136
|
+
* it produced a good outcome, and inflating strength on a cheap automatic check
|
|
137
|
+
* would let a skill climb the index without ever having worked.
|
|
138
|
+
*
|
|
139
|
+
* Skills with no `verify` block return `unverifiable` and are left untouched.
|
|
140
|
+
*
|
|
141
|
+
* @param {string} projectRoot
|
|
142
|
+
* @param {string} name
|
|
143
|
+
* @param {Object} [opts] - { cwd }
|
|
144
|
+
* @returns {Object} { name, status, passed, total, checks, strength? }
|
|
145
|
+
*/
|
|
146
|
+
function verifySkillByName(projectRoot, name, opts = {}) {
|
|
147
|
+
const idx = readSkillsIndex(projectRoot);
|
|
148
|
+
const s = idx.skills.find((x) => x.name === slug(name));
|
|
149
|
+
if (!s) return { error: `Skill not found: ${name}` };
|
|
150
|
+
|
|
151
|
+
const result = verifySkill(s, { cwd: opts.cwd || process.cwd() });
|
|
152
|
+
if (result.status === 'unverifiable') {
|
|
153
|
+
return { name: s.name, ...result };
|
|
154
|
+
}
|
|
155
|
+
|
|
156
|
+
const now = new Date().toISOString();
|
|
157
|
+
s.last_verified = now;
|
|
158
|
+
s.verify_status = result.status;
|
|
159
|
+
if (result.status === 'failed') {
|
|
160
|
+
s.fail_count = (s.fail_count || 0) + 1;
|
|
161
|
+
s.strength = Math.max(0, (s.strength ?? DEFAULT_STRENGTH) - 0.10);
|
|
162
|
+
}
|
|
163
|
+
writeSkillsIndex(idx, projectRoot);
|
|
164
|
+
|
|
165
|
+
setFrontmatterFields(getBrainDir(projectRoot), skillPath(name), {
|
|
166
|
+
last_verified: now,
|
|
167
|
+
verify_status: result.status,
|
|
168
|
+
...(result.status === 'failed'
|
|
169
|
+
? { strength: Math.round(s.strength * 1000) / 1000, fail_count: s.fail_count }
|
|
170
|
+
: {}),
|
|
171
|
+
});
|
|
172
|
+
|
|
173
|
+
return {
|
|
174
|
+
name: s.name,
|
|
175
|
+
...result,
|
|
176
|
+
strength: Math.round((s.strength ?? DEFAULT_STRENGTH) * 1000) / 1000,
|
|
177
|
+
advertised: isAdvertised(s),
|
|
178
|
+
};
|
|
179
|
+
}
|
|
180
|
+
|
|
119
181
|
/**
|
|
120
182
|
* Record a use. Success strengthens; failure weakens and counts toward demotion.
|
|
121
183
|
* @param {Object} [opts] - { failed: boolean }
|
|
@@ -202,6 +264,7 @@ module.exports = {
|
|
|
202
264
|
advertisedSummaries,
|
|
203
265
|
showSkill,
|
|
204
266
|
useSkill,
|
|
267
|
+
verifySkillByName,
|
|
205
268
|
removeSkill,
|
|
206
269
|
exportSkill,
|
|
207
270
|
DEMOTE_FAIL_RATIO,
|