@staix/agent-mem 0.14.0 → 0.16.0

package/src/memory/candidate-overlaps.ts

@@ -0,0 +1,87 @@
+import type { Candidate, CandidateInput } from "./candidates.ts";
+import { overlapWords, wordOverlap } from "./consolidation-clusters.ts";
+import { memoryPolicySnapshot, type StandalonePolicy } from "./policy.ts";
+import { stripPrivateDeep } from "./private-spans.ts";
+import { recallViewIsLive } from "./recall.ts";
+import { resolveAlias } from "./shard.ts";
+import type { MemoryStore, View } from "./store.ts";
+
+export interface CandidateOverlap { id: string; title: string | null; score: number }
+interface OverlapOptions {
+  project: string;
+  policy: () => StandalonePolicy;
+  policyVersion: () => string;
+  assertCurrent?: () => void;
+}
+
+type OverlapCandidate = Pick<Candidate, "status" | "input">;
+interface PreparedCandidate {
+  proposed: Pick<View, "title" | "text">;
+  terms: Set<string>;
+  selected: { row: View; score: number }[];
+  target?: View;
+}
+
+function candidateText(input: CandidateInput, target?: View): Pick<View, "title" | "text"> | undefined {
+  if (input.kind === "promotion") return target;
+  return { title: input.kind === "memory" ? input.title ?? null : null,
+    text: input.kind === "correction" ? input.proposedText : input.kind === "decay" ? input.reason
+      : input.kind === "fail" ? [input.approach, input.symptom, input.cause, ...input.evidenceRefs, input.retryWhen].join("\n") : input.text };
+}
+
+/** One policy-screened, tokenized note pass for the whole batch. Keep only three winners per candidate, not the corpus. */
+export async function candidateOverlapsBatch(candidates: readonly OverlapCandidate[], store: MemoryStore, options: OverlapOptions): Promise<CandidateOverlap[][]> {
+  const inputs = candidates.map(candidate => candidate.status === "pending" && resolveAlias(store.profile.home, candidate.input.project) === options.project ? stripPrivateDeep(candidate.input) : undefined);
+  if (!inputs.some(Boolean)) return candidates.map(() => []);
+  const revision = options.policyVersion(), policy = options.policy(), sourceCurrent = store.beginRecallRead();
+  const check = () => {
+    options.assertCurrent?.(); sourceCurrent();
+    if (options.policyVersion() !== revision) throw Error("overlap policy changed");
+  };
+  check();
+  // Promotion text lives in its target. Screen each distinct target once, reusing that verdict in the note pass.
+  const targets = new Map<string, View | undefined>(), targetTerms = new Map<string, Set<string>>();
+  for (const input of inputs) {
+    if (input?.kind !== "promotion" || targets.has(input.target.id)) continue;
+    const target = memoryPolicySnapshot(store.get(input.target.id, options.project));
+    const allowed = target && target.project === options.project && recallViewIsLive(target, store.readNow()) && await policy.screen(target);
+    check(); targets.set(input.target.id, allowed ? target : undefined);
+    if (allowed && target) targetTerms.set(target.id, overlapWords(target));
+  }
+  const prepared = inputs.map((input): PreparedCandidate | undefined => {
+    if (!input) return undefined;
+    const target = input.kind === "promotion" ? targets.get(input.target.id) : undefined, proposed = candidateText(input, target);
+    return proposed ? { proposed, terms: target ? targetTerms.get(target.id)! : overlapWords(proposed), selected: [], ...(target ? { target } : {}) } : undefined;
+  });
+  if (!prepared.some(Boolean)) { check(); return candidates.map(() => []); }
+  let after: Parameters<MemoryStore["readPage"]>[0]["after"];
+  for (;;) {
+    check();
+    const page = store.withDeferredPromotions(() => store.readPage({ project: options.project, limit: 128, after }));
+    for (const value of page.rows) {
+      const row = memoryPolicySnapshot(value);
+      if (!row || row.project !== options.project || !recallViewIsLive(row, store.readNow())) continue;
+      const allowed = targets.has(row.id) ? targets.get(row.id) !== undefined : await policy.screen(row); check();
+      if (!allowed || !recallViewIsLive(row, store.readNow())) continue;
+      const terms = targetTerms.get(row.id) ?? overlapWords(row);
+      for (const candidate of prepared) {
+        if (!candidate) continue;
+        const score = candidate.proposed.text === row.text ? 1 : wordOverlap(candidate.terms, terms), selected = candidate.selected, last = selected.at(-1);
+        if (score <= 0 || selected.length === 3 && last && (score < last.score || score === last.score && row.id.localeCompare(last.row.id) >= 0)) continue;
+        selected.push({ row, score });
+        selected.sort((a, b) => b.score - a.score || a.row.id.localeCompare(b.row.id));
+        if (selected.length > 3) selected.pop();
+      }
+    }
+    if (!page.next) break;
+    after = page.next;
+  }
+  check();
+  return prepared.map(candidate => !candidate || candidate.target && !recallViewIsLive(candidate.target, store.readNow()) ? []
+    : candidate.selected.filter(({ row }) => recallViewIsLive(row, store.readNow())).map(({ row, score }) => ({ id: row.id, title: row.title, score })));
+}
+
+/** Single-candidate callers share the same screening and source/policy fences as JSON list batches. */
+export async function candidateOverlaps(candidate: OverlapCandidate, store: MemoryStore, options: OverlapOptions): Promise<CandidateOverlap[]> {
+  return (await candidateOverlapsBatch([candidate], store, options))[0]!;
+}

package/src/memory/capture-input.ts

@@ -5,16 +5,21 @@ import { stripPrivateSpans } from "./private-spans.ts";
 export const CAPTURE_MAX_EXCERPT = 2000;
 export const CAPTURE_MAX_PATHS = 32;
 const ROW_OVERHEAD_BYTES = 96;
+/** The session key is a fixed-width hash prefix, so it adds a bounded amount covered by the row overhead. */
+export const SESSION_KEY = /^[a-f0-9]{16}$/;
 
 export interface CaptureFields {
   agent: string; event: string;
   tool?: string; paths?: string[]; status?: string; excerpt?: string;
+  /** #173: a 16-hex hash of the native session id (never the raw id), and a subagent marker. Both optional. */
+  session?: string; subagent?: boolean;
   /** Tests and the spool replay pin the time; hooks leave it to the store clock. */
   at?: string;
 }
 export interface NormalizedCaptureFields {
   at: string; agent: string; event: string;
   tool: string | null; paths: string[]; status: string | null; excerpt: string; bytes: number;
+  session?: string; subagent?: true;
 }
 
 /** Pure capture shaping; no store, project lookup or filesystem operation is loaded or invoked here. */
@@ -31,6 +36,13 @@ export function normalizeCaptureFields(input: CaptureFields, now: () => number =
   // `<private>` spans go first: they are never screened, counted or stored. The cap applies to what is left.
   let excerpt = stripPrivateSpans(input.excerpt ?? "").slice(0, maxExcerpt);
   if (excerpt && screen(excerpt)) excerpt = "[secret-screened]";
+  const session = typeof input.session === "string" && SESSION_KEY.test(input.session) ? input.session : undefined;
+  const subagent = input.subagent === true;
   return { at, agent: input.agent, event: input.event, tool, paths, status, excerpt,
-    bytes: Buffer.byteLength(excerpt) + Buffer.byteLength(JSON.stringify(paths)) + ROW_OVERHEAD_BYTES };
+    bytes: Buffer.byteLength(excerpt) + Buffer.byteLength(JSON.stringify(paths)) + ROW_OVERHEAD_BYTES,
+    ...(session ? { session } : {}), ...(subagent ? { subagent: true as const } : {}) };
 }
+
+/** Shared by every capture reader: the #173 columns are optional, so a shard without them reads unchanged. */
+export const captureAttribution = (r: { session?: string | null; subagent?: number | null }): { session?: string; subagent?: true } =>
+  ({ ...(typeof r.session === "string" && SESSION_KEY.test(r.session) ? { session: r.session } : {}), ...(r.subagent === 1 ? { subagent: true as const } : {}) });

package/src/memory/capture.ts

@@ -3,7 +3,7 @@ import { createHash, randomBytes } from "node:crypto";
 import { chmodSync, closeSync, existsSync, lstatSync, mkdirSync, openSync, opendirSync, readFileSync, readSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { looksSecret } from "./screen.ts";
-import { normalizeCaptureFields, type CaptureFields } from "./capture-input.ts";
+import { captureAttribution, normalizeCaptureFields, SESSION_KEY, type CaptureFields } from "./capture-input.ts";
 export { CAPTURE_MAX_EXCERPT, CAPTURE_MAX_PATHS } from "./capture-input.ts";
 import { memoryBase } from "./home.ts";
 import { captureShardDir, ensureShardDescriptor, readShardDescriptor, resolveAlias, shardKeyHash } from "./shard.ts";
@@ -63,6 +63,8 @@ export interface CaptureInput extends CaptureFields { project: string }
 export interface CaptureRow {
   id: number; at: string; project: string; agent: string; event: string;
   tool: string | null; paths: string[]; status: string | null; excerpt: string;
+  /** #173 attribution, absent on older rows: a 16-hex session hash and the subagent marker. */
+  session?: string; subagent?: true;
 }
 export interface CaptureConfig { capMb: number; retentionDays: number }
 export interface CaptureOptions {
@@ -104,6 +106,7 @@ export type CaptureAppend = { id: number; already?: true } | { spooled: true };
 interface NormalizedCapture {
   at: string; project: string; agent: string; event: string;
   tool: string | null; paths: string[]; status: string | null; excerpt: string; bytes: number;
+  session?: string; subagent?: true;
   /** Entropy per spooled line, so two byte-identical hook events are two rows; a replayed line still dedupes. */
   nonce?: string;
 }
@@ -159,8 +162,23 @@ export function writeCaptureConfig(dir: string, config: Partial<CaptureConfig>):
 
 const lockError = (error: unknown): boolean => /lock|busy/i.test((error as Error)?.message ?? "");
 
-interface RawRow { id: number; at: string; project: string; agent: string; event: string; tool: string | null; paths: string; status: string | null; excerpt: string; bytes: number }
-const toRow = (r: RawRow): CaptureRow => ({ id: r.id, at: r.at, project: r.project, agent: r.agent, event: r.event, tool: r.tool, paths: JSON.parse(r.paths) as string[], status: r.status, excerpt: r.excerpt });
+/**
+ * #173 migration, safe under concurrent first opens after an upgrade. Another writer can add a column between our
+ * table_info read and our ALTER; SQLite then reports "duplicate column name", which means the column exists. Lock
+ * and busy errors still propagate, so the constructor's contended path spools as before.
+ */
+export function addAttributionColumns(db: Database, beforeAlter?: (column: string) => void): void {
+  const has = () => new Set((db.query("PRAGMA table_info(rows)").all() as { name: string }[]).map(c => c.name));
+  for (const [column, type] of [["session", "TEXT"], ["subagent", "INTEGER"]] as const) {
+    if (has().has(column)) continue;
+    beforeAlter?.(column);
+    try { db.run(`ALTER TABLE rows ADD COLUMN ${column} ${type}`); }
+    catch (error) { if (!/duplicate column name/i.test((error as Error)?.message ?? "") || !has().has(column)) throw error; }
+  }
+}
+
+interface RawRow { id: number; at: string; project: string; agent: string; event: string; tool: string | null; paths: string; status: string | null; excerpt: string; bytes: number; session?: string | null; subagent?: number | null }
+const toRow = (r: RawRow): CaptureRow => ({ id: r.id, at: r.at, project: r.project, agent: r.agent, event: r.event, tool: r.tool, paths: JSON.parse(r.paths) as string[], status: r.status, excerpt: r.excerpt, ...captureAttribution(r) });
 
 export class CaptureStore {
   readonly dir: string;
@@ -268,6 +286,8 @@ export class CaptureStore {
       db.run("CREATE UNIQUE INDEX IF NOT EXISTS rows_spool ON rows (spool_id) WHERE spool_id IS NOT NULL");
       db.run("CREATE INDEX IF NOT EXISTS rows_at ON rows (at)");
       db.run("CREATE TABLE IF NOT EXISTS meta (key TEXT PRIMARY KEY, value TEXT NOT NULL)");
+      // #173: additive nullable columns. Older readers use explicit or `SELECT *` column names and ignore extras.
+      addAttributionColumns(db);
       this.ensureFts();
     } catch (error) {
       if (!lockError(error)) { db.close(); throw error; }
@@ -437,8 +457,8 @@ export class CaptureStore {
 
   /** The one place input becomes a row: caps fields, deny-filters paths, screens the excerpt, counts its bytes. */
   private normalize(input: CaptureInput): NormalizedCapture {
-    const { at, agent, event, tool, paths, status, excerpt, bytes } = normalizeCaptureFields(input, () => this.now(), text => this.screen(text), this.caps);
-    return { at, project: input.project, agent, event, tool, paths, status, excerpt, bytes };
+    const { at, agent, event, tool, paths, status, excerpt, bytes, session, subagent } = normalizeCaptureFields(input, () => this.now(), text => this.screen(text), this.caps);
+    return { at, project: input.project, agent, event, tool, paths, status, excerpt, bytes, ...(session ? { session } : {}), ...(subagent ? { subagent } : {}) };
   }
 
   private spoolLine(row: NormalizedCapture, nonce = randomBytes(12).toString("hex")): string {
@@ -485,7 +505,8 @@ export class CaptureStore {
       && typeof row.agent === "string" && row.agent.length > 0 && typeof row.event === "string" && row.event.length > 0
       && (row.tool === null || typeof row.tool === "string") && Array.isArray(row.paths) && row.paths.every((p) => typeof p === "string")
       && (row.status === null || typeof row.status === "string") && typeof row.excerpt === "string"
-      && typeof row.bytes === "number" && Number.isFinite(row.bytes) && row.bytes >= 0;
+      && typeof row.bytes === "number" && Number.isFinite(row.bytes) && row.bytes >= 0
+      && (row.session === undefined || typeof row.session === "string" && SESSION_KEY.test(row.session)) && (row.subagent === undefined || row.subagent === true);
     candidates.sort((a, b) => a.name.localeCompare(b.name));
     for (const source of candidates) {
       if (budget <= 0 || byteBudget <= 0 || performance.now() - started >= SPOOL_MAX_MS) break;
@@ -557,8 +578,8 @@ export class CaptureStore {
     // it), so the replay check is a plain indexed lookup, never the statement's change count.
     if (spoolId !== null && this.db.query("SELECT 1 FROM rows WHERE spool_id = ?").get(spoolId)) return undefined;
     try {
-      const id = Number(this.db.query("INSERT INTO rows (at, project, agent, event, tool, paths, status, excerpt, bytes, spool_id) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)")
-        .run(row.at, row.project, row.agent, row.event, row.tool, JSON.stringify(row.paths), row.status, row.excerpt, row.bytes, spoolId).lastInsertRowid);
+      const id = Number(this.db.query("INSERT INTO rows (at, project, agent, event, tool, paths, status, excerpt, bytes, spool_id, session, subagent) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)")
+        .run(row.at, row.project, row.agent, row.event, row.tool, JSON.stringify(row.paths), row.status, row.excerpt, row.bytes, spoolId, row.session ?? null, row.subagent ? 1 : null).lastInsertRowid);
       this.addBytes(row.bytes);
       return id;
     } catch (error) {

package/src/memory/commands.ts

@@ -14,6 +14,8 @@ import type { GoalPromotionReport } from "./goal-promotion.ts";
 export interface CommandNames { memory: string; goal: string }
 export const AMEM_NAMES: CommandNames = { memory: "amem", goal: "amem goal" };
 
+import type { ForgetNearby } from "./forget-nearby.ts";
+import { forgetNearbyText } from "./forget-nearby.ts";
 export interface MemoryCommandOptions {
   /** Host-authenticated person intent. Never accept this from model arguments. Required for retained history/as-of. */
   person?: boolean;
@@ -35,6 +37,8 @@ export interface MemoryCommandOptions {
   importPolicy: () => (text: string) => boolean;
   /** Explicit person-status receipt; model-facing hosts omit this callback. */
   onBridgeStatus?: (status: { skippedRows: number } | undefined) => void;
+  /** #188: standalone CLI only. Lists same-project machine-local rows near a forgotten note (ids, counts). */
+  forgetNearby?: (note: { project: string; text: string; title: string | null }) => Promise<ForgetNearby>;
 }
 export interface GoalCommandOptions {
   /** Defaults to amem's own names. */
@@ -185,7 +189,12 @@ export async function rawMemoryCommand(args: string[], cwd: string, opts: Memory
       case "demote": { const v = visibleTarget(store.get(rest[0] ?? fail(usage), project), rest[0]!); if (v.tier !== "long") return `${v.id.slice(0, 8)} is already short-term`; store.demote(v.id, actor, project); return `demoted ${v.id.slice(0, 8)}: it expires ${store.get(v.id, project)?.expiresAt ?? "with its short-term lifetime"}`; }
       case "forget": { const target = visibleTarget(store.get(rest[0] ?? fail(usage), project), rest[0]!);
         if (cliAttribution()?.actor === "agent") for (const member of store.forgetTargets(target.id, project)) visibleTarget(member, member.id);
-        const v = need(store.forget(target.id, actor, project), rest[0]!); return `forgot ${v.id.slice(0, 8)}${v.local ? "" : "; it stays in the sync remote's git history until a person rewrites it (docs/memory.md)"}`; }
+        const v = need(store.forget(target.id, actor, project), rest[0]!);
+        const remote = v.local ? "" : "; it stays in the sync remote's git history until a person rewrites it (docs/purge.md)";
+        const nearby = opts.forgetNearby ? await opts.forgetNearby({ project: target.project, text: target.text, title: target.title ?? null }).catch(() => undefined) : undefined;
+        // Hosts that do not opt in keep the existing single-line receipt (with or without --json).
+        if (json && opts.forgetNearby) return JSON.stringify({ forgot: v.id, local: !!v.local, ...(nearby ? { nearby } : {}) }, null, 2);
+        return [`forgot ${v.id.slice(0, 8)}${remote}`, ...(nearby ? forgetNearbyText(nearby) : [])].join("\n"); }
       case "supersede": {
         if (rest.length !== 2) fail(`usage: ${names.memory} supersede <old> <new>`);
         if (cliAttribution()?.actor === "agent") for (const id of rest) visibleTarget(store.get(id, project), id);

package/src/memory/consolidation-clusters.ts

@@ -6,7 +6,7 @@ import type { View } from "./store.ts";
 export type ConsolidationAction = "merge" | "supersession" | "recurring-fix";
 export interface ConsolidationCluster { action: ConsolidationAction; sources: View[]; reason: string }
 export const CONSOLIDATION_SOURCE_LIMIT = 256, CONSOLIDATION_PROPOSAL_LIMIT = 32;
-const words = (row: View) => new Set((`${row.title ?? ""} ${row.text}`.toLowerCase().match(/[\p{L}\p{N}_]{3,}/gu) ?? []).filter(word => !["the", "and", "for", "with", "from", "this", "that", "approach", "symptom", "cause", "evidence", "retry", "when"].includes(word)).slice(0, 128));
+export const overlapWords = (row: Pick<View, "title" | "text">) => new Set((`${row.title ?? ""} ${row.text}`.toLowerCase().match(/[\p{L}\p{N}_]{3,}/gu) ?? []).filter(word => !["the", "and", "for", "with", "from", "this", "that", "approach", "symptom", "cause", "evidence", "retry", "when"].includes(word)).slice(0, 128));
 /** A note written by accepting a consolidation candidate. Proposing over one would be a summary of summaries. */
 export function isAcceptedConsolidation(row: Pick<View, "text">): boolean {
   const end = row.text.indexOf("\n\n"); if (end < 0) return false;
@@ -18,7 +18,7 @@ export function isAcceptedConsolidation(row: Pick<View, "text">): boolean {
 }
 const paths = (row: View) => row.about.filter(node => node.startsWith("path:"));
 const sharedPath = (a: View, b: View) => paths(a).some(node => paths(b).includes(node));
-const overlap = (a: Set<string>, b: Set<string>) => [...a].filter(word => b.has(word)).length / Math.max(1, Math.min(a.size, b.size));
+export const wordOverlap = (a: Set<string>, b: Set<string>) => [...a].filter(word => b.has(word)).length / Math.max(1, Math.min(a.size, b.size));
 
 /** Bounded deterministic proposals over already-screened rows. Never mutates a note or runs a model. */
 export function consolidationClusters(input: readonly View[], project: string, now: number): { clusters: ConsolidationCluster[]; truncated: boolean; engine: "fts5" | "substring" } {
@@ -37,12 +37,12 @@ export function consolidationClusters(input: readonly View[], project: string, n
   try {
     index.resync(() => rows.map(row => ({ id: row.id, at: row.at, project, tier: row.tier, scope: row.scope, body: `${row.title ?? ""}\n${row.text}` })));
     if (index.available && index.needsResync(rows.length)) throw Error("consolidation index unavailable");
-    const terms = new Map(rows.map(row => [row.id, words(row)]));
+    const terms = new Map(rows.map(row => [row.id, overlapWords(row)]));
     for (let i = 0; i < rows.length; i++) {
       const row = rows[i]!, candidates = index.available ? new Set(index.query([...terms.get(row.id)!].slice(0, 32).join(" "), rows.length, project).map(hit => hit.ref)) : undefined;
       for (const peer of rows.slice(i + 1)) {
         if (row.kind !== peer.kind) continue;
-        const lexical = overlap(terms.get(row.id)!, terms.get(peer.id)!);
+        const lexical = wordOverlap(terms.get(row.id)!, terms.get(peer.id)!);
         if (row.text === peer.text) add("supersession", [row, peer], "Identical text; review one replacement for both originals.");
         else if ((!candidates || candidates.has(peer.id)) && lexical >= 0.5 && sharedPath(row, peer)) add("merge", [row, peer], "Shared path and overlapping indexed terms; no equivalence is assumed.");
       }
@@ -52,8 +52,8 @@ export function consolidationClusters(input: readonly View[], project: string, n
     const failRows = rows.filter(row => row.kind === "fail"), decisions = rows.filter(row => row.kind === "decision" || row.kind === "contract");
     for (let i = 0; i < failRows.length; i++) for (const peer of failRows.slice(i + 1)) {
       const fail = failRows[i]!;
-      if (!sharedPath(fail, peer) || overlap(terms.get(fail.id)!, terms.get(peer.id)!) < 0.5) continue;
-      const fix = decisions.find(row => sharedPath(row, fail) && overlap(terms.get(row.id)!, terms.get(fail.id)!) >= 0.25);
+      if (!sharedPath(fail, peer) || wordOverlap(terms.get(fail.id)!, terms.get(peer.id)!) < 0.5) continue;
+      const fix = decisions.find(row => sharedPath(row, fail) && wordOverlap(terms.get(row.id)!, terms.get(fail.id)!) >= 0.25);
       if (fix) add("recurring-fix", [fail, peer, fix], "Repeated fail notes and a related decision on the same path; review whether the decision addresses the failures.");
     }
     return { clusters, truncated, engine: index.available ? "fts5" : "substring" };

package/src/memory/doctor.ts

@@ -57,6 +57,8 @@ export interface DoctorReport {
     duplicates: Section; stale: Section; candidates: Section; capture: Section; brief: Section; index: Section; readers: Section; policy: Section; cadence: Section;
     /** Added after v1 shipped (#132); additive, so the schema stays amem.doctor/v1. */
     drops: Section;
+    /** #188, additive: present only when the project's curated logs hold forget or prune operations. Informational; status is always ok. */
+    masked?: Section;
   };
 }
 
@@ -64,6 +66,13 @@ const worst = (values: SectionStatus[]): SectionStatus => values.includes("atten
 const message = (error: unknown): string => (error instanceof Error ? error.message : String(error)).split("\n")[0]!.slice(0, 200);
 const unavailable = (reason: string): Section => ({ status: "unavailable", reason });
 const skipped = (reason: string): Section => ({ status: "skipped", reason });
+/** #188: counts only, from the curated copy the doctor already opened. Never raises attention by itself. */
+function maskedSection(curated: MemoryStore | undefined): { masked?: Section } {
+  if (!curated) return {};
+  const { forgets, prunes } = curated.maskingCounts();
+  if (!forgets && !prunes) return {};
+  return { masked: { status: "ok", forgets, prunes, note: "masked entries stay in the local log and in sync history; see docs/purge.md" } };
+}
 const ids = (list: string[]): string[] => list.slice(0, MAX_IDS).map(id => id.slice(0, 8));
 const regularDir = (path: string): boolean => { try { const stat = lstatSync(path); return stat.isDirectory() && !stat.isSymbolicLink(); } catch { return false; } };
 const regularFile = (path: string): boolean => { try { const stat = lstatSync(path); return stat.isFile() && !stat.isSymbolicLink(); } catch { return false; } };
@@ -422,7 +431,7 @@ async function runDoctor(options: DoctorOptions): Promise<DoctorReport> {
   let sections: DoctorReport["sections"];
   try {
     await tick();
-    sections = { duplicates, stale, candidates, capture: captureSection(options), brief: await briefSection(options, curated, workBase, copyFailed), index, readers: readersSection(options), policy: policySection(options), cadence: cadenceSection(options), drops: dropsSection(options) };
+    sections = { duplicates, stale, candidates, capture: captureSection(options), brief: await briefSection(options, curated, workBase, copyFailed), index, readers: readersSection(options), policy: policySection(options), cadence: cadenceSection(options), drops: dropsSection(options), ...maskedSection(curated) };
     await tick();   // a signal that arrived during the last synchronous stage is handled while the guard is still installed
   } finally { try { curated?.close(); } finally { try { if (scratch) rmSync(scratch, { recursive: true, force: true }); } finally { unguard?.(); } } }
   return { schema: DOCTOR_SCHEMA, status: worst(Object.values(sections).map(section => section.status)), home: { path: options.home, source: options.homeSource }, project: options.project, sections };
@@ -432,6 +441,7 @@ async function runDoctor(options: DoctorOptions): Promise<DoctorReport> {
 const SECTION_TITLE: Record<keyof DoctorReport["sections"], string> = {
   duplicates: "duplicate notes", stale: "stale path references", candidates: "review candidates", capture: "capture per CLI", brief: "session brief",
   index: "index equals rebuild", readers: "reader leases", policy: "policy in effect", cadence: "ingest and sync cadence", drops: "recent capture drops",
+  masked: "forgotten or pruned entries (informational)",
 };
 
 function sectionDetail(name: string, detail: Record<string, unknown>, s: Style): string[] {

package/src/memory/external-import.ts

@@ -22,9 +22,11 @@ export interface ExternalImportResult {
   limitReached: boolean;
   skipped: { rules: number; policy: number; invalid: number; truncated: number };
   pending: PendingSummary;
+  /** Set only when no source layout exists: the absolute locations that were checked (#177). */
+  checked?: string[];
 }
 
-type SourceFile = { path: string; relative: string };
+type SourceFile = { path: string; relative: string; root?: string };
 type RawRecord = { text: string; title?: string; line?: number };
 type Discovery = { files: SourceFile[]; rules: number };
 
@@ -231,12 +233,22 @@ export async function importExternalMemory(opts: {
   const root = sourceRoot(source), project = resolveAlias(opts.base, opts.project), aliases = aliasedKeys(opts.base, project);
   const projectDirectory = opts.from === undefined && opts.source === "claude-auto" ? claudeProjectDirectory(opts.cwd ?? process.cwd()) : undefined;
   const discovery = root ? opts.source === "claude-auto" ? discoverClaude(root, projectDirectory) : discoverCodex(root) : { files: [], rules: 0 };
-  const result: ExternalImportResult = { source: opts.source, project, files: 0, read: 0, added: 0, queueFull: false, limitReached: false, skipped: { rules: discovery.rules, policy: 0, invalid: 0, truncated: 0 }, pending: { count: 0, oldestExpiresInDays: null, dueWithin7Days: 0, unshown: 0 } };
+  // #177: Codex memories v2 (default since 0.165.0) is the sibling root `memories_v2/`. Only the default location adds it;
+  // an explicit --from stays one root. v1 discovery, titles and order are unchanged; v2 titles carry a `memories_v2/` prefix.
+  const v2Source = opts.from === undefined && opts.source === "codex" ? join(dirname(source), "memories_v2") : undefined;
+  const v2Root = v2Source ? sourceRoot(v2Source) : undefined;
+  if (v2Root && discovery.files.length < EXTERNAL_IMPORT_LIMITS.maxFiles) {
+    const v2 = discoverCodex(v2Root);
+    discovery.rules += v2.rules;
+    for (const file of v2.files.slice(0, EXTERNAL_IMPORT_LIMITS.maxFiles - discovery.files.length)) discovery.files.push({ ...file, relative: `memories_v2/${file.relative}`, root: v2Root });
+  }
+  const result: ExternalImportResult = { source: opts.source, project, files: 0, read: 0, added: 0, queueFull: false, limitReached: false, skipped: { rules: discovery.rules, policy: 0, invalid: 0, truncated: 0 }, pending: { count: 0, oldestExpiresInDays: null, dueWithin7Days: 0, unshown: 0 },
+    ...(!root && !v2Root ? { checked: [source, ...(v2Source ? [v2Source] : [])] } : {}) };
   const store = new CandidateStore({ memoryDir: opts.base, reconcile: { canonical: project, aliases } });
   try {
     for (const file of discovery.files) {
       result.files++;
-      const input = readBounded(file.path, root!);
+      const input = readBounded(file.path, file.root ?? root!);
       if (!input) { result.skipped.invalid++; continue; }
       if (input.truncated) result.skipped.truncated++;
       for (const sourceRecord of records(file, input.text)) {

package/src/memory/forget-nearby.ts

@@ -0,0 +1,107 @@
+import { createHash } from "node:crypto";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { Database } from "bun:sqlite";
+import { machineId } from "./machine.ts";
+import { captureShardDir, shardDir } from "./shard.ts";
+import { CandidateStore, type Candidate } from "./candidates.ts";
+import { overlapWords, wordOverlap } from "./consolidation-clusters.ts";
+import { aliasedKeys } from "./aliases.ts";
+import { WorkListStore } from "./work-lists.ts";
+
+/** #188: ids per tier in a forget receipt; the total keeps counting past this. */
+export const FORGET_NEARBY_CAP = 20;
+/** The #174 candidate-overlap floor: half of the smaller word set shared. */
+const CANDIDATE_OVERLAP = 0.5;
+const CAPTURE_PAGE = 256, CAPTURE_PAGES = 8;
+
+export interface ForgetNearbyTier { ids: string[]; total: number; truncated: boolean }
+export interface ForgetNearby { capture: ForgetNearbyTier; candidates: ForgetNearbyTier; work: ForgetNearbyTier }
+
+/**
+ * Listing only, for the purge procedure (docs/purge.md step 4): same-project machine-local rows that contain or
+ * overlap a forgotten note's text. Ids and counts only, never text. Deterministic, no model or vectors:
+ * - capture: a read-only scan of the newest 2048 rows of the project's shard, matching the note text's longest line as a
+ *   case-insensitive substring of the excerpt (no migration or index build);
+ * - candidates: the #174 word-overlap measure (`overlapWords`/`wordOverlap`, >= 0.5) over each candidate's text;
+ * - work items: case-insensitive substring of that longest line in the task name or any string field. A task name can
+ *   itself hold the leak, and so can a list name, so a work item is listed as `work:<sha256(list)[:12]>#<sha256(task)[:12]>`,
+ *   never by name; a list name holding the text matches every item in it.
+ * Rows the screen refuses are neither listed nor counted. Each tier fails open to an empty result.
+ */
+export async function forgetNearby(opts: { base: string; project: string; text: string; title?: string | null; screen: (value: unknown) => boolean | Promise<boolean> }): Promise<ForgetNearby> {
+  const needle = probe(opts.text), words = overlapWords({ title: opts.title ?? null, text: opts.text });
+  const tier = (): ForgetNearbyTier & { add(id: string): void } => {
+    const result = { ids: [] as string[], total: 0, truncated: false, add(id: string) { result.total++; if (result.ids.length < FORGET_NEARBY_CAP) result.ids.push(id); else result.truncated = true; } };
+    return result;
+  };
+  const capture = tier(), candidates = tier(), work = tier();
+  const captureFile = needle ? join(captureShardDir(opts.base, opts.project, machineId(opts.base).id), "capture.db") : "";
+  if (needle && existsSync(captureFile)) {
+    try {
+      // Listing only: a read-only connection, so a forget never migrates the shard or builds an index as a side effect.
+      const db = new Database(captureFile, { readonly: true });
+      try {
+        db.run("PRAGMA busy_timeout = 200");
+        const projects = JSON.stringify([opts.project, ...aliasedKeys(opts.base, opts.project)]);
+        // SQLite lower() folds ASCII only; JavaScript's toLowerCase confirms the match for every script.
+        const limit = CAPTURE_PAGE * CAPTURE_PAGES, lower = needle.toLowerCase();
+        const rows = db.query("SELECT id, at, project, agent, event, tool, paths, status, excerpt FROM rows WHERE project IN (SELECT value FROM json_each(?)) ORDER BY id DESC LIMIT ?").all(projects, limit + 1) as { id: number; at: string; project: string; agent: string; event: string; tool: string | null; paths: string; status: string | null; excerpt: string }[];
+        if (rows.length > limit) capture.truncated = true;
+        for (const raw of rows.slice(0, limit).reverse()) {
+          if (!raw.excerpt.toLowerCase().includes(lower)) continue;
+          let paths: unknown = []; try { paths = JSON.parse(raw.paths); } catch { /* malformed paths are screened as empty */ }
+          if (await opts.screen({ ...raw, paths })) capture.add(`capture:${raw.id}`);
+        }
+      } finally { db.close(); }
+    } catch { /* unreadable or contended: nothing to list */ }
+  }
+  if (words.size && existsSync(join(opts.base, "candidates.db"))) {
+    try {
+      const store = new CandidateStore({ memoryDir: opts.base, reconcile: { canonical: opts.project, aliases: aliasedKeys(opts.base, opts.project) } });
+      try {
+        for (const row of store.list({ project: opts.project, status: "all" }).sort((a, b) => a.id.localeCompare(b.id))) {
+          const text = candidateText(row); if (!text) continue;
+          if (wordOverlap(words, overlapWords(text)) >= CANDIDATE_OVERLAP && await opts.screen(row.input)) candidates.add(row.id);
+        }
+      } finally { store.close(); }
+    } catch { /* no candidates database */ }
+  }
+  if (needle && [opts.project, ...aliasedKeys(opts.base, opts.project)].some(key => existsSync(join(shardDir(opts.base, key), "work", "log")))) {
+    try {
+      const store = new WorkListStore({ base: opts.base, project: opts.project, aliases: aliasedKeys(opts.base, opts.project), policy: async row => !!await opts.screen(row) });
+      try {
+        const lower = needle.toLowerCase();
+        for (const list of await store.read(undefined, true)) for (const item of list.items) {
+          const haystack = [list.list, item.task, ...Object.values(item.fields).filter((value): value is string => typeof value === "string")].join("\n").toLowerCase();
+          if (haystack.includes(lower)) work.add(`work:${shortHash(list.list)}#${shortHash(item.task)}`);
+        }
+      } finally { store.close(); }
+    } catch { /* no work lists */ }
+  }
+  const plain = (t: ForgetNearbyTier) => ({ ids: t.ids, total: t.total, truncated: t.truncated });
+  return { capture: plain(capture), candidates: plain(candidates), work: plain(work) };
+}
+
+const shortHash = (value: string) => createHash("sha256").update(value).digest("hex").slice(0, 12);
+
+/** The longest non-empty line, trimmed and bounded: the most specific fragment to look for. */
+function probe(text: string): string {
+  const line = text.split(/\r?\n/).map(part => part.trim()).sort((a, b) => b.length - a.length || a.localeCompare(b))[0] ?? "";
+  return line.length >= 8 ? line.slice(0, 200) : "";
+}
+function candidateText(row: Candidate): { title: string | null; text: string } | undefined {
+  const input = row.input;
+  if (input.kind === "memory") return { title: input.title ?? null, text: input.text };
+  if (input.kind === "correction") return { title: null, text: input.proposedText };
+  if (input.kind === "decay") return { title: null, text: input.reason };
+  if (input.kind === "fail") return { title: null, text: [input.approach, input.symptom, input.cause, input.retryWhen].join("\n") };
+  if (input.kind === "model-answer" || input.kind === "consolidation") return { title: null, text: input.text };
+  return undefined;
+}
+/** Human receipt lines; ids only. */
+export function forgetNearbyText(nearby: ForgetNearby): string[] {
+  const line = (label: string, t: ForgetNearbyTier) => t.total ? [`${label}: ${t.total}${t.truncated ? "+" : ""} (${t.ids.join(", ")}${t.total > t.ids.length ? ", ..." : ""})`] : [];
+  const lines = [...line("capture rows", nearby.capture), ...line("candidates", nearby.candidates), ...line("work items", nearby.work)];
+  return lines.length ? ["Machine-local rows in this project that contain or overlap the forgotten text (not deleted; see docs/purge.md step 4):", ...lines.map(text => `  ${text}`)] : [];
+}

package/src/memory/search-fts.ts

@@ -249,7 +249,7 @@ export class ScreenedSearchIndex<T> {
   }
 }
 
-interface RawCaptureRow { id: number; at: string; project: string; agent: string; event: string; tool: string | null; paths: string; status: string | null; excerpt: string }
+interface RawCaptureRow { id: number; at: string; project: string; agent: string; event: string; tool: string | null; paths: string; status: string | null; excerpt: string; session?: string | null; subagent?: number | null }
 
 /**
  * The capture leg of #13 search: BM25 over the excerpts of one capture shard (`machine/<id>` of a project shard,
@@ -269,7 +269,9 @@ export function captureSearch(dir: string, q: string, limit: number, notBefore?:
     const rows = (notBefore === undefined
       ? db.query(`SELECT r.*, bm25(fts) AS rank FROM fts JOIN rows r ON r.id = fts.rowid WHERE fts MATCH ? ORDER BY rank LIMIT ?`).all(match, limit)
       : db.query(`SELECT r.*, bm25(fts) AS rank FROM fts JOIN rows r ON r.id = fts.rowid WHERE fts MATCH ? AND r.at >= ? ORDER BY rank LIMIT ?`).all(match, notBefore, limit)) as (RawCaptureRow & { rank: number })[];
-    return rows.map((r) => ({ row: { id: r.id, at: r.at, project: r.project, agent: r.agent, event: r.event, tool: r.tool, paths: JSON.parse(r.paths) as string[], status: r.status, excerpt: r.excerpt }, rank: r.rank }));
+    return rows.map((r) => ({ row: { id: r.id, at: r.at, project: r.project, agent: r.agent, event: r.event, tool: r.tool, paths: JSON.parse(r.paths) as string[], status: r.status, excerpt: r.excerpt,
+      // #173 attribution, mirrored from capture-input.ts captureAttribution (this module stays import-light for the ablation harness).
+      ...(typeof r.session === "string" && /^[a-f0-9]{16}$/.test(r.session) ? { session: r.session } : {}), ...(r.subagent === 1 ? { subagent: true as const } : {}) }, rank: r.rank }));
   } catch { return []; }
   finally { db?.close(); }
 }

package/src/memory/store.ts

@@ -1553,6 +1553,14 @@ export class MemoryStore {
     return { short: all.filter((v) => v.tier === "short").length, long: all.filter((v) => v.tier === "long").length, segments, machine: this.machine };
   }
 
+  /**
+   * #188: counts only, for `amem doctor`. Forget operations in the index and, on a generation profile, prune rows.
+   * Masked entries stay in the local log and in sync history; nothing here reads or returns their text.
+   */
+  maskingCounts(): { forgets: number; prunes: number } {
+    const count = (sql: string) => { try { return Number((this.db.query(sql).get() as { n: number } | null)?.n ?? 0); } catch { return 0; } };
+    return { forgets: count("SELECT COUNT(*) AS n FROM ops WHERE op = 'forget'"), prunes: count("SELECT COUNT(*) AS n FROM generation_prunes") };
+  }
   /** The index's rows in a fixed order: what a rebuild must reproduce. */
   dump(): string {
     return JSON.stringify(["entries", "ops", "edges", "goals"].map((t) => this.db.query(`SELECT * FROM ${t} ORDER BY 1, 2`).all()));

package/src/session-brief.ts

@@ -199,6 +199,8 @@ export async function sessionStartBrief(options: BriefOptions): Promise<BriefRes
           const page = read({ project, limit: PAGE_ROWS, after });
           for (const row of page.rows) {
             if ((row as { project?: unknown }).project !== project) { coverage[section] = "partial"; continue; }
+            // #173: subagent capture stays searchable but never enters the session brief.
+            if (section === "capture" && (row as { subagent?: unknown }).subagent === true) continue;
             if (!await screen(row)) continue;
             if (selected++ >= SECTION_RECORDS) { coverage[section] = "partial"; return; }
             await add(section, display(row), section === "curated");

package/src/setup-gemini.ts

@@ -0,0 +1,31 @@
+import { isAbsolute, join, resolve } from "node:path";
+
+// Gemini CLI 0.61.0 (google-gemini/gemini-cli v0.61.0; docs/gemini-cli.md).
+// User settings: <GEMINI_CLI_HOME or HOME>/.gemini/settings.json (packages/core/src/utils/paths.ts homedir,
+// packages/core/src/config/storage.ts getGlobalSettingsPath). The Antigravity file
+// <home>/.gemini/config/mcp_config.json is a different client's and is never read or written here.
+type Env = Readonly<Record<string, string | undefined>>;
+
+/**
+ * GEMINI_CLI_HOME replaces the home directory for all Gemini CLI state. Never throws: the shared setup context
+ * computes every target's paths, so a relative value falls back to the home here and is refused only by
+ * assertGeminiHome when gemini is actually selected.
+ */
+export function geminiSettingsPath(env: Env, home: string): string {
+  const configured = env.GEMINI_CLI_HOME;
+  return join(configured && isAbsolute(configured) ? resolve(configured) : home, ".gemini", "settings.json");
+}
+/** A relative GEMINI_CLI_HOME would resolve against Gemini CLI's own cwd, so setup refuses it rather than guess. */
+export function assertGeminiHome(env: Env): void {
+  const configured = env.GEMINI_CLI_HOME;
+  if (configured !== undefined && configured !== "" && !isAbsolute(configured)) throw Error("setup requires an absolute GEMINI_CLI_HOME; unset it to use the home directory");
+}
+/** Gemini CLI expands $VAR, ${VAR} and ${VAR:-default} inside settings strings (packages/cli/src/utils/envVarResolver.ts). */
+export function assertGeminiRuntime(bun: string, entry: string): void {
+  if ([bun, entry].some(value => value.includes("$"))) throw Error("Gemini CLI expands $VAR placeholders in settings strings; setup cannot register this runtime exactly");
+}
+/** Native registration: user scope, stdio, in the private staging HOME (setup.ts stagingEnvironment). */
+export function geminiAddCommand(bun: string, entry: string): string[] {
+  return ["gemini", "mcp", "add", "--scope", "user", "--transport", "stdio", "amem", bun, "--", "--smol", entry, "mcp"];
+}
+export const GEMINI_REMOVE: readonly string[] = ["gemini", "mcp", "remove", "--scope", "user", "amem"];

package/src/setup-opencode.ts

@@ -0,0 +1,15 @@
+import type { ConfigImage } from "./setup-owned.ts";
+import { createJsonMcpCodec } from "./setup-json.ts";
+
+// OpenCode v1.18.35 keeps MCP servers under `mcp.<name>` in its global config
+// (packages/opencode/src/config/config.ts loadGlobal; docs/opencode.md).
+// ponytail: strict JSON only. A global opencode.jsonc is refused because its later merge could
+// override the entry; a comment-aware lexical view is the upgrade path.
+const codec = createJsonMcpCodec({ canonicalKey: "mcp", label: "OpenCode strict JSON" });
+export function readOpencodeMcp(image: ConfigImage): unknown { return codec.read(image); }
+export function putOpencodeMcp(image: ConfigImage, value: unknown): ConfigImage { return codec.put(image, value); }
+export function restoreOpencodeMcp(before: ConfigImage, after: ConfigImage, current: ConfigImage): ConfigImage { return codec.restore(before, after, current); }
+/** The local stdio server record OpenCode starts in the session's project directory (no `cwd`). */
+export function opencodeServer(bun: string, entry: string): Record<string, unknown> {
+  return { type: "local", command: [bun, "--smol", entry, "mcp"], enabled: true };
+}

package/src/setup-owned.ts

@@ -2,6 +2,7 @@ import { isDeepStrictEqual } from "node:util";
 import { SETUP_CONFIG_BYTES, setTomlPath, updateTomlArray } from "./setup-toml.ts";
 import { readJcodeMcp, putJcodeMcp, restoreJcodeMcp } from "./setup-jcode.ts";
 import { readAgyMcp, putAgyMcp, restoreAgyMcp } from "./setup-agy.ts";
+import { readOpencodeMcp, putOpencodeMcp, restoreOpencodeMcp } from "./setup-opencode.ts";
 export interface ConfigImage { bytes: string | null; mode: number }
 export const sameImage = (a: ConfigImage, b: ConfigImage): boolean => a.bytes === b.bytes && a.mode === b.mode;
 const text = (image: ConfigImage) => image.bytes === null ? "" : new TextDecoder("utf-8", { fatal: true }).decode(Buffer.from(image.bytes, "base64"));
@@ -18,12 +19,14 @@ function finishJson(value: Record<string, unknown>, current: ConfigImage, origin
 }
 export function mcpRecord(target: string, image: ConfigImage): unknown {
   if (target === "agy") return readAgyMcp(image);
+  if (target === "opencode") return readOpencodeMcp(image);
   if (target === "jcode") return readJcodeMcp(image);
   const doc = target === "codex" ? toml(image) : json(image), servers = doc[target === "codex" ? "mcp_servers" : "mcpServers"];
   return servers === undefined ? undefined : object(servers).amem;
 }
 export function putMcpRecord(target: string, current: ConfigImage, value: unknown): ConfigImage {
   if (target === "agy") return putAgyMcp(current, value);
+  if (target === "opencode") return putOpencodeMcp(current, value);
   if (target === "jcode") return putJcodeMcp(current, value);
   if (target === "codex") return rendered(setTomlPath(text(current), ["mcp_servers", "amem"], value), current);
   const doc = json(current), servers = { ...object(doc.mcpServers ?? {}) };
@@ -114,6 +117,7 @@ function restoreMcpOwned(target: string, before: ConfigImage, after: ConfigImage
 /** Exact restore when untouched; otherwise reverse only this receipt's managed entry/rows. */
 export function restoreOwned(target: string, index: number, before: ConfigImage, after: ConfigImage, current: ConfigImage): ConfigImage {
   if (target === "agy" && index === 0) return restoreAgyMcp(before, after, current);
+  if (target === "opencode" && index === 0) return restoreOpencodeMcp(before, after, current);
   if (target === "jcode" && index === 0) return restoreJcodeMcp(before, after, current);
   if (sameImage(current, after)) return before;
   if (sameImage(current, before)) return current;