brain-memory 0.2.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.
@@ -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,