@staix/agent-mem 0.3.1 → 0.5.0

package/src/memory/catalog.ts

@@ -0,0 +1,135 @@
+import { Database } from "bun:sqlite";
+import { chmodSync, existsSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { memoryBase } from "./home.ts";
+import { effectiveAliases, readShardDescriptor, SHARDED_SCHEMA } from "./shard.ts";
+import { readProfileJSON, validGeneration } from "./generation.ts";
+import { captureShardStats, readCaptureConfig } from "./capture.ts";
+import { openShardStore } from "./store.ts";
+
+/**
+ * #15 D3 (storage part only): the user-level catalog of project shards. `catalog.db` in the memory home is derived
+ * only from the shards (`projects/* /project.json`, their `machine/<id>` capture stores and configs) and the
+ * append-only `aliases.jsonl`; it carries no truth of its own, so deleting it and rebuilding from the shards always
+ * reproduces the same rows. The D3 management commands (`amem projects/usage/gc/export/archive/forget`) are #15 T5
+ * and are deliberately not built here.
+ */
+
+export interface CatalogProject {
+  hash: string; key: string; local: boolean; aliases: string[];
+  captureRows: number; captureBytes: number; captureLastAt: string | null;
+  curatedEntries: number | null; curatedLastAt: string | null; curatedAvailable: boolean;
+  capMb: number; retentionDays: number;
+}
+
+interface CatalogRow { hash: string; key: string; local: number; aliases: string; capture_rows: number; capture_bytes: number; capture_last_at: string | null; curated_entries: number | null; curated_last_at: string | null; cap_mb: number; retention_days: number }
+
+const fromRow = (r: CatalogRow): CatalogProject => ({ hash: r.hash, key: r.key, local: r.local === 1, aliases: JSON.parse(r.aliases) as string[],
+  captureRows: r.capture_rows, captureBytes: r.capture_bytes, captureLastAt: r.capture_last_at, curatedEntries: r.curated_entries, curatedLastAt: r.curated_last_at, curatedAvailable: r.curated_entries !== null, capMb: r.cap_mb, retentionDays: r.retention_days });
+
+/** Interrupted splits expose capture facts, but cannot authorize any curated store open or initialization. */
+function capturedSelection(base: string): boolean {
+  const value = readProfileJSON(join(base, "shards.json")) as { schema?: unknown; generation?: unknown; phase?: unknown; selectorRevision?: unknown } | undefined;
+  if (value === undefined) return false;
+  if (!value || value.schema !== SHARDED_SCHEMA || !validGeneration(value.generation) || (value.phase !== "captured" && value.phase !== "active") || typeof value.selectorRevision !== "string") throw new Error("curated shard selection is unavailable or invalid");
+  return value.phase === "captured";
+}
+
+/** Refresh the disposable curated index from its sealed logs before deriving an own-project receipt. */
+function curatedStats(base: string, hash: string, key: string, captured: boolean): { entries: number | null; lastAt: string | null } {
+  if (captured) return { entries: null, lastAt: null };
+  const dir = join(base, "projects", hash);
+  // A capture-only descriptor is not permission to initialize a curated store while listing the catalog.
+  if (!existsSync(join(dir, "generation.json")) && !existsSync(join(dir, "generation-seal.json"))) return { entries: 0, lastAt: null };
+  const store = openShardStore({ memoryDir: base, project: key, deferPromotions: true });
+  try {
+    const db = new Database(join(dir, "index.db"), { readonly: true });
+    try {
+      db.run("PRAGMA busy_timeout = 0");
+      const row = db.query("SELECT COUNT(*) AS n, MAX(at) AS last FROM entries WHERE scope = 'project' AND project = ?").get(key) as { n: number; last: string | null };
+      return { entries: row.n, lastAt: row.last };
+    } finally { db.close(); }
+  } finally { store.close(); }
+}
+
+/** Every readable shard with its machine-scope directories; the walk behind the catalog and the capacity advisor. */
+export function walkShards(base: string): { hash: string; key: string; local: boolean; machineDirs: string[] }[] {
+  const projectsDir = join(base, "projects");
+  let hashes: string[] = [];
+  try { hashes = readdirSync(projectsDir, { withFileTypes: true }).filter((e) => e.isDirectory() && /^[0-9a-f]{16}$/.test(e.name)).map((e) => e.name).sort(); } catch { /* no shards yet */ }
+  const out: { hash: string; key: string; local: boolean; machineDirs: string[] }[] = [];
+  for (const hash of hashes) {
+    const descriptor = readShardDescriptor(base, hash);
+    if (!descriptor) continue; // a half-created or corrupt shard is skipped, never fatal
+    const machineDirs: string[] = [];
+    try {
+      for (const entry of readdirSync(join(projectsDir, hash, "machine"), { withFileTypes: true })) if (entry.isDirectory()) machineDirs.push(join(projectsDir, hash, "machine", entry.name));
+    } catch { /* no machine scope yet */ }
+    out.push({ hash, key: descriptor.key, local: descriptor.local, machineDirs: machineDirs.sort() });
+  }
+  return out;
+}
+
+/** What the shards and the alias log say, before anything is persisted. */
+export function scanCatalog(base: string): CatalogProject[] {
+  const captured = capturedSelection(base);
+  // The latest op per alias (a removal included): an alias lists only under the key it currently points at, never under a past target or after `alias remove`.
+  const latest = effectiveAliases(base);
+  const out: CatalogProject[] = [];
+  for (const shard of walkShards(base)) {
+    let rows = 0, bytes = 0, lastAt: string | null = null;
+    for (const dir of shard.machineDirs) {
+      const stats = captureShardStats(dir);
+      rows += stats.rows;
+      bytes += stats.bytes;
+      if (stats.lastAt && (lastAt === null || stats.lastAt > lastAt)) lastAt = stats.lastAt;
+    }
+    const config = readCaptureConfig(shard.machineDirs[shard.machineDirs.length - 1] ?? join(base, "projects", shard.hash, "machine", "_"), base);
+    const curated = curatedStats(base, shard.hash, shard.key, captured);
+    out.push({ hash: shard.hash, key: shard.key, local: shard.local,
+      aliases: [...latest.entries()].filter(([, key]) => key === shard.key).map(([alias]) => alias).sort(),
+      captureRows: rows, captureBytes: bytes, captureLastAt: lastAt, curatedEntries: curated.entries, curatedLastAt: curated.lastAt, curatedAvailable: curated.entries !== null, capMb: config.capMb, retentionDays: config.retentionDays });
+  }
+  return out.sort((a, b) => a.key.localeCompare(b.key));
+}
+
+/** Rewrite `catalog.db` from the shards in one transaction: the same shards always reproduce the same rows. */
+export function rebuildCatalog(opts: { home?: string } = {}): CatalogProject[] {
+  const base = memoryBase(opts.home);
+  const projects = scanCatalog(base);
+  const file = join(base, "catalog.db");
+  const db = new Database(file, { create: true });
+  try {
+    db.run("PRAGMA busy_timeout = 3000");
+    try { chmodSync(file, 0o600); } catch { /* best effort */ }
+    db.transaction(() => {
+      const columns = db.query("PRAGMA table_info(projects)").all() as { name: string; notnull: number }[];
+      // This database is disposable. Rebuild older derived schemas instead of coercing unavailable into zero.
+      if (columns.length && (!columns.some(column => column.name === "curated_entries" && column.notnull === 0) || !columns.some(column => column.name === "curated_last_at"))) db.run("DROP TABLE projects");
+      db.run(`CREATE TABLE IF NOT EXISTS projects (hash TEXT PRIMARY KEY, key TEXT NOT NULL, local INTEGER NOT NULL, aliases TEXT NOT NULL,
+        capture_rows INTEGER NOT NULL, capture_bytes INTEGER NOT NULL, capture_last_at TEXT, curated_entries INTEGER, curated_last_at TEXT, cap_mb REAL NOT NULL, retention_days REAL NOT NULL)`);
+      db.run("DELETE FROM projects");
+      for (const p of projects) db.query("INSERT INTO projects (hash, key, local, aliases, capture_rows, capture_bytes, capture_last_at, curated_entries, curated_last_at, cap_mb, retention_days) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)")
+        .run(p.hash, p.key, p.local ? 1 : 0, JSON.stringify(p.aliases), p.captureRows, p.captureBytes, p.captureLastAt, p.curatedEntries, p.curatedLastAt, p.capMb, p.retentionDays);
+    }).immediate();
+  } finally { db.close(); }
+  return projects;
+}
+
+/** The stored catalog, rebuilt when absent. Listing may lag the shards; `rebuildCatalog` is the fresh read. */
+export function readCatalog(opts: { home?: string } = {}): CatalogProject[] {
+  const base = memoryBase(opts.home);
+  const file = join(base, "catalog.db");
+  if (!existsSync(file)) return rebuildCatalog(opts);
+  const captured = capturedSelection(base);
+  let db: Database | undefined;
+  try {
+    db = new Database(file, { readonly: true });
+    db.run("PRAGMA busy_timeout = 3000");
+    const columns = new Set((db.query("PRAGMA table_info(projects)").all() as { name: string }[]).map(column => column.name));
+    if (!columns.has("curated_entries") || !columns.has("curated_last_at")) throw new Error("catalog schema needs rebuild");
+    return (db.query("SELECT * FROM projects ORDER BY key").all() as CatalogRow[]).map(fromRow)
+      .map(project => captured ? { ...project, curatedEntries: null, curatedLastAt: null, curatedAvailable: false } : project);
+  } catch { return rebuildCatalog(opts); }
+  finally { db?.close(); }
+}

package/src/memory/commands.ts

@@ -4,6 +4,8 @@ import { importClaudeMem } from "./import.ts";
 import { memoryProjectKey, projectChain } from "./project.ts";
 
 export interface MemoryCommandOptions {
+  /** Startup-bound canonical project supplied by a host; no model-facing selector. */
+  project?: string;
   store?: MemoryStore;
   sync?: Omit<SyncOptions, "remote">;
   open: () => MemoryStore;
@@ -13,6 +15,7 @@ export interface MemoryCommandOptions {
   onBridgeStatus?: (status: { skippedRows: number } | undefined) => void;
 }
 export interface GoalCommandOptions {
+  project?: string;
   store?: MemoryStore;
   link?: (goal: string, task: string) => Promise<string>;
   open: () => MemoryStore;
@@ -40,7 +43,7 @@ export async function rawMemoryCommand(args: string[], cwd: string, opts: Memory
   const sub = rest[0] && !rest[0].startsWith("--") ? rest.shift()! : "list";
   const store = opts.store ?? opts.open();
   const actor = "user";
-  const project = memoryProjectKey(cwd);
+  const project = opts.project ?? memoryProjectKey(cwd);
   const need = (v: View | undefined, id: string) => v ?? fail(`no memory entry ${id} (ahub memory list shows the ids)`);
   try {
     switch (sub) {
@@ -108,7 +111,7 @@ export async function rawMemoryCommand(args: string[], cwd: string, opts: Memory
         if (rest[0] !== "claude-mem" || rest.length !== 1) fail("usage: ahub memory import claude-mem [--db <path>] [--limit N] [--restart]");
         if (limit && !(Number(limit) > 0)) fail("--limit takes a positive number");
         const isPii = opts.importPolicy();
-        const key = memoryProjectKey(cwd);
+        const key = opts.project ?? memoryProjectKey(cwd);
         const nodes = (text: string) => extractNodes(text, { cwd, project: key, repo: key.startsWith("github.com/") ? key.slice("github.com/".length) : key, checkExists: false });
         const r = importClaudeMem(store, { project: key, chain: projectChain(cwd), nodes, restart, isPii, ...(db ? { db } : {}), ...(limit ? { limit: Number(limit) } : {}) });
         if (json) return JSON.stringify(r, null, 2);
@@ -125,7 +128,7 @@ export async function rawMemoryCommand(args: string[], cwd: string, opts: Memory
       }
       case "machine": {
         const label = flag("--label");
-        const m = label ? setMachineLabel(store.dir, label) : store.machine;
+        const m = label ? setMachineLabel(store.profile.sharded ? store.profile.home : store.dir, label) : store.machine;
         return json ? JSON.stringify(m) : `this machine: ${m.id} (${m.label})`;
       }
       case "rebuild": { store.rebuild(); const c = store.counts(); return `rebuilt the index from ${c.segments} segment${c.segments === 1 ? "" : "s"}: ${c.long} long-term, ${c.short} short-term entries`; }
@@ -154,7 +157,7 @@ export async function rawGoalCommand(args: string[], cwd: string, opts: GoalComm
   const take = (name: string) => { const out: string[] = []; for (let i = rest.indexOf(name); i >= 0; i = rest.indexOf(name)) { out.push(rest[i + 1] ?? fail(`${name} needs a value`)); rest.splice(i, 2); } return out; };
   const sub = rest[0] && !rest[0].startsWith("--") ? rest.shift()! : "list";
   const store = opts.store ?? opts.open();
-  const project = memoryProjectKey(cwd);
+  const project = opts.project ?? memoryProjectKey(cwd);
   const me = store.machine.id;
   // Only this project's long-term tasks and shared ones, like every other lookup an agent may run.
   const need = (id: string | undefined) => store.goalOf(id?.replace(/^goal:/, "") ?? fail(GOAL_USAGE), project) ?? fail(`no long-term task ${id} for this project (ahub goal list shows them)`);

package/src/memory/generation-index.ts

@@ -1,15 +1,17 @@
+import { SHARDED_SCHEMA } from "./shard.ts";
+import { readShardLegacySnapshot } from "./shard-bridge.ts";
 import type { Database } from "bun:sqlite";
 import { createHash } from "node:crypto";
 import { closeSync, constants, existsSync, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, readdirSync, unlinkSync, writeSync } from "node:fs";
 import { join } from "node:path";
-import { canonicalJSON, fsyncDirectory, readProfileJSON, selectorRevision, writeProfileJSON, type BoundProfile } from "./generation.ts";
+import { canonicalJSON, hashJSON, fsyncDirectory, readProfileJSON, selectorRevision, writeProfileJSON, type BoundProfile, validateVaultLinkRow, type VaultLink } from "./generation.ts";
 import { legacyEntries, legacyHead, readLegacySnapshot, SegmentReader, type LegacyCheckpoint, type LegacySegment } from "./bridge.ts";
 import { reducePruneRows, validatePruneRow, type PrunePlan, type PruneRow, type PruneSnapshot, type PruneSourceRow, type PruneStorePort } from "./prune.ts";
 import { PROMOTED_KINDS, type Entry } from "./store.ts";
 
 const digest = (bytes: Uint8Array) => createHash("sha256").update(bytes).digest("hex");
 const fail = (): never => { throw new Error("generation input unavailable or changed; person inspection required"); };
-export const GENERATION_TABLES = ["generation_rows", "generation_prunes", "generation_targets", "generation_segments", "generation_state"] as const;
+export const GENERATION_TABLES = ["generation_vault_links", "generation_rows", "generation_prunes", "generation_targets", "generation_segments", "generation_state"] as const;
 export interface GenerationIndexOptions {
   profile: BoundProfile; db: Database; now: () => number;
   apply: (line: string, source: string) => void;
@@ -43,6 +45,18 @@ export function explicitExpirySnapshot(rows: readonly PruneSourceRow[]): PruneSn
   });
 }
 
+/** Exact source-presence reducer shared by indexing and migration proof validation. */
+export function coalesceGenerationSource(prior: PruneSourceRow | undefined, row: Entry, source: { source: string; local: boolean }): PruneSourceRow {
+  if (prior && canonicalJSON(prior.row) !== canonicalJSON(row)) return fail();
+  const local = source.local || row.op === "settle" || row.op === "note" && row.tier === "short";
+  const publicWitness = !local && source.source !== "legacy-local";
+  const own = source.source === "generation";
+  return { row, placement: local && (!prior || prior.placement === "local") ? "local" : "synced",
+    publicWitness: !!prior?.publicWitness || publicWitness,
+    own: prior ? row.op === "note" ? prior.own === true && own : prior.own === true || own : own,
+    legacy: !!prior?.legacy || !own };
+}
+
 /** Generation-owned derived state. Legacy files are inputs, never opened as a MemoryStore. */
 export class GenerationIndex {
   readonly profile: BoundProfile;
@@ -55,6 +69,7 @@ export class GenerationIndex {
     const db = options.db;
     db.run("CREATE TABLE IF NOT EXISTS generation_rows (id TEXT PRIMARY KEY, line TEXT NOT NULL, local INTEGER NOT NULL, public INTEGER NOT NULL, own INTEGER NOT NULL, legacy INTEGER NOT NULL)");
     if (!(db.query("PRAGMA table_info(generation_rows)").all() as { name: string }[]).some(row => row.name === "legacy")) { db.run("ALTER TABLE generation_rows ADD COLUMN legacy INTEGER NOT NULL DEFAULT 0"); this.replayProvenance = true; }
+    db.run("CREATE TABLE IF NOT EXISTS generation_vault_links (id TEXT PRIMARY KEY, target TEXT NOT NULL, row_hash TEXT NOT NULL, project TEXT NOT NULL, path TEXT NOT NULL, at TEXT NOT NULL)");
     db.run("CREATE TABLE IF NOT EXISTS generation_prunes (id TEXT PRIMARY KEY, line TEXT NOT NULL, local INTEGER NOT NULL)");
     db.run("CREATE TABLE IF NOT EXISTS generation_targets (id TEXT PRIMARY KEY)");
     db.run("CREATE TABLE IF NOT EXISTS generation_segments (source TEXT NOT NULL, path TEXT NOT NULL, offset INTEGER NOT NULL, hash TEXT NOT NULL, commit_id TEXT, stamp TEXT, PRIMARY KEY(source,path))");
@@ -74,7 +89,15 @@ export class GenerationIndex {
       });
     });
   }
+  /** Authoring handles cannot read or append a partially resumed split; migration index bootstraps use captured limits. */
+  private shardFrontier(): string | undefined {
+    if (!this.profile.sharded || this.options.limits !== undefined) return undefined;
+    const value = readProfileJSON(join(this.profile.home, "shards.json")) as { schema?: unknown; phase?: unknown; generation?: unknown; selectorRevision?: unknown } | undefined;
+    if (!value || value.schema !== SHARDED_SCHEMA || value.phase !== "active" || value.generation !== this.profile.generation || value.selectorRevision !== this.profile.selectorRevision) return fail();
+    return hashJSON(value);
+  }
   private capture(): { segments: LegacySegment[]; commit?: string } {
+    const shardBefore = this.shardFrontier();
     const db = this.options.db;
     const previous = db.query("SELECT source,path,offset,hash,commit_id,stamp FROM generation_segments WHERE source != 'generation'").all() as (LegacyCheckpoint & { commit_id: string | null; stamp: string | null })[];
     const initial = readProfileJSON(join(this.profile.dir, "migration-sources.json")) as { sources?: LegacyCheckpoint[]; legacyCommit?: string } | undefined;
@@ -84,13 +107,18 @@ export class GenerationIndex {
     const persisted = new Set(previous.map(row => `${row.source}:${row.path}`));
     const completeFrontier = checkpoints.every(row => persisted.has(`${row.source}:${row.path}`));
     const prior = (db.query("SELECT value FROM generation_state WHERE key='legacyCommit'").get() as { value: string } | null)?.value ?? initial?.legacyCommit;
-    const commit = this.options.commit ?? legacyHead(this.profile.home, this.profile.generation!);
-    const legacy = readLegacySnapshot(this.profile.home, { generation: this.profile.generation, ...(commit ? { commit } : {}), checkpoints, ...(prior ? { previousCommit: prior } : {}), ...(this.options.limits ? { limits: this.options.limits } : {}), reader: this.reader, incremental: !this.fullCapture && !this.options.limits && completeFrontier });
+    const legacyHome = this.profile.legacyHome ?? this.profile.home;
+    const generation = this.profile.sharded ? undefined : this.profile.generation;
+    const commit = this.options.commit ?? (generation ? legacyHead(legacyHome, generation) : undefined);
+    const legacy = this.profile.sharded
+      ? readShardLegacySnapshot(this.profile, { checkpoints, ...(this.options.limits ? { limits: this.options.limits } : {}), reader: this.reader, incremental: !this.fullCapture && !this.options.limits && completeFrontier })
+      : readLegacySnapshot(legacyHome, { ...(generation ? { generation } : {}), ...(commit ? { commit } : {}), checkpoints, ...(generation && prior ? { previousCommit: prior } : {}), ...(this.options.limits ? { limits: this.options.limits } : {}), reader: this.reader, incremental: !this.fullCapture && !this.options.limits && completeFrontier });
     const own = this.ownSegments();
     for (const old of db.query("SELECT path,offset,hash FROM generation_segments WHERE source='generation'").all() as { path: string; offset: number; hash: string }[]) {
       const segment = own.find(s => s.path === old.path);
       if (!segment || segment.offset < old.offset) fail();
     }
+    if (this.shardFrontier() !== shardBefore) return fail();
     return { segments: [...legacy, ...own], ...(commit ? { commit } : {}) };
   }
   private index(captured: { segments: LegacySegment[]; commit?: string }): void {
@@ -107,19 +135,21 @@ export class GenerationIndex {
           db.query("INSERT OR IGNORE INTO generation_prunes VALUES (?,?,?)").run(row.id, canonicalJSON(row), Number(segment.local));
           continue;
         }
+        if (segment.source === "generation" && parsed && typeof parsed === "object" && (parsed as { op?: string }).op === "vault_link") {
+          const row = validateVaultLinkRow(parsed, this.profile.generation, segment.local ? "local" : "synced");
+          if (segment.path !== `local/${row.machine}.jsonl`) fail();
+          db.query("INSERT OR IGNORE INTO generation_vault_links VALUES (?,?,?,?,?,?)").run(row.id, row.target, row.rowHash, row.project, row.path, row.at);
+          continue;
+        }
         const bytes = Buffer.from(line + "\n");
         const row = legacyEntries([{ ...segment, bytes, offset: bytes.length, hash: digest(bytes) }], { strict: segment.source === "generation", onMalformed: () => this.recordSkipped(segment) })[0];
         if (!row) continue;
-        const canonical = canonicalJSON(row), old = db.query("SELECT line,own,legacy FROM generation_rows WHERE id=?").get(row.id) as { line: string; own: number; legacy: number } | null;
+        const canonical = canonicalJSON(row), old = db.query("SELECT line,local,public,own,legacy FROM generation_rows WHERE id=?").get(row.id) as { line: string; local: number; public: number; own: number; legacy: number } | null;
         if (old && old.line !== canonical) fail();
         this.options.apply(line, segment.path);
-        const local = segment.local || row.op === "settle" || row.op === "note" && row.tier === "short";
-        const publicWitness = !local && segment.source !== "legacy-local";
-        const own = segment.source === "generation", legacy = !own;
-        // Notes retain legacy birth when duplicated; ops can independently occur in both birth realms.
-        const ownPresence = old ? row.op === "note" ? !!old.own && own : !!old.own || own : own;
+        const presence = coalesceGenerationSource(old ? { row, placement: old.local ? "local" : "synced", publicWitness: !!old.public, own: !!old.own, legacy: !!old.legacy } : undefined, row, segment);
         db.query("INSERT INTO generation_rows VALUES (?,?,?,?,?,?) ON CONFLICT(id) DO UPDATE SET local=MIN(local,excluded.local), public=MAX(public,excluded.public), own=excluded.own, legacy=excluded.legacy")
-          .run(row.id, canonical, Number(local), Number(publicWitness), Number(ownPresence), Number(!!old?.legacy || legacy));
+          .run(row.id, canonical, Number(presence.placement === "local"), Number(presence.publicWitness), Number(presence.own), Number(presence.legacy));
       }
       db.query("INSERT INTO generation_segments VALUES (?,?,?,?,?,?) ON CONFLICT(source,path) DO UPDATE SET offset=excluded.offset,hash=excluded.hash,commit_id=excluded.commit_id,stamp=excluded.stamp")
         .run(segment.source, segment.path, segment.offset, segment.hash, segment.commit ?? null, segment.stamp ?? null);
@@ -173,6 +203,18 @@ export class GenerationIndex {
     if (!committed) { if (attempt < 5) return this.rebuild(attempt + 1); return fail(); }
     this.replayProvenance = false;
   }
+  vaultWitnesses(ids: readonly string[]): Map<string, string> {
+    if (ids.length > 5000) throw new Error("vault scan budget exceeded");
+    return new Map((this.options.db.query("SELECT id,line FROM generation_rows WHERE id IN (SELECT value FROM json_each(?))").all(JSON.stringify(ids)) as { id: string; line: string }[])
+      .map(row => [row.id, hashJSON(JSON.parse(row.line))]));
+  }
+  vaultLinks(project: string): VaultLink[] {
+    const rows = this.options.db.query("SELECT l.id,l.target,l.row_hash AS rowHash,l.project,l.path,l.at,r.line FROM generation_vault_links l JOIN generation_rows r ON r.id=l.target WHERE l.project=? ORDER BY l.at,l.id LIMIT 5001").all(project) as (VaultLink & { line: string })[];
+    if (rows.length > 5000) throw new Error("vault scan budget exceeded");
+    return rows
+      .filter(row => { const note = JSON.parse(row.line) as Entry; return note.op === "note" && note.project === row.project && hashJSON(note) === row.rowHash; })
+      .map(({ line: _line, ...row }) => row);
+  }
   own(id: string): boolean { return !!(this.options.db.query("SELECT own FROM generation_rows WHERE id=?").get(id) as { own: number } | null)?.own; }
   snapshot(refresh = true): PruneSnapshot {
     if (refresh) this.refresh();
@@ -191,6 +233,7 @@ export class GenerationIndex {
   private pendingPath(local: boolean, machine: string): string { return join(this.profile.dir, "prune-plans", `pending-${local ? "local" : "log"}-${machine}.json`); }
   /** Every ordinary writer must refuse to append unrelated JSON after a prune crash tail. */
   assertAppendable(local: boolean, machine: string): void {
+    this.shardFrontier();
     if (readProfileJSON(this.pendingPath(local, machine)) !== undefined) fail();
     const file = join(this.profile.dir, local ? "local" : "log", `${machine}.jsonl`);
     if (!existsSync(file)) return;

package/src/memory/generation.ts

@@ -1,6 +1,7 @@
 import { createHash, randomBytes } from "node:crypto";
+import { types } from "node:util";
 import { closeSync, existsSync, fsyncSync, lstatSync, openSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
-import { mutationDatabase } from "./mutation.ts";
+import { readerAdmissionDatabase } from "./mutation.ts";
 import { dirname, join } from "node:path";
 import { canonicalPath, processLiveness, processSignature, realPath } from "./platform.ts";
 
@@ -11,6 +12,13 @@ export interface BoundProfile {
   dir: string;
   generation?: string;
   selectorRevision: string;
+  /** Sharded profiles read only their own legacy input; the root home remains the machine/selector identity. */
+  legacyHome?: string;
+  /** Public legacy witnesses stay distinct from same-machine private bridge input. */
+  legacyMainHome?: string;
+  sharded?: boolean;
+  shardKey?: string;
+  shardUser?: boolean;
 }
 export type ProfileInput = "shared-v1" | { generation: string };
 export interface ProfileSelector { schema: "agent-mem.profile/v1"; kind: "shared-v1" | "generation"; generation?: string }
@@ -102,7 +110,7 @@ export async function withProfileLock<T>(memoryDir: string, work: () => T | Prom
   const deadline = Date.now() + PROFILE_LOCK_TIMEOUT_MS;
   for (;;) {
     let acquired = false;
-    const fence = mutationDatabase(memoryDir);
+    const fence = readerAdmissionDatabase(memoryDir);
     let fenced = false;
     try {
       // Serialize the complete stale-owner probe/unlink/recreate sequence, then release before waiting on a live owner.
@@ -141,3 +149,34 @@ export async function withProfileLock<T>(memoryDir: string, work: () => T | Prom
     }
   }
 }
+
+
+export interface VaultLinkRow {
+  schema: "agent-mem.vault-link/v1"; op: "vault_link"; generation: string;
+  id: string; at: string; machine: string; actor: "person"; placement: "local";
+  target: string; rowHash: string; project: string; path: string;
+}
+export interface VaultLink { id: string; target: string; rowHash: string; project: string; path: string; at: string }
+const invalidVaultLink = (): never => { throw new Error("invalid vault link or unavailable exact entry"); };
+export const vaultLinkId = (body: unknown): string => createHash("sha256").update(canonicalJSON(body)).digest("hex").slice(0, 32);
+
+/** Metadata only: this path is never resolved, opened, copied or written by amem. */
+export function validVaultPath(path: unknown): path is string {
+  return typeof path === "string" && path.length > 0 && Buffer.byteLength(path) <= 512 && path.endsWith(".md")
+    && !/[\\:\p{Cc}]/u.test(path) && !path.startsWith("/") && path.split("/").every(part => part !== "" && part !== "." && part !== "..");
+}
+export function validateVaultLinkRow(value: unknown, generation: string | undefined, placement: "local" | "synced"): VaultLinkRow {
+  if (!value || typeof value !== "object" || types.isProxy(value) || Array.isArray(value) || Object.getPrototypeOf(value) !== Object.prototype || Object.getOwnPropertySymbols(value).length) return invalidVaultLink();
+  const expected = ["schema", "op", "generation", "id", "at", "machine", "actor", "placement", "target", "rowHash", "project", "path"].sort();
+  const descriptors = Object.getOwnPropertyDescriptors(value);
+  if (canonicalJSON(Object.keys(descriptors).sort()) !== canonicalJSON(expected) || Object.values(descriptors).some(field => !("value" in field) || !field.enumerable || typeof field.value !== "string")) return invalidVaultLink();
+  const row = value as VaultLinkRow;
+  if (row.schema !== "agent-mem.vault-link/v1" || row.op !== "vault_link" || row.generation !== generation || !/^[a-f0-9]{32}$/.test(row.generation)
+    || row.placement !== "local" || placement !== "local" || row.actor !== "person" || !/^[a-f0-9]{16}$/.test(row.machine)
+    || !/^[a-f0-9]{32}$/.test(row.id) || !/^[a-f0-9]{32}$/.test(row.target) || !/^[a-f0-9]{64}$/.test(row.rowHash)
+    || !row.project.trim() || row.project.length > 400 || /\p{Cc}/u.test(row.project) || !validVaultPath(row.path)
+    || !Number.isFinite(Date.parse(row.at)) || new Date(row.at).toISOString() !== row.at || Buffer.byteLength(canonicalJSON(row)) > 4096) return invalidVaultLink();
+  const { id, ...body } = row;
+  if (id !== vaultLinkId(body)) return invalidVaultLink();
+  return row;
+}

package/src/memory/home.ts

@@ -8,3 +8,8 @@ export function memoryHome(env: NodeJS.ProcessEnv = process.env): string {
   if (own) return canonicalPath(own);
   return join(canonicalPath(env.AGENTHUB_HOME?.trim() || join(homedir(), ".agenthub")), "memory");
 }
+
+/** The store's own base convention: `StoreOptions.home` names the parent and gets `/memory` appended. */
+export function memoryBase(home?: string): string {
+  return home === undefined ? memoryHome() : join(home, "memory");
+}

package/src/memory/import.ts

@@ -5,6 +5,8 @@ import { realPath } from "./platform.ts";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { KINDS, looksSecret, type Kind, type MemoryStore } from "./store.ts";
+import { aliasedKeys, resolveAlias } from "./shard.ts";
+import { WorkListStore, type WorkListFields, type WorkListPolicy } from "./work-lists.ts";
 
 /** The claude-mem store is another program's: opened read-only, never written, its locks waited on briefly. */
 export const CLAUDE_MEM_BUSY_TIMEOUT_MS = 3000;
@@ -12,6 +14,63 @@ export const CLAUDE_MEM_BUSY_TIMEOUT_MS = 3000;
 const MODEL_ANSWER = "ahub ask (model answer)";
 
 export interface ImportResult { read: number; added: number; skipped: { model: number; pii: number; secret: number }; more: boolean; cursor: number }
+export interface WorkStateImportResult { read: number; added: number; skipped: { invalid: number; policy: number }; more: boolean; cursor: number }
+
+/**
+ * Import only the source project names explicitly mapped by the person's D2 alias table. A basename or even
+ * an exact canonical-key match is not permission to adopt another program's project. Source receipts preserve
+ * synced device/id identity across database copies; unsynced rows are scoped to the source's real path.
+ */
+export async function importClaudeMemWorkState(opts: { base: string; project: string; policy: WorkListPolicy; db?: string; limit?: number; restart?: boolean; log?: (line: string) => void }): Promise<WorkStateImportResult> {
+  const file = opts.db ?? join(homedir(), ".claude-mem", "claude-mem.db");
+  if (!existsSync(file)) throw new Error(`no claude-mem store at ${file}`);
+  const limit = opts.limit ?? 10_000;
+  if (!Number.isSafeInteger(limit) || limit <= 0) throw new Error("--limit takes a positive integer");
+  const project = resolveAlias(opts.base, opts.project);
+  const aliases = aliasedKeys(opts.base, project);
+  const result: WorkStateImportResult = { read: 0, added: 0, skipped: { invalid: 0, policy: 0 }, more: false, cursor: 0 };
+  if (!aliases.length) return result;
+  const db = new Database(file, { readonly: true });
+  let store: WorkListStore | undefined;
+  let state: string | undefined, key = "", cursor = 0;
+  try {
+    db.run(`PRAGMA busy_timeout = ${CLAUDE_MEM_BUSY_TIMEOUT_MS}`);
+    if (!db.query("SELECT name FROM sqlite_master WHERE type = 'table' AND name = 'work_state_entries'").get()) return result;
+    const columns = new Set((db.query("PRAGMA table_info(work_state_entries)").all() as { name: string }[]).map(row => row.name));
+    const origin = columns.has("origin_device_id") && columns.has("origin_local_id");
+    const sourceMachine = createHash("sha256").update(realPath(file)).digest("hex");
+    store = new WorkListStore({ base: opts.base, project, policy: opts.policy });
+    state = join(store.dir, "import-state.json");
+    key = createHash("sha256").update(JSON.stringify([sourceMachine, aliases, project])).digest("hex");
+    cursor = opts.restart ? 0 : readCursors(state)[key] ?? 0;
+    const where = `project IN (${aliases.map(() => "?").join(",")})`;
+    const max = db.query(`SELECT MAX(id) AS id FROM work_state_entries WHERE ${where}`).get(...aliases) as { id: number | null };
+    if ((max.id ?? 0) < cursor) cursor = 0;
+    const rows = db.query(`SELECT id, list_name, fields, created_at_epoch${origin ? ", origin_device_id, origin_local_id" : ", NULL AS origin_device_id, NULL AS origin_local_id"} FROM work_state_entries WHERE ${where} AND id > ? ORDER BY id LIMIT ?`)
+      .all(...aliases, cursor, limit) as { id: number; list_name: string; fields: string; created_at_epoch: number; origin_device_id: string | null; origin_local_id: string | null }[];
+    result.read = rows.length; result.more = rows.length === limit;
+    for (const row of rows) {
+      try {
+        let fields: WorkListFields;
+        try { fields = JSON.parse(row.fields) as WorkListFields; } catch { result.skipped.invalid++; cursor = row.id; continue; }
+        const synced = typeof row.origin_device_id === "string" && !!row.origin_device_id && typeof row.origin_local_id === "string" && !!row.origin_local_id;
+        const written = await store.write(row.list_name, fields, { source: "claude-mem/work_state", id: synced ? row.origin_local_id! : String(row.id), machine: synced ? row.origin_device_id! : sourceMachine, at: row.created_at_epoch });
+        if (!written.already) result.added++;
+      } catch (error) {
+        if (error instanceof Error && error.message === "invalid work-list input") result.skipped.invalid++;
+        else if (error instanceof Error && error.message === "work-list privacy policy refused the write") result.skipped.policy++;
+        else throw error; // Do not advance a receipt conflict or a failed append.
+      }
+      cursor = row.id;
+    }
+  } finally {
+    db.close();
+    result.cursor = cursor;
+    if (state) writeCursor(state, key, cursor, opts.log ?? console.error);
+    store?.close();
+  }
+  return result;
+}
 
 /** Machine-local progress is disposable; malformed/unreadable state simply replays the idempotent import. */
 function readCursors(file: string): Record<string, number> {

package/src/memory/migrate.ts

@@ -97,10 +97,17 @@ function writeSources(memoryDir: string, journal: MigrationJournal): void {
     { schema: "agent-mem.migration-sources/v1", sources: journal.sources, legacyCommit: journal.legacyCommit });
 }
 
+function refuseShardSelection(memoryDir: string): void {
+  try { lstatSync(join(memoryDir, "shards.json")); }
+  catch (error) { if ((error as NodeJS.ErrnoException).code === "ENOENT") return; throw error; }
+  throw new Error("ordinary generation migration is unavailable after shard migration starts; inspect amem status and use amem migrate --shards --resume; the existing selector was retained");
+}
+
 export async function migrate(options: MigrateOptions): Promise<MigrationResult> {
   if (options.authorizedPerson !== true || options.tty !== true) throw new Error("migration requires an authorized person in a terminal");
   if (!["dry-run", "apply", "resume", "deactivate"].includes(options.mode) || options.generation !== undefined && !validGeneration(options.generation)) throw new Error("invalid migration request");
   const memoryDir = existsSync(options.memoryDir) ? realPath(options.memoryDir) : canonicalPath(options.memoryDir);
+  refuseShardSelection(memoryDir);
   const selection = readSelector(memoryDir);
   // Explicit undo reads only the selector: broken/missing G must not make the escape back to v1 impossible.
   const selectedG = selection.selector?.kind === "generation" ? selection.selector.generation : undefined;
@@ -111,6 +118,7 @@ export async function migrate(options: MigrateOptions): Promise<MigrationResult>
     return { mode: options.mode, profile: initial, counts: await counts(memoryDir, options.generation ?? initial.generation, (options.now ?? Date.now)()), consequence };
   }
   return withProfileLock(memoryDir, async () => {
+    refuseShardSelection(memoryDir);
     const selected = readSelector(memoryDir);
     if (selected.revision !== initial.selectorRevision) return changed();
     if (options.mode === "deactivate") {

package/src/memory/mutation.ts

@@ -1,5 +1,5 @@
 import { Database } from "bun:sqlite";
-import { chmodSync } from "node:fs";
+import { chmodSync, lstatSync } from "node:fs";
 import { join } from "node:path";
 
 export const MUTATION_BUSY_TIMEOUT_MS = 3000;
@@ -20,3 +20,15 @@ export function acquireMutation(dir: string): (() => void) | undefined {
   catch { db.close(); return undefined; }
   return () => { try { db.run("ROLLBACK"); } finally { db.close(); } };
 }
+
+/** Short local admission fence, never held across sync/network or data mutations. */
+export function readerAdmissionDatabase(dir: string): Database {
+  const file = join(dir, "reader-admission.db");
+  for (const suffix of ["", "-wal", "-shm", "-journal"]) {
+    const stat = lstatSync(file + suffix, { throwIfNoEntry: false });
+    if (stat && (stat.isSymbolicLink() || !stat.isFile())) throw new Error("reader admission fence is not a regular file");
+  }
+  const db = new Database(file, { create: true });
+  try { chmodSync(file, 0o600); db.run(`PRAGMA busy_timeout = ${MUTATION_BUSY_TIMEOUT_MS}`); return db; }
+  catch (error) { db.close(); throw error; }
+}

package/src/memory/ops-contract.ts

@@ -118,7 +118,7 @@ export interface GenerationOpContract extends Omit<OpContract, "implemented" | "
   implemented: true;
   generationOnly: true;
   targetSemantics: "exact-entry-v1";
-  validator: "validatePruneRow";
+  validator: "validatePruneRow" | "validateVaultLinkRow";
   validation: readonly string[];
   payloadSchema: {
     version: 1;
@@ -156,4 +156,21 @@ export const PRUNE_GENERATION_CONTRACT: GenerationOpContract = Object.freeze<Gen
   crashBoundary: "fsync exact local sealed plan, mutation fence, revalidate proofs/policy, append+fsync complete row then refresh; per-row atomicity; retry skips durable IDs; incomplete own tail completes only from identical persisted-plan prefix; mismatched tail refuses",
   fixtures: ["test/generation-prune.test.ts#only explicit note expires or demote settle by values can prove expiry", "test/generation-prune.test.ts#exact-entry reducer waits for witnesses and cannot be reversed by clock or later deadlines", "test/generation-prune.test.ts#prune partitions private target or basis locally and public attestations bind only public rows", "test/generation-prune.test.ts#prune row shape hashes canonical time ordering placement and byte bounds are strict"],
 });
-export const GENERATION_OP_CONTRACTS: Readonly<Record<"prune", GenerationOpContract>> = Object.freeze({ prune: PRUNE_GENERATION_CONTRACT });
+export const VAULT_LINK_GENERATION_CONTRACT: GenerationOpContract = Object.freeze<GenerationOpContract>({
+  status: "truth-changing", implemented: true, generationOnly: true, targetSemantics: "exact-entry-v1", validator: "validateVaultLinkRow",
+  validation: ["exact string-valued keys; no additional fields; canonical UTC and bounded metadata", "id is canonical complete payload hash excluding id", "bound generation and local authored machine segment must match", "projection requires exact full target id and authored row hash in the same project"],
+  payloadVersion: "agent-mem.vault-link/v1", required: ["schema", "op", "generation", "id", "at", "machine", "actor", "placement", "target", "rowHash", "project", "path"],
+  payloadSchema: { version: 1, required: ["schema", "op", "generation", "id", "at", "machine", "actor", "placement", "target", "rowHash", "project", "path"], additionalProperties: false, maxUtf8Bytes: 4096, fields: {
+    schema: { type: "string", values: ["agent-mem.vault-link/v1"] }, op: { type: "string", values: ["vault_link"] },
+    generation: generationId, id: generationId, at: canonicalUtc, machine: { type: "string", pattern: "^[a-f0-9]{16}$" },
+    actor: { type: "string", values: ["person"] }, placement: { type: "string", values: ["local"] }, target: generationId, rowHash: authoredHash,
+    project: { type: "string" }, path: { type: "string" },
+  } },
+  immutableTargets: "full exact note id and SHA-256 of the complete canonical authored row; project must match; no aliases, promotion ancestry or replacements",
+  placement: "generation local segment only; vault paths are machine-local metadata and never sync; shard migration carries the row to its exact target owner",
+  precedence: "append-only links suppress only their witnessed exact entry from future candidates; independent replacement ids survive; malformed or missing witnesses cannot suppress",
+  identity: "sha256(canonical complete vault-link payload excluding id), first 32 hex; generation, target id, full witness hash and path participate",
+  crashBoundary: "mutation fence and exact id/hash recheck; refuse an incomplete prior tail; append+fsync then derived refresh; complete rows replay, incomplete tails require person inspection",
+  fixtures: ["test/vault.test.ts#vault links refuse shared-v1 and bind exact generation entries, survive rebuild, and never touch v1 logs", "test/vault.test.ts#vault link validation rejects changed payload hashes, foreign generation and public placement", "test/vault.test.ts#vault links retain their exact target through curated shard migration"],
+});
+export const GENERATION_OP_CONTRACTS: Readonly<Record<"prune" | "vault_link", GenerationOpContract>> = Object.freeze({ prune: PRUNE_GENERATION_CONTRACT, vault_link: VAULT_LINK_GENERATION_CONTRACT });