total-recall-brain 3.44.0 → 3.45.0

package/src/core/dream.mjs

@@ -1,7 +1,6 @@
 import fs from 'fs';
 import path from 'path';
 import os from 'os';
-import crypto from 'crypto';
 import matter from './frontmatter.mjs';
 import { writeNode, walkMd } from './vault.mjs';
 import { updateNodeInPlace } from './validated-write.mjs';
@@ -127,7 +126,7 @@ export function autoPruneStorage(brainDir, vaultDir, conflictsDir) {
   // Retrieve node slugs of active research projects so we never prune their drafts in progress
   const activeResearchSlugs = new Set();
   try {
-    const queue = loadQueue();
+    const queue = loadQueue(brainDir);
     for (const item of queue) {
       if (item.status === 'pending' || item.status === 'in_progress') {
         if (item.node_slug) {
@@ -152,6 +151,13 @@ export function autoPruneStorage(brainDir, vaultDir, conflictsDir) {
           if (activeResearchSlugs.has(baseName)) {
             continue;
           }
+          // Lesson drafts remain reviewable until promotion or explicit disposition.
+          if (dir.startsWith(inboxDir) && file.endsWith('.md')) {
+            try {
+              const { data } = matter(fs.readFileSync(fullPath, 'utf8'));
+              if (data.x_review_hold || data.tags?.includes('post-mortem') || data.tags?.includes('lesson-review')) continue;
+            } catch { continue; }
+          }
           if (now - stat.mtimeMs > maxAge) {
             fs.unlinkSync(fullPath);
           }
@@ -244,22 +250,14 @@ export function autoPruneStorage(brainDir, vaultDir, conflictsDir) {
 
 import { 
   generateMemoryCleanupProposals,
-  generateStaleKnowledgeRefreshProposals,
   evaluateProposalGate,
   dedupeProposals,
+  runSmartDecay,
 } from './optimizer.mjs';
 import { applyAcceptedProposals } from './proposal-applier.mjs';
 
 const DREAM_PROMOTION_THRESHOLD = 0.7;
 
-// Master switch for the stale-knowledge-refresh *ticket generator* (see PHASE 4).
-// Disabled 2026-08-01: it filed one .md per stale node every cycle (16,401
-// unread tickets at its peak). Its successor, which queued "Verify
-// still-current" research every cycle, was removed too (RESEARCH_SYSTEM2):
-// research runs only when a human asks or a project needs it. Stale nodes are
-// listed for a human by `total-recall proposals stale` / GET /api/proposals/stale.
-const ENABLE_STALE_KNOWLEDGE_REFRESH = false;
-
 /**
  * Phase 1: Light Sleep. Scan for modifications.
  */
@@ -298,6 +296,7 @@ export function loadCandidatesFromInbox(brainDirPath) {
         const { data, content } = matter(raw);
         if (!data || (!data.slug && !data.title && !String(content || '').trim())) continue;
         const status = data.status || 'draft';
+        if (data.x_review_hold === true) continue;
         if (status === 'archived' || status === 'active') continue;
         candidates.push({
           ...data,
@@ -319,91 +318,12 @@ export function loadCandidatesFromInbox(brainDirPath) {
   return candidates;
 }
 
-/**
- * Lightweight session → candidate extraction (deterministic heuristics).
- * User lines that signal durable preferences/rules become draft candidates.
- */
-export function loadCandidatesFromSessions(sessionsDir, { maxFiles = 8, maxCandidates = 20 } = {}) {
-  const candidates = [];
-  if (!fs.existsSync(sessionsDir)) return candidates;
-
-  const signal =
-    /\b(always|never|prefer|remember|must not|must|invariant|don't|do not|from now on)\b/i;
-
-  let files = [];
-  try {
-    files = fs
-      .readdirSync(sessionsDir)
-      .filter((f) => f.endsWith('.jsonl'))
-      .map((f) => ({
-        name: f,
-        mtime: fs.statSync(path.join(sessionsDir, f)).mtimeMs,
-      }))
-      .sort((a, b) => b.mtime - a.mtime)
-      .slice(0, maxFiles);
-  } catch {
-    return candidates;
-  }
-
-  for (const file of files) {
-    let lines;
-    try {
-      lines = fs.readFileSync(path.join(sessionsDir, file.name), 'utf8').split('\n').filter(Boolean);
-    } catch {
-      continue;
-    }
-    for (const line of lines) {
-      if (candidates.length >= maxCandidates) return candidates;
-      let entry;
-      try {
-        entry = JSON.parse(line);
-      } catch {
-        continue;
-      }
-      const content = entry.content || entry.text || '';
-      if (!content || content.length < 24 || content.length > 2000) continue;
-      if (entry.type === 'tool_call') continue;
-      const role = entry.role;
-      if (role && role !== 'user' && role !== 'human') continue;
-      if (!signal.test(content)) continue;
-
-      const hash = crypto.createHash('sha256').update(content).digest('hex').slice(0, 10);
-      candidates.push({
-        slug: `session-extract-${hash}`,
-        category: 'preferences',
-        title: content.slice(0, 80).replace(/\s+/g, ' '),
-        status: 'draft',
-        confidence: 0.55,
-        importance: 3,
-        evidence_count: 1,
-        modality: /must not|never|don't|do not/i.test(content) ? 'must_not' : 'should',
-        subject: 'user',
-        predicate: 'prefers',
-        object: 'behavior',
-        tags: ['session-extract', 'dream-rem'],
-        source: {
-          type: 'session',
-          session_id: path.basename(file.name, '.jsonl'),
-          evidence_count: 1,
-        },
-        body: content,
-      });
-    }
-  }
-  return candidates;
-}
-
-/**
- * Collect all REM candidates (inbox + sessions). Dedupe by slug.
- */
+/** Collect reviewed inbox candidates. Session models run through lesson-review. */
 export function collectRemCandidates({ brainDirPath, sessionsDir }) {
   const bySlug = new Map();
   for (const c of loadCandidatesFromInbox(brainDirPath)) {
     bySlug.set(c.slug, c);
   }
-  for (const c of loadCandidatesFromSessions(sessionsDir)) {
-    if (!bySlug.has(c.slug)) bySlug.set(c.slug, c);
-  }
   return [...bySlug.values()];
 }
 
@@ -444,9 +364,11 @@ export function evaluateCandidates(candidates, existingNodes, conflictsDir) {
  * Main Dream Cycle execution.
  */
 export async function runDreamCycle({
-  vaultDir, skillsDir, derivedDir, conflictsDir, instructionsFile
+  vaultDir, skillsDir, derivedDir, conflictsDir, instructionsFile, runtimeConfig
 }) {
-  const sessionsDir = path.join(brainDir, 'sessions');
+  const cycleBrainDir = path.dirname(vaultDir);
+  const sessionsDir = path.join(cycleBrainDir, 'sessions');
+  const errors = [];
 
   logger.info('dream', 'PHASE 0 — Session Ingestion (IDE Conversation Logs)');
   try {
@@ -462,7 +384,7 @@ export async function runDreamCycle({
   logger.info('dream', `Modified vault files: ${modified.length}`);
 
   const candidates = collectRemCandidates({
-    brainDirPath: brainDir,
+    brainDirPath: cycleBrainDir,
     sessionsDir,
   });
   logger.info('dream', `REM candidates collected: ${candidates.length}`);
@@ -508,6 +430,7 @@ export async function runDreamCycle({
     await compileSurface({ vaultDir, skillsDir, derivedDir, instructionsFile });
     logger.info('dream', 'Surface recompiled successfully');
   } catch (err) {
+    errors.push(`Deep Sleep compile failed: ${err.message}`);
     logger.error('dream', `Deep Sleep compile failed: ${err.message}`);
   }
 
@@ -516,14 +439,16 @@ export async function runDreamCycle({
   try {
     const cleanupProposals = await generateMemoryCleanupProposals(vaultDir);
 
-    // Stale-knowledge-refresh generation is DISABLED. It filed one ticket per
-    // high-importance node untouched for 30 days — ~600 of them — and nothing
-    // in this system ever reads or applies a proposal, so every one was write-
-    // only noise. Flip to true to re-enable; the dedupe gate below keeps it
-    // bounded at one open ticket per target if you do.
-    const staleProposals = ENABLE_STALE_KNOWLEDGE_REFRESH
-      ? await generateStaleKnowledgeRefreshProposals(vaultDir)
-      : [];
+    // DECAY-01: memories the access ledger shows unused for the decay age are judged by the
+    // local reasoning runtime; the gate and applier below verify each one before it applies.
+    let decayProposals = [];
+    try {
+      decayProposals = await runSmartDecay(vaultDir, runtimeConfig, undefined, { derivedDir });
+      logger.info('dream', `Smart decay: ${decayProposals.length} proposal(s).`);
+    } catch (err) {
+      errors.push(`Smart decay failed: ${err.message}`);
+      logger.error('dream', `Smart decay failed: ${err.message}`);
+    }
 
     // The generators are pure functions of vault state, so every cycle produces
     // the SAME proposals as the last one — a node stale on Monday is still stale
@@ -531,7 +456,7 @@ export async function runDreamCycle({
     // random slugs; the global vault accumulated 16,401 proposals for 594 real
     // targets (~28 copies each, ~5k/day) until proposals were 95% of the vault.
     const { kept: allProposals, suppressed } = dedupeProposals(
-      [...cleanupProposals, ...staleProposals],
+      [...cleanupProposals, ...decayProposals],
       vaultDir,
     );
     if (suppressed > 0) {
@@ -560,6 +485,7 @@ export async function runDreamCycle({
       logger.info('dream', `Applied ${applied.applied} proposals (${applied.superseded} superseded, ${applied.failed} failed).`);
     }
   } catch (err) {
+    errors.push(`Optimizer failed: ${err.message}`);
     logger.error('dream', `Optimizer failed: ${err.message}`);
   }
 
@@ -573,18 +499,20 @@ export async function runDreamCycle({
       `Proposals accepted: ${proposalCount}`,
     ]);
   } catch (err) {
+    errors.push(`Daily note write failed: ${err.message}`);
     logger.error('dream', `Daily note write failed: ${err.message}`);
   }
 
   logger.info('dream', 'PHASE 5 — Automatic Storage & Memory Pruning');
   try {
-    autoPruneStorage(brainDir, vaultDir, conflictsDir);
+    autoPruneStorage(cycleBrainDir, vaultDir, conflictsDir);
     logger.info('dream', 'Automated VFS storage pruning completed successfully');
   } catch (err) {
+    errors.push(`Storage pruning failed: ${err.message}`);
     logger.error('dream', `Storage pruning failed: ${err.message}`);
   }
 
-  return { status: 'success' };
+  return errors.length ? { status: 'failed', errors } : { status: 'success' };
 }
 
 // ─── Standalone Daemon Execution ────────────────────────────────────────────────

package/src/core/ensure-dependencies.mjs

@@ -0,0 +1,148 @@
+/** Restore a repository's locked dependencies before edit or test work. */
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+export const DEFAULT_INSTALL_TIMEOUT_MS = 300_000;
+const MARKER = '.total-recall-install.json';
+const LOCKFILES = [
+  ['npm', 'npm-shrinkwrap.json'], ['npm', 'package-lock.json'],
+  ['pnpm', 'pnpm-lock.yaml'], ['yarn', 'yarn.lock'],
+  ['bun', 'bun.lock'], ['bun', 'bun.lockb'],
+];
+const pending = new Map();
+// The package this module runs from. `npm ci` deletes node_modules before installing, so running
+// it here breaks every total-recall command, the preflight gate included, for the whole install
+// (2026-11-10: the release's checks and every agent tool call failed until a manual install).
+const RUNNING_PACKAGE_ROOT = (() => {
+  try { return fs.realpathSync(path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..')); }
+  catch { return null; }
+})();
+
+/**
+ * npm records the tree it installed in node_modules/.package-lock.json. The tree matches the
+ * lockfile when every installed package has the locked version and every required locked package
+ * is installed (optional packages may be absent on this platform; workspace links are not copies).
+ */
+export function npmTreeMatchesLock(root) {
+  let lock, installed;
+  try {
+    lock = JSON.parse(fs.readFileSync(path.join(root, 'package-lock.json'), 'utf8')).packages;
+    installed = JSON.parse(fs.readFileSync(path.join(root, 'node_modules', '.package-lock.json'), 'utf8')).packages;
+  } catch { return false; }
+  if (!lock || !installed) return false;
+  for (const [key, entry] of Object.entries(installed)) {
+    if (!key || entry.link) continue;
+    if (!lock[key] || lock[key].version !== entry.version) return false;
+  }
+  for (const [key, entry] of Object.entries(lock)) {
+    if (!key.startsWith('node_modules/') && !key.includes('/node_modules/')) continue;
+    if (entry.optional || entry.link || entry.peer) continue;
+    if (!installed[key]) return false;
+  }
+  return true;
+}
+
+const hash = file => crypto.createHash('sha256').update(fs.readFileSync(file)).digest('hex');
+
+/** No shell, bounded output, and a deadline that also stops lifecycle-script children. */
+function runInstall(command, args, { cwd, timeoutMs }) {
+  return new Promise(resolve => {
+    const child = spawn(command, args, {
+      cwd, env: { ...process.env, CI: 'true' }, detached: process.platform !== 'win32',
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    let output = '', timedOut = false, error = null;
+    const collect = chunk => { output += chunk.toString().slice(0, Math.max(0, 65536 - output.length)); };
+    child.stdout.on('data', collect);
+    child.stderr.on('data', collect);
+    const timer = setTimeout(() => {
+      timedOut = true;
+      try {
+        if (process.platform === 'win32') child.kill('SIGKILL');
+        else process.kill(-child.pid, 'SIGKILL');
+      } catch { /* the install already exited */ }
+    }, timeoutMs);
+    child.on('error', err => { error = err.message; });
+    child.on('close', (exitCode, signal) => {
+      clearTimeout(timer);
+      resolve({ exitCode, signal, timedOut, output, error });
+    });
+  });
+}
+
+async function ensure(root, { reason = 'work', timeoutMs = DEFAULT_INSTALL_TIMEOUT_MS, run = runInstall, packageRoot = RUNNING_PACKAGE_ROOT } = {}) {
+  const started = Date.now();
+  const base = { root, reason, manager: null, lockfile: null, command: null };
+  const result = (status, fields = {}) => ({ ...base, ok: status !== 'failed', status, durationMs: Date.now() - started, ...fields });
+  try {
+    if (!Number.isInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 600_000) throw new Error('Install timeout must be 1..600000 ms');
+    const locks = LOCKFILES.filter(([, file]) => fs.existsSync(path.join(root, file)));
+    if (!locks.length) return result('skipped', { trigger: 'no-lockfile' });
+    const manifest = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8'));
+    const declared = manifest.packageManager?.split('@')[0];
+    const managers = new Set(locks.map(([manager]) => manager));
+    const manager = declared || (managers.size === 1 ? locks[0][0] : null);
+    if (!manager || !managers.has(manager)) throw new Error('Lockfiles do not identify one package manager; set package.json packageManager to a manager with a lockfile');
+    const lockfile = locks.find(([name]) => name === manager)[1];
+    const lockPath = path.join(root, lockfile);
+    const lockHash = hash(lockPath);
+    const lockMtimeMs = fs.statSync(lockPath).mtimeMs;
+    const modernYarn = manager === 'yarn' && (/^yarn@(?:[2-9]|\d{2,})\./.test(manifest.packageManager || '') || /^__metadata:/m.test(fs.readFileSync(lockPath, 'utf8')));
+    const args = manager === 'npm' ? ['ci'] : ['install', modernYarn ? '--immutable' : '--frozen-lockfile'];
+    Object.assign(base, { manager, lockfile, command: [manager, ...args] });
+    const installDir = () => path.join(root, modernYarn && fs.existsSync(path.join(root, '.pnp.cjs')) ? '.yarn' : 'node_modules');
+    const markerPath = () => path.join(installDir(), MARKER);
+    let marker;
+    try { marker = JSON.parse(fs.readFileSync(markerPath(), 'utf8')); } catch { /* no trusted install */ }
+    const current = marker?.version === 1 && marker.manager === manager && marker.lockfile === lockfile
+      && marker.lockHash === lockHash && marker.lockMtimeMs === lockMtimeMs;
+    if (current) return result('current');
+    const writeMarker = () => {
+      fs.mkdirSync(installDir(), { recursive: true });
+      fs.writeFileSync(markerPath(), `${JSON.stringify({ version: 1, manager, lockfile, lockHash, lockMtimeMs, installedAt: new Date().toISOString() })}\n`);
+    };
+    // Installed by hand or by an earlier npm run: npm's own record says the tree is current.
+    if (manager === 'npm' && lockfile === 'package-lock.json' && npmTreeMatchesLock(root)) {
+      writeMarker();
+      return result('current', { trigger: 'npm-tree-record' });
+    }
+    // Never reinstall the package this process runs from: the install would delete the code
+    // that is running, and every other total-recall process with it.
+    if (packageRoot && root === packageRoot) {
+      return result('failed', { trigger: 'running-package', error: `${root} is the Total Recall package this command runs from and its dependencies do not match ${lockfile}. Run '${manager} install' there yourself; it is never reinstalled automatically.` });
+    }
+    const trigger = fs.existsSync(installDir()) ? 'stale' : 'missing';
+    // A failed reinstall must not leave an old marker that can certify a partial install.
+    fs.rmSync(markerPath(), { force: true });
+    const installed = await run(manager, args, { cwd: root, timeoutMs });
+    if (installed.error || installed.timedOut || installed.exitCode !== 0) {
+      return result('failed', { ...installed, trigger, error: installed.error || (installed.timedOut ? `Install timed out after ${timeoutMs} ms` : `Install exited ${installed.exitCode ?? installed.signal ?? 'without a status'}`) });
+    }
+    if (hash(lockPath) !== lockHash || fs.statSync(lockPath).mtimeMs !== lockMtimeMs) throw new Error('Lockfile changed during install; retry with the current lockfile');
+    fs.mkdirSync(installDir(), { recursive: true });
+    const stamp = { version: 1, manager, lockfile, lockHash, lockMtimeMs, installedAt: new Date().toISOString() };
+    fs.writeFileSync(markerPath(), `${JSON.stringify(stamp)}\n`);
+    return result('installed', { trigger });
+  } catch (err) {
+    return result('failed', { error: err.message });
+  }
+}
+
+/**
+ * @returns {Promise<{ok:boolean, status:string, root:string, reason:string, manager:string|null, lockfile:string|null, command:string[]|null, durationMs:number}>}
+ * `run` is a fixture seam. Production callers use the bounded installer above.
+ * Concurrent callers in this host process share one install for the same real root.
+ */
+export async function ensureDependencies(root, options = {}) {
+  let resolved;
+  try { resolved = fs.realpathSync(root); }
+  catch (err) { return { ok: false, status: 'failed', root, reason: options.reason || 'work', manager: null, lockfile: null, command: null, durationMs: 0, error: err.message }; }
+  if (pending.has(resolved)) return pending.get(resolved);
+  const job = ensure(resolved, options);
+  pending.set(resolved, job);
+  try { return await job; }
+  finally { pending.delete(resolved); }
+}

package/src/core/fast-recall.mjs

@@ -73,7 +73,7 @@ function readIndex(file) {
 
 /** Local retrieval never imports the whole-vault cache or a provider. */
 export function fastSearch(query, { derivedDir, vaultDir, top_k = 5, category = null,
-  tags = null, modality = null, importance = null, priority = null, fullText = false } = {}) {
+  tags = null, modality = null, importance = null, priority = null, fullText = false, rankResults = null } = {}) {
   const started = performance.now();
   const stats = { mode: fullText ? 'local-full-text' : 'local-metadata', index: 'missing',
     freshness: 'index-snapshot; selected documents verified against canonical Markdown', hydrated_documents: 0, stale_documents: 0 };
@@ -114,7 +114,7 @@ export function fastSearch(query, { derivedDir, vaultDir, top_k = 5, category =
   candidates.sort((a, b) => b.score - a.score);
   stats.match_ms = performance.now() - started - stats.index_ms;
   const hydration = performance.now();
-  for (const candidate of candidates) {
+  for (const candidate of rankResults ? rankResults(candidates) : candidates) {
     if (results.length >= Math.max(1, Math.min(20, top_k))) break;
     if (!vaultDir) { results.push(candidate); continue; }
     const relative = candidate.relative || (isSafeVaultName(candidate.category) && isSafeVaultName(candidate.slug) ? `${candidate.category}/${candidate.slug}.md` : null);

package/src/core/field-evaluation.mjs

@@ -0,0 +1,23 @@
+/** Paired local recall evaluation. The caller fixes the corpus, labels and query order. */
+export async function evaluateField(cases, { search, topK = 5 } = {}) {
+  if (!Number.isInteger(topK) || topK < 1 || topK > 20) throw new Error('topK must be an integer from 1 to 20');
+  if (!Array.isArray(cases) || !cases.length || cases.some(entry =>
+    typeof entry?.query !== 'string' || !entry.query.trim() || !Array.isArray(entry.relevant) ||
+    !entry.relevant.length || entry.relevant.some(slug => typeof slug !== 'string' || !slug.trim()))) {
+    throw new Error('Queries must be a nonempty array of { query, relevant: [slug, ...] }');
+  }
+  const rows = [];
+  for (const entry of cases) {
+    const baseline = (await search(entry.query, false)).slice(0, topK).map(result => result.slug);
+    const field = (await search(entry.query, true)).slice(0, topK).map(result => result.slug);
+    const shared = new Set(baseline.filter(slug => field.includes(slug))).size;
+    rows.push({ query: entry.query, relevant: entry.relevant, baseline, field,
+      overlap: shared / topK,
+      baseline_hit: baseline.some(slug => entry.relevant.includes(slug)),
+      field_hit: field.some(slug => entry.relevant.includes(slug)) });
+  }
+  const average = key => rows.reduce((sum, row) => sum + Number(row[key]), 0) / rows.length;
+  return { mode: 'local', top_k: topK, query_count: rows.length,
+    top_k_overlap: average('overlap'), baseline_hit_rate: average('baseline_hit'),
+    field_hit_rate: average('field_hit'), default_enabled: false, queries: rows };
+}

package/src/core/gate-mode.mjs

@@ -4,7 +4,7 @@
  * The preflight receipt is not one of these rules and has no mode.
  *
  * Settings live in `config/gate.json` in a brain:
- *   { "default": "warn", "router": "enforce", "plugins": { "git-sentinel": "enforce" } }
+ *   { "default": "warn", "router": "enforce", "plugins": { "git": "enforce" } }
  * The repository's brain wins over the machine's. This runs on every tool call, so it reads the
  * files directly, and an unreadable file or unknown value counts as unset: a bad settings file
  * must never be what blocks work.

package/src/core/harness-hooks.mjs

@@ -15,7 +15,7 @@ export async function loadGateAdapters(projectRoot = process.cwd()) {
 }
 
 /** Never throws: an install must finish, and a failure must be reported. */
-export async function installHarnessHooks({ projectRoot, dryRun = false, log = (line) => console.error(line) } = {}) {
+export async function installHarnessHooks({ projectRoot, home, dryRun = false, log = (line) => console.error(line) } = {}) {
   try {
     const { adapters, failures } = await loadGateAdapters(projectRoot);
     if (!adapters?.installAll) {
@@ -23,12 +23,18 @@ export async function installHarnessHooks({ projectRoot, dryRun = false, log = (
       log(`  ✖ Harness hooks not installed: ${cause}`);
       return { ok: false, rows: [], error: cause };
     }
-    const result = await adapters.installAll({ dryRun });
+    const result = await adapters.installAll({ dryRun, ...(home ? { home } : {}) });
+    const { installLessonHooks } = await import('./lesson-hooks.mjs');
+    for (const row of result.rows) {
+      try { row.lessons = installLessonHooks(row, { dryRun }); }
+      catch (error) { row.lessons = { status: 'failed', error: error.message }; result.ok = false; }
+    }
     const active = result.rows.filter((row) => row.status !== 'not-present');
     log(`  ${result.ok ? '✔' : '✖'} Harness hooks: ${active.map((row) => `${row.harness} ${row.status}`).join(', ') || 'no harness on this machine'}`);
     for (const row of active) {
       const note = row.note || row.reason;
       if (note) log(`    ${row.harness}: ${note}`);
+      if (row.lessons?.error || row.lessons?.note) log(`    ${row.harness} lessons: ${row.lessons.error || row.lessons.note}`);
     }
     return result;
   } catch (err) {
@@ -50,6 +56,12 @@ export async function removeHarnessHooks({ projectRoot, dryRun = false, log = (l
       log(`  ✖ Harness hooks not removed: ${cause}`);
       return { ok: false, rows: [], error: cause };
     }
+    const { installLessonHooks } = await import('./lesson-hooks.mjs');
+    // Find each owner's settings before removal can remove the path.
+    for (const adapter of adapters.list()) {
+      const existing = await adapter.install({ dryRun: true, remove: true });
+      if (existing.settings) installLessonHooks({ harness: adapter.id, settings: existing.settings, status: 'installed' }, { dryRun, remove: true });
+    }
     const result = await adapters.removeAll({ dryRun });
     const removed = result.rows.filter((row) => row.status === 'removed').map((row) => row.harness);
     log(`  ${result.ok ? '✔' : '✖'} Harness hooks: ${removed.length ? `removed from ${removed.join(', ')}` : 'none present'}`);

package/src/core/lesson-hooks.mjs

@@ -0,0 +1,74 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { parseDocument } from 'yaml';
+import { atomicWrite } from './vault.mjs';
+
+const managed = hook => String(hook?.command || '').includes('total-recall lessons ');
+const command = (harness, end = false) => `total-recall lessons ${end ? 'session-end' : 'tick'} --harness ${harness} --global`;
+
+/** Extend the existing installer's selected settings file. Preserve unrelated hooks. */
+export function installLessonHooks(row, { dryRun = false, remove = false } = {}) {
+  const { harness, settings } = row;
+  if (!settings || ['not-present', 'failed', 'unsupported'].includes(row.status)) return { status: 'session-ingest' };
+  if (harness === 'hermes') {
+    const text = fs.existsSync(settings) ? fs.readFileSync(settings, 'utf8') : '';
+    const doc = parseDocument(text || '{}');
+    if (doc.errors.length) throw new Error(`Invalid Hermes hook settings: ${doc.errors[0].message}`);
+    for (const [event, end] of [['post_llm_call', false], ['on_session_finalize', true]]) {
+      const old = doc.getIn(['hooks', event])?.toJSON() || [];
+      if (!Array.isArray(old)) throw new Error(`Hermes ${event} hooks must be a list`);
+      const hooks = old.filter(hook => !managed(hook));
+      if (!remove) hooks.push({ command: command(harness, end), timeout: 10 });
+      doc.setIn(['hooks', event], hooks);
+    }
+    if (!dryRun) atomicWrite(settings, String(doc));
+    return { status: remove ? 'removed' : dryRun ? 'would-install' : 'installed', settings };
+  }
+  if (harness === 'pi') {
+    const file = path.join(path.dirname(settings), 'total-recall-lessons.ts');
+    if (!dryRun) {
+      if (remove) fs.rmSync(file, { force: true });
+      else atomicWrite(file, PI_LESSONS_EXTENSION);
+    }
+    return { status: remove ? 'removed' : dryRun ? 'would-install' : 'installed', settings: file };
+  }
+  const events = harness === 'cursor' ? [['stop', false], ['sessionEnd', true]]
+    : ['claude', 'codex', 'dsh', 'agy'].includes(harness) ? [['Stop', false], ['SessionEnd', true]] : null;
+  if (!events || !settings.endsWith('.json')) return { status: 'session-ingest', note: 'Native lesson hook requires the harness owner; use session-end ingest.' };
+  const text = fs.existsSync(settings) ? fs.readFileSync(settings, 'utf8') : '{}';
+  const config = JSON.parse(text);
+  const hooks = harness === 'agy' ? (config['total-recall-lessons'] ||= {}) : (config.hooks ||= {});
+  for (const [event, end] of events) {
+    const old = hooks[event] || [];
+    if (!Array.isArray(old)) throw new Error(`${harness} ${event} hooks must be a list`);
+    // Remove only our command even when a group contains another owner's hook.
+    hooks[event] = old.flatMap(group => {
+      if (Array.isArray(group.hooks)) {
+        const kept = group.hooks.filter(hook => !managed(hook));
+        return kept.length ? [{ ...group, hooks: kept }] : [];
+      }
+      return managed(group) ? [] : [group];
+    });
+    if (!remove) hooks[event].push(harness === 'cursor' ? { command: command(harness, end), timeout: 10 }
+      : { hooks: [{ type: 'command', command: command(harness, end), timeout: 10 }] });
+  }
+  if (!dryRun) atomicWrite(settings, JSON.stringify(config, null, 2) + '\n');
+  return { status: remove ? 'removed' : dryRun ? 'would-install' : 'installed', settings };
+}
+
+export const PI_LESSONS_EXTENSION = `import { spawn } from 'node:child_process';
+export default function (pi) {
+  const review = (event, ctx) => new Promise((resolve) => {
+    const entries = ctx.sessionManager.getBranch().filter(e => e.type === 'message').map(e => e.message);
+    const child = spawn('total-recall', ['lessons', event, '--harness', 'pi', '--global'], { stdio: ['pipe', 'ignore', 'pipe'] });
+    child.on('error', error => { console.error('Total Recall lessons:', error.message); resolve(); });
+    child.stderr.on('data', data => console.error(String(data)));
+    child.stdin.on('error', () => {});
+    child.stdin.end(JSON.stringify({ session_id: ctx.sessionManager.getSessionId(), entries }));
+    const timer = setTimeout(() => child.kill('SIGKILL'), 10000);
+    child.on('close', () => { clearTimeout(timer); resolve(); });
+  });
+  pi.on('agent_end', (_event, ctx) => review('tick', ctx));
+  pi.on('session_shutdown', (_event, ctx) => review('session-end', ctx));
+}
+`;

package/src/core/lesson-memory.mjs

@@ -0,0 +1,24 @@
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+import { execFile } from 'node:child_process';
+import { loadNodes } from './vault.mjs';
+
+const cli = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../bin/total-recall.mjs');
+
+/** Use remember's length, duplicate and validated-write guards, with a pinned brain. */
+export function rememberLessonRule(content, { brainDir, title, sourceRef, hold = false, execute = execFile } = {}) {
+  if (typeof content !== 'string' || !content.trim()) throw new Error('Lesson rule has no content');
+  const agentDir = path.resolve(brainDir, '../..');
+  if (path.resolve(agentDir, 'skills', 'total-recall') !== path.resolve(brainDir)) throw new Error('Lesson remember requires a standard brain path');
+  const slug = `lesson-rule-${crypto.createHash('sha256').update(content).digest('hex').slice(0, 16)}`;
+  const existing = loadNodes(path.join(brainDir, 'memory-vault')).find(node => node.slug === slug);
+  if (existing && existing.body?.trim() === content.trim()) return Promise.resolve({ slug, existing: true });
+  const args = [cli, 'remember', 'invariant', content, '--global', '--slug', slug,
+    '--status', hold ? 'draft' : 'active', '--tags', 'lesson-review',
+    ...(title ? ['--title', title] : [])];
+  return new Promise((resolve, reject) => {
+    execute(process.execPath, args, { env: { ...process.env, AGENT_DIR: agentDir, TR_SESSION_ID: sourceRef }, timeout: 120_000, maxBuffer: 1024 * 1024 },
+      (error, stdout, stderr) => error ? reject(new Error(`Lesson remember failed: ${stderr || error.message}`)) : resolve({ slug, stdout }));
+  });
+}

package/src/core/lesson-sessions.mjs

@@ -0,0 +1,52 @@
+import fs from 'node:fs';
+
+const text = value => typeof value === 'string' ? value : Array.isArray(value)
+  ? value.map(block => block.text || (block.type === 'tool_result' ? text(block.content) : JSON.stringify(block))).join('\n')
+  : value == null ? '' : JSON.stringify(value);
+
+/** Normalize native hook transcripts and the session-ingest format. Keep tool evidence. */
+export function readLessonEntries(file) {
+  const records = fs.readFileSync(file, 'utf8').split('\n').filter(Boolean).flatMap(line => {
+    try { return [JSON.parse(line)]; } catch { return []; }
+  });
+  // Codex records messages both as event notifications and as response items.
+  const hasResponseMessages = records.some(row => row.type === 'response_item' && row.payload?.type === 'message');
+  return records.flatMap(row => {
+    let message = row.message || row;
+    if (row.type === 'response_item') {
+      message = row.payload || {};
+      if (message.type === 'function_call' || message.type === 'function_call_output') {
+        return [{ role: 'tool', content: text(message), ts: row.timestamp }];
+      }
+      if (message.type !== 'message') return [];
+    } else if (row.type === 'event_msg') {
+      if (hasResponseMessages) return [];
+      const payload = row.payload || {};
+      if (!['user_message', 'agent_message'].includes(payload.type)) return [];
+      message = { role: payload.type === 'user_message' ? 'user' : 'assistant', content: payload.message };
+    }
+    let role = message.role || row.role;
+    if (role === 'human') role = 'user';
+    if (!['user', 'assistant', 'tool'].includes(role)) return [];
+    const content = [text(message.content ?? message.text), ...(message.tool_calls ? [JSON.stringify(message.tool_calls)] : [])].filter(Boolean).join('\n');
+    if (!content.trim()) return [];
+    // Claude tool results have role user, but do not start a user turn.
+    if (Array.isArray(message.content) && message.content.every(block => block.type === 'tool_result')) role = 'tool';
+    return [{ role, content, ts: row.ts || row.timestamp, ...(row.cwd ? { cwd: row.cwd } : {}) }];
+  });
+}
+
+export function countLessonTurns(entries) {
+  return entries.filter(entry => entry.role === 'user').length;
+}
+
+export function selectLessonTurns(entries, { fromTurn = 1, toTurn = Infinity } = {}) {
+  if (!Number.isInteger(fromTurn) || fromTurn < 1 || !(toTurn === Infinity || Number.isInteger(toTurn)) || toTurn < fromTurn) {
+    throw new Error('Lesson turn range must be positive and ordered');
+  }
+  let turn = 0;
+  return entries.filter(entry => {
+    if (entry.role === 'user') turn++;
+    return turn >= fromTurn && turn <= toTurn;
+  });
+}