pan-wizard 3.33.0 → 3.34.0

package/pan-wizard-core/bin/lib/memory.cjs

@@ -1,9 +1,15 @@
 /**
- * Memory — cross-phase agent memory layer
+ * Memory — the agent memory store
  *
  * Each agent has an append-only memory log at `.planning/memory/<agent>.md`.
- * Agents read their memory at start of each invocation and append lessons
- * learned at end. Compaction keeps file size bounded.
+ * Compaction keeps file size bounded.
+ *
+ * PAN's workflows do not load this store into agents (ADR-0036, amended
+ * `2026-10-04`). The harness found that a recorded lesson changed no phase's work
+ * beyond what state.md, the summaries and the code already carried, so exec-phase
+ * and plan-phase stopped injecting it and nothing writes to it automatically. The
+ * store, these commands and hygiene remain for anyone who records lessons by hand;
+ * `/pan:knowledge` reads it.
  *
  * File format: a markdown file with a stable YAML frontmatter header and
  * an append-only "## Entries" section containing one bullet per entry:
@@ -17,17 +23,41 @@
  *
  *   - 2026-04-18: Prefer bulk writes over per-row commits for Postgres
  *   - 2026-04-19: ...
+ *
+ * Cited, verified, expiring entries (memory optimisation O4 — the Copilot Memory
+ * pattern). An entry may end in a metadata comment:
+ *
+ *   - 2026-10-04: Batch inserts through the writer <!-- cites: src/db/writer.js#bulkInsert; used: 2026-10-12 -->
+ *
+ * `cites` names the code the lesson rests on (`path` or `path#symbol`, relative to
+ * the project root). `memory select` checks every citation against the working
+ * tree and leaves out an entry whose evidence is gone. `used` is the last day the
+ * entry was selected with `memory select --mark-used`. An entry not used for
+ * MEMORY_EXPIRE_DAYS is left out too, and `memory prune` archives both kinds to
+ * `.planning/memory/archive/<agent>.md`, never deleting.
+ *
+ * Not every file in `.planning/memory/` is an agent log. RESERVED_MEMORY_NAMES
+ * are PAN's own archives there, and they are never loaded as memory: the
+ * quarantine holds directives PAN refused to follow (ADR-0040).
  */
 
 const fs = require('fs');
 const path = require('path');
-const { output, error } = require('./core.cjs');
-const { CHARS_PER_TOKEN, MEMORY_SELECT_BUDGET_TOKENS, MEMORY_RECENCY_FLOOR, MEMORY_SOFT_CAP_MULT, MEMORY_LOAD_WARN_TOKENS, MEMORY_LOAD_CRIT_TOKENS, MEMORY_LOAD_MAX_FRACTION } = require('./constants.cjs');
-const { planningPath } = require('./utils.cjs');
+const { output, error, toLf, dominantEol, withEol } = require('./core.cjs');
+const { CHARS_PER_TOKEN, MEMORY_SELECT_BUDGET_TOKENS, MEMORY_RECENCY_FLOOR, MEMORY_SOFT_CAP_MULT, MEMORY_LOAD_WARN_TOKENS, MEMORY_LOAD_CRIT_TOKENS, MEMORY_LOAD_MAX_FRACTION, MEMORY_EXPIRE_DAYS, MEMORY_CITED_FILE_MAX_BYTES } = require('./constants.cjs');
+const { planningPath, planningRel } = require('./utils.cjs');
 
 const MEMORY_DIR = 'memory';
+const MEMORY_ARCHIVE_DIR = 'archive';
 const DEFAULT_MAX_ENTRIES = 500;
 const AGENT_NAME_RE = /^[a-zA-Z0-9_-]+$/;
+/**
+ * Files PAN writes into `.planning/memory/` that are not agent logs: the ADR-0040
+ * quarantine (memory-optimize QUARANTINE_FILE), the state.md archive
+ * (STATE_ARCHIVE_FILE) and distill's patterns (distill PATTERNS_FILE). A test
+ * pins these names to those constants.
+ */
+const RESERVED_MEMORY_NAMES = ['quarantine', 'state-archive', 'distill-patterns'];
 
 function memoryDir(cwd) {
   return path.join(planningPath(cwd), MEMORY_DIR);
@@ -37,13 +67,124 @@ function memoryFile(cwd, agent) {
   return path.join(memoryDir(cwd), `${agent}.md`);
 }
 
+function isReservedMemoryName(name) {
+  return RESERVED_MEMORY_NAMES.includes(String(name).toLowerCase());
+}
+
 function validateAgentName(agent) {
   if (typeof agent !== 'string' || !AGENT_NAME_RE.test(agent)) {
     return `Invalid agent name: ${agent}. Must match ${AGENT_NAME_RE}`;
   }
+  if (isReservedMemoryName(agent)) {
+    return `${agent}.md is one of PAN's archives in .planning/memory/, not an agent log; it is never read or written as memory`;
+  }
   return null;
 }
 
+// ─── Entry metadata: citations and last use (O4) ────────────────────────────
+
+const ENTRY_META_RE = /\s*<!--\s*((?:cites|evidence|used|uses)\s*:[^>]*?)\s*-->\s*$/i;
+const ENTRY_DATE_RE = /^(\d{4}-\d{2}-\d{2}):\s*/;
+
+/**
+ * An entry's parts: `{ date, text, cites: string[], evidence, used, uses }`.
+ * `evidence` is the observed failure a recorded lesson came from (`finding:f_…` or
+ * `trace:<session>`, O6); `uses` counts the days it was selected with `--mark-used`.
+ */
+function parseEntryMeta(entry) {
+  const s = String(entry == null ? '' : entry);
+  const m = s.match(ENTRY_META_RE);
+  const body = m ? s.slice(0, m.index) : s;
+  const d = body.match(ENTRY_DATE_RE);
+  const meta = { date: d ? d[1] : null, text: d ? body.slice(d[0].length) : body, cites: [], evidence: null, used: null, uses: 0 };
+  if (m) {
+    for (const field of m[1].split(';')) {
+      const kv = field.match(/^\s*(cites|evidence|used|uses)\s*:\s*(.*?)\s*$/i);
+      if (!kv) continue;
+      const key = kv[1].toLowerCase();
+      if (key === 'cites') meta.cites = kv[2].split(',').map(c => c.trim()).filter(Boolean);
+      else if (key === 'evidence') meta.evidence = kv[2] || null;
+      else if (key === 'used') { if (/^\d{4}-\d{2}-\d{2}$/.test(kv[2])) meta.used = kv[2]; }
+      else if (/^\d+$/.test(kv[2])) meta.uses = Number(kv[2]);
+    }
+  }
+  return meta;
+}
+
+/** The entry string for `meta` — the inverse of parseEntryMeta. */
+function formatEntry(meta) {
+  const fields = [];
+  if (meta.cites && meta.cites.length) fields.push(`cites: ${meta.cites.join(', ')}`);
+  if (meta.evidence) fields.push(`evidence: ${meta.evidence}`);
+  if (meta.used) fields.push(`used: ${meta.used}`);
+  if (meta.uses) fields.push(`uses: ${meta.uses}`);
+  const head = meta.date ? `${meta.date}: ${meta.text}` : meta.text;
+  return fields.length ? `${head} <!-- ${fields.join('; ')} -->` : head;
+}
+
+/**
+ * Why a citation (`path` or `path#symbol`) does not hold in the working tree, or
+ * null when it does. Paths are relative to the project root and may not leave it.
+ * A symbol made of word characters must appear as a whole word; any other symbol
+ * as a substring.
+ */
+function citationProblem(cwd, cite) {
+  const s = String(cite || '');
+  const hash = s.indexOf('#');
+  const rel = hash === -1 ? s : s.slice(0, hash);
+  const symbol = hash === -1 ? '' : s.slice(hash + 1);
+  if (!rel || path.isAbsolute(rel) || /^[A-Za-z]:/.test(rel)) return 'not a project-relative path';
+  const root = path.resolve(cwd);
+  const abs = path.resolve(root, rel);
+  if (abs !== root && !abs.startsWith(root + path.sep)) return 'outside the project';
+  // One open handle for the check and the read, so the file cannot change between them.
+  let fd;
+  try { fd = fs.openSync(abs, 'r'); } catch { return 'file not found'; }
+  let text;
+  try {
+    const st = fs.fstatSync(fd);
+    if (!symbol) return null;
+    if (!st.isFile()) return 'a symbol needs a file';
+    if (st.size > MEMORY_CITED_FILE_MAX_BYTES) return null;
+    try { text = fs.readFileSync(fd, 'utf-8'); } catch { return 'unreadable'; }
+  } finally { fs.closeSync(fd); }
+  const found = /^\w+$/.test(symbol) ? new RegExp(`\\b${symbol}\\b`).test(text) : text.includes(symbol);
+  return found ? null : `\`${symbol}\` not found`;
+}
+
+function daysSince(isoDate, now) {
+  return Math.floor((now - Date.parse(`${isoDate}T00:00:00Z`)) / 86400000);
+}
+
+/**
+ * Whether `memory select` returns an entry: `valid`, `expired` (not used for `expireDays`;
+ * checked first, it needs no file reads) or `stale` (a citation no longer holds).
+ * An undated entry never expires; an uncited one is never stale.
+ */
+function entryStatus(cwd, entry, { now = Date.now(), expireDays = MEMORY_EXPIRE_DAYS } = {}) {
+  const meta = parseEntryMeta(entry);
+  const last = meta.used || meta.date;
+  if (last && expireDays > 0) {
+    const age = daysSince(last, now);
+    if (age > expireDays) return { status: 'expired', meta, last_used: last, age_days: age };
+  }
+  const missing = [];
+  for (const c of meta.cites) {
+    const p = citationProblem(cwd, c);
+    if (p) missing.push(`${c} (${p})`);
+  }
+  return missing.length ? { status: 'stale', meta, missing } : { status: 'valid', meta };
+}
+
+function isoDay(now) {
+  return new Date(now).toISOString().slice(0, 10);
+}
+
+function expireDaysFrom(v) {
+  const n = Number(v);
+  return v != null && v !== '' && Number.isInteger(n) && n >= 0 ? n : MEMORY_EXPIRE_DAYS;
+}
+
 function today() {
   return new Date().toISOString().slice(0, 10);
 }
@@ -73,28 +214,41 @@ function readMemory(cwd, agent) {
  * @returns {string[]} ordered entries (oldest → newest, as stored)
  */
 function parseEntries(raw) {
-  const entries = [];
-  const lines = raw.split(/\r?\n/);
+  const lines = toLf(raw).split('\n');
+  return entryLineIndexes(lines).map(i => lines[i].match(/^-\s+(.+)$/)[1]);
+}
+
+/** Line indexes of the `## Entries` bullets in LF lines, in order — parseEntries' walk. */
+function entryLineIndexes(lines) {
+  const idx = [];
   let inEntries = false;
-  for (const line of lines) {
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
     if (/^##\s+Entries\s*$/.test(line)) { inEntries = true; continue; }
     if (inEntries && /^##\s+/.test(line)) break;
-    if (!inEntries) continue;
-    const match = line.match(/^-\s+(.+)$/);
-    if (match) entries.push(match[1]);
+    if (inEntries && /^-\s+(.+)$/.test(line)) idx.push(i);
   }
-  return entries;
+  return idx;
+}
+
+/** Citations from `--cites a.js#x,b.js` (string) or an array. */
+function citeList(cites) {
+  if (Array.isArray(cites)) return cites.map(c => String(c).trim()).filter(Boolean);
+  return typeof cites === 'string' ? cites.split(',').map(c => c.trim()).filter(Boolean) : [];
 }
 
 /**
  * Append a single entry to an agent's memory log. Creates file+dir if absent.
  * Entries are prefixed with today's date automatically unless already prefixed.
+ * `opts.cites` attaches citations; each must hold in the working tree now, since a
+ * lesson whose evidence is already missing would never be selected.
  * @param {string} cwd - Project root
  * @param {string} agent - Agent name
  * @param {string} entry - Single-line lesson (newlines will be collapsed)
+ * @param {{cites?: string|string[]}} [opts]
  * @returns {{appended: true, file: string, count: number}|{error: string}}
  */
-function appendMemory(cwd, agent, entry) {
+function appendMemory(cwd, agent, entry, opts = {}) {
   const err = validateAgentName(agent);
   if (err) return { error: err };
   if (typeof entry !== 'string' || !entry.trim()) {
@@ -103,7 +257,17 @@ function appendMemory(cwd, agent, entry) {
 
   const cleaned = entry.replace(/\r?\n/g, ' ').trim();
   const datePrefixed = /^\d{4}-\d{2}-\d{2}:/.test(cleaned);
-  const finalEntry = datePrefixed ? cleaned : `${today()}: ${cleaned}`;
+  let finalEntry = datePrefixed ? cleaned : `${today()}: ${cleaned}`;
+  const extra = citeList(opts.cites);
+  if (extra.length) {
+    const meta = parseEntryMeta(finalEntry);
+    meta.cites = [...new Set([...meta.cites, ...extra])];
+    finalEntry = formatEntry(meta);
+  }
+  for (const c of parseEntryMeta(finalEntry).cites) {
+    const problem = citationProblem(cwd, c);
+    if (problem) return { error: `citation ${c}: ${problem}` };
+  }
 
   try {
     fs.mkdirSync(memoryDir(cwd), { recursive: true });
@@ -119,16 +283,18 @@ function appendMemory(cwd, agent, entry) {
     // new file
   }
 
+  // Built on LF, written in the file's own line ending (a CRLF log stays CRLF).
+  const eol = dominantEol(existing);
   let contents;
   if (!existing) {
     contents = buildHeader(agent) + '\n\n## Entries\n\n- ' + finalEntry + '\n';
   } else if (/##\s+Entries/.test(existing)) {
     // Ensure file ends with newline, then append bullet.
     const needsNl = !existing.endsWith('\n');
-    contents = existing + (needsNl ? '\n' : '') + `- ${finalEntry}\n`;
+    contents = existing + (needsNl ? eol : '') + withEol(`- ${finalEntry}\n`, eol);
   } else {
     const needsNl = !existing.endsWith('\n');
-    contents = existing + (needsNl ? '\n' : '') + '\n## Entries\n\n- ' + finalEntry + '\n';
+    contents = existing + (needsNl ? eol : '') + withEol('\n## Entries\n\n- ' + finalEntry + '\n', eol);
   }
 
   try {
@@ -156,7 +322,31 @@ function buildHeader(agent) {
 }
 
 /**
- * Trim a memory file to the last N entries. Preserves frontmatter header.
+ * Append a block to `.planning/memory/archive/<agent>.md`, creating it with its
+ * preamble. Callers write the archive BEFORE they rewrite the log, so an entry is
+ * never in neither place.
+ * @param {string} cwd - Project root
+ * @param {string} agent - Agent name (already validated)
+ * @param {string} block - Bullet block to append (LF)
+ * @returns {string} The archive's absolute path
+ */
+function appendToMemoryArchive(cwd, agent, block) {
+  fs.mkdirSync(path.join(memoryDir(cwd), MEMORY_ARCHIVE_DIR), { recursive: true });
+  const archivePath = path.join(memoryDir(cwd), MEMORY_ARCHIVE_DIR, `${agent}.md`);
+  const preamble = `# Archived memory: ${agent}\n\nEntries moved out of \`${planningRel(MEMORY_DIR, `${agent}.md`)}\` by \`memory prune\` (their cited code was gone, or they went unused for the expiry window) or by compaction (past the log's entry cap). To restore one, move its line back under \`## Entries\` there.\n`;
+  try {
+    fs.writeFileSync(archivePath, preamble, { flag: 'wx', encoding: 'utf-8' });
+  } catch (e) {
+    if (e.code !== 'EEXIST') throw e;
+  }
+  fs.appendFileSync(archivePath, withEol(block, dominantEol(fs.readFileSync(archivePath, 'utf-8'))), 'utf-8');
+  return archivePath;
+}
+
+/**
+ * Trim a memory file to the last N entries. Preserves frontmatter header. The
+ * entries it drops go to the agent's archive first, as `memory prune` does: they
+ * may be lessons a person recorded, and compaction used to discard them.
  * @param {string} cwd - Project root
  * @param {string} agent - Agent name
  * @param {number} maxEntries - Keep this many most-recent entries
@@ -184,41 +374,58 @@ function compactMemory(cwd, agent, maxEntries = DEFAULT_MAX_ENTRIES) {
   }
 
   const keep = entries.slice(-max);
-  const removed = entries.length - keep.length;
+  const dropped = entries.slice(0, entries.length - keep.length);
+  const removed = dropped.length;
 
+  // 1. The archive first.
+  try {
+    appendToMemoryArchive(cwd, agent, `\n<!-- compacted on ${isoDay(new Date())} -->\n`
+      + dropped.map(e => `- ${e}\n  - compacted: past the ${max}-entry cap`).join('\n') + '\n');
+  } catch (e) {
+    return { error: `Failed to archive the compacted entries: ${e.message}` };
+  }
+  // 2. Only then rewrite the log.
   const headerMatch = raw.match(/^---[\s\S]*?---/);
   const header = headerMatch ? headerMatch[0] : buildHeader(agent);
   const body = '\n\n## Entries\n\n' + keep.map(e => `- ${e}`).join('\n') + '\n';
   try {
-    fs.writeFileSync(file, header + body, 'utf-8');
+    fs.writeFileSync(file, withEol(toLf(header) + body, dominantEol(raw)), 'utf-8');
   } catch (e) {
     return { error: `Failed to write memory file: ${e.message}` };
   }
-  return { compacted: true, kept: keep.length, removed };
+  return { compacted: true, kept: keep.length, removed, archived: removed, archive: planningRel(MEMORY_DIR, MEMORY_ARCHIVE_DIR, `${agent}.md`) };
 }
 
 /**
- * List all agents that have a memory file.
+ * List the agent logs in `.planning/memory/` — the files memory is loaded from.
+ * Every other `.md` file there is listed under `not_loaded` with the reason: PAN's
+ * own archives (RESERVED_MEMORY_NAMES; the quarantine holds directives PAN refused
+ * to follow) and files with no `## Entries` list, whose text `memory select` can
+ * neither verify nor expire.
  * @param {string} cwd - Project root
- * @returns {{agents: Array<{agent: string, entries: number}>}}
+ * @returns {{agents: Array<{agent: string, entries: number}>, not_loaded: Array<{file: string, reason: string}>}}
  */
 function listMemoryAgents(cwd) {
   let files;
   try {
     files = fs.readdirSync(memoryDir(cwd));
   } catch {
-    return { agents: [] };
+    return { agents: [], not_loaded: [] };
   }
   const agents = [];
+  const notLoaded = [];
   for (const f of files) {
     if (!f.endsWith('.md')) continue;
     const name = f.slice(0, -3);
-    if (!AGENT_NAME_RE.test(name)) continue;
+    if (isReservedMemoryName(name)) { notLoaded.push({ file: f, reason: 'PAN archive, never loaded as memory' }); continue; }
+    if (!AGENT_NAME_RE.test(name)) { notLoaded.push({ file: f, reason: 'not a valid agent name' }); continue; }
     const mem = readMemory(cwd, name);
-    agents.push({ agent: name, entries: mem ? mem.entries.length : 0 });
+    if (!mem || !/^##\s+Entries\s*$/m.test(mem.raw)) { notLoaded.push({ file: f, reason: 'no `## Entries` list' }); continue; }
+    agents.push({ agent: name, entries: mem.entries.length });
   }
   agents.sort((a, b) => a.agent.localeCompare(b.agent));
-  return { agents };
+  notLoaded.sort((a, b) => a.file.localeCompare(b.file));
+  return { agents, not_loaded: notLoaded };
 }
 
 // ─── Cue + recency scoped, token-budgeted read (ADR-0036 FW-2) ───────────────
@@ -247,36 +454,58 @@ function estMemoryTokens(str) {
 /**
  * Select a cue-relevant, recency-floored, token-budgeted slice of an agent's
  * memory instead of the whole log (ADR-0036 FW-2) — distill-and-select on the
- * memory axis, so per-agent memory injection can't flood context.
+ * memory axis, so whoever hands an agent its memory cannot flood its context.
  *
  * Always keeps the newest `recencyFloor` entries (recall never returns empty on
  * a non-empty log); fills the remaining budget by cue relevance, falling back to
  * recency-only when the cue is empty or matches nothing; greedily packs under
  * `tokenBudget`. Output is in stored (chronological) order.
  *
+ * Only valid entries are candidates (O4): an entry whose cited code is gone
+ * (`stale`) or that was not used for `expireDays` (`expired`) is left out and
+ * reported. `all` takes every valid entry with no budget. `markUsed` records
+ * today as the last use of each selected entry, in the file.
+ *
  * @param {string} cwd
  * @param {string} agent
- * @param {{cue?: string, tokenBudget?: number, recencyFloor?: number}} [opts]
- * @returns {{agent, cue, selected: string[], total_tokens, considered, dropped, mode}|{error}}
+ * @param {{cue?: string, tokenBudget?: number, recencyFloor?: number, all?: boolean,
+ *   markUsed?: boolean, expireDays?: number, now?: number}} [opts]
+ * @returns {{agent, cue, selected: string[], total_tokens, considered, dropped, mode,
+ *   stale: Array<{entry, missing}>, expired: Array<{entry, last_used}>, marked_used?: number}|{error}}
  */
 function selectMemory(cwd, agent, opts = {}) {
   const err = validateAgentName(agent);
   if (err) return { error: err };
   const mem = readMemory(cwd, agent);
   if (!mem || mem.entries.length === 0) {
-    return { agent, cue: opts.cue || '', selected: [], total_tokens: 0, considered: 0, dropped: 0, mode: 'empty' };
+    return { agent, cue: opts.cue || '', selected: [], total_tokens: 0, considered: 0, dropped: 0, mode: 'empty', stale: [], expired: [] };
+  }
+  const now = Number.isFinite(opts.now) ? opts.now : Date.now();
+  const expireDays = expireDaysFrom(opts.expireDays);
+  const stale = [];
+  const expired = [];
+  const valid = []; // { text, i } with i the entry's index in the log
+  mem.entries.forEach((text, i) => {
+    const s = entryStatus(cwd, text, { now, expireDays });
+    if (s.status === 'expired') expired.push({ entry: text, last_used: s.last_used });
+    else if (s.status === 'stale') stale.push({ entry: text, missing: s.missing });
+    else valid.push({ text, i });
+  });
+  const base = { agent, cue: opts.cue || '', considered: mem.entries.length, stale, expired };
+  if (valid.length === 0) {
+    return { ...base, selected: [], total_tokens: 0, dropped: 0, mode: 'empty' };
   }
-  const all = mem.entries; // oldest -> newest
+
   const bN = Number(opts.tokenBudget);
-  const budget = Number.isFinite(bN) && bN > 0 ? bN : MEMORY_SELECT_BUDGET_TOKENS;
+  const budget = opts.all ? Infinity : (Number.isFinite(bN) && bN > 0 ? bN : MEMORY_SELECT_BUDGET_TOKENS);
   const fN = Number(opts.recencyFloor);
   const recencyFloor = Number.isFinite(fN) && fN >= 0 ? fN : MEMORY_RECENCY_FLOOR;
   const tokens = cueTokens(opts.cue);
 
-  const floorFrom = Math.max(0, all.length - recencyFloor);
-  const scored = all.map((text, i) => ({
-    text, i, tokens: estMemoryTokens(text),
-    score: i >= floorFrom ? Infinity : scoreEntry(text, tokens),
+  const floorFrom = Math.max(0, valid.length - recencyFloor);
+  const scored = valid.map((v, k) => ({
+    text: v.text, i: v.i, tokens: estMemoryTokens(v.text),
+    score: k >= floorFrom ? Infinity : scoreEntry(v.text, tokens),
   }));
   const anyCueHit = scored.some(e => Number.isFinite(e.score) && e.score > 0);
   // Priority: recency-floor first (Infinity), then cue score, then newest.
@@ -294,22 +523,190 @@ function selectMemory(cwd, agent, opts = {}) {
     chosen.push(newest); total += newest.tokens; dropped = Math.max(0, dropped - 1);
   }
   chosen.sort((a, b) => a.i - b.i); // chronological for output
-  const mode = tokens.length === 0 ? 'recency' : (anyCueHit ? 'cue' : 'recency');
-  return { agent, cue: opts.cue || '', selected: chosen.map(e => e.text), total_tokens: total, considered: all.length, dropped, mode };
+  const mode = opts.all ? 'all' : tokens.length === 0 ? 'recency' : (anyCueHit ? 'cue' : 'recency');
+  const result = { ...base, selected: chosen.map(e => e.text), total_tokens: total, dropped, mode };
+  if (opts.markUsed) result.marked_used = markEntriesUsed(cwd, agent, chosen.map(e => e.i), isoDay(now));
+  return result;
+}
+
+/**
+ * Record `day` as the last use of the entries at `indexes` (positions in the log),
+ * rewriting only those bullet lines, in the file's own line ending. Returns how
+ * many changed; an entry already marked for `day` is left alone.
+ */
+function markEntriesUsed(cwd, agent, indexes, day) {
+  const file = memoryFile(cwd, agent);
+  let raw;
+  try { raw = fs.readFileSync(file, 'utf-8'); } catch { return 0; }
+  const lines = toLf(raw).split('\n');
+  const at = entryLineIndexes(lines);
+  let changed = 0;
+  for (const k of indexes) {
+    const li = at[k];
+    if (li === undefined) continue;
+    const meta = parseEntryMeta(lines[li].replace(/^-\s+/, ''));
+    if (meta.used === day) continue;
+    meta.used = day;
+    meta.uses = (meta.uses || 0) + 1; // days selected: the use telemetry O6 asked for
+    lines[li] = `- ${formatEntry(meta)}`;
+    changed++;
+  }
+  if (changed) fs.writeFileSync(file, withEol(lines.join('\n'), dominantEol(raw)), 'utf-8');
+  return changed;
 }
 
+// ─── The gated write path (O6) ───────────────────────────────────────────────
+
+const LESSON_MIN_CHARS = 20;
+const LESSON_MAX_CHARS = 300;
+const TRACE_SESSION_RE = /^[A-Za-z0-9._-]{1,120}$/;
+const sameText = (a, b) => String(a || '').toLowerCase().replace(/[^a-z0-9]+/g, ' ').trim() === String(b || '').toLowerCase().replace(/[^a-z0-9]+/g, ' ').trim();
+
 /**
- * Memory-load telemetry gate (ADR-0036 acceptance signal). Estimates the tokens
- * of memory that would be injected whole (every agent log) and compares to the
- * median per-agent PROMPT from the trustworthy cost ledger (suspect records
- * quarantined). Read-only, non-blocking; degrades to an absolute-token check
- * when the ledger is thin.
+ * Record a lesson in an agent's memory — the gated write path (memory
+ * optimisation O6). The market and the research agree on what makes agent memory
+ * pay: lessons from observed failures, carrying the correction and its evidence,
+ * never raw traces and never what the code already says. So a lesson is recorded
+ * only:
+ *   - from evidence of a corrected failure: `finding` (a finding in the ledger whose
+ *     status is `fixed`: a verifier gap a fix round closed) or `trace` (a trace
+ *     session, where the optimizer saw a recurring tool failure);
+ *   - with at least one citation that holds (O4), the code the correction lives in;
+ *   - as one line of 20–300 characters that says the correction, not the finding;
+ *   - when it is not a directive to bypass the process (ADR-0040);
+ *   - once: one lesson per finding, and never a lesson already in the log.
+ * A refusal is `{recorded: false, reason}`; bad input is `{error}`.
+ * @param {string} cwd
+ * @param {string} agent
+ * @param {{lesson: string, finding?: string, trace?: string, cites?: string|string[]}} opts
+ */
+function recordLesson(cwd, agent, opts = {}) {
+  const err = validateAgentName(agent);
+  if (err) return { error: err };
+  if (opts.finding && opts.trace) return { error: 'give one piece of evidence: --finding <id> or --trace <session>' };
+  const lesson = String(opts.lesson || '').replace(/\s+/g, ' ').trim();
+  const refuse = (reason, extra = {}) => ({ recorded: false, agent, reason, ...extra });
+  if (lesson.length < LESSON_MIN_CHARS) return refuse(`a lesson needs at least ${LESSON_MIN_CHARS} characters: write the correction, not a label`);
+  if (lesson.length > LESSON_MAX_CHARS) return refuse(`a lesson is one rule of at most ${LESSON_MAX_CHARS} characters`);
+  if (/<!--|--!?>/.test(lesson)) return refuse('a lesson may not carry an HTML comment');
+  if (require('./memory-optimize.cjs').isSuspiciousDirective(lesson)) {
+    return refuse('it reads as a directive to override or bypass the process (ADR-0040), so it is not recorded');
+  }
+
+  let evidence;
+  if (opts.finding) {
+    const f = require('./findings.cjs').listFindings(cwd, {}).findings.find(x => x.id === opts.finding);
+    if (!f) return refuse(`no finding ${opts.finding} in the findings ledger`);
+    if (f.status !== 'fixed') return refuse(`finding ${opts.finding} is ${f.status}, not fixed: a lesson comes from a failure that was corrected`);
+    if (sameText(lesson, f.summary)) return refuse('the lesson repeats the finding: write the correction, what to do next time');
+    evidence = `finding:${f.id}`;
+  } else if (opts.trace) {
+    if (!TRACE_SESSION_RE.test(opts.trace)) return refuse(`not a trace session id: ${opts.trace}`);
+    try { fs.statSync(planningPath(cwd, 'optimization', 'traces', opts.trace, 'trace.jsonl')); } catch {
+      return refuse(`no trace session ${opts.trace} under ${planningRel('optimization', 'traces')}/`);
+    }
+    evidence = `trace:${opts.trace}`;
+  } else {
+    return refuse('a lesson needs evidence of the failure it corrects: --finding <id> (a fixed finding) or --trace <session>');
+  }
+
+  const cites = citeList(opts.cites);
+  if (!cites.length) return refuse('a lesson needs --cites <path[#symbol]>: the code the correction lives in');
+  for (const c of cites) {
+    const problem = citationProblem(cwd, c);
+    if (problem) return refuse(`citation ${c}: ${problem}`);
+  }
+
+  const mem = readMemory(cwd, agent);
+  for (const e of mem ? mem.entries : []) {
+    const m = parseEntryMeta(e);
+    if (evidence.startsWith('finding:') && m.evidence === evidence) return refuse(`${evidence} already has a lesson: ${m.text}`, { duplicate: true });
+    if (sameText(m.text, lesson)) return refuse('the same lesson is already in the log', { duplicate: true });
+  }
+
+  const entry = formatEntry({ date: today(), text: lesson, cites, evidence });
+  const r = appendMemory(cwd, agent, entry);
+  if (r.error) return r;
+  try {
+    require('./optimize.cjs').logTraceEvent(cwd, {
+      type: 'decision', category: 'memory_recorded', agent: 'orchestrator', impact: 'minor',
+      description: `lesson recorded for ${agent} from ${evidence}`,
+      context: { agent, evidence, cites },
+    });
+  } catch { /* telemetry is best effort */ }
+  return { recorded: true, agent, evidence, entry, file: planningRel(MEMORY_DIR, `${agent}.md`), count: r.count };
+}
+
+/**
+ * Archive the entries `memory select` no longer returns — stale (cited code gone) and
+ * expired (unused for `days`) — from one agent's log or all of them. The archive
+ * at `.planning/memory/archive/<agent>.md` is written FIRST, then only those
+ * bullet lines leave the log, so an interruption can duplicate and never lose.
+ * Dry-run unless `apply`.
+ * @param {string} cwd
+ * @param {string|null} agent - one agent, or null for every agent log
+ * @param {{apply?: boolean, days?: number, now?: number}} [opts]
+ */
+function pruneMemory(cwd, agent, opts = {}) {
+  const names = agent ? [agent] : listMemoryAgents(cwd).agents.map(a => a.agent);
+  const now = Number.isFinite(opts.now) ? opts.now : Date.now();
+  const expireDays = expireDaysFrom(opts.days);
+  const day = isoDay(now);
+  const agents = [];
+  for (const name of names) {
+    const err = validateAgentName(name);
+    if (err) return { error: err };
+    const mem = readMemory(cwd, name);
+    if (!mem) {
+      if (agent) return { error: `No memory file for agent: ${name}` };
+      continue;
+    }
+    const archive = [];
+    mem.entries.forEach((text, i) => {
+      const s = entryStatus(cwd, text, { now, expireDays });
+      if (s.status === 'expired') archive.push({ i, entry: text, reason: `not used since ${s.last_used}` });
+      else if (s.status === 'stale') archive.push({ i, entry: text, reason: `cited code gone: ${s.missing.join(', ')}` });
+    });
+    agents.push({ agent: name, archive, kept: mem.entries.length - archive.length, raw: mem.raw });
+  }
+  const total = agents.reduce((n, a) => n + a.archive.length, 0);
+  const summary = {
+    expire_days: expireDays,
+    archive_dir: planningRel(MEMORY_DIR, MEMORY_ARCHIVE_DIR),
+    agents: agents.map(a => ({ agent: a.agent, kept: a.kept, archive: a.archive.map(({ entry, reason }) => ({ entry, reason })) })),
+    archivable: total,
+    applied: false,
+    dry_run: !opts.apply,
+  };
+  if (!opts.apply || total === 0) return summary;
+
+  fs.mkdirSync(path.join(memoryDir(cwd), MEMORY_ARCHIVE_DIR), { recursive: true });
+  for (const a of agents) {
+    if (!a.archive.length) continue;
+    // 1. The archive first.
+    appendToMemoryArchive(cwd, a.agent, `\n<!-- pruned on ${day} -->\n` + a.archive.map(x => `- ${x.entry}\n  - pruned: ${x.reason}`).join('\n') + '\n');
+    // 2. Only then take those bullet lines out of the log.
+    const lines = toLf(a.raw).split('\n');
+    const at = entryLineIndexes(lines);
+    const drop = new Set(a.archive.map(x => at[x.i]));
+    fs.writeFileSync(memoryFile(cwd, a.agent), withEol(lines.filter((_, li) => !drop.has(li)).join('\n'), dominantEol(a.raw)), 'utf-8');
+  }
+  return { ...summary, applied: true, dry_run: false };
+}
+
+/**
+ * Memory-load telemetry (ADR-0036 acceptance signal). Estimates the tokens the
+ * whole store would add to an agent that was handed every agent log, and compares
+ * them to the median per-agent PROMPT from the trustworthy cost ledger (suspect
+ * records quarantined). Read-only, non-blocking; degrades to an absolute-token
+ * check when the ledger is thin. PAN's workflows no longer hand memory to agents
+ * (`2026-10-04`), so this sizes the store for someone who would.
  *
  * The prompt is `input + cache_read + cache_write`, not `input` alone: under prompt
  * caching the uncached remainder is tens of tokens, so dividing by it reported 1.8k
  * of memory as 8,940% of a "median agent input" and called it critical (field sweep
- * 2026-09-17). Memory is injected into the whole prompt, so the whole prompt is what
- * it must be measured against.
+ * 2026-09-17). Memory handed to an agent joins the whole prompt, so the whole
+ * prompt is what it must be measured against.
  *
  * @returns {{memory_tokens, agents, median_prompt_tokens, fraction, status, advisory}}
  */
@@ -340,9 +737,9 @@ function memoryLoadBudget(cwd, opts = {}) {
   else if (memoryTokens >= warnT || (fraction != null && fraction >= maxFrac)) status = 'warning';
   const advisory = status === 'ok'
     ? 'Memory-load within budget.'
-    : `Memory injection is ~${memoryTokens} tokens across ${agents.length} agent log(s)` +
+    : `Agent memory is ~${memoryTokens} tokens across ${agents.length} agent log(s)` +
       (fraction != null ? ` (~${Math.round(fraction * 100)}% of a median agent prompt)` : '') +
-      `. Bound it with cue-scoped 'memory select' or trim with 'memory compact <agent>'.`;
+      `. PAN's workflows do not load it into agents; to hand some of it to one, use cue-scoped 'memory select', and trim it with 'memory compact <agent>' or 'memory prune'.`;
   return { memory_tokens: memoryTokens, agents: agents.length, median_prompt_tokens: median, fraction, status, advisory };
 }
 
@@ -350,19 +747,45 @@ function memoryLoadBudget(cwd, opts = {}) {
 
 function cmdMemoryRead(cwd, agent, raw) {
   if (!agent) { error('Usage: memory read <agent>'); }
+  // An archive or invalid name is refused, as append, select and prune refuse it:
+  // answering `exists: false` hid that state-archive.md was right there.
+  const refused = validateAgentName(agent);
+  if (refused) { output({ agent, error: refused }, raw); return; }
   const result = readMemory(cwd, agent);
   if (!result) { output({ agent, entries: [], exists: false }, raw); return; }
   output({ agent, entries: result.entries, exists: true }, raw);
 }
 
-function cmdMemoryAppend(cwd, agent, entry, raw) {
-  if (!agent || !entry) { error('Usage: memory append <agent> <entry>'); }
-  const result = appendMemory(cwd, agent, entry);
-  output(result, raw);
+function cmdMemoryAppend(cwd, agent, entry, raw, opts = {}) {
+  if (!agent || !entry) { error('Usage: memory append <agent> <entry> [--cites <path[#symbol]>,...]'); }
+  // A refused entry is reported as `{ error }` on stdout, like every append error.
+  output(appendMemory(cwd, agent, entry, opts), raw);
+}
+
+/**
+ * Use telemetry across the agent logs (O6): how many entries carry evidence of the
+ * failure they came from, cite code, and were ever used (`uses`, counted by
+ * `memory select --mark-used`). An entry never used is memory nobody reads.
+ */
+function memoryUsage(cwd, agents) {
+  const u = { entries: 0, with_evidence: 0, cited: 0, used: 0, never_used: 0 };
+  for (const a of agents) {
+    const mem = readMemory(cwd, a.agent);
+    for (const e of mem ? mem.entries : []) {
+      const m = parseEntryMeta(e);
+      u.entries++;
+      if (m.evidence) u.with_evidence++;
+      if (m.cites.length) u.cited++;
+      if (m.uses > 0 || m.used) u.used++;
+      else u.never_used++;
+    }
+  }
+  return u;
 }
 
 function cmdMemoryList(cwd, raw) {
-  output(listMemoryAgents(cwd), raw);
+  const l = listMemoryAgents(cwd);
+  output({ ...l, usage: memoryUsage(cwd, l.agents) }, raw);
 }
 
 function cmdMemoryCompact(cwd, agent, maxEntries, raw) {
@@ -372,10 +795,31 @@ function cmdMemoryCompact(cwd, agent, maxEntries, raw) {
 }
 
 function cmdMemorySelect(cwd, agent, opts, raw) {
-  if (!agent) { error('Usage: memory select <agent> [--cue <text>] [--token-budget N] [--recency-floor N]'); }
+  if (!agent) { error('Usage: memory select <agent> [--cue <text>] [--token-budget N] [--recency-floor N] [--all] [--mark-used] [--days N]'); }
   output(selectMemory(cwd, agent, opts || {}), raw);
 }
 
+/** `memory record <agent> --lesson <text> (--finding <id> | --trace <session>) --cites <path[#symbol]>,...` */
+function cmdMemoryRecord(cwd, agent, opts, raw) {
+  if (!agent) { error('Usage: memory record <agent> --lesson "<correction>" (--finding <id> | --trace <session>) --cites <path[#symbol]>,...'); }
+  const r = recordLesson(cwd, agent, opts || {});
+  if (r.error) { error(r.error); }
+  // A refusal is the gate working, reported as data (exit 0) with the reason.
+  output(r, raw, r.recorded ? `recorded for ${r.agent} from ${r.evidence}` : `not recorded: ${r.reason}`);
+}
+
+/** `memory prune [<agent>] [--apply] [--days N]` */
+function cmdMemoryPrune(cwd, agent, opts, raw) {
+  const r = pruneMemory(cwd, agent || null, opts || {});
+  if (r.error) { error(r.error); }
+  const text = r.applied
+    ? `archived ${r.archivable} entr${r.archivable === 1 ? 'y' : 'ies'} to ${r.archive_dir}/`
+    : r.archivable
+      ? `would archive ${r.archivable} entr${r.archivable === 1 ? 'y' : 'ies'} (stale or unused for ${r.expire_days} days) — rerun with --apply`
+      : 'nothing to prune — every entry is cited correctly and was used recently';
+  output(r, raw, text);
+}
+
 function cmdMemoryBudget(cwd, raw) {
   output(memoryLoadBudget(cwd), raw);
 }
@@ -386,16 +830,26 @@ module.exports = {
   compactMemory,
   listMemoryAgents,
   selectMemory,
+  pruneMemory,
+  recordLesson,
   memoryLoadBudget,
   scoreEntry,
   parseEntries,
+  parseEntryMeta,
+  formatEntry,
+  citationProblem,
+  entryStatus,
   validateAgentName,
   cmdMemoryRead,
   cmdMemoryAppend,
   cmdMemoryList,
   cmdMemoryCompact,
   cmdMemorySelect,
+  cmdMemoryPrune,
+  cmdMemoryRecord,
   cmdMemoryBudget,
   MEMORY_DIR,
+  MEMORY_ARCHIVE_DIR,
+  RESERVED_MEMORY_NAMES,
   DEFAULT_MAX_ENTRIES,
 };