@staix/agent-mem 0.16.0 → 0.18.0

package/src/memory/gc.ts

@@ -14,7 +14,8 @@ import { lifecycleResolver } from "./lifecycle.ts";
  * or rewritten (#13 AC5, #15 D7). An archived project is still bounded (cold shards shrink first); a forgotten one is skipped, never opened.
  */
 
-export interface GcShardPlan { key: string; state: "active" | "archived"; rows: number; bytes: number; capMb: number; retentionDays: number; expiredRows: number; overCap: boolean }
+/** `trimRows`: unexpired rows, oldest first, that must go for the shard to fit its cap once the expired ones are gone. `evict()` removes them in whole batches. */
+export interface GcShardPlan { key: string; state: "active" | "archived"; rows: number; bytes: number; capMb: number; retentionDays: number; expiredRows: number; overCap: boolean; trimRows: number }
 export interface GcShardResult { key: string; expired: number; trimmed: number; batches: number; remainingOverCap: boolean }
 export interface GcSkip { key: string; reason: string }
 export interface GcResult { dryRun: boolean; shards: GcShardResult[]; skipped: GcSkip[] }
@@ -26,15 +27,16 @@ export function planGc(base: string, opts: { now?: () => number } = {}): GcShard
   for (const shard of walkShards(base)) {
     const state = stateOf(shard.key);
     if (state === "forgotten") continue;
-    let rows = 0, bytes = 0, expiredRows = 0, capMb = 0, retentionDays = 0;
+    let rows = 0, bytes = 0, expiredRows = 0, capMb = 0, retentionDays = 0, trimRows = 0;
     for (const dir of shard.machineDirs) {
       const config = readCaptureConfig(dir, base);
       capMb = config.capMb; retentionDays = config.retentionDays;
-      const stats = captureShardStats(dir);
+      const stats = captureShardStats(dir), cutoff = new Date(now() - config.retentionDays * 24 * 3600_000).toISOString();
       rows += stats.rows; bytes += stats.bytes;
-      expiredRows += expiredIn(dir, new Date(now() - config.retentionDays * 24 * 3600_000).toISOString());
+      expiredRows += expiredIn(dir, cutoff);
+      trimRows += trimIn(dir, cutoff, config.capMb * 1024 * 1024);
     }
-    out.push({ key: shard.key, state, rows, bytes, capMb, retentionDays, expiredRows, overCap: capMb > 0 && bytes > capMb * 1024 * 1024 });
+    out.push({ key: shard.key, state, rows, bytes, capMb, retentionDays, expiredRows, overCap: capMb > 0 && bytes > capMb * 1024 * 1024, trimRows });
   }
   return out.sort((a, b) => a.key.localeCompare(b.key));
 }
@@ -48,6 +50,21 @@ function expiredIn(dir: string, cutoff: string): number {
   } catch { return 0; }
 }
 
+/** Each machine directory has its own cap (evict() runs per store): the unexpired rows, oldest first, that must go to fit it. Read-only. */
+function trimIn(dir: string, cutoff: string, capBytes: number): number {
+  if (capBytes <= 0 || !existsSync(join(dir, "capture.db"))) return 0;
+  try {
+    const db = new Database(join(dir, "capture.db"), { readonly: true });
+    try {
+      db.run("PRAGMA busy_timeout = 3000");
+      const kept = db.query("SELECT bytes FROM rows WHERE at >= ? ORDER BY at, id").all(cutoff) as { bytes: number }[];
+      let left = kept.reduce((sum, row) => sum + row.bytes, 0), n = 0;
+      for (const row of kept) { if (left <= capBytes) break; left -= row.bytes; n++; }
+      return n;
+    } finally { db.close(); }
+  } catch { return 0; }
+}
+
 export function runGc(base: string, opts: GcOptions = {}): GcResult {
   const maxBatches = opts.maxBatchesPerShard ?? 1;
   if (!Number.isSafeInteger(maxBatches) || maxBatches < 1 || maxBatches > 1000) throw new Error("maxBatchesPerShard takes a number from 1 to 1000");

package/src/memory/metrics.ts

@@ -36,8 +36,8 @@ export function readMetrics(base: string, limit = METRICS_KEEP): MetricSample[]
 }
 
 
-export type CaptureDropReason = "spool_full" | "cwd_removed" | "undrainable_expired" | "scope_unknown" | "project_archived" | "project_forgotten";
-const DROP_REASONS: readonly CaptureDropReason[] = ["spool_full", "cwd_removed", "undrainable_expired", "scope_unknown", "project_archived", "project_forgotten"];
+export type CaptureDropReason = "spool_full" | "cwd_removed" | "undrainable_expired" | "scope_unknown" | "project_archived" | "project_forgotten" | "unknown_schema_expired";
+const DROP_REASONS: readonly CaptureDropReason[] = ["spool_full", "cwd_removed", "undrainable_expired", "scope_unknown", "project_archived", "project_forgotten", "unknown_schema_expired"];
 /** Numeric notice only, bounded to the rolling metric tail; never an all-time counter. Fails open to no counts: hooks never deny over metrics. */
 export function captureDropSummary(base: string): Partial<Record<CaptureDropReason, number>> {
   const read = readCaptureDrops(base);

package/src/memory/search-fts.ts

@@ -1,4 +1,4 @@
-import { rankedScoreSql, rankedScoreSqlDetails, type ScoreFactors } from "./search-score.ts";
+import { captureEventWeightSql, rankedScoreSql, rankedScoreSqlDetails, type ScoreFactors } from "./search-score.ts";
 import { Database } from "bun:sqlite";
 import { chmodSync, existsSync } from "node:fs";
 import { join } from "node:path";
@@ -204,8 +204,8 @@ export class ScreenedSearchIndex<T> {
       if ((db.query("SELECT sqlite_compileoption_used('TEMP_STORE=3') AS memoryOnly").get() as { memoryOnly: number }).memoryOnly) throw Error("disk-backed search unavailable");
       db.run("PRAGMA temp_store = FILE");
       db.run(this.available
-        ? "CREATE VIRTUAL TABLE temp.docs USING fts5(body, ref UNINDEXED, tier UNINDEXED, at UNINDEXED, payload UNINDEXED, expires UNINDEXED)"
-        : "CREATE TEMP TABLE docs (body TEXT, ref TEXT, tier TEXT, at TEXT, payload TEXT, expires REAL)");
+        ? "CREATE VIRTUAL TABLE temp.docs USING fts5(body, ref UNINDEXED, tier UNINDEXED, at UNINDEXED, payload UNINDEXED, expires UNINDEXED, event UNINDEXED, session UNINDEXED)"
+        : "CREATE TEMP TABLE docs (body TEXT, ref TEXT, tier TEXT, at TEXT, payload TEXT, expires REAL, event TEXT, session TEXT)");
       db.run("PRAGMA temp.cache_size = -2048");
       // A platform spill minimum can exceed cache_size (macOS: 20,000 pages).
       // Spill at the cache target so dirty TEMP pages cannot accumulate behind that minimum.
@@ -214,13 +214,13 @@ export class ScreenedSearchIndex<T> {
     } catch (error) { db?.close(); throw error; }
   }
 
-  append(rows: readonly { body: string; ref: string; tier: string; at: string; value: T; expiresAt?: string | null }[]): void {
-    const insert = this.db.query("INSERT INTO docs (body, ref, tier, at, payload, expires) VALUES (?, ?, ?, ?, ?, ?)");
+  append(rows: readonly { body: string; ref: string; tier: string; at: string; value: T; expiresAt?: string | null; event?: string; session?: string }[]): void {
+    const insert = this.db.query("INSERT INTO docs (body, ref, tier, at, payload, expires, event, session) VALUES (?, ?, ?, ?, ?, ?, ?, ?)");
     this.db.transaction(() => {
       for (const row of rows) {
         const deadline = row.expiresAt == null ? null : Date.parse(row.expiresAt);
         // Invalid deadlines fail closed; this sentinel predates every representable Date.
-        insert.run(row.body, row.ref, row.tier, row.at, JSON.stringify(row.value), deadline !== null && !Number.isFinite(deadline) ? Number.MIN_SAFE_INTEGER : deadline);
+        insert.run(row.body, row.ref, row.tier, row.at, JSON.stringify(row.value), deadline !== null && !Number.isFinite(deadline) ? Number.MIN_SAFE_INTEGER : deadline, row.event ?? null, row.session ?? null);
       }
     })();
   }
@@ -242,6 +242,31 @@ export class ScreenedSearchIndex<T> {
     });
   }
 
+  /** Weighted capture-only fill after the caller fixes the legacy noncapture slots. The caller has already screened every row before append. */
+  bestCaptureGroups(query: string, limit: number, now: number, useFts = this.available, explain = false): { value: T; score: number; scoreDetails?: ScoreFactors }[] {
+    if (!Number.isSafeInteger(limit) || limit < 1 || useFts && !ftsTerms(query)) return [];
+    const instant = new Date(now).toISOString(), score = useFts ? SCREENED_SCORE : SCREENED_SUBSTRING_SCORE;
+    const weight = captureEventWeightSql("event");
+    const factors = explain ? rankedScoreSqlDetails(useFts ? "bm25(docs)" : "-1.0", useFts) : undefined;
+    const columns = factors ? `, ${factors.rawBm25Rank} AS rawBm25Rank, ${factors.tierFactor} AS tierFactor, ${factors.recencyFactor} AS recencyFactor` : "";
+    const where = "WHERE tier = 'capture' AND (expires IS NULL OR expires > ?)" + (useFts ? " AND docs MATCH ?" : "");
+    const selected: { value: T; score: number; scoreDetails?: ScoreFactors }[] = [], groups = new Set<string>();
+    // Sort once in SQLite-owned TEMP storage, then stream past duplicate sessions without growing JS pages or re-sorting OFFSET windows.
+    const statement = this.db.query(`SELECT payload, ref, event, session, ${score} AS score${columns} FROM docs ${where} ORDER BY score * ${weight} DESC, ref`);
+    const orderedArgs = [instant, ...(explain ? [instant] : []), now, ...(useFts ? [ftsTerms(query)] : [])];
+    for (const row of statement.iterate(...orderedArgs) as Iterable<{ payload: string; ref: string; event: string | null; session: string | null; score: number; rawBm25Rank?: number | null; tierFactor?: number | null; recencyFactor?: number | null }>) {
+      const session = typeof row.session === "string" && /^[a-f0-9]{16}$/.test(row.session) ? row.session : undefined;
+      const group = session ? `session:${session}` : `row:${row.ref}`;
+      if (groups.has(group)) continue;
+      groups.add(group);
+      const hit: { value: T; score: number; scoreDetails?: ScoreFactors } = { value: JSON.parse(row.payload) as T, score: row.score };
+      if (explain) hit.scoreDetails = { rawBm25Rank: row.rawBm25Rank ?? null, tierFactor: row.tierFactor ?? null, recencyFactor: row.recencyFactor ?? null, finalScore: row.score, matchMode: useFts ? "fts5" : "substring" };
+      selected.push(hit);
+      if (selected.length === limit) break;
+    }
+    return selected;
+  }
+
   close(): void {
     if (this.closed) return;
     this.closed = true;
@@ -250,6 +275,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; session?: string | null; subagent?: number | null }
+export interface CaptureSearchOptions { weightEvents?: boolean; onePerSession?: boolean; now?: number }
 
 /**
  * The capture leg of #13 search: BM25 over the excerpts of one capture shard (`machine/<id>` of a project shard,
@@ -257,21 +283,43 @@ interface RawCaptureRow { id: number; at: string; project: string; agent: string
  * Rows older than `notBefore` (an ISO time) are left out; the store passes the shard's retention cutoff, so an expired
  * row is not recalled before a later append evicts it.
  */
-export function captureSearch(dir: string, q: string, limit: number, notBefore?: string): { row: CaptureRow; rank: number }[] {
+export function captureSearch(dir: string, q: string, limit: number, notBefore?: string, options: CaptureSearchOptions = {}): { row: CaptureRow; rank: number }[] {
   const match = ftsTerms(q);
-  if (!match || !fts5Available() || !existsSync(join(dir, "capture.db"))) return [];
+  if (!match || !Number.isSafeInteger(limit) || limit < 1 || !fts5Available() || !existsSync(join(dir, "capture.db"))) return [];
+  const weightEvents = options.weightEvents !== false, onePerSession = options.onePerSession ?? weightEvents;
+  const eventWeight = captureEventWeightSql("r.event");
+  const weightedOrder = `bm25(fts) * ${eventWeight}, r.id`;
+  const selected: { row: CaptureRow; rank: number }[] = [], groups = new Set<string>();
   let db: Database | undefined;
   try {
     db = new Database(join(dir, "capture.db"), { readonly: true });
     db.run("PRAGMA busy_timeout = 3000");
     if (!db.query("SELECT 1 FROM sqlite_master WHERE name = 'fts' AND type = 'table'").get()) return [];
-    // `notBefore` (retention cutoff, `since`) runs inside the query: rows past it never take a LIMIT slot.
-    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,
-      // #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 }));
+    // Filter first, then sort once. In the grouped path the first row of each session is
+    // its best complete-score match, so stopping at limit cannot hide a better unread row.
+    const matchWhere = notBefore === undefined ? "fts MATCH ?" : "fts MATCH ? AND r.at >= ?";
+    const args: (string | number)[] = notBefore === undefined ? [match] : [match, notBefore];
+    const order = onePerSession
+      ? `${rankedScoreSql("bm25(fts)")} * ${weightEvents ? eventWeight : "1.0"} DESC, r.id`
+      : weightEvents ? weightedOrder : "rank";
+    // The capture tier is an existing score input, projected only for the shared SQL recipe.
+    const sql = `SELECT r.*, ${onePerSession ? "'capture' AS tier, " : ""}bm25(fts) AS rank FROM fts JOIN rows r ON r.id = fts.rowid WHERE ${matchWhere} ORDER BY ${order}${onePerSession ? "" : " LIMIT ?"}`;
+    args.push(onePerSession ? new Date(options.now ?? Date.now()).toISOString() : limit);
+    const statement = db.query(sql);
+    const rows = (onePerSession ? statement.iterate(...args) : statement.all(...args)) as Iterable<RawCaptureRow & { rank: number }>;
+    for (const r of rows) {
+      const session = typeof r.session === "string" && /^[a-f0-9]{16}$/.test(r.session) ? r.session : undefined;
+      if (onePerSession && session) {
+        if (groups.has(session)) continue;
+        groups.add(session);
+      }
+      const row: 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 attribution, mirrored from capture-input.ts captureAttribution (this module stays import-light for the ablation harness).
+        ...(session ? { session } : {}), ...(r.subagent === 1 ? { subagent: true as const } : {}) };
+      selected.push({ row, rank: r.rank });
+      if (selected.length === limit) break;
+    }
+    return selected;
   } catch { return []; }
   finally { db?.close(); }
 }

package/src/memory/search-score.ts

@@ -14,6 +14,16 @@ type ScoreExpr = { op: "rank" | "tier" | "age" } | { op: "constant"; value: numb
 const MONTH_DAYS = 30;
 const TIER_WEIGHTS: Readonly<Record<string, number>> = { long: 1, capture: 0.5 };
 const DEFAULT_TIER_WEIGHT = 0.9;
+// ponytail: fixed 1.25x ceiling for conversational capture, not a learned relevance model.
+// Raise it only with fresh S/M no-loss and private-capture evidence; curated tier factors stay unchanged.
+export const CAPTURE_CONVERSATION_WEIGHT = 1.25;
+export function captureEventWeight(event: string): number {
+  return event === "Stop" || event === "UserPromptSubmit" ? CAPTURE_CONVERSATION_WEIGHT : 1;
+}
+/** Only fixed internal SQL identifiers are supplied by callers; event values remain stored data. */
+export function captureEventWeightSql(eventColumn: string): string {
+  return `(CASE WHEN ${eventColumn} IN ('Stop', 'UserPromptSubmit') THEN ${CAPTURE_CONVERSATION_WEIGHT} ELSE 1.0 END)`;
+}
 const TIER_FACTOR: ScoreExpr = { op: "tier" };
 const DENOMINATOR: ScoreExpr = { op: "add", left: { op: "constant", value: 1 }, right: { op: "max", left: { op: "constant", value: 0 }, right: { op: "age" } } };
 const RECENCY_FACTOR: ScoreExpr = { op: "reciprocal", value: DENOMINATOR };
@@ -53,6 +63,9 @@ function sql(expr: ScoreExpr, rank: string): string {
 export function rankedScore(rank: number, tier: string, at: string, now: number): number {
   return numeric(SCORE, rank, tier, at, now);
 }
+export function captureWeightedScore(rank: number, event: string, at: string, now: number): number {
+  return rankedScore(rank, "capture", at, now) * captureEventWeight(event);
+}
 /** SQL uses fixed internal identifiers and bound clock values, never interpolated row/query input. */
 export function rankedScoreSql(rank = "bm25(docs)"): string { return sql(SCORE, rank); }
 export function rankedScoreSqlDetails(rank = "bm25(docs)", useFts = true): { rawBm25Rank: string; tierFactor: string; recencyFactor: string } {

package/src/memory/store.ts

@@ -1094,6 +1094,7 @@ export class MemoryStore {
     for (const store of this.readStores()) store.syncSearchIndex();
     const now = this.now();
     const hits: SearchHit[] = [];
+    let captureShard: string | undefined, captureNotBefore: string | undefined;
     // The project filter runs inside the FTS query (its rows plus shared ones), so a busy sibling project can never
     // starve this project's LIMIT.
     // Superseded, forgotten, expired and `since` rows are filtered after FTS, so a fixed candidate cap could be filled
@@ -1122,13 +1123,17 @@ export class MemoryStore {
     // #15 D4/T1: the capture tier is project-scoped; without a project key there is no shard to recall from.
     if (f.includeCapture !== false && f.project) {
       const shard = shardMachineDir(this.memoryBaseDir, resolveAlias(this.memoryBaseDir, f.project), this.machine.id);
+      captureShard = shard;
       // The retention cutoff and `since` run in the capture query, so neither expired nor old rows take a candidate slot.
       // An out-of-range retention_days gives no cutoff rather than failing the whole search (eviction keeps its own check).
       const override = f.captureRetentionDays, days = typeof override === "number" && Number.isFinite(override) && override > 0 ? override : readCaptureConfig(shard, this.memoryBaseDir).retentionDays;
       const cutoff = new Date(now - days * 24 * 3600_000);
       const retained = Number.isFinite(cutoff.getTime()) ? cutoff.toISOString() : undefined;
       const since = f.since && Number.isFinite(Date.parse(f.since)) ? new Date(Date.parse(f.since)).toISOString() : undefined;
-      for (const { row, rank } of captureSearch(shard, q, Math.max(limit * 4, 32), since && (!retained || since > retained) ? since : retained)) {
+      captureNotBefore = since && (!retained || since > retained) ? since : retained;
+      // First reproduce the old unweighted BM25 candidate window. Only these baseline capture slots may change;
+      // curated membership and positions are not affected by conversational weighting or session collapse.
+      for (const { row, rank } of captureSearch(shard, q, Math.max(limit * 4, 32), captureNotBefore, { weightEvents: false, onePerSession: false })) {
         const selected: SearchHit = { source: "capture", score: rankedScore(rank, "capture", row.at, now), capture: row };
         if (f.explain) selected.scoreDetails = rankedScoreDetails("capture", rank, "capture", row.at, now, selected.score);
         hits.push(selected);
@@ -1144,7 +1149,23 @@ export class MemoryStore {
     }
     const ref = (h: SearchHit): string => h.view?.id ?? String(h.capture?.id ?? 0).padStart(12, "0");
     hits.sort((a, b) => b.score - a.score || ref(a).localeCompare(ref(b)));
-    return { engine: "fts5", hits: hits.slice(0, limit) };
+    const baseline = hits.slice(0, limit), captureSlots = baseline.filter(hit => hit.source === "capture").length;
+    if (!captureSlots || !captureShard) return { engine: "fts5", hits: baseline };
+    // Stream session representatives in complete weighted-score order; the legacy
+    // baseline above still owns noncapture slots and exposed scores remain unweighted.
+    const weighted = captureSearch(captureShard, q, captureSlots, captureNotBefore,
+      { weightEvents: true, onePerSession: true, now });
+    const replacements = weighted.map(({ row, rank }) => {
+      const score = rankedScore(rank, "capture", row.at, now), hit: SearchHit = { source: "capture", score, capture: row };
+      if (f.explain) hit.scoreDetails = rankedScoreDetails("capture", rank, "capture", row.at, now, score);
+      return hit;
+    });
+    let nextCapture = 0;
+    const selected = baseline.flatMap(hit => {
+      if (hit.source !== "capture") return [hit];
+      const replacement = replacements[nextCapture++]; return replacement ? [replacement] : [];
+    });
+    return { engine: "fts5", hits: selected };
   }
 
   /** Bring the derived FTS copy level with the curated rows when a prune, a crash, a lock or a rebuild drifted them apart. */

package/src/session-brief.ts

@@ -17,6 +17,8 @@ import type { MemoryStore, View } from "./memory/store.ts";
 import { WorkListStore, type WorkListFields, type WorkListView } from "./memory/work-lists.ts";
 
 export interface BriefOptions { cwd: string; base?: string; project?: string; maxTokens?: number; policy?: StandalonePolicyOptions;
+  /** Repository-less hosts use only machine policy and omit the repo section, even if their home lies inside a repository. */
+  repository?: false;
   /** Host-only monotonic budget probe. The native hook still owns the hard child deadline. */
   timeRemaining?: () => number;
   /** Host-only parent CLI path: precomputed owned process identity and zero-wait stores. */
@@ -26,7 +28,7 @@ export interface BriefOptions { cwd: string; base?: string; project?: string; ma
   /** Test seam for the pending-candidate line's clock. */
   now?: () => number;
   /**
-   * `amem doctor` only (F15): size the brief without writing to the memory home. No reader lease is taken. The caller supplies the two sections that would otherwise
+   * Read-only diagnostic/console projection: build the brief without writing to the memory home. No reader lease is taken. The caller supplies the two sections that would otherwise
    * open a store read-write: `curated` is a store opened on a private copy of the logs (absent: the project has no curated notes, an empty complete section) and
    * `workBase` is a private base holding a copy of the project's and its aliases' work logs (absent: the work section is `unavailable`, never claimed complete).
    * The capture section opens this machine's capture database read-only, and only when it exists.
@@ -104,7 +106,7 @@ export async function sessionStartBrief(options: BriefOptions): Promise<BriefRes
   try {
     if (options.nativeSession && typeof options.timeRemaining !== "function") return result;
     const cwdForConfig = options.cwd, baseForConfig = canonicalPath(options.base ?? memoryHome());
-    const configuredBrief = loadAmemConfig(baseForConfig, repoConfigRoot(cwdForConfig)).config.briefBytes;
+    const configuredBrief = loadAmemConfig(baseForConfig, options.repository === false ? undefined : repoConfigRoot(cwdForConfig)).config.briefBytes;
     // A caller's explicit budget wins over the default; the person's configured budget can only lower either.
     const maximum = Math.min(options.maxTokens ?? DEFAULT_TOKENS, configuredBrief ?? Number.MAX_SAFE_INTEGER);
     if (!Number.isSafeInteger(maximum) || maximum < 1) return result;
@@ -112,7 +114,7 @@ export async function sessionStartBrief(options: BriefOptions): Promise<BriefRes
     const requested = options.project ?? memoryProjectKey(cwd, { repositoryIsolation: true }), project = resolveAlias(base, requested);
     // #15 T5: a project the person archived or forgot yields no brief at all, before any lease, store or screen is opened.
     if (projectState(base, project) !== "active") return result;
-    const policy = createStandalonePolicy(configuredPolicyOptions(base, cwd, options.policy)), release = options.measureOnly ? Object.assign(() => {}, { verify: () => {} }) : registerReaderLease(base, options.nativeSession ? { signature: options.nativeSession.signature, busyTimeoutMs: 0 } : undefined);
+    const policy = createStandalonePolicy(configuredPolicyOptions(base, options.repository === false ? undefined : cwd, options.policy)), release = options.measureOnly ? Object.assign(() => {}, { verify: () => {} }) : registerReaderLease(base, options.nativeSession ? { signature: options.nativeSession.signature, busyTimeoutMs: 0 } : undefined);
     closers.push(release);
     const selection = readSelector(base).revision;
     const sharded = !!lstatSync(join(base, "shards.json"), { throwIfNoEntry: false });
@@ -138,7 +140,7 @@ export async function sessionStartBrief(options: BriefOptions): Promise<BriefRes
     const coverage: BriefResult["coverage"] = { work: "complete", curated: "complete", capture: "complete" };
     // #15 T4: the bound repository's `.amem/log.jsonl`, only when the repository IS this project (AC3). The `lstat` probe comes FIRST and on every path (the SessionStart
     // worker builds this brief without `nativeSession`): a repository with no `.amem/log.jsonl` at or above the cwd costs a few syscalls and no git process.
-    const repoRoot = !repoLogNearby(cwd) ? undefined : options.projectFromCwd ? nearestRepoRootWithLog(cwd) : boundRepoRoot(cwd, base, project);
+    const repoRoot = options.repository === false || !repoLogNearby(cwd) ? undefined : options.projectFromCwd ? nearestRepoRootWithLog(cwd) : boundRepoRoot(cwd, base, project);
     if (repoLogPresent(repoRoot)) coverage.repo = "complete";
     const lines: string[] = [];
     const reasons: Partial<Record<Section, string>> = {};
@@ -179,7 +181,7 @@ export async function sessionStartBrief(options: BriefOptions): Promise<BriefRes
       await run("work", async () => {
         const measured = options.measureOnly;
         if (measured && !measured.workBase) { coverage.work = "unavailable"; return; }
-        if (measured && !lstatSync(join(shardDir(measured.workBase!, project), "work", "log"), { throwIfNoEntry: false })) return;   // no work log: the real brief shows an empty list
+        if (measured && ![project, ...aliases].some(key => lstatSync(join(shardDir(measured.workBase!, key), "work", "log"), { throwIfNoEntry: false }))) return;   // no work log: the real brief shows an empty list
         const work = new WorkListStore({ base: measured?.workBase ?? base, project, aliases, policy: screen, ...(options.nativeSession ? { busyTimeoutMs: 0, timeRemaining: options.timeRemaining } : {}) }); closers.push(() => work.close());
         // Complete operation rows AND the composed view are screened before closed-item filtering or display caps.
         const views = await work.read(undefined, true); guard();

package/src/setup-console.ts

@@ -0,0 +1,50 @@
+import { createHash } from "node:crypto";
+import { chmodSync, lstatSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { isDeepStrictEqual } from "node:util";
+
+export interface ConsoleSetup { file: string; module: string; change: "add" | "replace" | "unchanged" | "remove" | "none"; reason?: string }
+
+/**
+ * `amem setup console`: the acon plugin manifest `{api, tool, module, sha256}` at `$AGENTHUB_HOME/console/plugins/amem.json`, in a 0700 directory
+ * and a 0600 file, which is what agent-console's scanPlugins accepts. Preview writes nothing; undo removes only a manifest that points at this install.
+ */
+export function consoleSetup(mode: "preview" | "apply" | "undo", env: Readonly<Record<string, string | undefined>> = process.env,
+  module = fileURLToPath(new URL("./ui/plugin.ts", import.meta.url))): ConsoleSetup {
+  const family = env.AGENTHUB_HOME?.trim() ? resolve(env.AGENTHUB_HOME) : join(env.HOME?.trim() || homedir(), ".agenthub");
+  const dir = join(family, "console", "plugins"), file = join(dir, "amem.json");
+  // acon refuses a manifest directory or file that is a link, another kind of entry or another user's; so does setup, before writing anything.
+  for (const [path, kind] of [[dir, "directory"], [file, "file"]] as const) {
+    const info = lstatSync(path, { throwIfNoEntry: false });
+    if (!info) continue;
+    if (kind === "directory" ? !info.isDirectory() : !info.isFile()) throw Error(`${path}: acon needs a real ${kind}, not a link or another entry`);
+    if (typeof process.getuid === "function" && info.uid !== process.getuid()) throw Error(`${path} is owned by another user; acon would refuse it`);
+  }
+  const before = lstatSync(file, { throwIfNoEntry: false }) ? JSON.parse(readFileSync(file, "utf8")) as Record<string, unknown> : undefined;
+  if (mode === "undo") {
+    if (!before) return { file, module, change: "none", reason: "no console manifest" };
+    if (before.module !== module) throw Error(`${file} points at another amem install (${String(before.module)}); left as is`);
+    unlinkSync(file);
+    return { file, module, change: "remove" };
+  }
+  const next = { api: 1, tool: "amem", module, sha256: createHash("sha256").update(readFileSync(module)).digest("hex") };
+  const mode7 = (path: string, want: number) => (lstatSync(path, { throwIfNoEntry: false })?.mode ?? want) & 0o777;
+  const modesOk = mode7(dir, 0o700) === 0o700 && mode7(file, 0o600) === 0o600;
+  if (isDeepStrictEqual(before, next) && modesOk) return { file, module, change: "unchanged" };
+  const change = before ? "replace" : "add";
+  if (mode === "apply") {
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    chmodSync(dir, 0o700);
+    const temp = `${file}.${process.pid}.tmp`;
+    writeFileSync(temp, `${JSON.stringify(next, null, 2)}\n`, { mode: 0o600 });
+    renameSync(temp, file);
+    chmodSync(file, 0o600);
+  }
+  return { file, module, change, ...(modesOk ? {} : { reason: "permissions: plugin directory 0700, manifest 0600" }) };
+}
+
+export const consoleSetupText = (result: ConsoleSetup, mode: "preview" | "apply" | "undo"): string =>
+  `console plugin: ${mode === "preview" && result.change !== "unchanged" && result.change !== "none" ? `would ${result.change}` : result.change} ${result.file}${result.change === "remove" || result.change === "none" ? "" : ` -> ${result.module}`}${result.reason ? ` (${result.reason})` : ""}`
+  + (mode === "preview" && result.change !== "unchanged" ? "\nPreview only; add --apply to write it, --undo to remove it. Re-run after upgrading amem: acon refuses a module whose hash changed." : "");

package/src/ui/panel.css

@@ -0,0 +1,15 @@
+.amem { display: flex; flex-direction: column; gap: var(--acon-space-3); min-width: 0; }
+.amem > .btn, .amem-card > .btn { align-self: flex-start; }
+.amem-bar { display: flex; flex-wrap: wrap; align-items: center; gap: var(--acon-space-2); }
+.amem-bar input[type="search"] { flex: 1; min-width: 0; max-width: 480px; }
+.amem-inline { display: inline-flex; flex-wrap: wrap; gap: var(--acon-space-2); }
+.amem-input { min-height: 32px; min-width: 0; max-width: 100%; padding: 0 10px; border: 1px solid var(--acon-line-2); border-radius: var(--acon-radius-2); background: var(--acon-surface); color: var(--acon-text); font: inherit; }
+.amem-text { width: 100%; min-height: 10em; padding: var(--acon-space-2) 10px; font: var(--acon-text-sm)/1.5 var(--acon-font-mono); resize: vertical; }
+.amem-form { display: flex; flex-direction: column; gap: var(--acon-space-2); }
+.amem-form .btn { align-self: flex-start; }
+.amem-sub { margin: 0; color: var(--acon-text-2); overflow-wrap: anywhere; }
+.amem-card { display: flex; flex-direction: column; gap: var(--acon-space-2); }
+.amem-card h3 { margin: 0; font-size: var(--acon-text-lg); }
+.amem-diff { display: flex; flex-direction: column; gap: var(--acon-space-1); }
+.amem-pre { margin: 0 0 var(--acon-space-2); padding: var(--acon-space-3); max-height: 40vh; overflow: auto; white-space: pre-wrap; overflow-wrap: anywhere; background: var(--acon-surface-2); border: 1px solid var(--acon-line); border-radius: var(--acon-radius-2); font: var(--acon-text-sm)/1.5 var(--acon-font-mono); }
+@media (max-width: 600px) { .amem-inline { width: 100%; } .amem-inline .amem-input { flex: 1; } }

package/src/ui/panel.js

@@ -0,0 +1,154 @@
+// amem console panels (acon api 1). Runs under the shell's strict CSP and renders data as text through host.ui only.
+export default (host) => {
+  const { ui } = host;
+  const { h } = ui;
+  const root = h("div", { class: "amem" });
+  host.mount.append(root);
+  let panel = "review", params = {}, project = null;
+  const go = (p, extra = {}) => host.navigate(host.tool, p, { ...(project ? { project } : {}), ...extra });
+  const btn = (text, onclick, cls = "btn") => h("button", { type: "button", class: cls, text, onclick });
+  const day = (iso) => (typeof iso === "string" ? iso.slice(0, 16).replace("T", " ") : "");
+  const line = (text, max = 120) => { const flat = String(text ?? "").replace(/\s+/g, " ").trim(); return flat.length > max ? `${flat.slice(0, max - 3)}...` : flat; };
+  const act = (input) => host.action({ ...input, ...(project ? { project } : {}) });
+
+  const picker = (s) => {
+    const list = s.projects ?? [];
+    if (list.length < 2) return list.length ? h("p", { class: "amem-sub", text: `Project ${list[0]}` }) : null;
+    const select = h("select", { name: "project", class: "amem-input", "aria-label": "Project", onchange: () => { project = select.value; go(panel); } },
+      list.map((key) => { const o = h("option", { value: key, text: key }); if (key === s.project) o.selected = true; return o; }));
+    return h("label", { class: "amem-bar" }, h("span", { text: "Project" }), select);
+  };
+
+  const reviewDetail = (r) => {
+    const reason = h("input", { type: "text", name: "reason", class: "amem-input", placeholder: "Reason (optional)", "aria-label": "Reject reason (optional)" });
+    const actions = [
+      r.acceptable ? btn("Accept", () => act({ action: "accept", id: r.id }), "btn primary") : null,
+      h("form", { class: "amem-inline", onsubmit: (e) => { e.preventDefault(); act({ action: "reject", id: r.id, ...(reason.value.trim() ? { reason: reason.value.trim() } : {}) }); } },
+        reason, h("button", { type: "submit", class: "btn", text: "Reject" })),
+    ].filter(Boolean);
+    const sections = [];
+    if (r.diff) sections.push({ title: "Now and proposed", open: true, body: h("div", { class: "amem-diff" },
+      h("strong", { text: "Now" }), h("pre", { class: "amem-pre", text: r.diff.now ?? "(the current note is not visible)" }),
+      h("strong", { text: "Proposed" }), h("pre", { class: "amem-pre", text: r.diff.proposed }),
+      h("p", { class: "amem-sub", text: `Reason: ${r.diff.reason}` })) });
+    const evidence = [...(r.evidence ?? []).map((ref) => ({ title: ref, sub: "evidence reference" })),
+      ...(r.targets ?? []).map((t) => ({ title: t.text ? line(t.title ?? t.text) : `mem:${t.id} (not visible)`, sub: t.at ? `mem:${t.id.slice(0, 8)} · ${t.kind} · ${day(t.at)}` : "" }))];
+    sections.push({ title: `Evidence (${evidence.length})`, open: evidence.length > 0, body: ui.rows(evidence, (e) => ui.row(e)) ?? ui.empty("No evidence attached", "This kind of candidate carries no references.") });
+    sections.push({ title: `Similar memories (${r.overlaps.length})`, open: r.overlaps.length > 0,
+      body: ui.rows(r.overlaps, (o) => ui.row({ title: o.title ?? "Untitled note", sub: `mem:${o.id.slice(0, 8)} · overlap ${o.score.toFixed(2)}` })) ?? ui.empty("No similar memories") });
+    if (r.edit !== null) {
+      const text = h("textarea", { name: "edit", class: "amem-input amem-text", "aria-label": "Edited text" });
+      text.value = r.edit;
+      sections.push({ title: "Edit, then accept", body: h("form", { class: "amem-form", onsubmit: (e) => { e.preventDefault(); act({ action: "edit_accept", id: r.id, text: text.value }); } },
+        text, h("button", { type: "submit", class: "btn", text: "Save edit and accept" })) });
+    }
+    return ui.detail({ kind: `${r.kind} candidate`, title: line(r.text, 90), state: { text: "pending", tone: "warn" }, whoseMove: "you", actions, summary: r.text,
+      provenance: [{ label: "Proposed", value: day(r.createdAt), at: r.createdAt }, { label: "Project", value: project ?? "" }, ...(r.noteKind ? [{ label: "Note kind", value: r.noteKind }] : [])],
+      sections, footer: [r.id] });
+  };
+
+  const views = {
+    review(s) {
+      const rows = s.rows ?? [], picked = rows.find((r) => r.id === s.selected);
+      const hidden = s.hidden ? ui.notice(`${s.hidden} candidate${s.hidden === 1 ? " is" : "s are"} withheld by the privacy screen; review ${s.hidden === 1 ? "it" : "them"} with amem review walk.`, "warn") : null;
+      if (picked) return [btn("Back to the queue", () => go("review")), reviewDetail(picked)];
+      return [hidden, ui.rows(rows, (r) => ui.row({ title: line(r.text), sub: `${r.kind} · ${day(r.createdAt)}${r.overlaps.length ? ` · ${r.overlaps.length} similar` : ""}`,
+        onOpen: () => go("review", { id: r.id }),
+        verbs: [r.acceptable ? btn("Accept", () => act({ action: "accept", id: r.id }), "btn primary") : null, btn("Reject", () => act({ action: "reject", id: r.id }))].filter(Boolean) }))
+        ?? ui.empty("No candidates waiting", "Agents propose memories with amem_remember; they wait here for your decision.")];
+    },
+    find(s) {
+      const q = h("input", { type: "search", name: "q", class: "amem-input", value: s.q ?? "", placeholder: "Search memory", "aria-label": "Search memory" });
+      q.value = s.q ?? "";
+      const form = h("form", { class: "amem-bar", role: "search", onsubmit: (e) => { e.preventDefault(); go("find", q.value.trim() ? { q: q.value.trim() } : {}); } }, q, h("button", { type: "submit", class: "btn", text: "Search" }));
+      const hits = s.hits ?? [];
+      return [form, s.q ? ui.rows(hits, (x) => {
+        const v = x.view, c = x.capture;
+        return ui.row({ title: line(v ? v.title ?? v.text : c?.excerpt), sub: [x.source, v?.kind ?? c?.event, day(v?.at ?? c?.at), v?.stale ? "stale" : ""].filter(Boolean).join(" · ") });
+      }) ?? ui.empty("Nothing found", "Search uses the same screened index as amem_search.") : ui.empty("Search this project's memory", "Results are screened exactly like amem_search.")];
+    },
+    timeline(s) {
+      return [ui.rows(s.entries ?? [], (x) => {
+        const c = x.capture;
+        return c ? ui.row({ title: line(c.excerpt), sub: `capture · ${c.event} · ${day(c.at)}` }) : ui.row({ title: line(x.title ?? x.text), sub: `${x.kind} · ${x.tier} · ${x.peer} · ${day(x.at)}` });
+      }) ?? ui.empty("Nothing on the timeline yet")];
+    },
+    work(s) {
+      const lists = s.lists ?? [];
+      return lists.length ? lists.map((l) => h("section", { class: "card amem-card" }, h("h3", { text: l.list }),
+        h("p", { class: "amem-sub", text: Object.entries(l.fields ?? {}).map(([k, v]) => `${k}: ${v}`).join(" · ") }),
+        ui.rows(l.items ?? [], (i) => ui.row({ title: i.task, sub: Object.entries(i.fields ?? {}).map(([k, v]) => `${k}: ${v}`).join(" · ") })) ?? ui.empty("No open items")))
+        : [ui.empty("No open work lists", "Agents write them with amem_work_state_write.")];
+    },
+    goals(s) {
+      return [ui.rows(s.goals ?? [], (g) => ui.row({ title: g.title, sub: [g.milestones.length ? `${g.milestones.length} milestones` : "", g.links.length ? `${g.links.length} linked tasks` : "", day(g.at)].filter(Boolean).join(" · "),
+        chip: { text: g.state, tone: g.state === "done" ? "ok" : g.state === "blocked" ? "err" : "neutral" } })) ?? ui.empty("No goals", "Create one with amem goal add.")];
+    },
+    capacity(s) {
+      if (s.withheld) return [ui.notice("The capacity report is withheld by the privacy screen.", "warn")];
+      const r = s.report;
+      const out = [];
+      if (r) {
+        out.push(h("section", { class: "card amem-card" }, h("h3", { text: "Capture" }),
+          h("dl", { class: "ui-provenance" },
+            h("dt", { text: "Rows" }), h("dd", { text: `${r.capture.rows} in ${r.capture.shards} shards, ${(r.capture.bytes / 1048576).toFixed(1)} MB` }),
+            h("dt", { text: "Growth" }), h("dd", { text: `${Math.round(r.capture.rowsPerDay)} rows/day` }),
+            h("dt", { text: "Disk free" }), h("dd", { text: `${(r.disk.freeBytes / 1073741824).toFixed(1)} GB` }),
+            h("dt", { text: "Current" }), h("dd", { text: `${r.current.capMb} MB, ${r.current.retentionDays} days` }),
+            h("dt", { text: "Proposed" }), h("dd", { text: `${r.proposal.capMb} MB, ${r.proposal.retentionDays} days` })),
+          h("p", { class: "amem-sub", text: r.proposal.reason }),
+          s.applyNeeded ? btn("Apply proposal...", () => host.action({ action: "capacity_apply" }), "btn primary") : ui.chip("current settings match the proposal", "ok")));
+      } else out.push(ui.empty("No memory home yet"));
+      const cutoff = () => new Date().toISOString().replace(/\.\d{3}Z$/, ".000Z");
+      out.push(h("section", { class: "card amem-card" }, h("h3", { text: "Maintenance" }),
+        h("p", { class: "amem-sub", text: "Each action shows what it will change and runs only after you confirm." }),
+        h("div", { class: "amem-bar" },
+          btn("Evict expired capture...", () => host.action({ action: "gc" })),
+          project ? btn("Demote old notes...", () => act({ action: "decay_apply" })) : null,
+          project ? btn("Prune expired notes...", () => act({ action: "prune", cutoff: cutoff() })) : null,
+          project ? btn("Forget this project...", () => act({ action: "project_forget" }), "btn danger") : null)));
+      return out;
+    },
+    recap(s) {
+      const brief = s.brief;
+      if (!brief || typeof brief.context !== "string") return [ui.empty("Recap unavailable", "The current SessionStart brief could not be computed.")];
+      const coverage = brief.coverage ?? {};
+      const sections = ["work", "curated", "capture", "repo"].filter((key) => Object.hasOwn(coverage, key));
+      const rows = sections.map((key) => {
+        const value = coverage[key];
+        const detail = value && typeof value === "object" ? JSON.stringify(value) : String(value);
+        return { title: key, sub: line(detail, 180) };
+      });
+      const tokens = Number.isSafeInteger(brief.tokens) && brief.tokens >= 0 ? `At most ${brief.tokens} tokens` : "Token upper bound unavailable";
+      const generated = typeof s.generatedAt === "string" ? s.generatedAt : "unavailable";
+      return [
+        ui.notice("Computed now for this snapshot; this is not a copy of a prior session's injected brief.", "neutral"),
+        h("section", { class: "card amem-card" },
+          h("h3", { text: "Coverage" }),
+          ui.rows(rows, (row) => ui.row(row)) ?? ui.empty("No coverage details"),
+          h("dl", { class: "ui-provenance" },
+            h("dt", { text: "Status" }), h("dd", { text: brief.partial === true ? "Partial" : "Complete" }),
+            h("dt", { text: "Token bound" }), h("dd", { text: tokens }),
+            h("dt", { text: "Generated" }), h("dd", { text: generated }))),
+        s.repoAbsent === true ? h("p", { class: "amem-sub", text: "Repository section absent: the console has no repository binding." }) : null,
+        h("section", { class: "card amem-card" }, h("h3", { text: "SessionStart context" }), h("pre", { class: "amem-pre", text: brief.context })),
+      ].filter(Boolean);
+    },
+  };
+
+  host.onSnapshot((s) => {
+    project = s.project ?? null;
+    // A poll re-renders the view: carry typed values and focus over by field name.
+    const values = new Map([...root.querySelectorAll("input[name], textarea[name]")].map((el) => [el.name, el.value]));
+    const focused = root.contains(document.activeElement) ? document.activeElement.getAttribute("name") : null;
+    const body = s.error ? [ui.notice(s.error, "err")] : !s.projects?.length && panel !== "capacity" ? [ui.empty("No memory yet", "Projects appear once an agent captures or proposes memory.")] : views[panel]?.(s) ?? [ui.empty("Unknown panel")];
+    root.replaceChildren(...[picker(s), ...body].filter(Boolean));
+    for (const el of root.querySelectorAll("input[name], textarea[name]")) if (values.has(el.name) && el.name !== "q") el.value = values.get(el.name);
+    if (focused) root.querySelector(`[name="${focused}"]`)?.focus();
+  });
+  return {
+    show(id, p = {}) { panel = id; params = p; root.replaceChildren(); },
+    hide() {},
+    destroy() { root.remove(); },
+  };
+};