@staix/agent-mem 0.3.1 → 0.5.0

package/src/mcp-memory.ts

@@ -0,0 +1,194 @@
+import { lstatSync } from "node:fs";
+import { join } from "node:path";
+import type { McpHandlers } from "./mcp.ts";
+import { CandidateStore } from "./memory/candidates.ts";
+import { capacityReport } from "./memory/capacity.ts";
+import { CaptureStore } from "./memory/capture.ts";
+import { readSelector } from "./memory/generation.ts";
+import { memoryHome } from "./memory/home.ts";
+import { canonicalPath, realPath } from "./memory/platform.ts";
+import { createStandalonePolicy, type StandalonePolicyOptions } from "./memory/policy.ts";
+import { memoryProjectKey } from "./memory/project.ts";
+import { registerReaderLease } from "./memory/reader-lease.ts";
+import { type ReadRef, type ReadWindow, SearchIndex } from "./memory/search-fts.ts";
+import { aliasedKeys, readShardedSelection, resolveAlias } from "./memory/shard.ts";
+import { MemoryStore, openShardStore, type Graph, type View } from "./memory/store.ts";
+import { vaultCandidates } from "./memory/vault.ts";
+import { WorkListStore, type WorkListFields } from "./memory/work-lists.ts";
+
+// Graph retains its complete-corpus ceiling; search/timeline/show page matching bodies instead.
+export const MCP_SCAN_LIMIT = 5000;
+// ponytail: rank the newest 5000 permitted matching candidates per tier; use since to narrow or upgrade to a policy-bound persistent index for global ranking.
+const SEARCH_CANDIDATES = 5000;
+const READ_PAGE = 256;
+export interface MemoryMcpOptions { cwd: string; base?: string; project?: string; policy?: StandalonePolicyOptions }
+export interface MemoryMcp { tools: McpHandlers; close(): void }
+const unavailable = (): never => { throw new Error("memory operation unavailable"); };
+const bound = (args: Record<string, unknown>, keys: string[]) => { if (Object.keys(args).some(key => !keys.includes(key))) unavailable(); };
+const limitOf = (args: Record<string, unknown>): number => args.limit === undefined ? 20 : Number.isSafeInteger(args.limit) && Number(args.limit) >= 1 && Number(args.limit) <= 100 ? Number(args.limit) : unavailable();
+const textOf = (args: Record<string, unknown>, key: string, optional = false): string | undefined => {
+  const value = args[key]; if (value === undefined && optional) return undefined;
+  return typeof value === "string" && value.trim() && !value.includes("\0") ? value : unavailable();
+};
+const sinceOf = (args: Record<string, unknown>): string | undefined => { const since = textOf(args, "since", true); if (since !== undefined && !Number.isFinite(Date.parse(since))) unavailable(); return since === undefined ? undefined : new Date(since).toISOString(); };
+
+/** All identities are resolved once. Per-call arguments cannot change projects, homes, profiles or policy. */
+export function createMemoryMcp(options: MemoryMcpOptions): MemoryMcp {
+  const cwd = realPath(options.cwd), base = canonicalPath(options.base ?? memoryHome());
+  const requested = options.project ?? memoryProjectKey(cwd), project = resolveAlias(base, requested);
+  const policy = createStandalonePolicy(options.policy), release = registerReaderLease(base);
+  const closers: (() => void)[] = [release]; let closed = false;
+  const close = () => { if (closed) return; closed = true; let failure: unknown; for (const closer of closers.reverse()) { try { closer(); } catch (error) { failure ??= error; } } if (failure) throw failure; };
+  try {
+    const selection = readSelector(base).revision;
+    const sharded = !!lstatSync(join(base, "shards.json"), { throwIfNoEntry: false });
+    const shardSelection = sharded ? JSON.stringify(readShardedSelection(base)) : undefined;
+    // #27: the project filter covers the canonical key and every key aliased to it; the keys are fixed with the project, so a later alias change fails the guard below.
+    const aliases = aliasedKeys(base, project), reconcile = aliases.length ? { canonical: project, aliases } : undefined;
+    const store = sharded ? openShardStore({ memoryDir: base, project, deferPromotions: true, ...(reconcile ? { reconcile } : {}) }) : new MemoryStore({ memoryDir: base, deferPromotions: true, ...(reconcile ? { reconcile } : {}) });
+    closers.push(() => store.close());
+    const capture = new CaptureStore({ memoryDir: base, project }); closers.push(() => capture.close());
+    const candidates = new CandidateStore({ memoryDir: base, ...(reconcile ? { reconcile } : {}) }); closers.push(() => candidates.close());
+    const work = new WorkListStore({ base, project, aliases, policy: async row => { const permitted = await policy.screen(row); guard(); return permitted; } }); closers.push(() => work.close());
+    const guard = () => {
+      if (closed) unavailable();
+      release.verify();
+      if (resolveAlias(base, requested) !== project || aliasedKeys(base, project).join("\n") !== aliases.join("\n") || readSelector(base).revision !== selection) unavailable();
+      const split = !!lstatSync(join(base, "shards.json"), { throwIfNoEntry: false });
+      if (split !== sharded || split && JSON.stringify(readShardedSelection(base)) !== shardSelection) unavailable();
+    };
+    const screen = async <T>(rows: T[]): Promise<T[]> => {
+      if (rows.length > MCP_SCAN_LIMIT) unavailable();
+      const publicRows: T[] = []; for (const row of rows) if (await policy.screen(row)) publicRows.push(row); return publicRows;
+    };
+    const curated = async (superseded = false) => {
+      guard();
+      // list() includes shared rows: remove other projects before screening or selection.
+      const rows = store.list({ project, includeSuperseded: superseded, limit: MCP_SCAN_LIMIT + 1 });
+      if (rows.length > MCP_SCAN_LIMIT) unavailable();
+      return screen(rows.filter(row => row.project === project));
+    };
+    const readPermitted = async <T>(read: (window: ReadWindow) => { rows: T[]; next?: ReadRef; engine?: "fts5" | "substring" },
+      options: Omit<ReadWindow, "project" | "limit" | "after">, cap: number, matches: (row: T, engine?: "fts5" | "substring") => boolean = () => true): Promise<T[]> => {
+      const result: T[] = []; let after: ReadWindow["after"];
+      while (result.length < cap) {
+        guard();
+        const page = read({ ...options, project, limit: READ_PAGE, after });
+        for (const row of page.rows) if (await policy.screen(row) && matches(row, page.engine)) {
+          result.push(row); if (result.length === cap) break;
+        }
+        guard();
+        if (!page.next) break;
+        after = { position: page.next.position, id: page.next.id };
+      }
+      return result;
+    };
+    const anchorAt = async (id: string): Promise<string | undefined> => {
+      if (/^capture:[1-9][0-9]*$/.test(id)) {
+        return (await readPermitted(window => capture.readPage(window), { id: id.slice(8) }, 1))[0]?.at;
+      }
+      const rows = await readPermitted(window => store.readPage({ ...window, includeSuperseded: true }), { prefix: id.replace(/^mem:/, "") }, 2);
+      return rows.length === 1 ? rows[0]!.at : undefined;
+    };
+    const tools: McpHandlers = {
+      async amem_search(args) {
+        bound(args, ["query", "limit", "since", "includeCapture"]); const query = textOf(args, "query")!, limit = limitOf(args), since = sinceOf(args);
+        if (args.includeCapture !== undefined && typeof args.includeCapture !== "boolean") unavailable();
+        if (!await policy.screen({ query })) unavailable();
+        const index = new SearchIndex(":memory:");
+        try {
+          const words = query.toLowerCase().split(/\s+/).filter(Boolean);
+          const captureState: { engine?: "fts5" | "substring" } = {};
+          const recalls = args.includeCapture === false ? [] : await readPermitted(window => {
+            const page = capture.readPage({ ...window, query, ...(captureState.engine === "substring" ? { match: "substring" as const } : {}) });
+            captureState.engine ??= page.engine;
+            return page;
+          }, { since }, SEARCH_CANDIDATES,
+            (row, engine) => index.available && engine === "fts5" || words.every(word => `${row.excerpt}\n${row.paths.join(" ")}\n${row.event}`.toLowerCase().includes(word)));
+          const useFts = index.available && captureState.engine !== "substring";
+          const notes = await readPermitted(window => store.readPage({ ...window, ...(useFts ? { query } : {}) }), { since }, SEARCH_CANDIDATES,
+            view => useFts || words.every(word => `${view.title ?? ""}\n${view.text}\n${view.about.join(" ")}`.toLowerCase().includes(word)));
+          const hits = [...notes.map(view => ({ source: "curated" as const, evidence: true, view, ref: view.id, at: view.at, tier: view.tier, body: `${view.title ?? ""}\n${view.text}\n${view.about.join(" ")}` })),
+            ...recalls.map(row => ({ source: "capture" as const, evidence: false, capture: row, ref: `capture:${row.id}`, at: row.at, tier: "capture", body: `${row.excerpt}\n${row.paths.join(" ")}\n${row.event}` }))].filter(hit => !since || Date.parse(hit.at) >= Date.parse(since));
+          if (useFts) {
+            index.resync(() => hits.map(hit => ({ id: hit.ref, at: hit.at, project, tier: hit.tier, scope: "project", body: hit.body })));
+            if (index.needsResync(hits.length)) unavailable();
+          }
+          const ranks = new Map((useFts ? index.query(query, MCP_SCAN_LIMIT * 2, project) : []).map(row => [row.ref, row.rank]));
+          const selected = hits.flatMap(hit => {
+            const rank = ranks.get(hit.ref);
+            if (useFts ? rank === undefined : !words.every(word => hit.body.toLowerCase().includes(word))) return [];
+            const weight = hit.tier === "long" ? 1 : hit.tier === "capture" ? 0.5 : 0.9;
+            const score = -(rank ?? -1) * weight / (1 + Math.max(0, Date.now() - Date.parse(hit.at)) / (30 * 86400_000));
+            return [{ source: hit.source, evidence: hit.evidence, ...(hit.source === "curated" ? { view: hit.view } : { capture: hit.capture }), score }];
+          }).sort((a, b) => b.score - a.score).slice(0, limit);
+          guard(); return { engine: useFts ? "fts5" : "substring", hits: selected };
+        } finally { index.close(); }
+      },
+      async amem_show(args) {
+        bound(args, ["id"]); guard(); const id = textOf(args, "id")!;
+        if (/^capture:[1-9][0-9]*$/.test(id)) {
+          const row = (await readPermitted(window => capture.readPage(window), { id: id.slice(8) }, 1))[0];
+          guard(); return row ? { source: "capture", evidence: false, capture: row } : null;
+        }
+        const rows = await readPermitted(window => store.readPage({ ...window, includeSuperseded: true }), { prefix: id.replace(/^mem:/, "") }, 2);
+        guard(); return rows.length === 1 ? rows[0]! : null;
+      },
+      async amem_timeline(args) {
+        bound(args, ["id", "since", "limit"]);
+        const id = textOf(args, "id", true), since = sinceOf(args), limit = limitOf(args);
+        guard();
+        const anchor = id ? await anchorAt(id) : undefined;
+        if (id && !anchor) { guard(); return []; }
+        const rows = await readPermitted(window => store.readPage({ ...window, includeSuperseded: true }), { since, anchor }, limit);
+        const recalls = await readPermitted(window => capture.readPage(window), { since, anchor }, limit);
+        const entries = [...rows.map(row => ({ at: row.at, ref: row.id, value: row as unknown })),
+          ...recalls.map(row => ({ at: row.at, ref: `capture:${row.id}`, value: { source: "capture", evidence: false, capture: row } as unknown }))];
+        entries.sort((a, b) => (anchor ? Math.abs(Date.parse(a.at) - Date.parse(anchor)) - Math.abs(Date.parse(b.at) - Date.parse(anchor)) : Date.parse(b.at) - Date.parse(a.at)) || (a.ref < b.ref ? -1 : a.ref > b.ref ? 1 : 0));
+        guard(); return entries.slice(0, limit).map(row => row.value);
+      },
+      async amem_graph(args) {
+        bound(args, ["start", "hops", "limit"]); const start = textOf(args, "start")!, cap = limitOf(args), hops = args.hops ?? 1;
+        if (hops !== 1 && hops !== 2) unavailable();
+        const rows = await curated(true); const result = screenedGraph(rows, start, Number(hops), cap); guard(); return result;
+      },
+      async amem_work_state_read(args) {
+        bound(args, ["list", "includeClosed"]); guard();
+        if (args.includeClosed !== undefined && typeof args.includeClosed !== "boolean") unavailable();
+        // Reduce complete views before policy: individually public appends can compose into private state.
+        const result = await work.read(textOf(args, "list", true), true);
+        const permitted: typeof result = [];
+        for (const view of result) if (await policy.screen(view)) permitted.push(view);
+        guard();
+        return args.includeClosed === true ? permitted : permitted.filter(view => !view.closed).map(view => ({ ...view, items: view.items.filter(item => item.fields.status !== "done" && item.fields.status !== "dropped") }));
+      },
+      async amem_work_state_write(args) { bound(args, ["list", "fields"]); guard(); const result = await work.write(textOf(args, "list")!, args.fields as WorkListFields); guard(); return result; },
+      async amem_remember(args) {
+        bound(args, ["text", "title", "kind"]); guard();
+        const kind = args.kind ?? "finding"; if (!["decision", "finding", "contract", "fail"].includes(String(kind))) unavailable();
+        const input = { project, kind: "memory" as const, text: textOf(args, "text")!, ...(args.title === undefined ? {} : { title: textOf(args, "title")! }), noteKind: kind as "decision" | "finding" | "contract" | "fail" };
+        if (!await policy.screen(input)) unavailable(); guard(); return { id: candidates.put(input, "public") };
+      },
+      async amem_vault_candidates(args) { bound(args, ["limit"]); guard(); const result = await vaultCandidates(store, { project, policy, limit: limitOf(args) }); guard(); return result; },
+      async amem_capacity(args) { bound(args, []); guard(); const report = capacityReport({ memoryDir: base }); if (!await policy.screen(report)) unavailable(); guard(); return report; },
+    };
+    return { tools, close };
+  } catch (error) { close(); throw error; }
+}
+
+/** Build only from screened project rows; even an absent starting node does not leak its label. */
+function screenedGraph(rows: View[], start: string, hops: number, cap: number): Graph {
+  const nodes = new Map<string, Graph["nodes"][number]>(), edges: Graph["edges"] = [];
+  const views = new Map(rows.map(row => [`mem:${row.id}`, row]));
+  for (const [id, row] of views) {
+    nodes.set(id, { id, type: "memory", label: (row.title ?? row.text).slice(0, 60), kind: row.kind, tier: row.tier });
+    for (const [other, rel] of [...row.about.map(node => [node, row.kind === "fail" ? "rules_out" : "about"] as const), [`peer:${row.peer}`, "by"], [`machine:${row.machine}`, "by"], [`project:${row.project}`, "in"]]) {
+      nodes.set(other!, { id: other!, type: other!.split(":")[0]!, label: other!.slice(other!.indexOf(":") + 1) }); edges.push({ from: id, to: other!, rel: rel! });
+    }
+    for (const old of row.supersedes) if (views.has(`mem:${old}`)) edges.push({ from: id, to: `mem:${old}`, rel: "supersedes" });
+  }
+  if (!nodes.has(start)) return { nodes: [], edges: [] };
+  const selected = new Set([start]); let frontier = [start];
+  for (let hop = 0; hop < hops; hop++) { const next: string[] = []; for (const id of frontier) for (const edge of edges) { const other = edge.from === id ? edge.to : edge.to === id ? edge.from : undefined; if (other && !selected.has(other) && selected.size < cap) { selected.add(other); next.push(other); } } frontier = next; }
+  return { nodes: [...selected].map(id => nodes.get(id)!), edges: edges.filter(edge => selected.has(edge.from) && selected.has(edge.to)) };
+}

package/src/mcp.ts

@@ -0,0 +1,122 @@
+import { once } from "node:events";
+import type { Readable, Writable } from "node:stream";
+
+const string = (maxLength: number, minLength = 1) => ({ type: "string", minLength, maxLength });
+const limit = { type: "integer", minimum: 1, maximum: 100 };
+const object = (properties: Record<string, unknown>, required: string[] = []) => ({ type: "object", properties, required, additionalProperties: false });
+const tool = <Name extends string>(name: Name, description: string, inputSchema: ReturnType<typeof object>, readOnlyHint = true) => ({ name, description, inputSchema,
+  annotations: { readOnlyHint, destructiveHint: false, openWorldHint: false } });
+
+/** Frozen #13 P2 surface. Storage scope comes from startup, never tool arguments. */
+export const MCP_TOOLS = [
+  tool("amem_search", "Search screened memory in this project. Capture results are recall, not curated evidence.", object({ query: string(1000), limit, since: string(40), includeCapture: { type: "boolean" } }, ["query"])),
+  tool("amem_show", "Show a screened memory entry in this project by its exact id or unique prefix.", object({ id: string(80) }, ["id"])),
+  tool("amem_timeline", "Read screened memory near an entry or time in this project.", object({ id: string(80), since: string(40), limit })),
+  tool("amem_graph", "Read the screened curated-memory neighbourhood. Capture is never graph evidence.", object({ start: string(500), hops: { type: "integer", minimum: 1, maximum: 2 }, limit }, ["start"])),
+  tool("amem_work_state_read", "Read project work lists; closed lists/items can be included explicitly.", object({ list: string(200), includeClosed: { type: "boolean" } })),
+  tool("amem_work_state_write", "Append scalar project work-list fields; null clears, task selects an item, list status done closes.", object({ list: string(200), fields: { type: "object", minProperties: 1, maxProperties: 64,
+    additionalProperties: { type: ["string", "number", "boolean", "null"], maxLength: 4000 } } }, ["list", "fields"]), false),
+  tool("amem_remember", "Propose a general memory candidate for person acceptance. Never writes directly to curated notes.", object({ text: string(3000), title: string(200), kind: { type: "string", enum: ["decision", "finding", "contract", "fail"] } }, ["text"]), false),
+  tool("amem_vault_candidates", "List screened durable curated notes eligible for a person to move to the vault. Read only.", object({ limit })),
+  tool("amem_capacity", "Read this machine's bounded capture capacity proposal; applying it is person-only.", object({})),
+] as const;
+export type McpToolName = typeof MCP_TOOLS[number]["name"];
+export type McpHandlers = Record<McpToolName, (args: Record<string, unknown>) => unknown | Promise<unknown>>;
+export interface McpOptions {
+  input?: Readable;
+  output?: Writable;
+  tools: McpHandlers;
+  close?: () => void | Promise<void>;
+  version?: string;
+}
+const FRAME_BYTES = 65_536, RESULT_BYTES = 262_144;
+const protocols = ["2025-06-18", "2025-03-26", "2024-11-05"];
+const plain = (v: unknown): v is Record<string, unknown> => !!v && typeof v === "object" && !Array.isArray(v) && (Object.getPrototypeOf(v) === Object.prototype || Object.getPrototypeOf(v) === null);
+
+/** The deliberately small schema vocabulary of the nine tools, shared with runtime validation. */
+function valid(value: unknown, raw: unknown): boolean {
+  const s = raw as Record<string, any>, type = value === null ? "null" : Array.isArray(value) ? "array" : typeof value;
+  const types = Array.isArray(s.type) ? s.type : [s.type];
+  if (!types.includes(type) && !(type === "number" && Number.isSafeInteger(value) && types.includes("integer"))) return false;
+  if (s.enum && !s.enum.includes(value)) return false;
+  if (typeof value === "string" && (value.length < (s.minLength ?? 0) || value.length > (s.maxLength ?? FRAME_BYTES) || value.includes("\0"))) return false;
+  if (typeof value === "number" && (!Number.isFinite(value) || value < (s.minimum ?? -Infinity) || value > (s.maximum ?? Infinity))) return false;
+  if (plain(value)) {
+    const keys = Object.keys(value);
+    if (keys.length < (s.minProperties ?? 0) || keys.length > (s.maxProperties ?? 64)) return false;
+    if ((s.required ?? []).some((key: string) => !Object.hasOwn(value, key))) return false;
+    for (const key of keys) {
+      if (["__proto__", "prototype", "constructor"].includes(key) || key.length > 200) return false;
+      if (Object.hasOwn(s.properties ?? {}, key)) { if (!valid(value[key], s.properties[key])) return false; }
+      else if (s.additionalProperties === false || !plain(s.additionalProperties) || !valid(value[key], s.additionalProperties)) return false;
+    }
+  } else if (type === "object") return false;
+  return true;
+}
+
+/** MCP 2025-06-18 basic/transports: newline stdio only. Sequential, bounded, no listener or timer. */
+export async function serveMcp(options: McpOptions): Promise<void> {
+  const input = options.input ?? process.stdin, output = options.output ?? process.stdout;
+  let phase: "new" | "initializing" | "ready" = "new";
+  const send = async (response: unknown) => { if (!output.write(JSON.stringify(response) + "\n")) await once(output, "drain"); };
+  const error = (id: unknown, code: number, message: string) => send({ jsonrpc: "2.0", id, error: { code, message } });
+  const handle = async (line: string) => {
+    let msg: unknown;
+    try { msg = JSON.parse(line); } catch { await error(null, -32700, "Parse error"); return; }
+    if (!plain(msg) || msg.jsonrpc !== "2.0" || typeof msg.method !== "string") { await error(null, -32600, "Invalid request"); return; }
+    if (!Object.hasOwn(msg, "id")) {
+      if (msg.method === "notifications/initialized" && phase === "initializing") phase = "ready";
+      return; // Notifications never invoke a mutating handler.
+    }
+    const id = msg.id;
+    if (!(typeof id === "string" && id.length <= 200 || typeof id === "number" && Number.isSafeInteger(id))) { await error(null, -32600, "Invalid request id"); return; }
+    if (msg.method === "ping") { await send({ jsonrpc: "2.0", id, result: {} }); return; }
+    if (msg.method === "initialize") {
+      if (phase !== "new" || !plain(msg.params) || typeof msg.params.protocolVersion !== "string" || !plain(msg.params.capabilities) || !plain(msg.params.clientInfo)) { await error(id, -32602, "Invalid initialization"); return; }
+      phase = "initializing";
+      await send({ jsonrpc: "2.0", id, result: { protocolVersion: protocols.includes(msg.params.protocolVersion) ? msg.params.protocolVersion : protocols[0],
+        capabilities: { tools: { listChanged: false } }, serverInfo: { name: "amem", version: options.version ?? "unreleased" } } });
+      return;
+    }
+    if (phase !== "ready") { await error(id, -32002, "Initialize the session first"); return; }
+    if (msg.method === "tools/list") {
+      const params = msg.params;
+      if (params !== undefined && params !== null && (!plain(params) || Object.keys(params).some(key => key !== "cursor" && key !== "_meta") || params.cursor !== undefined && params.cursor !== null || params._meta !== undefined && (!plain(params._meta) || Object.keys(params._meta).length > 0))) { await error(id, -32602, "Invalid tool listing arguments"); return; }
+      await send({ jsonrpc: "2.0", id, result: { tools: MCP_TOOLS } }); return;
+    }
+    if (msg.method !== "tools/call") { await error(id, -32601, "Method not found"); return; }
+    const params = msg.params;
+    if (!plain(params) || Object.keys(params).some(k => !["name", "arguments", "_meta"].includes(k)) || typeof params.name !== "string") { await error(id, -32602, "Invalid tool call"); return; }
+    const definition = MCP_TOOLS.find(t => t.name === params.name), args = params.arguments ?? {};
+    if (!definition || !valid(args, definition.inputSchema)) { await error(id, -32602, "Invalid tool name or arguments"); return; }
+    let result: unknown;
+    try {
+      const value = await options.tools[definition.name](args as Record<string, unknown>), text = JSON.stringify(value);
+      if (text === undefined || Buffer.byteLength(text) > RESULT_BYTES) throw new Error("result unavailable");
+      result = { content: [{ type: "text", text }] };
+    } catch { result = { isError: true, content: [{ type: "text", text: "Memory operation unavailable or refused; no partial result is shown." }] }; }
+    await send({ jsonrpc: "2.0", id, result });
+  };
+  let pending = "", overflow = false;
+  const decoder = new TextDecoder("utf-8", { fatal: true });
+  const consume = async (chunk: string) => {
+    let start = 0;
+    for (;;) {
+      const newline = chunk.indexOf("\n", start), part = chunk.slice(start, newline < 0 ? undefined : newline);
+      if (!overflow) {
+        if (Buffer.byteLength(pending) + Buffer.byteLength(part) > FRAME_BYTES) { overflow = true; pending = ""; }
+        else pending += part;
+      }
+      if (newline < 0) return;
+      if (overflow) await error(null, -32600, "Request exceeds the 64 KiB frame bound");
+      else if (pending.trim()) await handle(pending);
+      pending = ""; overflow = false; start = newline + 1;
+    }
+  };
+  try {
+    for await (const chunk of input) await consume(typeof chunk === "string" ? chunk : decoder.decode(chunk, { stream: true }));
+    await consume(decoder.decode());
+    // A truncated frame on EOF is not an accepted request and must never cause a write.
+    if (pending.trim() || overflow) await error(null, -32700, "Incomplete request at EOF");
+  } finally { await options.close?.(); }
+}

package/src/memory/candidates.ts

@@ -14,6 +14,7 @@ export interface CandidateTarget { id: string; revision: string }
 export type CandidateInput = { project: string } & (
   | { kind: "correction"; target: CandidateTarget; proposedText: string; reason: string; noteKind?: "decision" | "contract" | "fail" }
   | { kind: "fail"; target?: CandidateTarget; approach: string; symptom: string; cause: string; evidenceRefs: string[]; retryWhen: string }
+  | { kind: "memory"; text: string; title?: string; noteKind?: "decision" | "finding" | "contract" | "fail" }
   | { kind: "decay"; target: CandidateTarget; reason: string }
 );
 export type CandidateStatus = "pending" | "accepting" | "accepted" | "rejected";
@@ -50,6 +51,8 @@ function validate(input: CandidateInput): void {
     if (!validTarget(input.target) || !text(input.proposedText) || !text(input.reason) || input.noteKind !== undefined && !["decision", "contract", "fail"].includes(input.noteKind)) throw new Error("invalid correction candidate");
   } else if (input.kind === "fail") {
     if (input.target !== undefined && !validTarget(input.target) || ![input.approach, input.symptom, input.cause, input.retryWhen].every(x => text(x)) || !Array.isArray(input.evidenceRefs) || input.evidenceRefs.length < 1 || input.evidenceRefs.length > 16 || !input.evidenceRefs.every(x => text(x, 400))) throw new Error("invalid fail candidate");
+  } else if (input.kind === "memory") {
+    if (!text(input.text, 3000) || input.title !== undefined && !text(input.title, 200) || input.noteKind !== undefined && !["decision", "finding", "contract", "fail"].includes(input.noteKind)) throw new Error("invalid memory candidate");
   } else if (input.kind === "decay") {
     if (!validTarget(input.target) || !text(input.reason)) throw new Error("invalid decay candidate");
   } else throw new Error("invalid candidate kind");
@@ -73,8 +76,13 @@ export class CandidateStore {
   readonly path: string;
   private readonly db: Database;
   private readonly now: () => number;
-  constructor(options: { home?: string; now?: () => number } = {}) {
-    this.dir = options.home === undefined ? memoryHome() : join(options.home, "memory");
+  /** #27: the keys aliased to the canonical project; its candidates read, accept and reject under the canonical key. Absent in the library default. */
+  private readonly reconcile?: { canonical: string; aliases: readonly string[] };
+  private scope(project: string): string { return JSON.stringify(this.reconcile && project === this.reconcile.canonical ? [project, ...this.reconcile.aliases] : [project]); }
+  constructor(options: { home?: string; memoryDir?: string; now?: () => number; reconcile?: { canonical: string; aliases: readonly string[] } } = {}) {
+    if (options.reconcile?.aliases.length) this.reconcile = { canonical: options.reconcile.canonical, aliases: [...options.reconcile.aliases] };
+    if (options.memoryDir !== undefined && options.home !== undefined) throw new Error("choose a home or an exact memory directory");
+    this.dir = options.memoryDir ?? (options.home === undefined ? memoryHome() : join(options.home, "memory"));
     this.now = options.now ?? Date.now;
     mkdirSync(this.dir, { recursive: true, mode: 0o700 }); chmodSync(this.dir, 0o700);
     this.path = join(this.dir, "candidates.db");
@@ -108,15 +116,15 @@ export class CandidateStore {
   get(id: string, project: string): Candidate | undefined {
     if (!candidateId(id) || !text(project, 400)) throw new Error("invalid candidate identity");
     this.prune();
-    const row = this.db.query("SELECT * FROM candidates WHERE id = ? AND project = ?").get(id, project) as Parameters<CandidateStore["decode"]>[0] | null;
+    const row = this.db.query("SELECT * FROM candidates WHERE id = ? AND project IN (SELECT value FROM json_each(?))").get(id, this.scope(project)) as Parameters<CandidateStore["decode"]>[0] | null;
     return row ? this.decode(row) : undefined;
   }
   list(filter: CandidateFilter): Candidate[] {
-    if (!text(filter.project, 400) || filter.status !== undefined && !["pending", "accepting", "accepted", "rejected", "all"].includes(filter.status) || filter.kind !== undefined && !["correction", "fail", "decay"].includes(filter.kind)) throw new Error("invalid candidate filter");
+    if (!text(filter.project, 400) || filter.status !== undefined && !["pending", "accepting", "accepted", "rejected", "all"].includes(filter.status) || filter.kind !== undefined && !["correction", "fail", "decay", "memory"].includes(filter.kind)) throw new Error("invalid candidate filter");
     const limit = filter.limit ?? CANDIDATE_RETENTION.count;
     if (!Number.isSafeInteger(limit) || limit < 1 || limit > CANDIDATE_RETENTION.count) throw new Error("candidate limit must be 1..500");
     this.prune();
-    const where = ["project = ?"], bind: (string | number)[] = [filter.project];
+    const where = ["project IN (SELECT value FROM json_each(?))"], bind: (string | number)[] = [this.scope(filter.project)];
     if (filter.status === undefined) where.push("status IN ('pending', 'accepting')"); else if (filter.status !== "all") { where.push("status = ?"); bind.push(filter.status); }
     if (filter.kind) { where.push("kind = ?"); bind.push(filter.kind); }
     return (this.db.query(`SELECT * FROM candidates WHERE ${where.join(" AND ")} ORDER BY at DESC, rowid DESC LIMIT ?`).all(...bind, limit) as Parameters<CandidateStore["decode"]>[0][]).map(row => this.decode(row));
@@ -133,7 +141,7 @@ export class CandidateStore {
   counters(project: string, entry?: string): Counter[] {
     if (!text(project, 400) || entry !== undefined && !entryId(entry)) throw new Error("invalid counter filter");
     this.prune();
-    const rows = this.db.query("SELECT * FROM counters WHERE project = ? ORDER BY at DESC, rowid DESC").all(project) as { id: string; payload: string; at: number; rendered: number | null; delivered: number | null; cited: number | null }[];
+    const rows = this.db.query("SELECT * FROM counters WHERE project IN (SELECT value FROM json_each(?)) ORDER BY at DESC, rowid DESC").all(this.scope(project)) as { id: string; payload: string; at: number; rendered: number | null; delivered: number | null; cited: number | null }[];
     return rows.map(row => ({ id: row.id, key: JSON.parse(row.payload) as CounterKey, createdAt: new Date(row.at).toISOString(), rendered: row.rendered, delivered: row.delivered, cited: row.cited })).filter(row => !entry || row.key.entryId === entry);
   }
   reject(id: string, context: { project: string; actor: "person" | "agent"; verdict: CandidateVerdict }): void {
@@ -142,12 +150,12 @@ export class CandidateStore {
       const candidate = this.get(id, context.project);
       if (!candidate) throw new Error("candidate unavailable");
       if (candidate.status === "accepted" || candidate.status === "accepting") throw new Error("candidate acceptance already started; inspect its ordinary note before any further action");
-      this.db.query("UPDATE candidates SET status = 'rejected' WHERE id = ? AND project = ? AND status = 'pending'").run(id, context.project);
+      this.db.query("UPDATE candidates SET status = 'rejected' WHERE id = ? AND project IN (SELECT value FROM json_each(?)) AND status = 'pending'").run(id, this.scope(context.project));
     }).immediate();
   }
   accept(id: string, context: CandidateAcceptance): CandidateAcceptanceResult {
     personOnly(context.actor); publicOnly(context.verdict);
-    if (realPath(context.store.dir) !== realPath(this.dir) || typeof context.policy !== "function") throw new Error("candidate acceptance requires its memory store and a current host policy");
+    if (realPath(context.store.profile.home) !== realPath(this.dir) || typeof context.policy !== "function") throw new Error("candidate acceptance requires its memory store and a current host policy");
     return context.store.withDeferredPromotions(() => this.acceptDeferred(id, context));
   }
   private acceptDeferred(id: string, context: CandidateAcceptance): CandidateAcceptanceResult {
@@ -157,21 +165,21 @@ export class CandidateStore {
     if (candidate.status !== "pending") throw new Error("candidate is rejected or acceptance was interrupted; no automatic replay");
     if (candidate.input.kind === "decay") throw new Error("decay candidates are listing-only; no automatic mutation is available");
     const resolve = () => {
-      const target = candidate.input.target;
+      const target = candidate.input.kind === "memory" ? undefined : candidate.input.target;
       if (!target) return undefined;
       const current = context.store.get(target.id, context.project);
       if (!current || current.id !== target.id || candidateTargetRevision(current) !== target.revision) throw new Error("candidate target revision is stale");
       return current;
     };
     const target = resolve(), data = candidate.input;
-    const body = data.kind === "correction" ? `${data.proposedText}\n\nReason: ${data.reason}`
+    const body = data.kind === "memory" ? data.text : data.kind === "correction" ? `${data.proposedText}\n\nReason: ${data.reason}`
       : `Approach: ${data.approach}\nSymptom: ${data.symptom}\nCause: ${data.cause}\nEvidence: ${data.evidenceRefs.join(", ")}\nRetry when: ${data.retryWhen}`;
-    const note: NoteInput = { op: "note", project: data.kind === "correction" ? target!.project : context.project,
+    const note: NoteInput = { op: "note", ...(data.kind === "memory" && data.title ? { title: data.title } : {}), project: data.kind === "correction" ? target!.project : context.project,
       scope: data.kind === "correction" ? target!.scope : "project",
       // A demoted synced target is logically short, but replacing it locally would narrow its reach (X04).
       tier: data.kind === "correction" && target!.local ? "short" : "long",
       kind: data.kind === "fail" ? "fail" : data.noteKind ?? (target?.kind === "contract" || target?.kind === "fail" ? target.kind : "decision"), peer: "person", source: "person", about: [...target?.about ?? []],
-      text: `Accepted candidate: ${id}\nTarget revision: ${data.target?.revision ?? "none"}\nTarget entry: ${data.target?.id ?? "none"}\n\n${body}` };
+      text: `Accepted candidate: ${id}\nTarget revision: ${(data.kind === "memory" ? undefined : data.target)?.revision ?? "none"}\nTarget entry: ${(data.kind === "memory" ? undefined : data.target)?.id ?? "none"}\n\n${body}` };
     if (note.text.length > 4000) throw new Error("accepted candidate text exceeds the v1 note limit");
     if (context.policy(structuredClone(candidate), target && structuredClone(target), structuredClone(note)) !== true) throw new Error("candidate refused by current host policy");
     return context.store.withAcceptedNote(note, append => {
@@ -181,7 +189,7 @@ export class CandidateStore {
         if (!current) throw new Error("candidate unavailable");
         if (current.status === "accepted") return current.acceptedNoteId!;
         if (current.status !== "pending") throw new Error("candidate is rejected or acceptance was interrupted; no automatic replay");
-        this.db.query("UPDATE candidates SET status = 'accepting' WHERE id = ? AND project = ?").run(id, context.project);
+        this.db.query("UPDATE candidates SET status = 'accepting' WHERE id = ? AND project IN (SELECT value FROM json_each(?))").run(id, this.scope(context.project));
         return undefined;
       }).immediate();
       if (started) return { candidateId: id, noteId: started, alreadyAccepted: true };
@@ -189,7 +197,7 @@ export class CandidateStore {
       // automatic replay; add explicit person-audited recovery before offering background acceptance retries.
       const noteId = append();
       if (data.kind === "correction" && !context.store.supersede(target!.id, noteId, "person", context.project)) throw new Error("candidate replacement refused; inspect the accepted note before recovery");
-      this.db.query("UPDATE candidates SET status = 'accepted', note_id = ? WHERE id = ? AND project = ?").run(noteId, id, context.project);
+      this.db.query("UPDATE candidates SET status = 'accepted', note_id = ? WHERE id = ? AND project IN (SELECT value FROM json_each(?))").run(noteId, id, this.scope(context.project));
       return { candidateId: id, noteId, alreadyAccepted: false };
     });
   }

package/src/memory/capacity.ts

@@ -0,0 +1,179 @@
+import { spawnSync } from "node:child_process";
+import { appendFileSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { totalmem } from "node:os";
+import { join } from "node:path";
+import { memoryBase } from "./home.ts";
+import { walkShards } from "./catalog.ts";
+import { captureShardGrowth, captureShardStats, readCaptureConfigFile, CAPTURE_DEFAULT_CAP_MB, CAPTURE_DEFAULT_RETENTION_DAYS, type CaptureConfig } from "./capture.ts";
+
+/**
+ * #13 R7: the capacity advisor. `capacityReport()` reads this machine's load and proposes capture bounds; the
+ * `amem capacity` CLI renders it and `amem capacity apply` writes the home default config after a preview. An
+ * agent may read the proposal through this library function; applying stays person-only at the CLI.
+ *
+ * Proposal rule (owner decision, 2026-10-17): P1 is shrink-only — the proposed cap and retention are the largest
+ * values not exceeding the current ones whose projection stays within the disk-share bound (default 2% of free
+ * space, configurable) and whose measured search and hook readings stay within R2/R3. Growth proposals are a
+ * follow-up after the agent-hub release; growing in P1 is the person's explicit `amem capacity apply --cap-mb N`.
+ * The reason names the binding constraint: `disk-share retention`, `disk-share cap`, `R3 search RSS`, `R2 hook cost`, or `none`.
+ *
+ * Metrics: a small rolling `metrics.jsonl` in the memory home (not a memory log: it is trimmed, never synced).
+ * `scripts/measure-budget.ts` writes only to its synthetic home; the P3 hooks will append real samples per invocation.
+ */
+
+export interface MetricSample { at: string; kind: "hook" | "search"; wallMs?: number; rssMB?: number; idleMB?: number }
+const METRICS_MAX_BYTES = 64 * 1024, METRICS_KEEP = 200;
+
+export function metricsPath(base: string): string {
+  return join(base, "metrics.jsonl");
+}
+
+/** Append samples, trimming the rolling file when it outgrows its bound (newest samples win). */
+export function appendMetrics(base: string, samples: MetricSample[]): void {
+  mkdirSync(base, { recursive: true, mode: 0o700 });
+  const file = metricsPath(base);
+  appendFileSync(file, samples.map((s) => JSON.stringify(s)).join("\n") + "\n", { mode: 0o600 });
+  try {
+    if (statSync(file).size <= METRICS_MAX_BYTES) return;
+    const lines = readFileSync(file, "utf8").split("\n").filter(Boolean).slice(-METRICS_KEEP);
+    writeFileSync(file, lines.join("\n") + "\n", { mode: 0o600 });
+  } catch { /* a trim failure loses nothing: the file simply stays larger */ }
+}
+
+/** The newest samples first-preserved order (oldest to newest); malformed lines are skipped. */
+export function readMetrics(base: string, limit = METRICS_KEEP): MetricSample[] {
+  let lines: string[] = [];
+  try { lines = readFileSync(metricsPath(base), "utf8").split("\n").filter(Boolean); } catch { return []; }
+  const out: MetricSample[] = [];
+  for (const line of lines.slice(-limit)) {
+    try {
+      const s = JSON.parse(line) as MetricSample;
+      if ((s?.kind === "hook" || s?.kind === "search") && typeof s.at === "string") out.push(s);
+    } catch { /* a malformed line is skipped */ }
+  }
+  return out;
+}
+
+const p95 = (samples: number[]): number | null => samples.length ? [...samples].sort((a, b) => a - b)[Math.max(0, Math.ceil(samples.length * 0.95) - 1)]! : null;
+
+function diskReadings(path: string): { freeBytes: number; totalBytes: number } {
+  const df = spawnSync("df", ["-k", path], { encoding: "utf8" });
+  const line = df.stdout?.trim().split("\n").at(-1) ?? "";
+  const fields = line.split(/\s+/);
+  const total = Number(fields[1]), avail = Number(fields[3]);
+  if (df.status !== 0 || !Number.isFinite(total) || !Number.isFinite(avail)) throw new Error(`df could not read ${path}`);
+  return { freeBytes: avail * 1024, totalBytes: total * 1024 };
+}
+
+/** Best-effort memory pressure: macOS `memory_pressure`, Linux `/proc/pressure/memory`; null when neither answers. */
+function memoryPressure(): string | null {
+  if (process.platform === "darwin") {
+    const r = spawnSync("/usr/bin/memory_pressure", [], { encoding: "utf8" });
+    const free = /System-wide memory free percentage:\s*(\d+)%/.exec(r.stdout ?? "")?.[1];
+    if (free !== undefined) return `free ${free}%`;
+    const level = /The system has (?:memory pressure level )?(\w+)/.exec(r.stdout ?? "")?.[1];
+    return level ?? null;
+  }
+  try {
+    const avg10 = /avg10=([\d.]+)/.exec(readFileSync("/proc/pressure/memory", "utf8"))?.[1];
+    return avg10 === undefined ? null : `avg10 ${avg10}`;
+  } catch { return null; }
+}
+
+export interface CapacityReport {
+  at: string;
+  capture: { shards: number; bytes: number; rows: number; rowsPerDay: number; bytesPerDay: number };
+  disk: { freeBytes: number; totalBytes: number };
+  memory: { totalBytes: number; pressure: string | null };
+  metrics: { samples: number; hookP95Ms: number | null; hookRssMB: number | null; searchP95Ms: number | null; searchRssMB: number | null };
+  projected: { days: number; bytes: number };
+  current: CaptureConfig;
+  diskShare: number;
+  proposal: { capMb: number; retentionDays: number; reason: string };
+}
+
+const MB = 1048576, GROWTH_DAYS = 7, PROJECT_DAYS = 30;
+
+export function capacityReport(opts: {
+  home?: string; memoryDir?: string; diskShare?: number; now?: () => number;
+  /** Tests and fixtures inject machine readings; the CLI always uses the native ones. */
+  inject?: { disk?: { freeBytes: number; totalBytes: number }; memoryPressure?: string | null; metrics?: MetricSample[] };
+} = {}): CapacityReport {
+  if (opts.memoryDir !== undefined && opts.home !== undefined) throw new Error("choose a home or an exact memory directory");
+  const base = opts.memoryDir ?? memoryBase(opts.home);
+  mkdirSync(base, { recursive: true, mode: 0o700 }); // a report on a fresh home still needs a path df can read
+  const now = opts.now ?? Date.now;
+  const since = new Date(now() - GROWTH_DAYS * 24 * 3600_000).toISOString();
+  const shards = walkShards(base);
+  let bytes = 0, rows = 0, growthRows = 0, growthBytes = 0;
+  for (const shard of shards) for (const dir of shard.machineDirs) {
+    const total = captureShardStats(dir);
+    rows += total.rows;
+    bytes += total.bytes;
+    const growth = captureShardGrowth(dir, since);
+    growthRows += growth.rows;
+    growthBytes += growth.bytes;
+  }
+  const rowsPerDay = growthRows / GROWTH_DAYS, bytesPerDay = growthBytes / GROWTH_DAYS;
+  const disk = opts.inject?.disk ?? diskReadings(base);
+  const pressure = opts.inject?.memoryPressure !== undefined ? opts.inject.memoryPressure : memoryPressure();
+  const samples = opts.inject?.metrics ?? readMetrics(base);
+  const hookWalls = samples.filter((s) => s.kind === "hook" && typeof s.wallMs === "number").map((s) => s.wallMs!);
+  const hookRss = samples.filter((s) => s.kind === "hook" && typeof s.rssMB === "number").map((s) => s.rssMB!);
+  const searchWalls = samples.filter((s) => s.kind === "search" && typeof s.wallMs === "number").map((s) => s.wallMs!);
+  const searchRss = samples.filter((s) => s.kind === "search" && typeof s.rssMB === "number").map((s) => s.rssMB!);
+  const metrics = { samples: samples.length, hookP95Ms: p95(hookWalls), hookRssMB: p95(hookRss), searchP95Ms: p95(searchWalls), searchRssMB: p95(searchRss) };
+
+  const homeConfig = readCaptureConfigFile(join(base, "capture-config.json"));
+  const current: CaptureConfig = {
+    capMb: homeConfig.capMb ?? CAPTURE_DEFAULT_CAP_MB,
+    retentionDays: homeConfig.retentionDays ?? CAPTURE_DEFAULT_RETENTION_DAYS,
+  };
+  const diskShare = opts.diskShare ?? 0.02;
+  // ponytail: the 2026-10-17 owner decision keeps R6 caps per shard in P1, while the disk-share budget is
+  // machine-wide; #15 T5 (D7) owns the machine-total split. Until then a home with N shards can hold N x cap.
+  const budgetBytes = diskShare * disk.freeBytes;
+  let { capMb, retentionDays } = current;
+  const binding: string[] = [];
+  if (bytesPerDay > 0 && bytesPerDay * retentionDays > budgetBytes) {
+    retentionDays = Math.max(1, Math.floor(budgetBytes / bytesPerDay));
+    binding.push("disk-share retention: steady-state capture at the current growth exceeds the disk-share bound");
+  }
+  if (capMb * MB > budgetBytes) {
+    capMb = Math.max(1, Math.floor(budgetBytes / MB));
+    binding.push("disk-share cap: the cap exceeds the disk-share bound");
+  }
+  if (metrics.searchRssMB !== null && metrics.searchRssMB > 200) {
+    retentionDays = Math.max(1, Math.floor(retentionDays / 2));
+    binding.push("R3 search RSS: measured peak search memory exceeds 200 MB");
+  }
+  if ((metrics.hookRssMB !== null && metrics.hookRssMB > 100) || (metrics.hookP95Ms !== null && metrics.hookP95Ms > 150)) {
+    capMb = Math.max(1, Math.floor(capMb / 2));
+    binding.push("R2 hook cost: measured hook latency or RSS exceeds the budget");
+  }
+  const reason = binding.length ? binding.join("; ") : "none: current bounds fit the disk share and the measured R2/R3 readings";
+  return {
+    at: new Date(now()).toISOString(),
+    capture: { shards: shards.length, bytes, rows, rowsPerDay, bytesPerDay },
+    disk,
+    memory: { totalBytes: totalmem(), pressure },
+    metrics,
+    projected: { days: PROJECT_DAYS, bytes: Math.round(bytes + bytesPerDay * PROJECT_DAYS) },
+    current,
+    diskShare,
+    proposal: { capMb, retentionDays, reason },
+  };
+}
+
+/** The non-JSON rendering of `amem capacity`. */
+export function capacityText(report: CapacityReport): string {
+  const mb = (n: number): string => `${(n / MB).toFixed(1)} MB`;
+  return [
+    `capture: ${report.capture.rows} rows, ${mb(report.capture.bytes)} in ${report.capture.shards} shard(s), +${report.capture.rowsPerDay.toFixed(1)} rows/day, +${mb(report.capture.bytesPerDay)}/day`,
+    `disk: ${mb(report.disk.freeBytes)} free of ${mb(report.disk.totalBytes)}; memory: ${mb(report.memory.totalBytes)} total${report.memory.pressure ? `, pressure ${report.memory.pressure}` : ""}`,
+    `metrics: ${report.metrics.samples} samples (hook p95 ${report.metrics.hookP95Ms?.toFixed(1) ?? "?"} ms, search peak ${report.metrics.searchRssMB?.toFixed(1) ?? "?"} MB)`,
+    `projected capture in ${report.projected.days} days: ${mb(report.projected.bytes)}`,
+    `current: cap ${report.current.capMb} MB, retention ${report.current.retentionDays} days`,
+    `proposal: cap ${report.proposal.capMb} MB, retention ${report.proposal.retentionDays} days (${report.proposal.reason})`,
+  ].join("\n");
+}