@staix/agent-mem 0.10.0 → 0.12.0

package/src/memory/eval-fixture.ts

@@ -79,18 +79,22 @@ export function evalSeeded(set: EvalSet, ks?: readonly number[], rank?: RankFn):
     const base = join(dir, "memory");
     mkdirSync(base, { recursive: true });
     // One entry per day, so the recency weight (a 30-day scale) is exercised, long-tier entries first and short-tier ones last: a short-term note leaves the index 14 days after it is
-    // written, and the clock stops a day after the last entry, so the short ones written in that window are live when the set is searched (a set with more short entries than that
+    // written, and the undated clock stops a day after the last entry, so the short ones written in that window are live when the set is searched (a set with more short entries than that
     // window holds loses its oldest, and a question naming one is then reported as not in the store, like any other missing entry).
+    // Explicit dates override only their entry; undated entries retain their legacy file-order day.
+    // Search a day after the latest actual seed time unless the set supplies its own clock.
     let current = EPOCH;
     store = new MemoryStore({ memoryDir: base, now: () => current, screen: () => "keep" });
     const ids = new Map<string, string>();
     const ordered = [...set.entries.filter(entry => entry.tier !== "short"), ...set.entries.filter(entry => entry.tier === "short")];
+    let latest = -Infinity;
     for (const [index, entry] of ordered.entries()) {
-      current = EPOCH + index * DAY;
+      current = entry.at === undefined ? EPOCH + index * DAY : Date.parse(entry.at);
+      latest = Math.max(latest, current);
       ids.set(entry.key, store.note({ op: "note", project: PROJECT, scope: "project", tier: entry.tier ?? "long", kind: entry.kind ?? "finding", peer: "eval", source: "person",
         ...(entry.title ? { title: entry.title } : {}), text: entry.text, about: entry.about ?? [] }, entry.tier === "short"));
     }
-    current = EPOCH + ordered.length * DAY;
+    current = set.now === undefined ? latest + DAY : Date.parse(set.now);
     const window = Math.max(...(ks ?? [10]));
     const search = rank ? { rank: (question: string) => rank(store!, question, window), engine: () => "custom" } : ranker(store, PROJECT, window);
     // Resolved through `store.get`, so a note that has already expired is absent, not silently present: coverage stays separate from ranking.

package/src/memory/eval.ts

@@ -12,10 +12,10 @@ export const MAX_QUESTIONS = 500, MAX_ENTRIES = 200, MAX_QUESTION_CHARS = 500, M
 export const DEFAULT_KS: readonly number[] = [1, 5, 10];
 
 export const EVAL_KINDS = ["decision", "finding", "contract", "fail"] as const;
-export interface EvalEntry { key: string; title?: string; text: string; kind?: (typeof EVAL_KINDS)[number]; tier?: "short" | "long"; about?: string[] }
+export interface EvalEntry { key: string; title?: string; text: string; kind?: (typeof EVAL_KINDS)[number]; tier?: "short" | "long"; about?: string[]; /** Explicit seed date; absent keeps the legacy positional day. */ at?: string }
 /** `tag` is an optional label for what a question probes (a test counts them); it never changes the scoring. */
 export interface EvalQuestion { q: string; expect: string[]; tag?: string }
-export interface EvalSet { schema: typeof EVAL_SCHEMA; entries?: EvalEntry[]; questions: EvalQuestion[] }
+export interface EvalSet { schema: typeof EVAL_SCHEMA; entries?: EvalEntry[]; questions: EvalQuestion[]; /** Search clock for a self-contained set; defaults to one day after its latest seed. */ now?: string }
 
 const fail = (message: string): never => { throw new Error(`invalid eval set: ${message}`); };
 const object = (value: unknown, what: string): Record<string, unknown> => typeof value === "object" && value !== null && !Array.isArray(value) ? value as Record<string, unknown> : fail(`${what} must be an object`);
@@ -24,17 +24,25 @@ function exact(row: Record<string, unknown>, allowed: readonly string[], what: s
 }
 const text = (value: unknown, what: string, max: number): string => typeof value === "string" && value.trim() !== "" && value.length <= max && !/[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/.test(value) ? value : fail(`${what} must be a non-empty string of at most ${max} characters`);
 
+/** ISO calendar date or canonical UTC timestamp; reject Date.parse's rollover and locale-dependent forms. */
+function date(value: unknown, what: string): string {
+  if (typeof value !== "string" || !/^[0-9]{4}-[0-9]{2}-[0-9]{2}(?:T[0-9]{2}:[0-9]{2}:[0-9]{2}(?:[.][0-9]{3})?Z)?$/.test(value)) return fail(`${what} must be an ISO date or UTC timestamp`);
+  const ms = Date.parse(value), normalized = value.length === 10 ? value + "T00:00:00.000Z" : value.length === 20 ? value.slice(0, -1) + ".000Z" : value;
+  if (!Number.isFinite(ms) || new Date(ms).toISOString() !== normalized) return fail(`${what} must be a valid ISO date or UTC timestamp`);
+  return value;
+}
+
 /** Strict, bounded parse of untrusted JSON. Unknown keys are errors, so a typo cannot silently change what is measured. */
 export function parseEvalSet(raw: unknown): EvalSet {
   const root = object(raw, "the set");
-  exact(root, ["schema", "entries", "questions"], "the set");
+  exact(root, ["schema", "entries", "questions", "now"], "the set");
   if (root.schema !== EVAL_SCHEMA) fail(`schema must be "${EVAL_SCHEMA}"`);
   const entries: EvalEntry[] = [], keys = new Set<string>();
   if (root.entries !== undefined) {
     if (!Array.isArray(root.entries) || !root.entries.length || root.entries.length > MAX_ENTRIES) fail(`entries must hold 1 to ${MAX_ENTRIES} items when present`);
     for (const [index, item] of (root.entries as unknown[]).entries()) {
       const row = object(item, `entries[${index}]`);
-      exact(row, ["key", "title", "text", "kind", "tier", "about"], `entries[${index}]`);
+      exact(row, ["key", "title", "text", "kind", "tier", "about", "at"], `entries[${index}]`);
       const key = text(row.key, `entries[${index}].key`, 80);
       if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(key)) fail(`entries[${index}].key may use letters, digits, ".", "_" and "-"`);
       if (keys.has(key)) fail(`entries[${index}].key "${key}" repeats`);
@@ -42,9 +50,10 @@ export function parseEvalSet(raw: unknown): EvalSet {
       const kind = row.kind === undefined ? undefined : (EVAL_KINDS as readonly unknown[]).includes(row.kind) ? row.kind as EvalEntry["kind"] : fail(`entries[${index}].kind must be one of ${EVAL_KINDS.join(", ")}`);
       const tier = row.tier === undefined ? undefined : row.tier === "short" || row.tier === "long" ? row.tier : fail(`entries[${index}].tier must be short or long`);
       const about = row.about === undefined ? undefined : Array.isArray(row.about) && row.about.length <= 20 ? (row.about as unknown[]).map((value, at) => text(value, `entries[${index}].about[${at}]`, 200)) : fail(`entries[${index}].about must be a list of at most 20 strings`);
-      entries.push({ key, text: text(row.text, `entries[${index}].text`, MAX_ENTRY_CHARS), ...(row.title === undefined ? {} : { title: text(row.title, `entries[${index}].title`, 200) }), ...(kind ? { kind } : {}), ...(tier ? { tier } : {}), ...(about ? { about } : {}) });
+      entries.push({ key, text: text(row.text, `entries[${index}].text`, MAX_ENTRY_CHARS), ...(row.title === undefined ? {} : { title: text(row.title, `entries[${index}].title`, 200) }), ...(kind ? { kind } : {}), ...(tier ? { tier } : {}), ...(about ? { about } : {}), ...(row.at === undefined ? {} : { at: date(row.at, `entries[${index}].at`) }) });
     }
   }
+  if (root.now !== undefined && !entries.length) fail("now requires self-contained entries");
   if (!Array.isArray(root.questions) || !root.questions.length || root.questions.length > MAX_QUESTIONS) fail(`questions must hold 1 to ${MAX_QUESTIONS} items`);
   const questions = (root.questions as unknown[]).map((item, index): EvalQuestion => {
     const row = object(item, `questions[${index}]`);
@@ -58,7 +67,7 @@ export function parseEvalSet(raw: unknown): EvalSet {
     }
     return { q: text(row.q, `questions[${index}].q`, MAX_QUESTION_CHARS), expect, ...(tag ? { tag } : {}) };
   });
-  return { schema: EVAL_SCHEMA, ...(entries.length ? { entries } : {}), questions };
+  return { schema: EVAL_SCHEMA, ...(entries.length ? { entries } : {}), questions, ...(root.now === undefined ? {} : { now: date(root.now, "now") }) };
 }
 
 /** `--k 1,5,10`: ascending, unique, 1 to MAX_K. */

package/src/memory/external-import.ts

@@ -206,7 +206,14 @@ function title(source: ExternalMemorySource, file: SourceFile, record: RawRecord
 }
 
 function portable(path: string): string { return path.split(sep).join("/"); }
-function claudeProjectDirectory(cwd: string): string { return realPath(cwd).replace(/[/.]/g, "-"); }
+/** Claude Code 2.1.311's project-path encoding, including its long-name suffix. */
+function claudeProjectDirectory(cwd: string): string {
+  const path = realPath(cwd), encoded = path.replace(/[^a-zA-Z0-9]/g, "-");
+  if (encoded.length <= 200) return encoded;
+  let hash = 0;
+  for (let index = 0; index < path.length; index++) hash = (Math.imul(hash, 31) + path.charCodeAt(index)) | 0;
+  return `${encoded.slice(0, 200)}-${Math.abs(hash).toString(36)}`;
+}
 
 export async function importExternalMemory(opts: {
   base: string;

package/src/memory/platform.ts

@@ -103,18 +103,18 @@ export function memoryGitEnv(env: NodeJS.ProcessEnv = process.env, options: { re
 /** spawnSync form of the same call: the env option is merged with memoryGitEnv, everything else passes through. */
 export function memoryGitSync(args: string[], options: SpawnSyncOptionsWithStringEncoding): SpawnSyncReturns<string> {
   const argv = memoryGitArgv(args);
-  return childProcess().spawnSync(argv[0]!, argv.slice(1), { ...(ambientGitTimeout !== undefined ? { timeout: ambientGitTimeout, killSignal: "SIGKILL" as const } : {}), ...options, env: memoryGitEnv(options.env ?? process.env) });
+  const timeout = gitTimeoutContext?.getStore();
+  return childProcess().spawnSync(argv[0]!, argv.slice(1), { ...(timeout !== undefined ? { timeout, killSignal: "SIGKILL" as const } : {}), ...options, env: memoryGitEnv(options.env ?? process.env) });
 }
-let ambientGitTimeout: number | undefined;
+let gitTimeoutContext: import("node:async_hooks").AsyncLocalStorage<number> | undefined;
 /**
- * Runs `work` with a timeout on every `memoryGitSync` call that sets none of its own: a synchronous git call blocks the event loop, so a signal sent to this process alone waits for it.
- * A call that times out reads as a failed git (`error` set, no status), which every caller already treats as "unknown". The setting is process-wide while `work` runs, so use it only in a
- * command that does nothing else at the same time (`amem doctor`).
- * ponytail: one global instead of a parameter on every caller between doctor and its git calls (project key, repository root, visibility). Upgrade: thread an options argument through them.
+ * Bound `memoryGitSync` calls inside this async operation unless a call supplies its own timeout.
+ * Nested and concurrent operations keep independent contexts; unrelated host calls retain their own options.
+ * Load async_hooks only when a caller requests a deadline, keeping path-only hook imports unchanged.
  */
 export async function withGitTimeout<T>(ms: number, work: () => Promise<T>): Promise<T> {
-  const prior = ambientGitTimeout; ambientGitTimeout = ms;
-  try { return await work(); } finally { ambientGitTimeout = prior; }
+  gitTimeoutContext ??= new (require("node:async_hooks").AsyncLocalStorage)();
+  return gitTimeoutContext!.run(ms, work);
 }
 
 /**

package/src/memory/project-import.ts

@@ -15,7 +15,7 @@ const NOTE_KEYS = new Set(["schema", "id", "at", "machine", "op", "project", "sc
 const OPERATIONS_WARNING = "Supersede, demote, settle and forget operations are not exported; re-import restores authored note rows only.";
 
 type ImportedNote = { id: string; at: string; machine: string; note: NoteInput };
-type Provenance = { source: Record<string, number>; peer: Record<string, number>; scope: Record<string, number> };
+type Provenance = { source: Record<string, number>; peer: Record<string, number>; scope: Record<string, number>; machine: Record<string, number> };
 export interface ProjectImportResult {
   applied: boolean;
   project: string;
@@ -46,13 +46,18 @@ function increment(counts: Map<string, number>, value: string | undefined): void
 }
 
 function provenance(notes: Iterable<ImportedNote>): Provenance {
-  const source = new Map<string, number>(), peer = new Map<string, number>(), scope = new Map<string, number>();
-  for (const { note } of notes) {
+  const source = new Map<string, number>(), peer = new Map<string, number>(), scope = new Map<string, number>(), machine = new Map<string, number>();
+  for (const { note, machine: origin } of notes) {
     increment(source, note.source);
     increment(peer, note.peer);
     increment(scope, note.scope);
+    increment(machine, origin);
   }
-  return { source: Object.fromEntries(source), peer: Object.fromEntries(peer), scope: Object.fromEntries(scope) };
+  return { source: Object.fromEntries(source), peer: Object.fromEntries(peer), scope: Object.fromEntries(scope), machine: Object.fromEntries(machine) };
+}
+
+function relationTargets(imported: ImportedNote): string[] {
+  return [imported.note.supersedes, imported.note.promotedFrom].filter((target): target is string => typeof target === "string");
 }
 
 function unchangedAfterNormalization(note: NoteInput): boolean {
@@ -71,10 +76,10 @@ export async function importProject(store: MemoryStore, opts: {
   const fd = openSync(opts.from, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
   const stream = createReadStream(opts.from, { fd, encoding: "utf8" });
   const result: ProjectImportResult = { applied: opts.confirm === true, project: opts.project, read: 0, added: 0, wouldAdd: 0,
-    skipped: { invalid: 0, policy: 0, other: 0 }, provenance: { source: {}, peer: {}, scope: {} }, warnings: [OPERATIONS_WARNING] };
+    skipped: { invalid: 0, policy: 0, other: 0 }, provenance: { source: {}, peer: {}, scope: {}, machine: {} }, warnings: [OPERATIONS_WARNING] };
   let header = false, bytes = 0;
   let aliases: string[] = [];
-  const pending = new Map<string, ImportedNote>(), accepted: ImportedNote[] = [];
+  const pending = new Map<string, ImportedNote>(), accepted = new Map<string, ImportedNote>();
   try {
     const stat = fstatSync(fd);
     if (!stat.isFile() || stat.size > PROJECT_IMPORT_MAX_BYTES) throw new Error("project import needs a regular JSONL file of at most 64 MiB");
@@ -121,22 +126,34 @@ export async function importProject(store: MemoryStore, opts: {
     if (!header) throw new Error("project import has no header");
 
     for (const imported of pending.values()) {
-      if (["supersedes", "promotedFrom"].some(field => {
-        const target = imported.note[field as "supersedes" | "promotedFrom"] as string | null | undefined;
-        return target !== undefined && target !== null && !pending.has(target);
-      })) {
+      if (relationTargets(imported).some(target => !pending.has(target))) {
         result.skipped.invalid++;
         continue;
       }
       const screened = stripPrivateDeep(imported.note);
       if (looksSecret(JSON.stringify(screened)) || !await opts.policy(screened)) { result.skipped.policy++; continue; }
-      accepted.push(imported);
+      accepted.set(imported.id, imported);
+    }
+    // A policy-refused target cannot authorize its dependents. Propagate removals before any append,
+    // regardless of file order, in linear time even when a long relation chain is refused.
+    const dependents = new Map<string, string[]>(), refused: string[] = [];
+    for (const imported of accepted.values()) for (const target of relationTargets(imported)) {
+      const rows = dependents.get(target) ?? [];
+      rows.push(imported.id); dependents.set(target, rows);
+      if (!accepted.has(target)) refused.push(imported.id);
+    }
+    for (let at = 0; at < refused.length; at++) {
+      const id = refused[at]!;
+      if (!accepted.delete(id)) continue;
+      result.skipped.invalid++;
+      for (const dependent of dependents.get(id) ?? []) refused.push(dependent);
     }
-    result.provenance = provenance(accepted);
+    result.provenance = provenance(accepted.values());
     const existing = new Set(store.portableNotes(opts.project).map(note => note.id));
-    result.wouldAdd = accepted.filter(note => !existing.has(note.id)).length;
+    result.wouldAdd = [...accepted.keys()].filter(id => !existing.has(id)).length;
     if (opts.confirm === true) {
-      for (const imported of accepted) {
+      store.assertImportable([...accepted.values()].map(imported => imported.note));
+      for (const imported of accepted.values()) {
         const written = store.importNote(imported.note, imported.at, { machine: imported.machine, expectedId: imported.id });
         if (written.added) result.added++;
       }

package/src/memory/search-fts.ts

@@ -1,3 +1,4 @@
+import { rankedScoreSql, rankedScoreSqlDetails, type ScoreFactors } from "./search-score.ts";
 import { Database } from "bun:sqlite";
 import { chmodSync, existsSync } from "node:fs";
 import { join } from "node:path";
@@ -187,6 +188,8 @@ export class SearchIndex {
   close(): void { this.db?.close(); }
 }
 
+const SCREENED_SCORE = rankedScoreSql(), SCREENED_SUBSTRING_SCORE = rankedScoreSql("-1.0");
+
 /** Screened query-local corpus in SQLite-owned TEMP storage, removed even when the process exits. */
 export class ScreenedSearchIndex<T> {
   readonly available = fts5Available();
@@ -222,15 +225,21 @@ export class ScreenedSearchIndex<T> {
     })();
   }
 
-  best(query: string, limit: number, now: number, useFts = this.available): { value: T; score: number }[] {
+  best(query: string, limit: number, now: number, useFts = this.available, explain = false): { value: T; score: number; scoreDetails?: ScoreFactors }[] {
     if (useFts && !ftsTerms(query)) return [];
-    const rank = useFts ? "-bm25(docs)" : "1.0";
+    const score = useFts ? SCREENED_SCORE : SCREENED_SUBSTRING_SCORE;
     const instant = new Date(now).toISOString();
     const where = "WHERE (expires IS NULL OR expires > ?)" + (useFts ? " AND docs MATCH ?" : "");
-    const rows = this.db.query(`SELECT payload, ${rank} * CASE tier WHEN 'long' THEN 1.0 WHEN 'capture' THEN 0.5 ELSE 0.9 END
-      / (1 + max(0, (julianday(?) - julianday(at)) / 30.0)) AS score FROM docs ${where} ORDER BY score DESC, ref LIMIT ?`)
-      .all(instant, now, ...(useFts ? [ftsTerms(query)] : []), limit) as { payload: string; score: number }[];
-    return rows.map(row => ({ value: JSON.parse(row.payload) as T, score: row.score }));
+    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 statement = this.db.query(`SELECT payload, ${score} AS score${columns} FROM docs ${where} ORDER BY score DESC, ref LIMIT ?`);
+    const rows = (explain ? statement.all(instant, instant, now, ...(useFts ? [ftsTerms(query)] : []), limit)
+      : statement.all(instant, now, ...(useFts ? [ftsTerms(query)] : []), limit)) as { payload: string; score: number; rawBm25Rank?: number | null; tierFactor?: number | null; recencyFactor?: number | null }[];
+    return rows.map(row => {
+      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" };
+      return hit;
+    });
   }
 
   close(): void {

package/src/memory/search-score.ts

@@ -0,0 +1,66 @@
+/** One fixed score recipe for numeric library ranking and native screened SQL. */
+export interface ScoreFactors {
+  rawBm25Rank: number | null;
+  tierFactor: number | null;
+  recencyFactor: number | null;
+  finalScore: number | null;
+  matchMode: "fts5" | "substring";
+}
+export interface SearchScoreDetails extends ScoreFactors { source: "curated" | "capture" | "repo" }
+
+type ScoreExpr = { op: "rank" | "tier" | "age" } | { op: "constant"; value: number }
+  | { op: "negative" | "reciprocal"; value: ScoreExpr }
+  | { op: "add" | "multiply" | "max"; left: ScoreExpr; right: ScoreExpr };
+const MONTH_DAYS = 30;
+const TIER_WEIGHTS: Readonly<Record<string, number>> = { long: 1, capture: 0.5 };
+const DEFAULT_TIER_WEIGHT = 0.9;
+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 };
+const SCORE: ScoreExpr = { op: "multiply", left: { op: "multiply", left: { op: "negative", value: { op: "rank" } }, right: TIER_FACTOR }, right: RECENCY_FACTOR };
+// ponytail: this represents only the fixed rank/tier/age recipe, not arbitrary expressions;
+// extend its operations with numeric/SQL parity tests when the ranking contract changes.
+function numeric(expr: ScoreExpr, rank: number, tier: string, at: string, now: number): number {
+  switch (expr.op) {
+    case "rank": return rank;
+    case "tier": return Object.hasOwn(TIER_WEIGHTS, tier) ? TIER_WEIGHTS[tier]! : DEFAULT_TIER_WEIGHT;
+    case "age": return (now - Date.parse(at)) / (MONTH_DAYS * 24 * 3600_000);
+    case "constant": return expr.value;
+    case "negative": return -numeric(expr.value, rank, tier, at, now);
+    case "reciprocal": return 1 / numeric(expr.value, rank, tier, at, now);
+    case "add": return numeric(expr.left, rank, tier, at, now) + numeric(expr.right, rank, tier, at, now);
+    case "multiply": return numeric(expr.left, rank, tier, at, now) * numeric(expr.right, rank, tier, at, now);
+    case "max": return Math.max(numeric(expr.left, rank, tier, at, now), numeric(expr.right, rank, tier, at, now));
+  }
+}
+const real = (value: number): string => Number.isInteger(value) ? `${value}.0` : String(value);
+function sql(expr: ScoreExpr, rank: string): string {
+  const get = (part: ScoreExpr): string => sql(part, rank);
+  switch (expr.op) {
+    case "rank": return rank;
+    case "tier": return `CASE tier ${Object.entries(TIER_WEIGHTS).map(([name, value]) => `WHEN '${name}' THEN ${real(value)}`).join(" ")} ELSE ${real(DEFAULT_TIER_WEIGHT)} END`;
+    case "age": return `((julianday(?) - julianday(at)) / ${real(MONTH_DAYS)})`;
+    case "constant": return real(expr.value);
+    case "negative": return `(-(${get(expr.value)}))`;
+    case "reciprocal": return `(1.0 / ${get(expr.value)})`;
+    case "add": return `(${get(expr.left)} + ${get(expr.right)})`;
+    // Preserve the existing SQL quotient's floating-point order; numeric ranking
+    // retains its original reciprocal product. Both interpret the same recipe.
+    case "multiply": return expr.right.op === "reciprocal" ? `(${get(expr.left)} / ${get(expr.right.value)})` : `(${get(expr.left)} * ${get(expr.right)})`;
+    case "max": return `max(${get(expr.left)}, ${get(expr.right)})`;
+  }
+}
+export function rankedScore(rank: number, tier: string, at: string, now: number): number {
+  return numeric(SCORE, rank, tier, at, now);
+}
+/** 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 } {
+  return { rawBm25Rank: useFts ? rank : "NULL", tierFactor: sql(TIER_FACTOR, rank), recencyFactor: sql(RECENCY_FACTOR, rank) };
+}
+export function rankedScoreDetails(source: SearchScoreDetails["source"], rank: number, tier: string, at: string, now: number, finalScore: number): SearchScoreDetails {
+  return { source, rawBm25Rank: rank, tierFactor: numeric(TIER_FACTOR, rank, tier, at, now), recencyFactor: numeric(RECENCY_FACTOR, rank, tier, at, now), finalScore, matchMode: "fts5" };
+}
+export function unrankedScoreDetails(source: SearchScoreDetails["source"], finalScore: number | null): SearchScoreDetails {
+  return { source, rawBm25Rank: null, tierFactor: null, recencyFactor: null, finalScore, matchMode: "substring" };
+}

package/src/memory/status-text.ts

@@ -0,0 +1,47 @@
+import { facts, label, PLAIN, type Style } from "./style.ts";
+
+/** The `amem status` object as the CLI builds it; `amem status --json` prints it unchanged. */
+export interface StatusView {
+  home: { path: string; source: string };
+  config: { machine: string | null; repo: string | null; denyPaths: number; piiPatterns: number } & Record<string, unknown>;
+  candidates: { unavailable: string } | ({ count: number; oldestExpiresInDays: number | null; dueWithin7Days: number; unshown: number; warning?: string });
+  active: boolean; generation?: string; phase?: string;
+  pending: Record<string, unknown> & { rows: number };
+  deadLeasesRemoved?: { lease: string; at: string }[]; refusals?: string[];
+}
+
+/** Person-facing `amem status` (#125): overall state, the effective home and policy, the counts that matter, then next actions. Zero counters are summarized, never listed. */
+export function statusText(status: StatusView, s: Style = PLAIN): string {
+  const actions: string[] = [], warnings: string[] = [];
+  const candidates = status.candidates;
+  let candidateLine: string, candidateState: "ok" | "attention" | "unavailable";
+  if ("unavailable" in candidates) { candidateState = "unavailable"; candidateLine = candidates.unavailable; warnings.push(candidates.unavailable); }
+  else {
+    candidateState = candidates.dueWithin7Days ? "attention" : "ok";
+    candidateLine = candidates.count ? `${candidates.count} pending${candidates.unshown ? ` (${candidates.unshown} never shown)` : ""}${candidates.oldestExpiresInDays !== null ? `, oldest expires in ${candidates.oldestExpiresInDays} days` : ""}` : "none pending";
+    if (candidates.warning) actions.push(candidates.warning);
+    else if (candidates.count) actions.push("review pending candidates: amem review walk");
+  }
+  const refusals = status.refusals ?? [];
+  const interrupted = status.phase === "captured" && !status.active;   // authoring refuses until activation (generation-index.ts)
+  const migrationState: "ok" | "attention" = refusals.length || status.pending.rows || interrupted ? "attention" : "ok";
+  if (interrupted) actions.push("a shard migration stopped after capture and authoring is refused until it activates: amem migrate --shards --resume");
+  if (refusals.length) warnings.push(...refusals.map(reason => `migration refusal: ${reason}`));
+  if (status.pending.rows && !interrupted) actions.push(`${status.pending.rows} old-layout rows wait for the shard migration: amem migrate --shards --resume carries them (amem migrate --shards --dry-run previews first)`);
+  const overall = candidateState === "unavailable" ? "unavailable" : candidateState === "attention" || migrationState === "attention" ? "attention" : "ok";
+  const { machine, repo, denyPaths, piiPatterns, ...limits } = status.config;
+  const pendingCounts = facts(Object.fromEntries(Object.entries(status.pending).filter(([key]) => !key.endsWith("Ids"))));
+  const lines = [
+    `${s.bold("amem status:")} ${overall === "ok" ? s.ok(overall) : overall === "attention" ? s.attention(overall) : s.error(overall)}`,
+    `home     ${status.home.path} ${s.dim(`(${status.home.source})`)}`,
+    "",
+    `${label(s, "ok")} policy: machine ${machine ?? "none (defaults)"}, repo ${repo ?? "none"}; ${denyPaths} deny paths, ${piiPatterns} PII patterns${facts(limits) ? `; ${facts(limits)}` : ""}`,
+    `${label(s, candidateState)} candidates: ${candidateLine}`,
+    `${label(s, migrationState)} layout: ${status.active ? `shards active${status.generation ? ` (generation ${status.generation.slice(0, 8)})` : ""}` : status.phase ? `shard migration ${status.phase}${interrupted ? ", not active" : ""}` : "single home"}; ${pendingCounts ? `pending ${pendingCounts}` : "no pending old-layout appends"}`,
+    ...(status.deadLeasesRemoved?.length ? [`            ${s.dim(`${status.deadLeasesRemoved.length} dead reader leases removed`)}`] : []),
+    ...(warnings.length ? ["", "Warnings:", ...warnings.map(warning => `  - ${s.attention(warning)}`)] : []),
+    "", actions.length ? "Next actions:" : "Next actions: none", ...actions.map(action => `  - ${action}`),
+    s.dim("Full report: amem status --json; health checks: amem doctor"),
+  ];
+  return lines.join("\n");
+}

package/src/memory/store.ts

@@ -10,6 +10,8 @@ import { memoryHome } from "./home.ts";
 import { machineId, type Machine } from "./machine.ts";
 import { assertProjectActive } from "./lifecycle.ts";
 export { machineId, type Machine } from "./machine.ts";
+import { rankedScore, rankedScoreDetails, unrankedScoreDetails, type SearchScoreDetails } from "./search-score.ts";
+export type { SearchScoreDetails } from "./search-score.ts";
 import { readWindowSql, readRef, type ReadWindow, type ReadRef, SearchIndex, captureSearch } from "./search-fts.ts";
 import { assertCuratedShardPaths, ensureShardDescriptor, readShardDescriptor, readShardedSelection, aliasedKeys, resolveAlias, resolveShardProfile, shardDir, shardKeyHash, shardMachineDir, userShardDir } from "./shard.ts";
 import { readCaptureConfig, type CaptureRow } from "./capture.ts";
@@ -168,10 +170,12 @@ export interface Filter { project?: string; tier?: Tier; kind?: Kind; peer?: str
 /** #13 search: `Filter` plus the capture-tier switch (on by default; capture is recall, never curated evidence). */
 export interface SearchFilter extends Filter {
   includeCapture?: boolean;
+  /** Attach score factors only when explicitly requested. */
+  explain?: boolean;
   /** A host that writes capture with a `retentionDays` override passes the same value here; files decide otherwise. */
   captureRetentionDays?: number;
 }
-export interface SearchHit { source: "curated" | "capture"; score: number; view?: View; capture?: CaptureRow }
+export interface SearchHit { source: "curated" | "capture"; score: number; scoreDetails?: SearchScoreDetails; view?: View; capture?: CaptureRow }
 export interface SearchResult { engine: "fts5" | "substring"; hits: SearchHit[] }
 export interface Graph { nodes: { id: Node; type: string; label: string; kind?: string; tier?: Tier }[]; edges: { from: Node; to: Node; rel: string }[] }
 
@@ -490,18 +494,30 @@ export class MemoryStore {
   // `ownClock`: a note asked for short-term on purpose expires on its own clock, open task or not, and is never promoted.
   note(n: NoteInput, ownClock = false): string { return this.append(n.tier === "short" && !n.expires && (ownClock || !n.task || this.settled(n.task)) ? { ...n, expires: this.until() } : n, n.tier === "short"); }
 
-  /**
-   * An entry from another store with its own time (`ahub memory import claude-mem`): the same source row always gives
-   * the same id, so a second import writes nothing. Returns the id and whether it was new.
-   */
-  importNote(n: NoteInput, at: string, identity: { machine?: string; expectedId?: string } = {}): { id: string; added: boolean } {
+  /** The already-opened owner of an imported row, shared by preflight and append. */
+  private importOwner(n: NoteInput): MemoryStore {
     if (this.bootstrapOnly) throw new Error("migration bootstrap cannot import memory");
-    if (this.userOverlay && n.scope === "shared") return this.userOverlay.importNote(n, at, identity);
+    if (this.userOverlay && n.scope === "shared") return this.userOverlay.importOwner(n);
     if (this.profile.sharded && !this.profile.shardUser && n.scope === "project" && n.project !== this.profile.shardKey) {
       const owner = this.aliasStores.find(store => store.profile.shardKey === n.project);
-      if (owner) return owner.importNote(n, at, identity);
+      if (owner) return owner.importOwner(n);
     }
     if (this.profile.sharded && (this.profile.shardUser ? n.scope !== "shared" : n.scope !== "project" || n.project !== this.profile.shardKey)) throw new Error("entry does not belong to this curated shard");
+    return this;
+  }
+
+  /** Check every import route before a multi-row caller appends; never creates a missing alias shard. */
+  assertImportable(notes: Iterable<NoteInput>): void {
+    for (const note of notes) this.importOwner(note);
+  }
+
+  /**
+   * An entry from another store with its own time (`ahub memory import claude-mem`): the same source row always gives
+   * the same id, so a second import writes nothing. Returns the id and whether it was new.
+   */
+  importNote(n: NoteInput, at: string, identity: { machine?: string; expectedId?: string } = {}): { id: string; added: boolean } {
+    const owner = this.importOwner(n);
+    if (owner !== this) return owner.importNote(n, at, identity);
     assertSharedV1Op(n.op);
     // A fixed machine: the same observation imported on two machines is one entry once they sync. A project import preserves the exported identity instead.
     const body = { schema: MEMORY_SCHEMA, at, machine: identity.machine ?? "claude-mem", ...n, text: stripPrivateSpans(n.text).slice(0, MAX_TEXT), ...(n.title ? { title: stripPrivateSpans(n.title).slice(0, MAX_TITLE) } : {}) } as Omit<Entry, "id">;
@@ -1057,12 +1073,15 @@ export class MemoryStore {
    */
   search(q: string, f: SearchFilter = {}): SearchResult {
     const limit = f.limit ?? 200;
-    if (!this.searchIndex.available) return { engine: "substring", hits: this.list({ ...f, q }).map((view) => ({ source: "curated" as const, score: 0, view })) };
+    if (!this.searchIndex.available) return { engine: "substring", hits: this.list({ ...f, q }).map(view => {
+      const hit: SearchHit = { source: "curated", score: 0, view };
+      if (f.explain) hit.scoreDetails = unrankedScoreDetails("curated", hit.score);
+      return hit;
+    }) };
     const visible = new Map(this.live(f).filter((v) => (!f.project || this.inScope(v.project, f.project) || v.scope === "shared")
       && (!f.since || Date.parse(v.at) >= Date.parse(f.since)) && (f.includeSuperseded || !v.supersededBy)).map((v) => [v.id, v]));
     for (const store of this.readStores()) store.syncSearchIndex();
     const now = this.now();
-    const recency = (at: string): number => 1 / (1 + Math.max(0, now - Date.parse(at)) / (30 * 24 * 3600_000));
     const hits: SearchHit[] = [];
     // 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.
@@ -1082,7 +1101,9 @@ export class MemoryStore {
           if (!view || seen.has(hit.ref)) continue;
           seen.add(hit.ref);
           found++;
-          hits.push({ source: "curated", score: -hit.rank * (view.tier === "long" ? 1 : 0.9) * recency(hit.at), view });
+          const selected: SearchHit = { source: "curated", score: rankedScore(hit.rank, view.tier, hit.at, now), view };
+          if (f.explain) selected.scoreDetails = rankedScoreDetails("curated", hit.rank, view.tier, hit.at, now, selected.score);
+          hits.push(selected);
         }
         if (ranked.length < page) break;
       }
@@ -1097,12 +1118,18 @@ export class MemoryStore {
       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)) {
-        hits.push({ source: "capture", score: -rank * 0.5 * recency(row.at), capture: row });
+        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);
       }
     }
     // Where FTS misses entirely (a stopword-only query, a tokenization edge), the substring filter is the safety net.
     if (!hits.length && q.trim()) {
-      for (const view of this.list({ ...f, q })) hits.push({ source: "curated", score: 0, view });
+      for (const view of this.list({ ...f, q })) {
+        const hit: SearchHit = { source: "curated", score: 0, view };
+        if (f.explain) hit.scoreDetails = unrankedScoreDetails("curated", hit.score);
+        hits.push(hit);
+      }
     }
     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)));

package/src/memory/style.ts

@@ -0,0 +1,37 @@
+/**
+ * A tiny, dependency-free text style for person-facing CLI output (#125).
+ * Color is decoration only: every caller also prints a textual label, so plain output carries the same facts.
+ * JSON output never passes through this module.
+ */
+export interface Style {
+  readonly color: boolean;
+  ok(text: string): string;
+  attention(text: string): string;
+  error(text: string): string;
+  dim(text: string): string;
+  bold(text: string): string;
+}
+
+/** Color only for an interactive stdout, and never with NO_COLOR (any value, per no-color.org) or TERM=dumb. */
+export function colorEnabled(env: Readonly<Record<string, string | undefined>>, isTTY: boolean | undefined): boolean {
+  return isTTY === true && env.NO_COLOR === undefined && env.TERM !== "dumb";
+}
+
+const wrap = (on: boolean, open: number, close: number) => (text: string) => on ? `\x1b[${open}m${text}\x1b[${close}m` : text;
+export function style(color: boolean): Style {
+  return { color, ok: wrap(color, 32, 39), attention: wrap(color, 33, 39), error: wrap(color, 31, 39), dim: wrap(color, 2, 22), bold: wrap(color, 1, 22) };
+}
+export const PLAIN: Style = style(false);
+
+/** Status label, padded so the columns line up; the word is always present. */
+export function label(s: Style, state: "ok" | "attention" | "skipped" | "unavailable" | "error"): string {
+  const word = { ok: "OK", attention: "ATTENTION", skipped: "SKIPPED", unavailable: "UNAVAILABLE", error: "ERROR" }[state].padEnd(11);
+  return state === "ok" ? s.ok(word) : state === "attention" ? s.attention(word) : state === "skipped" ? s.dim(word) : s.error(word);
+}
+
+/** "key value" pairs, leaving out zero, empty and null values; returns "" when nothing material is left. */
+export function facts(values: Record<string, unknown>): string {
+  return Object.entries(values).filter(([, value]) => value !== 0 && value !== null && value !== undefined && value !== false && value !== ""
+    && !(Array.isArray(value) && value.length === 0) && !(typeof value === "object" && !Array.isArray(value) && Object.keys(value as object).length === 0))
+    .map(([key, value]) => `${key} ${typeof value === "object" ? Array.isArray(value) ? value.join(", ") : JSON.stringify(value) : String(value)}`).join(", ");
+}

package/src/setup-toml.ts

@@ -162,11 +162,11 @@ function editTomlPath(text: string, path: readonly string[], value: unknown | un
       changes.push({ start: position, end: position, text: `${newline}${key} = ${inline(value)}${eol}` });
     }
     output = replace(text, changes);
-    // Removing the only child of an implicit table must retain its parsed empty parent value.
-    for (let depth = path.length - 1; depth > 0; depth--) {
-      const parent = path.slice(0, depth), wanted = at(expected, parent);
-      if (plain(wanted) && !Object.keys(wanted).length && at(parse(output), parent) === undefined) output += `${output && !output.endsWith("\n") ? eol : ""}[${parent.map(part => JSON.stringify(part)).join(".")}]${eol}`;
-    }
+  }
+  // Removing the only child of an implicit table must retain its parsed empty parent value.
+  for (let depth = path.length - 1; depth > 0; depth--) {
+    const parent = path.slice(0, depth), wanted = at(expected, parent);
+    if (plain(wanted) && !Object.keys(wanted).length && at(parse(output), parent) === undefined) output += `${output && !output.endsWith("\n") ? eol : ""}[${parent.map(part => JSON.stringify(part)).join(".")}]${eol}`;
   }
   if (!isDeepStrictEqual(shape(parse(output)), shape(expected))) return error();
   return output;