sawbuck 0.1.13 → 0.1.20

package/CONTRACT.md

@@ -2,12 +2,18 @@
 
 *Put your coding agent under contract: a win counts only if it survives verification from the source alone, not because the agent said so. The terms below are not a promise the agent makes, they are a result anyone can re-prove.*
 
-**Status:** Draft v0.1 · **License:** MIT · **Reference implementation:** [Sawbuck](https://github.com/sawbuck-ai/sawbuck) (the saddle), [promptwheel](https://github.com/promptwheel-ai/promptwheel) (the check), [@promptwheel/logbook](https://github.com/promptwheel-ai/logbook) (the context record)
+**Status:** Draft v0.1 · **License:** MIT · **Reference implementation:** [Sawbuck](https://github.com/sawbuck-ai/sawbuck) (the saddle), [promptwheel](https://github.com/promptwheel-ai/promptwheel) (the check), [@promptwheel/logbook](https://github.com/promptwheel-ai/logbook) (the default memory provider)
 
 This is an open interface for making an AI coding harness trustworthy. It defines how a loop's wins get verified, what a verdict looks like, what counts as gaming the goalposts, and how a repo's history is carried along. Any harness can emit or consume it without using this code. Sawbuck is a reference saddle that implements it; it is not the only possible one.
 
 The contract has one property that holds all of it together: a verdict is **deterministic and reproducible from `(base, head, config)` alone**. No LLM is in the path, and nothing is read from the agent's trajectory, so the result cannot be obfuscated against and does not change when you ask it twice.
 
+A corollary worth stating as an invariant: **the gate is defined only by in-repo, versioned config.** External systems (a dashboard, an issue tracker, a memory provider) may *report on* a verdict, but they must never *define* the guardrail. A guardrail that lives outside the repo is one the check cannot see in the diff, so it cannot be fingerprinted, so loosening it leaves no trace to catch as gamed. Memory (the input) is a pluggable socket; the gate (the output) stays in-repo and fingerprinted.
+
+> This contract covers the check. Sawbuck pairs it with the other half, **memory** (the relevant history for what you touch, plus the live debt), as the mirror idea: where the check is a standard others *conform to*, memory is a socket others *fill*. The default memory provider is @promptwheel/logbook, carried along so it works out of the box, but it is swappable; logbook is a default, not a requirement of the idea.
+>
+> Both halves nest with your folders, so policy and memory flow top-down and isolate across siblings. A parent `promptwheel.config.json` passes its guardrails down via `extends` (repos inherit the base gate; local metrics override by name), and memory inherits a parent folder's shared scope the same way (a repo sees itself and its ancestors, never a sibling). One model for both: the directory tree is the scope.
+
 ---
 
 ## 1. The reward contract (exit codes)

package/GLOSSARY.md

@@ -1,9 +1,10 @@
 # Sawbuck: Glossary & Controlled Vocabulary
 
 Sawbuck is a saddle: an isolated layer you attach to a repo that fits its shape
-and responds when the repo moves. It reads the history (via Logbook) and a small
-config of what to measure, runs the check when a change lands, and surfaces the
-relevant past finding before the agent repeats a known mistake.
+and responds when the repo moves. It reads the history (via its memory provider,
+logbook by default) and a small config of what to measure, runs the check when a
+change lands, and surfaces the relevant past finding before the agent repeats a
+known mistake.
 
 ## The rule: one plain surface
 
@@ -23,7 +24,7 @@ two vocabularies.
 | concept | term | notes |
 |---|---|---|
 | the product | **Sawbuck** | the only brand word |
-| the history reader | **Logbook** | a lab logbook: plain and scientific |
+| the memory (the role) | **memory**; default provider **Logbook** | the relevant history + live debt for what you touch. logbook (a lab logbook: plain, scientific) is a standalone product and the default fill; the role is a socket, swap your own via the Memory Contract |
 | the verifier | **the check** (verb: *verify*) | runs the metrics on a change |
 | a change that improved and holds | **verified** | |
 | a change that made a guarded metric worse | **regression** | do-not-retry |
@@ -36,6 +37,23 @@ two vocabularies.
 | code still silenced in HEAD now | **debt** (suppression debt) | disabled/weakened tests + lint/type suppressions still live; `sawbuck debt` ranks it by severity and file fragility |
 | the one-view accumulation | **inventory** | `sawbuck status`: what it has caught over time + the debt accruing now + whether it is armed here |
 
+## The two interfaces (a socket and a standard)
+
+Sawbuck composes two roles, and they are open in opposite directions. Keeping them
+straight is what stops "Sawbuck, then logbook?" confusion: logbook is not a second
+brand bolted on, it is the default fill for one of the two roles.
+
+- **the check** is a *standard we publish* (the Verified-Outcome Contract, see
+  CONTRACT.md): other tools conform to it, or embed it. promptwheel is the reference
+  implementation. It is not swappable, because the un-gameable source re-proof is the
+  asset; what you plug in is *what to measure*.
+- **the memory** is a *socket we expose*: you fill it with any provider. logbook is
+  the default, carried along so it works out of the box, and it is its own product you
+  can also run on its own.
+
+In one line: the check is a standard for others to meet; the memory is a socket for
+others to fill.
+
 ## The one humility rule
 
 Findings are **leads, not conclusions**, verify against the diff before acting.

package/README.md

@@ -45,6 +45,7 @@ sawbuck: gamed recorded on test.js       (the win came from editing the test, no
 | `sawbuck context` · `sawbuck rank` | the ranked relevant history for the current change |
 | `sawbuck debt` | the whole-repo live suppression debt: what is still silenced in HEAD now, disabled tests first, heaviest files ranked |
 | `sawbuck status` · `sawbuck log` | the inventory (caught over time + debt now + armed state), in one view; and the recent per-check feed |
+| `sawbuck recall` | related notes for your current change from extra memory providers you compose in (bring your own) |
 | `sawbuck run --attempt '<agent cmd>'` | thin harness: load context, run one attempt through the keep-if-verified gate |
 | `sawbuck trace` · `sawbuck doctor` · `detach --verify` | show the footprint; check the attachment resolves; prove a clean removal |
 
@@ -73,9 +74,11 @@ Debt also rises on its own: once attached, the per-turn `context` hook surfaces
 
 ## The engines
 
-Sawbuck is thin glue over two tools it depends on:
+Sawbuck is thin glue over two roles, each behind an open interface that points in opposite directions:
 
-- **promptwheel** : the check (the deterministic outcome gate).
-- **@promptwheel/logbook** : the memory (git history as agent memory; also ships an MCP server for on-demand lookups).
+- **the check** : the deterministic outcome gate, a published standard (the [Verified-Outcome Contract](CONTRACT.md)) that others conform to. Reference implementation: **promptwheel**. You plug in *what* to measure (your tests, lint, coverage, an eval); the un-gameable source re-proof is the fixed part. Embed it with `import { check }`, or check any tool's verdict with `promptwheel conformance`.
+- **the memory** : the relevant history for the files you touch, plus the live debt. A socket you can fill. Default provider: **@promptwheel/logbook** (git history as agent memory; also ships an MCP server). Sawbuck reads it through one adapter, so you can *compose in your own* memory: `SAWBUCK_MEMORY=logbook,obsidian` keeps logbook as the git-truth + debt provider and adds your notes, then `sawbuck recall`. Four reference providers ship in `providers/`: **obsidian** (local notes vault; set `OBSIDIAN_VAULT`), **local** (a plain JSON file, zero setup), **claude** (read-only: your project's `CLAUDE.md` / `.claude` memory, already there, nothing to configure), and **mem0** (semantic memory; the one that reaches the network, so it needs a `MEM0_API_KEY` or a `~/.mem0` key file, unlike the offline default; verified against Mem0's v3 API). Any bin that speaks the three contract verbs works; `sawbuck memory-conformance <bin>` checks one. Composed providers are **folder-scoped and isolated by default**: each repo sees only its own memory, never a sibling's. Drop a `.sawbuck-root` marker (or set `SAWBUCK_MEMORY_ROOT`) in a parent folder to let repos under it inherit that folder's shared memory, top down. logbook is the default, not a hard requirement of the idea.
+
+In one line: the check is a standard we publish for others to meet; the memory is a socket we expose for others to fill. Sawbuck composes the two.
 
 MIT.

package/debt.mjs

@@ -7,20 +7,8 @@
 // complete lens for CURRENT debt; the historical diff scan under-counts it.
 // Zero-dep. Usage: node debt.mjs [--repo P] [--top N] [--since REF] [--json]
 
-import { execFileSync } from 'node:child_process';
-import { createRequire } from 'node:module';
-import { basename, join, dirname, resolve } from 'node:path';
-import { fileURLToPath, pathToFileURL } from 'node:url';
-
-const HERE = dirname(fileURLToPath(import.meta.url));
-const require = createRequire(import.meta.url);
-const engineBin = (envVar, pkgSubpath, devPath) => {
-  if (process.env[envVar]) return process.env[envVar];
-  const bare = pkgSubpath.replace(/\/bin\/[^/]*$/, '');
-  for (const spec of [pkgSubpath, bare]) { try { return require.resolve(spec); } catch {} }
-  return devPath;
-};
-const LB = engineBin('LB_BIN', '@promptwheel/logbook/bin/logbook.mjs', join(HERE, '..', 'logbook', 'bin', 'logbook.mjs'));
+import { basename, resolve } from 'node:path';
+import { events as memEvents, debt as memDebt } from './memory.mjs';
 
 const flag = (n, d) => { const i = process.argv.indexOf(n); return i > -1 ? (process.argv[i + 1] ?? true) : d; };
 const repo = resolve(flag('--repo', process.cwd()));
@@ -30,46 +18,24 @@ const failRaw = flag('--fail-on', null); // undocumented | test | any | <N>; bar
 const failMode = failRaw === true ? 'undocumented' : (failRaw ? String(failRaw).toLowerCase() : null);
 const asJson = process.argv.includes('--json');
 
-// A disabled/skipped/weakened TEST is a hidden-failure risk; a lint/type/error suppression is
-// usually mundane. Same split sawbuck's rank uses, so the two faces agree.
-const isTestSkip = (m) => /\bit\.skip\b|\btest\.skip\b|xit\(|xdescribe\(|\bdescribe\.skip\b|pytest\.mark\.skip|unittest\.skip|\bt\.Skip\b|@Disabled\b|@Ignore\b|^\[Ignore\b|^Skip\s*=|^#\[ignore|markTestSkipped|markTestIncomplete/.test(String(m).trim());
-// DOCUMENTED = a rule code or reason follows the directive (declared intent); BARE = just the
-// directive. Heuristic, a lead not a verdict, but bare is the suspect kind worth scrutinizing.
-const isDocumented = (c) => {
-  c = String(c || '');
-  if (/eslint-disable/.test(c)) return /eslint-disable(?:-next-line|-line)?\s+\S/.test(c); // a rule name follows
-  if (/@ts-ignore/.test(c)) return false;                                                  // inherently undocumented
-  if (/@ts-expect-error/.test(c)) return /@ts-expect-error\s+\S/.test(c);
-  if (/noqa/i.test(c)) return /noqa:\s*\w/i.test(c);                                        // # noqa: E501
-  if (/type:\s*ignore/i.test(c)) return /ignore\s*\[/.test(c);                              // # type: ignore[code]
-  return /\(\s*["']/.test(c) || /=\s*["']/.test(c);   // annotation reason/code: @Disabled("..."), Skip="...", #[ignore = "..."]
-};
-
-// events give fragility + fall-back dates. Best-effort.
-let events = [];
-try { events = execFileSync(process.execPath, [LB, 'query', '--json'], { cwd: repo, encoding: 'utf8', maxBuffer: 256 * 1024 * 1024 }).split('\n').filter(Boolean).map((l) => { try { return JSON.parse(l); } catch { return null; } }).filter(Boolean); } catch {}
-
-let auditHead, SUPPRESS_PAT;
-try { ({ auditHead, SUPPRESS_PAT } = await import(pathToFileURL(LB).href)); } catch (e) { console.error(`sawbuck debt: cannot load logbook (${String(e.message).split('\n')[0]})`); process.exit(1); }
-
-let live;
-try { live = auditHead(repo, events); } catch (e) { console.error(`sawbuck debt: could not read the suppression ledger (${String(e.message).split('\n')[0]})`); process.exit(1); }
+// events give fragility + fall-back dates (the memory provider's recall facts). Best-effort.
+const events = memEvents(repo);
 
-// enrich each gated live suppression with its line content, so we can tell BARE from DOCUMENTED.
-// One extra HEAD grep; we only read content for lines auditHead already gated, so no gating drift.
-const grepAt = (ref) => { try { return execFileSync('git', ['-C', repo, 'grep', '-nP', SUPPRESS_PAT.source, ref], { encoding: 'utf8', maxBuffer: 512 * 1024 * 1024 }); } catch (e) { return (e.stdout || '').toString(); } };
-const parseGrep = (g, ref) => { const re = new RegExp('^' + ref.replace(/[.*+?^${}()|[\]\\]/g, '\\$&') + ':(.+?):(\\d+):(.*)$'); const m = []; for (const row of g.split('\n')) { const x = re.exec(row); if (x) m.push({ file: x[1], line: +x[2], content: x[3] }); } return m; };
-const headRows = SUPPRESS_PAT ? parseGrep(grepAt('HEAD'), 'HEAD') : [];
-const contentAt = new Map(headRows.map((r) => [r.file + ':' + r.line, r.content]));
-for (const it of live) { it.content = contentAt.get(it.file + ':' + it.line) || ''; it.documented = it.content ? isDocumented(it.content) : false; }
+// the live suppression ledger via the memory adapter (the Memory Contract's `debt` capability). Each
+// item arrives classified (documented/testSkip) and with its line content and blame date (`since`),
+// so this file no longer imports the provider's pattern or gating. null = the provider FAILED
+// (unmeasurable is NOT clean, refuse and exit nonzero); [] = a genuinely clean tree.
+const live = memDebt(repo);
+if (live === null) { console.error('sawbuck debt: could not read the suppression ledger (the memory provider failed)'); process.exit(1); }
 const bare = live.filter((it) => !it.documented && it.content).length;
 
 // --since REF: the DELTA. Suppressions in HEAD but not at REF = debt this branch/PR adds.
 if (since && typeof since === 'string') {
   const norm = (s) => String(s).trim().replace(/\s+/g, ' ');
-  const base = new Set(parseGrep(grepAt(since), since).map((r) => r.file + '\u0000' + norm(r.content)));
+  // the delta base: the raw suppression set at REF (the adapter's ref mode), subtracted from HEAD.
+  const base = new Set((memDebt(repo, { ref: since }) || []).map((r) => r.file + '\u0000' + norm(r.content)));
   const added = live.filter((it) => it.content && !base.has(it.file + '\u0000' + norm(it.content)));
-  const skips = added.filter((it) => isTestSkip(it.kind)).length, undoc = added.filter((it) => !it.documented).length;
+  const skips = added.filter((it) => it.testSkip).length, undoc = added.filter((it) => !it.documented).length;
   // the gate: fail (exit 1) when the branch adds the kind of debt --fail-on names.
   const fail = !failMode ? false
     : /^\d+$/.test(failMode) ? added.length >= +failMode
@@ -79,7 +45,7 @@ if (since && typeof since === 'string') {
   if (asJson) { console.log(JSON.stringify({ since, added: added.length, testSkips: skips, undocumented: undoc, failOn: failMode, fail, items: added.map((it) => ({ file: it.file, line: it.line, kind: String(it.kind).trim(), documented: it.documented })) }, null, 2)); process.exit(fail ? 1 : 0); }
   if (!added.length) { console.log(`🐴 sawbuck: no new suppression debt since ${since} (clean).`); process.exit(0); }
   const o = [`🐴 sawbuck: ${added.length} new suppression${added.length === 1 ? '' : 's'} since ${since}  ·  ${skips} disabled test${skips === 1 ? '' : 's'}  ·  ${undoc} undocumented (no code/reason)`];
-  for (const it of added.slice(0, Math.max(top, 20))) o.push(`     ${isTestSkip(it.kind) ? '🔴' : (it.documented ? '  ' : '✎ ')} ${it.file}:${it.line}  ${String(it.kind).trim()}${it.documented ? '' : '   (bare - no code/reason)'}`);
+  for (const it of added.slice(0, Math.max(top, 20))) o.push(`     ${it.testSkip ? '🔴' : (it.documented ? '  ' : '✎ ')} ${it.file}:${it.line}  ${String(it.kind).trim()}${it.documented ? '' : '   (bare - no code/reason)'}`);
   o.push(`\n   ✎ = bare/undocumented (the suspect kind); declare intent (a rule code or reason) or remove it.`);
   if (failMode) o.push(fail ? `\n   ❌ debt gate FAILED (--fail-on ${failMode}): this branch adds debt that must be declared or removed.` : `\n   ✓ debt gate passed (--fail-on ${failMode}).`);
   console.log(o.join('\n'));
@@ -118,11 +84,11 @@ const fragilityOf = (file) => {
 const byFile = new Map();
 let testSkips = 0, codeSup = 0;
 for (const it of live) {
-  const t = isTestSkip(it.kind); t ? testSkips++ : codeSup++;
+  const t = it.testSkip; t ? testSkips++ : codeSup++;
   const f = byFile.get(it.file) || { file: it.file, skips: 0, bareSup: 0, docSup: 0, kinds: new Set(), oldest: null };
   if (t) f.skips++; else (it.documented ? f.docSup++ : f.bareSup++);
   f.kinds.add(String(it.kind).trim());
-  if (it.date && (!f.oldest || it.date < f.oldest)) f.oldest = it.date;
+  if (it.since && (!f.oldest || it.since < f.oldest)) f.oldest = it.since;
   byFile.set(it.file, f);
 }
 // RISK = severity (disabled test 3, bare suppression 1.5, documented 1) x file fragility.
@@ -149,10 +115,10 @@ for (const f of files.slice(0, top)) {
   const frag = [f.reverts ? `${f.reverts} revert${f.reverts === 1 ? '' : 's'}` : '', f.hot ? 'fix-hotspot' : '', (!f.hot && f.fixes >= 3) ? `${f.fixes} fixes` : ''].filter(Boolean).join(', ');
   out.push(`     ${f.reverts || f.hot ? '🔥 ' : '   '}${f.file}  ·  ${f.n} (${bits})${frag ? `  · ${frag}` : ''}  ·  risk ${f.risk}`);
 }
-const dated = live.filter((it) => it.date).sort((a, b) => String(a.date).localeCompare(String(b.date)));
+const dated = live.filter((it) => it.since).sort((a, b) => String(a.since).localeCompare(String(b.since)));
 if (dated.length) {
   out.push(`\n   oldest still-silenced (most stale):`);
-  for (const it of dated.slice(0, 5)) out.push(`     ${it.file}:${it.line}  ${String(it.kind).trim()}  (since ${it.date})`);
+  for (const it of dated.slice(0, 5)) out.push(`     ${it.file}:${it.line}  ${String(it.kind).trim()}  (since ${it.since})`);
 }
 out.push(`\n   bare = no code/reason, the suspect kind. leads, not verdicts; full dated ledger: logbook audit`);
 console.log(out.join('\n'));

package/memory.mjs

@@ -0,0 +1,207 @@
+// memory.mjs, Sawbuck's memory adapter: the single seam between the glue and the memory provider(s).
+// It speaks the Memory Contract (recall / debt / record) over a provider's CLI, so no other glue file
+// imports a provider's internals. Zero-dep.
+//
+// Providers: SAWBUCK_MEMORY is an ordered, comma-separated list (default "logbook"). An entry is
+// either the built-in "logbook" (the reference provider, adapted to its native query/audit/annotate
+// verbs) or another provider that speaks the clean contract verbs: `recall --file P --json`,
+// `debt [--since REF] --json`, `record --ref SHA --summary S [--side X] [--evidence-file F] --by WHO`.
+// The shipped reference non-git provider is "obsidian" (providers/obsidian.mjs); point at any other
+// with SAWBUCK_MEMORY_<NAME>_BIN or a path entry.
+//
+// Degradation is explicit: a read returns null when its PRIMARY (git-truth) source failed, [] when it
+// ran clean. A provider that does not support a capability signals it by exiting nonzero (we skip it),
+// never by printing []. git-truth stays authoritative; other providers add supplementary notes.
+
+import { execFileSync } from 'node:child_process';
+import { createRequire } from 'node:module';
+import { existsSync } from 'node:fs';
+import { join, dirname, relative, resolve, basename, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { homedir } from 'node:os';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const require = createRequire(import.meta.url);
+
+function logbookBin() {
+  if (process.env.SAWBUCK_MEMORY_BIN) return process.env.SAWBUCK_MEMORY_BIN; // back-compat single-provider override
+  if (process.env.LB_BIN) return process.env.LB_BIN;
+  for (const spec of ['@promptwheel/logbook/bin/logbook.mjs', '@promptwheel/logbook']) { try { return require.resolve(spec); } catch {} }
+  return join(HERE, '..', 'logbook', 'bin', 'logbook.mjs');
+}
+const envKey = (name) => 'SAWBUCK_MEMORY_' + name.toUpperCase().replace(/[^A-Z0-9]/g, '_') + '_BIN';
+// the ordered provider list. Each: { name, bin, dialect: 'logbook' | 'contract' }.
+const SHIPPED = new Set(['obsidian', 'mem0', 'local', 'claude']); // reference contract providers that ship in providers/
+export function providers() {
+  const spec = (process.env.SAWBUCK_MEMORY || 'logbook').split(',').map((s) => s.trim()).filter(Boolean);
+  return spec.map((name) => {
+    if (name === 'logbook') return { name, bin: logbookBin(), dialect: 'logbook' };
+    if (SHIPPED.has(name)) return { name, bin: process.env[envKey(name)] || join(HERE, 'providers', name + '.mjs'), dialect: 'contract' };
+    return { name, bin: process.env[envKey(name)] || name, dialect: 'contract' }; // a bin path, or a name with an env-set bin
+  });
+}
+
+// scopeChain(): the folder-based scope chain for a repo, most-specific first: the repo, then each
+// ancestor up to the memory root, then the root ("" = the shared/global scope). ISOLATION BY DEFAULT:
+// with no configured root the chain is just the leaf, so a repo sees only itself and never a sibling.
+// A root is SAWBUCK_MEMORY_ROOT, or the nearest ancestor holding a `.sawbuck-root` marker; with one,
+// a repo also inherits its ancestors' shared memory. Ids are paths relative to the root (forward
+// slashes), so sibling repos with the same basename never collide and never leak into each other.
+export function scopeChain(repo) {
+  const start = resolve(repo);
+  let root = process.env.SAWBUCK_MEMORY_ROOT ? resolve(process.env.SAWBUCK_MEMORY_ROOT) : null;
+  if (!root) {
+    let d = start; const stop = resolve(homedir());
+    for (let i = 0; i < 64; i++) {
+      if (existsSync(join(d, '.sawbuck-root'))) { root = d; break; }
+      const up = dirname(d);
+      if (up === d || d === stop) break;
+      d = up;
+    }
+  }
+  if (root && (start === root || start.startsWith(root + sep))) {
+    const idOf = (dir) => relative(root, dir).split(sep).join('/'); // "" for the root itself
+    const chain = [];
+    let d = start;
+    for (let i = 0; i < 64; i++) {
+      chain.push(idOf(d));
+      if (d === root) break;
+      const up = dirname(d);
+      if (up === d) break;
+      d = up;
+    }
+    return chain; // leaf-first, ending with "" (root = shared/global)
+  }
+  return [basename(start) || '.']; // no root in play: an isolated leaf, no inheritance
+}
+
+// run a provider bin; null on a real failure / unsupported-capability (nonzero exit), stdout otherwise.
+function run(bin, repo, args, maxBuffer = 512 * 1024 * 1024) {
+  try { return execFileSync(process.execPath, [bin, ...args], { cwd: repo, encoding: 'utf8', maxBuffer, stdio: ['ignore', 'pipe', 'ignore'] }); }
+  catch { return null; }
+}
+function parseArray(out) {
+  const t = (out || '').trim();
+  if (!t.startsWith('[')) return [];
+  try { const v = JSON.parse(t); return Array.isArray(v) ? v : []; } catch { return []; }
+}
+
+// --- debt sub-classification (Sawbuck policy; applied once so the ledger and the per-turn surface
+// agree). Exported so the conformance checker can reuse them.
+export const isTestSkip = (m) => /\bit\.skip\b|\btest\.skip\b|xit\(|xdescribe\(|\bdescribe\.skip\b|pytest\.mark\.skip|unittest\.skip|\bt\.Skip\b|@Disabled\b|@Ignore\b|^\[Ignore\b|^Skip\s*=|^#\[ignore|markTestSkipped|markTestIncomplete/.test(String(m).trim());
+export const isDocumented = (c) => {
+  c = String(c || '');
+  if (/eslint-disable/.test(c)) return /eslint-disable(?:-next-line|-line)?\s+\S/.test(c);
+  if (/@ts-ignore/.test(c)) return false;
+  if (/@ts-expect-error/.test(c)) return /@ts-expect-error\s+\S/.test(c);
+  if (/noqa/i.test(c)) return /noqa:\s*\w/i.test(c);
+  if (/type:\s*ignore/i.test(c)) return /ignore\s*\[/.test(c);
+  return /\(\s*["']/.test(c) || /=\s*["']/.test(c);
+};
+
+const classify = (r, source) => ({
+  file: r.file, line: r.line, kind: String(r.kind ?? '').trim(), content: r.content ?? '',
+  since: r.since ?? null, sha: r.sha ?? null,
+  documented: r.content ? isDocumented(r.content) : false,
+  testSkip: isTestSkip(r.kind ?? r.content ?? ''),
+  source,
+});
+
+// events(): the raw git event record (the ranking input), from the logbook-dialect provider only
+// (events with revert/fix/suppression semantics are git-truth; a note provider does not produce them).
+// [] when there is no such provider or it fails, exactly as "no history".
+export function events(repo) {
+  const lb = providers().find((p) => p.dialect === 'logbook');
+  if (!lb) return [];
+  const out = run(lb.bin, repo, ['query', '--json'], 256 * 1024 * 1024);
+  if (out === null) return [];
+  return out.split('\n').filter(Boolean).map((l) => { try { return JSON.parse(l); } catch { return null; } }).filter(Boolean);
+}
+
+// the per-provider debt call, dialect-aware.
+function debtRaw(p, repo, { paths, ref }) {
+  const args = p.dialect === 'logbook'
+    ? ['audit', '--json', ...(ref ? ['--ref', ref] : []), ...((paths || []).flatMap((f) => ['--file', f]))]
+    : ['debt', '--json', ...(ref ? ['--since', ref] : []), ...((paths || []).flatMap((f) => ['--file', f]))];
+  return run(p.bin, repo, args);
+}
+
+// debt(): live suppressions still in the tree, each classified. Fans out across providers that SUPPORT
+// debt (git-truth); a provider that does not implement it exits nonzero and is skipped. Returns null
+// only when NO provider answered (unmeasurable, not clean); [] when a provider ran and the tree is
+// clean. Default (logbook-only) is byte-identical to the single-provider behavior.
+export function debt(repo, { paths = null, ref = null } = {}) {
+  let answered = false;
+  const rows = [];
+  for (const p of providers()) {
+    const out = debtRaw(p, repo, { paths, ref });
+    if (out === null) continue;              // failed or unsupported -> skip
+    answered = true;
+    for (const r of parseArray(out)) rows.push(classify(r, p.name));
+  }
+  return answered ? rows : null;
+}
+
+// recall(): supplementary relevant NOTES for the touched paths, from providers that produce them
+// (contract-dialect; logbook's own history is surfaced via rank, not here). Each is a Finding of kind
+// note/decision, source-tagged. [] when nothing relevant. git-truth is never diluted by these.
+const normText = (s) => String(s || '').toLowerCase().replace(/\s+/g, ' ').replace(/[^\w ]+/g, '').trim();
+export function recall(repo, paths) {
+  const scopeArgs = scopeChain(repo).flatMap((id) => ['--scope', id]); // leaf-first: self + ancestors, never siblings
+  const raw = [];
+  for (const p of providers()) {
+    if (p.dialect !== 'contract') continue;
+    const r = run(p.bin, repo, ['recall', '--json', ...((paths || []).flatMap((f) => ['--file', f])), ...scopeArgs]);
+    if (r === null) continue;
+    for (const it of parseArray(r)) raw.push({ kind: String(it.kind || 'note'), path: it.path ?? null, ref: it.ref ?? null, date: it.date ?? null, summary: String(it.summary || '').slice(0, 280), source: p.name, scope: it.scope ?? null, score: typeof it.score === 'number' ? it.score : null });
+  }
+  // Cross-provider dedup + unified ordering. The same note surfaced by two providers collapses to one
+  // (keep the higher score; record that both knew it). Ordering is best-effort by the providers' own
+  // relevance scores: these are SUPPLEMENTARY leads, never git-truth, so a fuzzy order is fine.
+  const byKey = new Map();
+  for (const f of raw) {
+    const k = (f.path ? normText(f.path) + '\u0000' : '') + normText(f.summary);
+    const prev = byKey.get(k);
+    if (!prev) { byKey.set(k, f); continue; }
+    const keep = (f.score ?? 0) > (prev.score ?? 0) ? f : prev, other = keep === f ? prev : f;
+    if (other.source && !String(keep.source).split('+').includes(other.source)) keep.source = `${keep.source}+${other.source}`;
+    byKey.set(k, keep);
+  }
+  return [...byKey.values()].sort((a, b) => (b.score ?? 0) - (a.score ?? 0)).slice(0, 8);
+}
+
+// conform(): read-only conformance probe of a contract-dialect provider bin. Checks recall returns a
+// JSON array (or errors cleanly) and that debt either returns an array (git-truth) or signals
+// unsupported by exiting nonzero (never a bare []). Does not write, so record is validated elsewhere
+// (the record fan-out). Returns a report the `memory-conformance` command prints.
+export function conform(bin, repo, probePath = 'README.md') {
+  const probe = (args) => { try { return { out: execFileSync(process.execPath, [bin, ...args], { cwd: repo, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }), code: 0 }; } catch (e) { return { out: (e.stdout || '').toString(), code: e.status || 1 }; } };
+  const isArray = (s) => { s = (s || '').trim(); if (!s.startsWith('[')) return false; try { return Array.isArray(JSON.parse(s)); } catch { return false; } };
+  const r = probe(['recall', '--json', '--file', probePath]);
+  const recall = r.code !== 0 ? 'error (nonzero exit on recall)' : (isArray(r.out) ? 'ok (Finding[])' : 'bad shape (recall must print a JSON array)');
+  const d = probe(['debt', '--json']);
+  const debt = d.code !== 0 ? 'unsupported (exits nonzero, ok for a non-git provider)' : (isArray(d.out) ? 'supported (Suppression[])' : 'bad shape (debt must print a JSON array or exit nonzero)');
+  const pass = /^ok/.test(recall) && !/bad shape/.test(debt);
+  return { bin, recall, debt, pass };
+}
+
+// record(): persist a machine finding to every WRITABLE provider (the write-back). Best-effort; never
+// throws into the caller. Returns true if at least one provider accepted it.
+export function record(repo, { sha, reason, side, evidenceFile, by = 'sawbuck' }) {
+  const text = String(reason).slice(0, 280);
+  const leaf = scopeChain(repo)[0]; // a finding belongs to the most-specific scope that produced it
+  let ok = false;
+  for (const p of providers()) {
+    const exec = (a) => execFileSync(process.execPath, [p.bin, ...a], { cwd: repo, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+    try {
+      if (p.dialect === 'logbook') {
+        const full = ['annotate', sha, text, ...(side ? ['--side', side] : []), ...(evidenceFile ? ['--evidence-file', evidenceFile] : []), '--by', by];
+        try { exec(full); } catch { exec(['annotate', sha, text, '--by', by]); }
+      } else {
+        exec(['record', '--ref', sha, '--summary', text, ...(side ? ['--side', side] : []), ...(evidenceFile ? ['--evidence-file', evidenceFile] : []), '--scope', leaf, '--by', by]);
+      }
+      ok = true;
+    } catch { /* this provider declined; others may still accept */ }
+  }
+  return ok;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sawbuck",
-  "version": "0.1.13",
+  "version": "0.1.20",
   "description": "Sign your agent to a contract so it does what you want: a deterministic, zero-LLM check that re-proves every win from the agent's source edits alone, so a green that came from editing the test is caught and reverted. A saddle for your coding harness.",
   "type": "module",
   "license": "MIT",
@@ -27,6 +27,11 @@
     "rank.mjs",
     "debt.mjs",
     "status.mjs",
+    "memory.mjs",
+    "providers/obsidian.mjs",
+    "providers/mem0.mjs",
+    "providers/local.mjs",
+    "providers/claude.mjs",
     "run.mjs",
     "README.md",
     "GLOSSARY.md",

package/providers/claude.mjs

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+// claude.mjs, a REFERENCE read-only memory provider: your project's Claude Code memory (CLAUDE.md,
+// AGENTS.md, and top-level .claude/*.md) as a recall source. It is the most UBIQUITOUS local memory -
+// a Claude Code repo already has it - so it is zero-setup. READ-ONLY by design: recall only; debt and
+// record EXIT NONZERO (unsupported). This is a view of memory you already keep, not a write target
+// (writing findings into CLAUDE.md would bloat the always-loaded project context), and the contract
+// lets a provider implement a subset. Inherently leaf-scoped (reads only this repo's files, so no
+// cross-repo leak). Zero-dep, offline, local-notes axis.
+//
+//   recall --file P [--file Q] --json   relevant lines from your project memory -> Finding[] (kind note)
+//   debt | record                        EXIT NONZERO (unsupported)
+
+import { readFileSync, readdirSync, existsSync, statSync } from 'node:fs';
+import { join, basename, extname } from 'node:path';
+
+const argv = process.argv.slice(2);
+const cmd = argv[0];
+const flagAll = (n) => argv.reduce((a, v, i) => (argv[i - 1] === n ? [...a, v] : a), []);
+const die = (m, c = 2) => { process.stderr.write(`claude provider: ${m}\n`); process.exit(c); };
+const CWD = process.cwd();
+
+if (cmd === 'debt' || cmd === 'record') die(`${cmd} is unsupported (claude memory is a read-only recall source)`, 2);
+
+if (cmd === 'recall') {
+  const paths = flagAll('--file');
+  if (!paths.length) { console.log('[]'); process.exit(0); }
+  const matches = (l) => paths.find((p) => l.includes(p) || (basename(p).length > 2 && l.includes(basename(p)))) || null;
+  // the project's Claude Code memory: CLAUDE.md / AGENTS.md at the root, plus top-level .claude/*.md.
+  const sources = [];
+  for (const f of ['CLAUDE.md', 'AGENTS.md']) { const p = join(CWD, f); if (existsSync(p)) sources.push(p); }
+  try { for (const e of readdirSync(join(CWD, '.claude'))) if (extname(e).toLowerCase() === '.md') sources.push(join(CWD, '.claude', e)); } catch {}
+  const out = [];
+  for (const src of sources) {
+    let text = ''; try { if (statSync(src).size > 512 * 1024) continue; text = readFileSync(src, 'utf8'); } catch { continue; }
+    const lines = text.split('\n');
+    let heading = basename(src);
+    for (let i = 0; i < lines.length; i++) {
+      const h = lines[i].match(/^#{1,6}\s+(.+)/);
+      if (h) { heading = h[1].trim(); continue; }
+      const hit = matches(lines[i]);
+      if (!hit) continue;
+      out.push({ kind: 'note', path: hit, ref: `${basename(src)}:${i + 1}`, date: null, summary: `${heading}: ${lines[i].trim()}`.slice(0, 280), score: 0.4 });
+    }
+  }
+  console.log(JSON.stringify(out.slice(0, 8)));
+  process.exit(0);
+}
+
+die(`unknown command '${cmd || ''}' (recall | debt | record)`, 2);

package/providers/local.mjs

@@ -0,0 +1,55 @@
+#!/usr/bin/env node
+// local.mjs, a REFERENCE minimal local-file memory provider: the simplest way to fill the socket with
+// no external tool. Findings live as JSON in <repo>/.sawbuck/memory-notes.json (git-excluded by attach).
+// It is the cleanest conformance target and a "bring your own, just a file" option. Zero-dep, offline,
+// in the local-notes axis alongside obsidian. Folder-scoped like the others.
+//
+//   recall --file P [--scope ID ...] --json   -> Finding[] (kind note)
+//   record --ref SHA --summary S [--scope ID] [--side X] [--evidence-file F] --by WHO
+//   debt   --json                              EXITS NONZERO (a note store is not git-aware)
+//
+// Store: SAWBUCK_LOCAL_MEMORY, else <cwd>/.sawbuck/memory-notes.json.
+
+import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { join, basename, dirname } from 'node:path';
+
+const argv = process.argv.slice(2);
+const cmd = argv[0];
+const flagAll = (n) => argv.reduce((a, v, i) => (argv[i - 1] === n ? [...a, v] : a), []);
+const flag = (n, d) => { const i = argv.indexOf(n); return i > -1 ? (argv[i + 1] ?? true) : d; };
+const die = (m, c = 2) => { process.stderr.write(`local provider: ${m}\n`); process.exit(c); };
+
+const STORE = process.env.SAWBUCK_LOCAL_MEMORY || join(process.cwd(), '.sawbuck', 'memory-notes.json');
+const load = () => { try { const v = JSON.parse(readFileSync(STORE, 'utf8')); return Array.isArray(v) ? v : []; } catch { return []; } };
+
+if (cmd === 'debt') die('debt is unsupported by a note store (git-truth lives in a git provider like logbook)', 2);
+
+if (cmd === 'recall') {
+  const paths = flagAll('--file');
+  if (!paths.length) { console.log('[]'); process.exit(0); }
+  const scopes = new Set(flagAll('--scope'));            // self + ancestors; empty (direct call) = match any
+  const bases = paths.map((p) => basename(p));
+  const out = [];
+  for (const f of load()) {
+    if (scopes.size && f.scope != null && !scopes.has(f.scope)) continue;   // isolation: a sibling scope is excluded
+    const hit = (f.path && paths.includes(f.path)) || (f.summary && bases.some((b) => f.summary.includes(b)));
+    if (!hit) continue;
+    out.push({ kind: 'note', path: f.path ?? null, ref: f.ref ?? null, date: f.date ?? null, summary: String(f.summary || '').slice(0, 280), scope: f.scope ?? '', score: 0.5 });
+  }
+  out.sort((a, b) => String(b.date).localeCompare(String(a.date)));
+  console.log(JSON.stringify(out.slice(0, 8)));
+  process.exit(0);
+}
+
+if (cmd === 'record') {
+  const ref = String(flag('--ref', '')), summary = String(flag('--summary', '')), by = String(flag('--by', 'sawbuck'));
+  const scope = flagAll('--scope')[0] ?? '';
+  const side = flag('--side', ''), evidence = flag('--evidence-file', '');
+  const notes = load();
+  if (notes.some((f) => f.ref === ref && f.summary === summary && f.scope === scope)) { console.log('recorded (already present)'); process.exit(0); }
+  notes.push({ ref, summary, path: evidence || null, scope, by, ...(side ? { side: String(side) } : {}), date: new Date().toISOString().slice(0, 10) });
+  try { mkdirSync(dirname(STORE), { recursive: true }); writeFileSync(STORE, JSON.stringify(notes, null, 2) + '\n'); console.log('recorded'); process.exit(0); }
+  catch (e) { die(`write failed: ${String(e.message).split('\n')[0]}`, 1); }
+}
+
+die(`unknown command '${cmd || ''}' (recall | debt | record)`, 2);

package/providers/mem0.mjs

@@ -0,0 +1,120 @@
+#!/usr/bin/env node
+// mem0.mjs, a REFERENCE semantic memory provider for Sawbuck's Memory Contract: Mem0 (mem0.ai) as the
+// memory.
+//
+// STATUS: VERIFIED against the live Mem0 platform v3 API on 2026-10-31. /v3/memories/search/ and
+// /v3/memories/add/ both returned 200 with the documented shapes (search -> { results: [...] }, add ->
+// { event_id, ... }) using the Token auth header. Offline degrade (no key -> [], debt unsupported) is
+// also tested. Adapt the query/scoping to taste; the wire calls are known-good.
+//
+// It is the THIRD contract implementation and a deliberately DIFFERENT axis from the other two:
+// a networked, LLM-backed semantic store, where logbook is deterministic git-truth and obsidian is
+// local notes. Because of that it is the one provider that is NOT offline: it needs the NETWORK and a
+// MEM0_API_KEY. So it is an OPTIONAL provider isolated behind the socket, never part of the zero-network
+// glue. Zero npm deps (Node >= 18 global fetch).
+//
+// Opt in: SAWBUCK_MEMORY=logbook,mem0 and MEM0_API_KEY=... (compose it WITH logbook so logbook stays the
+// git-truth + debt provider and Mem0 adds recalled semantic context).
+//
+//   recall --file P [--file Q] --json   semantic search of your Mem0 memories -> Finding[] (kind note)
+//   record --ref SHA --summary S --by WHO [--side X] [--evidence-file F]   add the finding as a memory
+//   debt   --json                        EXITS NONZERO: a semantic store is not git-aware (git-truth
+//                                         lives in a git provider like logbook); the contract skips it.
+//
+// Config: MEM0_API_KEY, or a `~/.mem0` key file (a plain token, or JSON with api_key/key); without a
+// key recall degrades to [] and record errors. Also MEM0_USER_ID (scope override), MEM0_NAMESPACE
+// (id prefix), MEM0_BASE_URL (default https://api.mem0.ai), MEM0_TIMEOUT_MS (default 8000). NOTE:
+// record SENDS the finding text to Mem0's service (your opt-in).
+
+import { readFileSync } from 'node:fs';
+import { basename, join } from 'node:path';
+import { homedir } from 'node:os';
+
+// the API key: MEM0_API_KEY, else a ~/.mem0 file (a plain token, or JSON with api_key/apiKey/key).
+function mem0Key() {
+  if (process.env.MEM0_API_KEY) return process.env.MEM0_API_KEY;
+  try {
+    const raw = readFileSync(join(homedir(), '.mem0'), 'utf8').trim();
+    if (raw.startsWith('{')) { const j = JSON.parse(raw); return j.api_key || j.apiKey || j.key || ''; }
+    return raw.split(/\s+/)[0] || '';
+  } catch { return ''; }
+}
+
+const argv = process.argv.slice(2);
+const cmd = argv[0];
+const flagAll = (n) => argv.reduce((a, v, i) => (argv[i - 1] === n ? [...a, v] : a), []);
+const flag = (n, d) => { const i = argv.indexOf(n); return i > -1 ? (argv[i + 1] ?? true) : d; };
+const die = (msg, code = 2) => { process.stderr.write(`mem0 provider: ${msg}\n`); process.exit(code); };
+
+// FOLDER SCOPING: each folder scope maps to a Mem0 user_id. --scope carries the chain, leaf-first
+// (paths relative to the memory root; "" is the root/shared scope). recall queries self + ancestors
+// and merges; record writes to the LEAF scope. MEM0_NAMESPACE prefixes the ids (keep them from
+// colliding with other Mem0 usage in the same account); MEM0_USER_ID, if set, overrides to a single
+// flat scope. With no --scope (direct call), it falls back to the repo folder name.
+const NS = process.env.MEM0_NAMESPACE || '';
+const scopeUid = (id) => process.env.MEM0_USER_ID || [NS, id || 'root'].filter(Boolean).join(':');
+const scopeUids = (scopes) => {
+  if (process.env.MEM0_USER_ID) return [process.env.MEM0_USER_ID];
+  if (scopes.length) return [...new Set(scopes.map(scopeUid))];
+  return [basename(process.cwd()) || 'sawbuck']; // back-compat: no scope passed
+};
+
+// one bounded POST to the Mem0 platform; null on any network/HTTP/auth failure, so a read never hangs
+// or crashes the caller. (A semantic recall is on-demand, never per-turn, so the timeout is generous.)
+async function post(path, body, key) {
+  const base = (process.env.MEM0_BASE_URL || 'https://api.mem0.ai').replace(/\/$/, '');
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), +(process.env.MEM0_TIMEOUT_MS) || 8000);
+  try {
+    const r = await fetch(base + path, {
+      method: 'POST',
+      headers: { Authorization: `Token ${key}`, 'Content-Type': 'application/json', Accept: 'application/json' },
+      body: JSON.stringify(body),
+      signal: ctrl.signal,
+    });
+    if (!r.ok) return null;
+    return await r.json();
+  } catch { return null; } finally { clearTimeout(timer); }
+}
+
+if (cmd === 'debt') {
+  die('debt is unsupported by a semantic store (git-truth lives in a git provider like logbook)', 2);
+}
+
+if (cmd === 'recall') {
+  const key = mem0Key();
+  if (!key) { console.log('[]'); process.exit(0); }                 // no key -> no memories, not an error
+  const paths = flagAll('--file');
+  if (!paths.length) { console.log('[]'); process.exit(0); }
+  const query = `code, decisions, and gotchas related to: ${paths.map((p) => basename(p)).join(', ')}`;
+  const seen = new Set();
+  const findings = [];
+  // one search per scope's user_id (self + ancestors), merged; isolated from sibling scopes.
+  for (const uid of scopeUids(flagAll('--scope'))) {
+    const res = await post('/v3/memories/search/', { query, filters: { user_id: uid }, top_k: 8 }, key);
+    for (const m of (res && Array.isArray(res.results) ? res.results : [])) {
+      if (!m.memory || seen.has(m.id)) continue;
+      seen.add(m.id);
+      findings.push({ kind: 'note', path: null, ref: m.id || null, date: (m.created_at || '').slice(0, 10) || null, summary: String(m.memory).slice(0, 280), scope: uid, score: typeof m.score === 'number' ? m.score : null });
+    }
+  }
+  console.log(JSON.stringify(findings.slice(0, 8)));
+  process.exit(0);
+}
+
+if (cmd === 'record') {
+  const key = mem0Key();
+  if (!key) die('cannot record: MEM0_API_KEY is unset', 2);
+  const ref = String(flag('--ref', '')), summary = String(flag('--summary', '')), by = String(flag('--by', 'sawbuck'));
+  const side = flag('--side', ''), evidence = flag('--evidence-file', '');
+  const leaf = flagAll('--scope')[0];
+  const userId = process.env.MEM0_USER_ID || (leaf !== undefined ? scopeUid(leaf) : (basename(process.cwd()) || 'sawbuck'));
+  const metadata = { sawbuck: 'finding', ref, by, scope: leaf ?? '', ...(side ? { side: String(side) } : {}), ...(evidence ? { evidence: String(evidence) } : {}) };
+  // infer:false stores the finding verbatim (no LLM extraction); we want the exact note, not a paraphrase.
+  const res = await post('/v3/memories/add/', { messages: [{ role: 'user', content: summary }], user_id: userId, metadata, infer: false }, key);
+  if (res === null) die('record failed (network or auth)', 1);
+  console.log('recorded');
+  process.exit(0);
+}
+
+die(`unknown command '${cmd || ''}' (recall | debt | record)`, 2);

package/providers/obsidian.mjs

@@ -0,0 +1,119 @@
+#!/usr/bin/env node
+// obsidian.mjs, a REFERENCE memory provider for Sawbuck's Memory Contract: an Obsidian vault as the
+// memory. Shows how to fill the socket, and the second contract implementation. Zero-dep. Opt in with
+// SAWBUCK_MEMORY=logbook,obsidian and OBSIDIAN_VAULT=/path/to/vault (compose it WITH logbook: logbook
+// stays the git-truth + debt provider, this adds your written notes).
+//
+//   recall --file P [--file Q] [--scope ID ...] --json   notes relevant to those paths -> Finding[] (kind note)
+//   record --ref SHA --summary S --by WHO [--scope ID]   write a note into the vault
+//   debt   --json                        EXITS NONZERO: a note vault cannot know what is silenced in HEAD
+//
+// FOLDER SCOPING (isolation): --scope carries the folder scope chain, leaf-first, as paths relative to
+// the memory root (Sawbuck computes them; "" is the vault root = shared/global). The vault MIRRORS the
+// project tree: notes for scope "group/repo" live in `<vault>/group/repo/`. recall searches the LEAF
+// scope recursively (so the repo's own notes + its Sawbuck/ folder are found) and each ANCESTOR scope
+// TOP-LEVEL ONLY (so it never descends into a sibling repo's folder). With no --scope it searches the
+// whole vault (direct calls / back-compat). record writes to the LEAF scope's Sawbuck/ folder.
+
+import { readFileSync, writeFileSync, readdirSync, statSync, mkdirSync, existsSync } from 'node:fs';
+import { join, basename, relative, extname, resolve, sep } from 'node:path';
+
+const argv = process.argv.slice(2);
+const cmd = argv[0];
+const flagAll = (n) => argv.reduce((a, v, i) => (argv[i - 1] === n ? [...a, v] : a), []);
+const flag = (n, d) => { const i = argv.indexOf(n); return i > -1 ? (argv[i + 1] ?? true) : d; };
+
+const VAULT = process.env.OBSIDIAN_VAULT ? resolve(process.env.OBSIDIAN_VAULT) : '';
+const die = (msg, code = 2) => { process.stderr.write(`obsidian provider: ${msg}\n`); process.exit(code); };
+
+const MAX_FILES = +(process.env.OBSIDIAN_MAX_FILES) || 4000;
+const MAX_BYTES = 512 * 1024;
+
+// resolve a scope id to a dir INSIDE the vault; null if it would escape (path-traversal guard).
+function scopeDir(id) {
+  if (id === '' || id == null) return VAULT;
+  const p = resolve(VAULT, id);
+  return (p === VAULT || p.startsWith(VAULT + sep)) ? p : null;
+}
+// collect .md files; recursive for the leaf scope, top-level only for an ancestor (so an ancestor
+// search never descends into a sibling repo's folder).
+function walkMd(dir, recursive, out) {
+  let entries = [];
+  try { entries = readdirSync(dir, { withFileTypes: true }); } catch { return; }
+  for (const e of entries) {
+    if (out.length >= MAX_FILES) return;
+    if (e.name.startsWith('.') || e.name === 'node_modules') continue;
+    const p = join(dir, e.name);
+    if (e.isDirectory()) { if (recursive) walkMd(p, true, out); }
+    else if (extname(e.name).toLowerCase() === '.md') out.push(p);
+  }
+}
+// the dirs to search, with their scope id and recursion, from the --scope chain (leaf-first).
+function searchScopes(scopes) {
+  if (!scopes.length) return [{ id: '', dir: VAULT, recursive: true }]; // no scope -> whole vault
+  const out = []; const seen = new Set();
+  scopes.forEach((id, i) => {
+    const dir = scopeDir(id);
+    if (!dir || seen.has(dir)) return; seen.add(dir);
+    out.push({ id, dir, recursive: i === 0 }); // leaf recursive; ancestors top-level only
+  });
+  if (!seen.has(VAULT)) out.push({ id: '', dir: VAULT, recursive: false }); // vault root is the shared scope
+  return out;
+}
+
+if (cmd === 'debt') {
+  die('debt is unsupported by a note vault (git-truth lives in a git provider like logbook)', 2);
+}
+
+if (cmd === 'recall') {
+  if (!VAULT || !existsSync(VAULT)) { console.log('[]'); process.exit(0); }
+  const paths = flagAll('--file');
+  if (!paths.length) { console.log('[]'); process.exit(0); }
+  const needles = [...new Set(paths.flatMap((p) => [p, basename(p)]).filter(Boolean))];
+  const findings = [];
+  for (const { id, dir, recursive } of searchScopes(flagAll('--scope'))) {
+    const files = []; walkMd(dir, recursive, files);
+    for (const file of files) {
+      let text = '';
+      try { if (statSync(file).size > MAX_BYTES) continue; text = readFileSync(file, 'utf8'); } catch { continue; }
+      const hitPath = paths.find((p) => text.includes(p) || text.includes(basename(p)));
+      if (!hitPath) continue;
+      let hits = 0; for (const n of needles) hits += text.split(n).length - 1;
+      const title = (text.match(/^#\s+(.+)$/m) || [, basename(file, '.md')])[1].trim();
+      const lineWith = (text.split('\n').find((l) => needles.some((n) => l.includes(n))) || '').trim().slice(0, 160);
+      let date = null; try { date = new Date(statSync(file).mtimeMs).toISOString().slice(0, 10); } catch {}
+      findings.push({ kind: 'note', path: hitPath, ref: relative(VAULT, file), date, summary: `${title}: ${lineWith}`.slice(0, 280), scope: id, score: Math.min(1, hits / 5), _hits: hits });
+    }
+  }
+  findings.sort((a, b) => b._hits - a._hits || String(b.date).localeCompare(String(a.date)));
+  console.log(JSON.stringify(findings.slice(0, 8).map(({ _hits, ...f }) => f)));
+  process.exit(0);
+}
+
+if (cmd === 'record') {
+  if (!VAULT || !existsSync(VAULT)) die('cannot record: OBSIDIAN_VAULT is unset or missing', 2);
+  const ref = flag('--ref', ''), summary = String(flag('--summary', '')), by = String(flag('--by', 'sawbuck'));
+  const side = flag('--side', ''), evidence = flag('--evidence-file', '');
+  const leaf = flagAll('--scope')[0] ?? '';
+  const base = scopeDir(leaf) || VAULT;                 // the finding belongs to its most-specific scope
+  const dir = join(base, 'Sawbuck');
+  try { mkdirSync(dir, { recursive: true }); } catch {}
+  const safeRef = String(ref || Date.now()).replace(/[^\w.-]/g, '_').slice(0, 40);
+  const date = new Date().toISOString();
+  // a [[wikilink]] to the evidence path so Obsidian's graph connects the finding to the code note.
+  const link = evidence ? `\n- evidence: [[${String(evidence).replace(/[[\]]/g, '')}]]` : '';
+  const body = `---\nsawbuck: finding\nref: ${ref}\nby: ${by}\ndate: ${date}\nscope: ${leaf}\n---\n\n# ${summary.slice(0, 80)}\n\n${summary}\n\n- ref: \`${ref}\`${side ? `\n- side: ${side}` : ''}${link}\n`;
+  // no-clobber + dedupe: if this exact finding is already noted, skip; if a DIFFERENT note shares the
+  // ref, write a suffixed sibling instead of overwriting the earlier one.
+  let target = join(dir, `${safeRef}.md`);
+  if (existsSync(target)) {
+    let prev = ''; try { prev = readFileSync(target, 'utf8'); } catch {}
+    if (prev.includes(summary)) { console.log('recorded (already present)'); process.exit(0); }
+    let i = 2; while (existsSync(join(dir, `${safeRef}-${i}.md`))) i++;
+    target = join(dir, `${safeRef}-${i}.md`);
+  }
+  try { writeFileSync(target, body); console.log('recorded'); process.exit(0); }
+  catch (e) { die(`write failed: ${String(e.message).split('\n')[0]}`, 1); }
+}
+
+die(`unknown command '${cmd || ''}' (recall | debt | record)`, 2);

package/rank.mjs

@@ -12,21 +12,7 @@
 // renames). v1 does not follow a file across a pre-rename name.
 
 import { execFileSync } from 'node:child_process';
-import { createRequire } from 'node:module';
-import { join, dirname } from 'node:path';
-import { fileURLToPath, pathToFileURL } from 'node:url';
-
-const HERE = dirname(fileURLToPath(import.meta.url));
-const require = createRequire(import.meta.url);
-const engineBin = (envVar, pkgSubpath, devPath) => {
-  if (process.env[envVar]) return process.env[envVar];
-  // deep bin subpath (no-exports pkgs, e.g. promptwheel), then the bare package name
-  // (pkgs whose exports map "." to the bin, e.g. @promptwheel/logbook), then the dev sibling.
-  const bare = pkgSubpath.replace(/\/bin\/[^/]*$/, '');
-  for (const spec of [pkgSubpath, bare]) { try { return require.resolve(spec); } catch {} }
-  return devPath;
-};
-const LB = engineBin('LB_BIN', '@promptwheel/logbook/bin/logbook.mjs', join(HERE, '..', 'logbook', 'bin', 'logbook.mjs'));
+import { events as memEvents, debt as memDebt } from './memory.mjs';
 
 const arg = (n, d) => { const i = process.argv.indexOf(n); return i > -1 ? process.argv[i + 1] : d; };
 const multi = (n) => process.argv.reduce((a, v, i) => (process.argv[i - 1] === n ? [...a, v] : a), []);
@@ -42,11 +28,9 @@ let paths = multi('--file');
 if (!paths.length) paths = git('diff', '--name-only', base, head).split('\n').filter(Boolean);
 if (!paths.length) { console.log(asJson ? '[]' : 'rank: no paths to rank'); process.exit(0); }
 
-// pull the full event record once (query --file does not narrow --json)
-let record = '';
-try { record = execFileSync(process.execPath, [LB, 'query', '--json'], { cwd: repo, encoding: 'utf8', maxBuffer: 256 * 1024 * 1024 }); }
-catch (e) { record = (e.stdout || '').toString(); }
-const EVENTS = record.split('\n').filter(Boolean).map((l) => { try { return JSON.parse(l); } catch { return null; } }).filter(Boolean);
+// the full event record (the memory provider's recall facts), ranked client-side below
+// (the provider's --file does not narrow the record, so we pull it once and filter by path here).
+const EVENTS = memEvents(repo);
 
 const resolveRename = (f) => f.replace(/\{[^}]*=>\s*([^}]*)\}/g, '$1').replace(/\/{2,}/g, '/');
 const touches = (e, p) => (e.files || []).some((f) => resolveRename(f) === p);
@@ -90,57 +74,32 @@ const normMult = (p, kind) => {
   return Math.max(0.4, Math.min(1, REF / b));
 };
 
-// Classify a live suppression MARKER (disabled test = hidden-failure risk) and its line as
-// DOCUMENTED (a rule code/reason follows) vs BARE (just the directive, the suspect kind). Same
-// splits `sawbuck debt` uses, so the ambient surface and the ledger agree.
-const isTestSkip = (m) => /\bit\.skip\b|\btest\.skip\b|xit\(|xdescribe\(|\bdescribe\.skip\b|pytest\.mark\.skip|unittest\.skip|\bt\.Skip\b|@Disabled\b|@Ignore\b|^\[Ignore\b|^Skip\s*=|^#\[ignore|markTestSkipped|markTestIncomplete/.test(String(m).trim());
-const isDocumented = (c) => {
-  c = String(c || '');
-  if (/eslint-disable/.test(c)) return /eslint-disable(?:-next-line|-line)?\s+\S/.test(c);
-  if (/@ts-ignore/.test(c)) return false;
-  if (/@ts-expect-error/.test(c)) return /@ts-expect-error\s+\S/.test(c);
-  if (/noqa/i.test(c)) return /noqa:\s*\w/i.test(c);
-  if (/type:\s*ignore/i.test(c)) return /ignore\s*\[/.test(c);
-  return /\(\s*["']/.test(c) || /=\s*["']/.test(c);
-};
 // The "slider": debt rises on its own, but gently. A disabled test or an undocumented suppression
 // on a touched file always surfaces; a file that is churning (hot / reverted) surfaces any debt;
 // a stable file's routine documented suppressions stay quiet until they pile past DEBT_MIN. Tune
 // with SAWBUCK_DEBT_MIN. This is how debt rises by itself in the per-turn context, no command run.
 const DEBT_MIN = Math.max(1, +(process.env.SAWBUCK_DEBT_MIN) || 6);
 
-// Still-live filter (lead #4). A suppression on a path that is now CLEAN of suppressions is churn,
-// not current risk (the study: AutoMapper carries 4 live `[Ignore]` vs ~158/repo across C# history).
-// logbook's own SUPPRESS_PAT, git-grepped at HEAD but SCOPED to just the touched paths so the
-// per-turn hook stays cheap, tells us which still carry one. Imported so the pattern never drifts;
-// degrades to "treat all as live" if logbook cannot be imported. --raw turns it off.
+// Still-live filter (lead #4) + ambient debt, via the memory adapter (the Memory Contract's `debt`
+// capability), scoped to the touched paths so the per-turn hook stays cheap. A suppression on a path
+// now CLEAN of suppressions is churn, not current risk (the study: AutoMapper carries 4 live
+// `[Ignore]` vs ~158/repo across C# history). The adapter runs the provider's own detection + gating
+// and returns classified suppressions, so the glue never imports the provider's pattern. null = the
+// provider failed -> treat all as live (do not penalize); [] = genuinely clean. --raw turns it off.
 let liveSet = null;
-const liveDebt = new Map(); // path -> { n, skips, bare }: live suppressions in HEAD, for ambient surfacing
+const liveDebt = new Map(); // path -> { n, skips, bare }: live suppressions, for ambient surfacing
 if (!raw && paths.length) {
-  try {
-    const { SUPPRESS_PAT, kindAllowedInFile, isMention } = await import(pathToFileURL(LB).href);
-    if (SUPPRESS_PAT && SUPPRESS_PAT.source) {
-      // -nP (content), still scoped to the touched paths, so we can both weight AND surface the debt.
-      let grep = '';
-      try { grep = execFileSync('git', ['-C', repo, 'grep', '-nP', SUPPRESS_PAT.source, 'HEAD', '--', ...paths], { encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 }); }
-      catch (e) { grep = (e.stdout || '').toString(); } // git grep exits 1 when nothing matches
-      liveSet = new Set();
-      for (const row of grep.split('\n')) {
-        const m = /^HEAD:(.+?):\d+:(.*)$/.exec(row); if (!m) continue;
-        const file = m[1], content = m[2];
-        const re = new RegExp(SUPPRESS_PAT.source, 'g'); let mm;
-        while ((mm = re.exec(content))) {
-          if (kindAllowedInFile && !kindAllowedInFile(mm[0], file)) continue; // gate exactly like audit
-          if (isMention && isMention(content, mm.index, mm[0])) continue;      // a comment ABOUT it is not live
-          liveSet.add(file);
-          const d = liveDebt.get(file) || { n: 0, skips: 0, bare: 0 };
-          d.n++;
-          if (isTestSkip(mm[0])) d.skips++; else if (!isDocumented(content)) d.bare++;
-          liveDebt.set(file, d);
-        }
-      }
+  const sup = memDebt(repo, { paths });
+  if (sup !== null) {
+    liveSet = new Set();
+    for (const it of sup) {
+      liveSet.add(it.file);
+      const d = liveDebt.get(it.file) || { n: 0, skips: 0, bare: 0 };
+      d.n++;
+      if (it.testSkip) d.skips++; else if (!it.documented) d.bare++;
+      liveDebt.set(it.file, d);
     }
-  } catch { liveSet = null; liveDebt.clear(); } // logbook unavailable -> skip, do not crash the read face
+  }
 }
 // a suppression on a still-silenced path keeps its weight; on a now-clean path it is near-zero.
 const stillLive = (p) => (liveSet === null || liveSet.has(p) ? 1 : 0.25);

package/reflect.mjs

@@ -19,11 +19,13 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { createRequire } from 'node:module';
+import { record as memRecord } from './memory.mjs';
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 const require = createRequire(import.meta.url);
-// Resolve each engine CLI: env override, then the installed package (published
-// install), then the monorepo sibling (dev checkout).
+// Resolve the check engine CLI: env override, then the installed package (published
+// install), then the monorepo sibling (dev checkout). The MEMORY engine is reached only
+// through memory.mjs (the Memory Contract seam), never resolved or shelled directly here.
 const engineBin = (envVar, pkgSubpath, devPath) => {
   if (process.env[envVar]) return process.env[envVar];
   // deep bin subpath (no-exports pkgs, e.g. promptwheel), then the bare package name
@@ -33,7 +35,6 @@ const engineBin = (envVar, pkgSubpath, devPath) => {
   return devPath;
 };
 const PW = engineBin('PW_BIN', 'promptwheel/bin/promptwheel.mjs', join(HERE, '..', 'referee', 'bin', 'promptwheel.mjs'));
-const LB = engineBin('LB_BIN', '@promptwheel/logbook/bin/logbook.mjs', join(HERE, '..', 'logbook', 'bin', 'logbook.mjs'));
 
 const flag = (name, def) => { const i = process.argv.indexOf(name); return i > -1 ? process.argv[i + 1] : def; };
 const repo = flag('--repo', process.cwd());
@@ -81,13 +82,10 @@ const reason = kind === 'gamed'
   : `sawbuck: a change here regressed a guarded metric beyond noise`;
 
 // --- 3) record the finding in memory (unreviewed, machine-authored note) ----
+// The Memory Contract's `record` capability, through the adapter (no direct engine shell here).
 // M0 keeps it simple: a commit-attached digest note. M1 adds --span grounding
-// + true coupling (the fix diff → "change X ⇒ also Y").
-try {
-  runNode(LB, ['annotate', sha, reason.slice(0, 280), '--side', 'diff', '--evidence-file', evidenceFile, '--by', 'sawbuck']);
-} catch {
-  try { runNode(LB, ['annotate', sha, reason.slice(0, 280), '--by', 'sawbuck']); } catch { /* best-effort */ }
-}
+// + true coupling (the fix diff -> "change X also needs Y").
+memRecord(repo, { sha, reason: reason.slice(0, 280), side: 'diff', evidenceFile, by: 'sawbuck' });
 
 // --- 4) tick the results record (the visible proof-of-work) -----------------
 const recDir = join(repo, '.sawbuck');

package/sawbuck.mjs

@@ -18,6 +18,7 @@ import { join, dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { homedir } from 'node:os';
 import { createRequire } from 'node:module';
+import { recall as memRecall, conform as memConform } from './memory.mjs';
 
 const SELF = fileURLToPath(import.meta.url);
 const HERE = dirname(SELF);
@@ -86,6 +87,10 @@ Usage:
   sawbuck rank [--base R --head R] [--file P ...]
                             Show the relevant past findings for the paths a change touches
   sawbuck context [repo]    Ranked relevant history for your current working changes (the read face)
+  sawbuck recall [repo]     Related notes for your current changes from extra memory providers
+                            (SAWBUCK_MEMORY=logbook,obsidian + OBSIDIAN_VAULT); supplementary to context
+  sawbuck memory-conformance <bin>
+                            Check a provider bin speaks the Memory Contract (recall/debt/record)
   sawbuck debt [repo] [--since REF] [--fail-on undocumented|test|any|N]
                             The whole-repo live suppression debt: what is still silenced in HEAD now,
                             risk-ranked (severity x file fragility), undocumented flagged. --since REF
@@ -181,6 +186,32 @@ switch (cmd) {
     else if (speak) out('🐴 sawbuck: no notable history for the files you are touching (a clean trail).');
     break;
   }
+  case 'recall': {
+    // the notes face: supplementary relevant notes for your current changes, from any non-git memory
+    // provider (e.g. an Obsidian vault). On-demand. Git history + live debt come from context / debt.
+    const repo = repoArg();
+    const g = (...a) => { try { return execFileSync('git', ['-C', repo, ...a], { encoding: 'utf8' }).trim(); } catch { return ''; } };
+    let changed = g('diff', '--name-only', 'HEAD').split('\n').filter(Boolean);
+    if (!changed.length) changed = g('diff', '--name-only', 'HEAD~1', 'HEAD').split('\n').filter(Boolean);
+    if (!changed.length) { out('🐴 sawbuck: nothing changed to look up.'); break; }
+    const notes = memRecall(repo, changed);
+    if (!notes.length) { out('🐴 sawbuck: no related notes (configure extra memory providers with SAWBUCK_MEMORY, e.g. logbook,obsidian; logbook history is in `sawbuck context`).'); break; }
+    out(`🐴 related notes for ${changed.length} changed path${changed.length === 1 ? '' : 's'} (leads, not conclusions):`);
+    for (const n of notes) out(`  - [${n.source}] ${n.summary}${n.ref ? `  (${n.ref})` : ''}`);
+    break;
+  }
+  case 'memory-conformance': {
+    // check that a provider bin speaks the Memory Contract (recall returns Finding[]; debt returns
+    // Suppression[] or exits nonzero to signal it is not a git-truth provider). Read-only probe.
+    const bin = positional[0];
+    if (!bin) die('usage: sawbuck memory-conformance <provider-bin>   (a bin speaking the contract verbs recall/debt/record)');
+    const r = memConform(bin, process.cwd());
+    out(`🐴 memory-conformance: ${bin}`);
+    out(`   recall: ${r.recall}`);
+    out(`   debt:   ${r.debt}`);
+    out(r.pass ? '   ✓ conforms to the Memory Contract.' : '   ✗ does not conform (see above).');
+    process.exit(r.pass ? 0 : 1);
+  }
   case 'run': {
     try { execFileSync(process.execPath, [join(HERE, 'run.mjs'), ...rest], { stdio: 'inherit' }); }
     catch (e) { process.exit(e.status || 1); }