@staix/agent-mem 0.22.1 → 0.23.0

package/src/hook-record.ts

@@ -0,0 +1,91 @@
+import { stripPrivateSpans } from "./memory/private-spans.ts";
+
+/** Package-owned instruction, never assembled from captured or configured text. */
+export const RECORD_INSTRUCTION = [
+  "Only when a turn settles a decision, fix, fail or contract, end the final answer with at most 2 records; otherwise none:",
+  "amem: <decision|fix|fail|contract|finding> | <repo/path[#symbol],... or - for decision/contract> | <text, max 300 characters>",
+  "For fix/fail use symptom/cause -> fix/retry-when. No fences, quotes, secrets or PII.",
+].join("\n");
+
+/** Data remains untrusted after the one exact package-owned instruction prefix. */
+export function recordContextData(context: string): string {
+  const prefix = `${RECORD_INSTRUCTION}\n`;
+  return context.startsWith(prefix) ? context.slice(prefix.length) : context;
+}
+
+export const RECORD_INPUT_BYTES = 256 * 1024;
+
+const KINDS = ["decision", "fix", "fail", "contract", "finding"] as const;
+export type RecordKind = typeof KINDS[number];
+export type RecordDropReason = "record_invalid" | "record_count" | "record_length" | "record_policy" | "record_identity" | "record_timestamp";
+export interface ParsedRecord { kind: RecordKind; anchors: string[]; text: string; line: string }
+export interface ParsedRecordTurn { records: ParsedRecord[]; drops: Partial<Record<RecordDropReason, number>>; incomplete?: true }
+const controls = /[\p{Cc}\p{Cf}\p{Zl}\p{Zp}]/u;
+
+/** Lexical repository-relative anchors; deleted paths need no filesystem lookup. */
+function validAnchor(anchor: string): boolean {
+  const parts = anchor.split("#"), path = parts[0]!;
+  if (!path || path.startsWith("/") || path.startsWith("~") || /[\\:|<>*?\[\]{}]/.test(path) || controls.test(anchor)
+    || parts.length > 2 || parts.length === 2 && (!parts[1] || /\s/.test(parts[1]))) return false;
+  return !path.split("/").some(part => !part || part === "." || part === "..");
+}
+
+function recordLine(line: string): ParsedRecord | RecordDropReason {
+  const fields = /^amem: ([^|\s]+) \| ([^|]+) \| (.*)$/.exec(line);
+  if (!fields || controls.test(line)) return "record_invalid";
+  const [, kind, rawAnchors, text] = fields;
+  if (!(KINDS as readonly string[]).includes(kind!) || !text || text !== text.trim()) return "record_invalid";
+  let characters = 0;
+  for (const _character of text) if (++characters > 300) return "record_length";
+  if ((kind === "fix" || kind === "fail") && !/^.+ -> .+$/u.test(text)) return "record_invalid";
+  const anchors = rawAnchors!.split(",").map(anchor => anchor.trim());
+  if (rawAnchors === "-") {
+    if (kind !== "decision" && kind !== "contract") return "record_invalid";
+    anchors.length = 0;
+  } else if (!anchors.every(validAnchor)) return "record_invalid";
+  return { kind: kind as RecordKind, anchors, text, line: `amem: ${kind} | ${anchors.length ? anchors.join(", ") : "-"} | ${text}` };
+}
+
+/** One complete assistant text, including its text blocks; no JSON/model/network/store work. */
+export function parseRecordLines(text: string, shouldStop?: () => boolean): ParsedRecordTurn {
+  const result: ParsedRecordTurn = { records: [], drops: {} };
+  // ponytail: share the native 256 KiB ceiling; larger answers need a bounded streaming parser.
+  if (text.length > RECORD_INPUT_BYTES || Buffer.byteLength(text) > RECORD_INPUT_BYTES) return { records: [], drops: { record_length: 1 } };
+  const drop = (reason: RecordDropReason) => { result.drops[reason] = (result.drops[reason] ?? 0) + 1; };
+  const privateRanges: { start: number; end: number }[] = [];
+  stripPrivateSpans(text, (start, end) => privateRanges.push({ start, end }));
+  let fence: { character: string; length: number } | undefined, quote = false, offset = 0, rangeIndex = 0;
+  for (const chunk of text.split("\n")) {
+    if (shouldStop?.()) { result.incomplete = true; break; }
+    const newline = offset + chunk.length < text.length, line = newline && chunk.endsWith("\r") ? chunk.slice(0, -1) : chunk;
+    const start = offset, end = start + line.length; offset += chunk.length + 1;
+    while (privateRanges[rangeIndex] && privateRanges[rangeIndex]!.end <= start) rangeIndex++;
+    let safeLine = "", cursor = start, hasPrivate = false, privatePrefix = false, endsPrivate = false;
+    for (let index = rangeIndex; privateRanges[index] && privateRanges[index]!.start < end; index++) {
+      const range = privateRanges[index]!;
+      hasPrivate = true; privatePrefix ||= range.start <= start && range.end > start;
+      safeLine += text.slice(cursor, Math.max(cursor, Math.min(range.start, end)));
+      cursor = Math.min(end, Math.max(cursor, range.end));
+      endsPrivate = range.end <= end;
+    }
+    safeLine += text.slice(cursor, end);
+    if (hasPrivate && !safeLine.trim() && !endsPrivate) continue;
+    const marker = /^ {0,3}(`{3,}|~{3,})(.*)$/.exec(safeLine);
+    if (fence) {
+      if (marker && marker[1]![0] === fence.character && marker[1]!.length >= fence.length && !marker[2]!.trim()) fence = undefined;
+      continue;
+    }
+    if (marker && (marker[1]![0] !== "`" || !marker[2]!.includes("`"))) {
+      fence = { character: marker[1]![0]!, length: marker[1]!.length }; quote = false; continue;
+    }
+    if (/^\s*>/.test(safeLine)) { quote = true; continue; }
+    if (quote) { if (!safeLine.trim()) quote = false; continue; }
+    if (hasPrivate) { if (!privatePrefix && line.startsWith("amem:")) drop("record_policy"); continue; }
+    if (!line.startsWith("amem:")) continue;
+    const record = recordLine(line);
+    if (typeof record === "string") drop(record);
+    else if (result.records.length >= 2) drop("record_count");
+    else result.records.push(record);
+  }
+  return result;
+}

package/src/hook-spool-replay.ts

@@ -20,6 +20,7 @@ import { isAbsolute, join } from "node:path";
 import { hookCaptureScope, hookLegacyCaptureScope, hookSpoolReplayInternals as spool, type HookSpoolOwnedFile } from "./hook-spool.ts";
 import { aliasedKeys, resolveAlias } from "./memory/aliases.ts";
 import { CaptureStore, type CaptureInput } from "./memory/capture.ts";
+import { RecordNormalizationRefusal } from "./memory/capture-input.ts";
 import { configuredPolicyOptions } from "./memory/config.ts";
 import { projectState } from "./memory/lifecycle.ts";
 import { canonicalPath, realPath } from "./memory/platform.ts";
@@ -316,7 +317,15 @@ export async function applyHookSpoolReplay(options: { base: string; plan: HookSp
         if (!decoded || decoded.unknown || hash(decoded.bytes) !== record.digest) { retain("decode_changed"); closeSync(claim.fd); held = undefined; continue; }
         // One CaptureStore at a time: close the previous project's store before opening the next one.
         if (storeProject !== record.project) { store?.close(); store = new CaptureStore({ memoryDir: home, project: record.project!, cwd: realPath(record.cwd) }); storeProject = record.project!; }
-        const result = store!.append(captureInput(decoded.value.capture as never, record.project!), { receipt: hash(decoded.bytes) });
+        let result: ReturnType<CaptureStore["append"]>;
+        try { result = store!.append(captureInput(decoded.value.capture as never, record.project!), { receipt: hash(decoded.bytes) }); }
+        catch (error) {
+          if (!(error instanceof RecordNormalizationRefusal) || decoded.value.capture.event !== "Record") throw error;
+          if (spool.retireRecordPolicy(home, claim)) {
+            receipt.retired++; receipt.outcomes.push({ name: record.name, outcome: "skipped", reason: "Record declined by current normalization policy; stage a complete compatible Record before replaying again" });
+          } else retain("claim changed before policy retirement; preview again before applying");
+          closeSync(claim.fd); held = undefined; continue;
+        }
         const spooled = "spooled" in result;
         if (spooled) receipt.spooled++; else receipt.applied++;
         const retired = spool.retireOwned(claim);

package/src/hook-spool.ts

@@ -4,7 +4,8 @@ import { chmodSync, closeSync, constants, fstatSync, lstatSync, mkdirSync, openS
 import { dirname, join, resolve } from "node:path";
 import { homedir } from "node:os";
 import type { CaptureAppend, CaptureInput } from "./memory/capture.ts";
-import { CAPTURE_MAX_EXCERPT, clipCaptureUtf8, normalizeCaptureFields, toolCaptureExcerpt, toolInputLine, type CaptureFields, type NormalizedCaptureFields } from "./memory/capture-input.ts";
+import { parseRecordLines, type ParsedRecord, type RecordDropReason } from "./hook-record.ts";
+import { CAPTURE_MAX_EXCERPT, TRANSCRIPT_CAPTURE_EVENTS, RecordNormalizationRefusal, clipCaptureUtf8, normalizeCaptureFields, toolCaptureExcerpt, toolInputLine, type CaptureFields, type NormalizedCaptureFields } from "./memory/capture-input.ts";
 import { canonicalPath, realPath } from "./memory/platform.ts";
 import { createStandalonePolicy, type StandalonePolicyOptions } from "./memory/policy.ts";
 import { configuredPolicyOptions, loadAmemConfig, repoConfigRoot } from "./memory/config.ts";
@@ -33,7 +34,12 @@ export const hookReplayBudget = (): HookReplayBudget => ({ files: HOOK_REPLAY_MA
 const CAPACITY_FILES = 32, CAPACITY_BYTES = 256 * 1024;
 const namePattern = /^(hook-(?:v[23]-)?([a-f0-9]{64})-([a-f0-9]{64})-([a-f0-9]{32})\.json)(?:\.draining-[a-f0-9]{24})?$/;
 const hash = (value: string | Uint8Array) => createHash("sha256").update(value).digest("hex");
-const summaryEvent = (event: string) => ["Title", "Recap", "Compact"].includes(event);
+const summaryEvent = (event: string) => TRANSCRIPT_CAPTURE_EVENTS.includes(event);
+function recordCapture(input: Pick<CaptureFields, "excerpt" | "paths">): ParsedRecord | undefined {
+  const parsed = parseRecordLines(input.excerpt ?? ""), record = parsed.records[0];
+  return record !== undefined && parsed.records.length === 1 && !Object.keys(parsed.drops).length && record.line === input.excerpt
+    && JSON.stringify(record.anchors) === JSON.stringify(input.paths ?? []) ? record : undefined;
+}
 interface Record { schema: string; format?: number; cwd: string; scope: string | null; root?: string; nonce: string; capture: NormalizedCaptureFields }
 export interface PendingHookCapture { name: string; cwd: string; receipt: string; deferred?: true; backlog?: true }
 export class HookSpoolFull extends Error { constructor() { super("hook storage full"); } }
@@ -379,9 +385,10 @@ function decoded(file: OwnedFile): { value: Record; bytes: Buffer; unknown?: tru
     const c = value.capture;
     if (!c || typeof c !== "object" || Array.isArray(c) || Object.keys(c).length < 8 || Object.keys(c).length > 10
       || Object.keys(c).some(key => !["at", "agent", "event", "tool", "paths", "status", "excerpt", "bytes", "session", "subagent"].includes(key))
-      || !(HOOK_AGENTS as readonly string[]).includes(c.agent) || (c.agent === "claude" && !["Title", "Recap", "Compact"].includes(c.event)) === v3 || ![...HOOK_EVENTS, "Title", "Recap", "Compact"].includes(c.event)
+      || !(HOOK_AGENTS as readonly string[]).includes(c.agent) || (c.agent === "claude" && !TRANSCRIPT_CAPTURE_EVENTS.includes(c.event)) === v3 || ![...HOOK_EVENTS, ...TRANSCRIPT_CAPTURE_EVENTS].includes(c.event)
       || typeof c.at !== "string" || !Number.isFinite(Date.parse(c.at)) || typeof c.excerpt !== "string"
       || !Array.isArray(c.paths) || c.paths.some(path => typeof path !== "string")) return undefined;
+    if (c.event === "Record" && (c.agent !== "claude" || c.subagent === true || !recordCapture(c))) return undefined;
     const normalized = normalizeCaptureFields({ agent: c.agent, event: c.event, at: c.at, paths: c.paths, excerpt: c.excerpt,
       ...(c.tool === null ? {} : { tool: c.tool }), ...(c.status === null ? {} : { status: c.status }),
       ...(c.session === undefined ? {} : { session: c.session }), ...(c.subagent === undefined ? {} : { subagent: c.subagent }) });
@@ -447,6 +454,13 @@ function retireClaim(base: string, file: OwnedFile, preserve: boolean, batch?: Q
   return true;
 }
 
+/** Reuse the existing body-free policy quarantine; refused Records must not monopolize replay slots. */
+function retireRecordPolicy(base: string, file: OwnedFile): boolean {
+  if (!owns(file)) return false;
+  appendMetrics(base, [{ at: new Date().toISOString(), kind: "hook", captureDrops: 1, captureDropReason: "record_policy" }]);
+  return retireClaim(base, file, true);
+}
+
 const RETIRE_AFTER_MS = 7 * 24 * 3600_000, MISSING_CWD_AFTER_MS = 3600_000;
 interface MaintenanceBudget { files: number; bytes: number }
 const maintenanceBudget = (): MaintenanceBudget => ({ files: DRAIN_FILES, bytes: DRAIN_BYTES });
@@ -689,23 +703,35 @@ export async function stageHookCapture(event: string, input: unknown, options: O
 }
 
 /** Transcript text is screened in full before caps, then shares the ordinary durable spool. */
-export async function stageTranscriptCapture(input: CaptureFields, options: Options, receiptIdentity?: string): Promise<PendingHookCapture | undefined> {
-  if (options.policy?.host || belowFloor(options.base) || input.agent !== "claude" || !["Title", "Recap", "Compact"].includes(input.event)) return;
+export async function stageTranscriptCapture(input: CaptureFields, options: Options, receiptIdentity?: string, onRecordDrop?: (reason: RecordDropReason) => void): Promise<PendingHookCapture | undefined> {
+  if (options.policy?.host || belowFloor(options.base) || !TRANSCRIPT_CAPTURE_EVENTS.includes(input.event) || input.agent !== "claude" && !(input.agent === "jcode" && (input.event === "Title" || input.event === "Compact"))) return;
   const cwd = realPath(options.cwd), base = canonicalPath(options.base);
   const policy = createStandalonePolicy(configuredPolicyOptions(base, cwd, options.policy));
-  if (!await policy.screen({ cwd, input })) return;
+  const record = input.event === "Record";
+  if (!record && !await policy.screen({ cwd, input })) return;
   const configured = loadAmemConfig(base, repoConfigRoot(cwd)).config;
+  if (record && (configured.records === false || input.subagent === true)) return;
+  if (record) {
+    if (typeof input.at !== "string" || !Number.isFinite(Date.parse(input.at))) { onRecordDrop?.("record_timestamp"); return; }
+    if (stripPrivateSpans(input.excerpt ?? "") !== input.excerpt) { onRecordDrop?.("record_policy"); return; }
+    const line = recordCapture(input);
+    if (!line) { onRecordDrop?.("record_invalid"); return; }
+    if (stripPrivateSpans(line.line) !== line.line
+      || !await policy.screen({ cwd, input, paths: line.anchors.map(anchor => anchor.split("#")[0]!) })) { onRecordDrop?.("record_policy"); return; }
+    if (Buffer.byteLength(line.line) > Math.min(CAPTURE_MAX_EXCERPT, configured.excerptBytes ?? CAPTURE_MAX_EXCERPT)) { onRecordDrop?.("record_length"); return; }
+  }
   const capture = normalizeCaptureFields({ ...input, excerpt: clipCaptureUtf8(stripPrivateSpans(input.excerpt ?? ""), Math.min(CAPTURE_MAX_EXCERPT, configured.excerptBytes ?? CAPTURE_MAX_EXCERPT)) }, undefined,
     text => looksSecret(text) || configured.piiPatterns.some(pattern => fold(text).includes(fold(pattern))),
     { excerptBytes: configured.excerptBytes, paths: configured.capturePaths, denyPaths: configured.denyPaths });
-  if (capture.excerpt === "[secret-screened]" || !await policy.screen({ cwd, capture })) return;
+  if (record && (capture.excerpt !== input.excerpt || JSON.stringify(capture.paths) !== JSON.stringify(input.paths ?? []))) { onRecordDrop?.("record_policy"); return; }
+  if (capture.excerpt === "[secret-screened]" || !await policy.screen({ cwd, capture })) { if (record) onRecordDrop?.("record_policy"); return; }
   return publishCapture(input.event, capture, { ...options, cwd, base }, hash(receiptIdentity === undefined ? JSON.stringify(capture) : JSON.stringify([capture, receiptIdentity])).slice(0, 32));
 }
 
 function publishCapture(event: string, capture: NormalizedCaptureFields, options: Options, nonce = randomBytes(16).toString("hex")): PendingHookCapture {
   const { cwd, base } = options;
   const scope = hookCaptureScope(cwd, base) ?? null;
-  const v3 = capture.agent !== "claude" || ["Title", "Recap", "Compact"].includes(event);
+  const v3 = capture.agent !== "claude" || TRANSCRIPT_CAPTURE_EVENTS.includes(event);
   const record: Record = { schema: FAMILY, format: v3 ? FORMAT_V3 : FORMAT, cwd, scope, root: physicalRoot(cwd), nonce, capture }, bytes = JSON.stringify(record);
   if (Buffer.byteLength(bytes) > RECORD_BYTES) throw new Error("hook record bound");
   const dir = directory(base), writing = join(dir, ".writing"); privateDirectory(dir); privateDirectory(writing);
@@ -715,7 +741,7 @@ function publishCapture(event: string, capture: NormalizedCaptureFields, options
   const withinShare = (rows: ReturnType<typeof entries>, maximum: number) => rows.filter(row => namePattern.exec(row.name)?.[2] === cwdHash).length < maximum / 4;
   const name = `${v3 ? PREFIX_V3 : PREFIX}${cwdHash}-${scope ?? "0".repeat(64)}-${nonce}.json`;
   let activeInventory: ReturnType<typeof entries> | undefined, reserveInventory: ReturnType<typeof entries> | undefined;
-  if (["Title", "Recap", "Compact"].includes(event)) {
+  if (TRANSCRIPT_CAPTURE_EVENTS.includes(event)) {
     // Transcript cursor recovery can repeat a deterministic publication. An already
     // durable identical body needs no new slot, including when a drainer owns it.
     for (const capacity of [false, true]) {
@@ -856,7 +882,13 @@ export async function drainHookCaptures(options: Options & { project: string; ex
         ...(c.session === undefined ? {} : { session: c.session }), ...(c.subagent === undefined ? {} : { subagent: c.subagent }) };
       if (!await policy.screen(value) || !await policy.screen(input)) { retireClaim(base, claim, true); blocked++; continue; }
       if (!owns(claim) || hookCaptureScope(cwd, base) !== stamp || value.scope === legacyStamp && captureScope(cwd, base, false, undefined, true) !== legacyStamp) { blocked++; continue; }
-      append(input, hash(record.bytes));
+      try {
+        append(input, hash(record.bytes));
+      }
+      catch (error) {
+        if (!(error instanceof RecordNormalizationRefusal) || input.event !== "Record") throw error;
+        retireRecordPolicy(base, claim); blocked++; continue;
+      }
       if (owns(claim)) { rmSync(claim.file); captured.push(name); }
       else blocked++;
     } catch { blocked++; } // Transient failure keeps the unique claim for a later idempotent retry.
@@ -875,6 +907,7 @@ export const hookSpoolReplayInternals = {
   owns: (file: OwnedFile) => owns(file),
   decoded: (file: OwnedFile) => decoded(file),
   belowFloor: (base: string) => belowFloor(base),
+  retireRecordPolicy: (base: string, file: OwnedFile) => retireRecordPolicy(base, file),
   /** Claim under a caller-chosen deterministic suffix (#217 decision B: hash(plan digest, publication)), never a random one. */
   claimAs(file: OwnedFile, name: string, suffix: string): OwnedFile | undefined {
     const match = namePattern.exec(name);

package/src/hook-transcript.ts

@@ -1,16 +1,18 @@
+import { parseRecordLines, RECORD_INPUT_BYTES, type ParsedRecordTurn, type RecordDropReason } from "./hook-record.ts";
+import { stripPrivateSpans } from "./memory/private-spans.ts";
 import { assertFormatFloor } from "./memory/formats.ts";
 import { Database } from "bun:sqlite";
 import { createHash } from "node:crypto";
 import { chmodSync, closeSync, constants, fstatSync, lstatSync, mkdirSync, openSync, readSync } from "node:fs";
 import { join } from "node:path";
 import { canonicalPath, realPath } from "./memory/platform.ts";
-import { configuredPolicyOptions } from "./memory/config.ts";
+import { configuredPolicyOptions, loadAmemConfig, repoConfigRoot } from "./memory/config.ts";
 import { createStandalonePolicy, type StandalonePolicyOptions } from "./memory/policy.ts";
 import { HookSpoolFull, stageTranscriptCapture, type PendingHookCapture } from "./hook-spool.ts";
 import { appendMetrics } from "./memory/metrics.ts";
 import type { HookTranscriptProgress } from "./hook-contract.ts";
 
-export const HOOK_TRANSCRIPT_BYTES = 256 * 1024;
+export const HOOK_TRANSCRIPT_BYTES = RECORD_INPUT_BYTES;
 const hash = (value: string) => createHash("sha256").update(value).digest("hex");
 type SummaryEvent = "Title" | "Recap" | "Compact";
 interface Cursor { offset: number; dev: string; ino: string; size: number; title: string; at: string; readStart: number; readAt: string; skipping: number }
@@ -40,6 +42,25 @@ export function transcriptSummary(line: string): { event: SummaryEvent; text: st
   return { event, text: visibleText, ...(timestamp(row.timestamp) ? { at: timestamp(row.timestamp)! } : {}), ...(row.isSidechain === true || typeof row.agentId === "string" && row.agentId.length > 0 ? { subagent: true as const } : {}) };
 }
 
+/** Only Claude main-session assistant text is a record source. Check the marker before parsing JSON. */
+export function transcriptRecords(line: string, shouldStop?: () => boolean): { messageId?: string; at?: string; parsed: ParsedRecordTurn } | undefined {
+  if (!line.includes("amem:")) return;
+  const row = object(JSON.parse(line));
+  if (!row || row.type !== "assistant" || row.isSidechain === true || typeof row.agentId === "string" && row.agentId.length > 0) return;
+  const message = object(row.message);
+  if (!message || message.role !== undefined && message.role !== "assistant") return;
+  const content = message.content;
+  const text = typeof content === "string" ? content : Array.isArray(content)
+    ? content.flatMap(part => { const value = object(part); return value?.type === "text" && typeof value.text === "string" ? [value.text] : []; }).join("\n") : undefined;
+  if (text === undefined || !stripPrivateSpans(text).includes("amem:")) return;
+  const messageId = typeof message.id === "string" && message.id.length > 0 && message.id.length <= 256 && message.id.trim() === message.id
+    && !/[\p{Cc}\p{Cf}\p{Zl}\p{Zp}]/u.test(message.id) ? message.id : undefined;
+  if (!messageId) return { parsed: { records: [], drops: { record_identity: 1 } } };
+  const at = timestamp(row.timestamp);
+  if (!at) return { parsed: { records: [], drops: { record_timestamp: 1 } } };
+  return { messageId, at, parsed: parseRecordLines(text, shouldStop) };
+}
+
 /** Read only a top-level timestamp token, without parsing ordinary message bodies. */
 function transcriptTimestamp(line: string): string | undefined {
   if (!line.includes('"timestamp"')) return;
@@ -62,13 +83,13 @@ function transcriptTimestamp(line: string): string | undefined {
   return at;
 }
 
-function privateDirectory(dir: string): void {
+export function privateDirectory(dir: string): void {
   mkdirSync(dir, { recursive: true, mode: 0o700 });
   const stat = lstatSync(dir);
   if (!stat.isDirectory() || stat.isSymbolicLink()) throw new Error("transcript cursor unavailable");
   chmodSync(dir, 0o700);
 }
-function cursorDatabase(file: string, dev: string, ino: string, size: number): Database {
+export function cursorDatabase(file: string, dev: string, ino: string, size: number): Database {
   const fd = openSync(file, constants.O_CREAT | constants.O_RDWR | constants.O_NOFOLLOW | constants.O_NONBLOCK, 0o600);
   try {
     const stat = fstatSync(fd), named = lstatSync(file);
@@ -103,6 +124,8 @@ export async function scanHookTranscriptTail(input: unknown, options: Options):
   if (value.cwd !== undefined && (typeof value.cwd !== "string" || realPath(value.cwd) !== cwd)) return;
   const policy = createStandalonePolicy(configuredPolicyOptions(base, cwd, options.policy));
   if (!await policy.screen(value)) return;
+  const recordsEnabled = loadAmemConfig(base, repoConfigRoot(cwd)).config.records !== false
+    && !(typeof value.agent_id === "string" && value.agent_id.length > 0);
   const session = hash(`amem-session\0${value.session_id}`).slice(0, 16);
   if (lstatSync(value.transcript_path).isSymbolicLink()) throw new Error("transcript unavailable");
   const transcript = realPath(value.transcript_path);
@@ -133,6 +156,11 @@ export async function scanHookTranscriptTail(input: unknown, options: Options):
     const after = fstatSync(fd), live = lstatSync(value.transcript_path);
     if (length !== bytes.length || after.size < stat.size || live.dev !== stat.dev || live.ino !== stat.ino || realPath(value.transcript_path) !== transcript) return;
     let start = 0, stopReason: HookTranscriptProgress["stopReason"];
+    // ponytail: the two-record cap is per native message.id within this scan only; no durable count.
+    // A crash after staging but before cursor save has the summaries' duplicate window.
+    // Upgrade to a msgid+ordinal receipt if the AC6 live week demonstrates duplicates.
+    const recordCounts = new Map<string, number>(), recordDrops: Partial<Record<RecordDropReason, number>> = {};
+    const dropRecord = (reason: RecordDropReason, count = 1) => { recordDrops[reason] = (recordDrops[reason] ?? 0) + count; };
     const workStart = performance.now();
     // The caller's deadline is read live (a caller may move it); the work budget only adds an earlier end after setup.
     const due = () => performance.now() >= options.deadline || options.workBudgetMs !== undefined && performance.now() - workStart >= options.workBudgetMs;
@@ -155,6 +183,36 @@ export async function scanHookTranscriptTail(input: unknown, options: Options):
       let line: string;
       try { line = new TextDecoder("utf-8", { fatal: true }).decode(bytes.subarray(start, newline)); }
       catch { start = newline + 1; continue; }
+      let records: ReturnType<typeof transcriptRecords>;
+      if (recordsEnabled) try { records = transcriptRecords(line, due); } catch { /* Malformed native JSON is not a record source. */ }
+      // Privacy flags and policy metadata belong to the source row, not just its extracted text.
+      if (records && !await policy.screen(JSON.parse(line))) { dropRecord("record_policy", Math.max(1, records.parsed.records.length)); records = undefined; }
+      let recordPublication: PendingHookCapture | undefined;
+      if (records) {
+        for (const [reason, count] of Object.entries(records.parsed.drops)) dropRecord(reason as RecordDropReason, count!);
+        if (records.parsed.incomplete) { stopReason = "deadline"; break; }
+        if (records.messageId && records.at) for (const record of records.parsed.records) {
+          const count = recordCounts.get(records.messageId) ?? 0;
+          if (count >= 2) { dropRecord("record_count"); continue; }
+          recordCounts.set(records.messageId, count + 1);
+          if (due()) { stopReason = "deadline"; break; }
+          const publish = () => stageTranscriptCapture({ agent: "claude", event: "Record", excerpt: record.line, paths: record.anchors,
+            at: records!.at, session }, { cwd, base, policy: options.policy, deferAtCapacity: true }, undefined, dropRecord);
+          try {
+            let staged: PendingHookCapture | undefined;
+            try { staged = await publish(); }
+            catch (error) {
+              if (!(error instanceof HookSpoolFull) || due() || !options.onBackpressure || !await options.onBackpressure() || due()) throw error;
+              staged = await publish();
+            }
+            if (staged) recordPublication = staged;
+          } catch (error) {
+            if (error instanceof HookSpoolFull) { stopReason = "spool_full"; break; }
+            throw error;
+          }
+        }
+        if (stopReason) break;
+      }
       let summary: ReturnType<typeof transcriptSummary>;
       try { summary = transcriptSummary(line); } catch { /* Malformed native JSON is not capture. */ }
       if (summary && !await policy.screen(JSON.parse(line))) summary = undefined;
@@ -192,9 +250,15 @@ export async function scanHookTranscriptTail(input: unknown, options: Options):
       // Carry timestamps without parsing ordinary messages (including across invocation boundaries).
       const at = transcriptTimestamp(line); if (at) cursor.at = at;
       start = newline + 1;
+      // Stage the whole row before optional replay. A slow replay must not restart
+      // its first Record forever; the remaining durable publications replay later.
+      if (recordPublication && !due()) await options.onPublication?.(recordPublication);
     }
     if (!stopReason && start < length && due()) stopReason = "deadline";
     if (!stopReason && cursor.offset + start < stat.size && length === HOOK_TRANSCRIPT_BYTES) stopReason = "cap";
+    if (Object.keys(recordDrops).length) appendMetrics(base, Object.entries(recordDrops).map(([reason, count]) => ({
+      at: new Date().toISOString(), kind: "hook", captureDrops: count!, captureDropReason: reason as RecordDropReason,
+    })));
     assertFormatFloor(base, "hook-spool");
     db.query("UPDATE cursor SET offset=?,dev=?,ino=?,size=?,title=?,at=?,skipping=? WHERE id=1").run(cursor.offset + start, String(stat.dev), String(stat.ino), stat.size, cursor.title, cursor.at, cursor.skipping);
     db.run("COMMIT");

package/src/hooks.ts

@@ -1,3 +1,5 @@
+import { homedir } from "node:os";
+import { RECORD_INSTRUCTION } from "./hook-record.ts";
 import { fileURLToPath } from "node:url";
 import { resolveHookProjectAsync, type HookProjectReceipt } from "./hook-project.ts";
 import { hookProcessSignature, type HookNativeUsage } from "./hook-native.ts";
@@ -6,7 +8,7 @@ import { combineRssSources, countedRssSources, emptyRssSources, hookRssReading,
 import { HookWorkerRss } from "./hook-rss-wire.ts";
 import { appendMetrics, captureDropSummary } from "./memory/metrics.ts";
 import { stageHookCapture, drainHookCaptures, hookCaptureScope, quarantineHookScope, HookSpoolFull, type HookAgent, type PendingHookCapture } from "./hook-spool.ts";
-import { jcodeHookCapture } from "./hook-jcode.ts";
+import { jcodeHookCapture, jcodeJournalTarget } from "./hook-jcode.ts";
 import { memoryHome } from "./memory/home.ts";
 import { canonicalPath, realPath } from "./memory/platform.ts";
 import { createStandalonePolicy, type MemoryPolicy, type StandalonePolicyOptions } from "./memory/policy.ts";
@@ -58,6 +60,12 @@ function joinedContext(context: string, notice: string, maximum: number): string
   return Buffer.byteLength(fallback) <= maximum ? fallback : "";
 }
 
+function instructionCost(context: string): { recordInstructionBytes: number; recordInstructionEstimatedTokens: number } {
+  const bytes = context.startsWith(`${RECORD_INSTRUCTION}\n`) ? Buffer.byteLength(RECORD_INSTRUCTION) + 1 : 0;
+  // Approximation only: the UTF-8 byte count is exact; tokens depend on the host tokenizer.
+  return { recordInstructionBytes: bytes, recordInstructionEstimatedTokens: Math.ceil(bytes / 4) };
+}
+
 async function before<T>(work: Promise<T>, deadline: number): Promise<T | undefined> {
   const safe = work.catch(() => undefined);
   const remaining = deadline - performance.now();
@@ -227,13 +235,17 @@ async function hookWorker(options: HookOptions, base: string, deadline: number,
 }
 
 /** SessionStart shared pieces: the numeric capture-loss notice and the native byte ceiling. */
-function sessionNoticeAndLimit(base: string, cwd: string, options: HookOptions, currentDropped: boolean): { dropNotice: string; contextLimit: number } {
+function sessionNoticeAndLimit(base: string, cwd: string, options: HookOptions, currentDropped: boolean, header = unavailable): { dropNotice: string; contextLimit: number; instruction: string } {
   const losses = captureDropSummary(base);
   if (currentDropped) losses.spool_full = (losses.spool_full ?? 0) + 1;
-  const dropNotice = Object.entries(losses).map(([reason, count]) => `capture dropped: ${reason.replaceAll("_", " ")} (${count})`).join("; ");
-  const configuredBrief = loadAmemConfig(base, repoConfigRoot(cwd)).config.briefBytes;
+  // Record parsing refusals remain observable metrics, but are not lost captures.
+  const dropNotice = Object.entries(losses).filter(([reason]) => !reason.startsWith("record_")).map(([reason, count]) => `capture dropped: ${reason.replaceAll("_", " ")} (${count})`).join("; ");
+  const config = loadAmemConfig(base, repoConfigRoot(cwd)).config;
+  const configuredBrief = config.briefBytes;
   const contextLimit = Math.min(HOOK_CONTEXT_BYTES, configuredBrief ?? HOOK_CONTEXT_BYTES, Math.max(1, Number.isFinite(options.maxTokens) ? Math.floor(options.maxTokens!) : HOOK_CONTEXT_BYTES));
-  return { dropNotice, contextLimit };
+  const prefix = `${RECORD_INSTRUCTION}\n`;
+  const instruction = config.records !== false && Buffer.byteLength(prefix) + Buffer.byteLength(header) + Buffer.byteLength(dropNotice) + (dropNotice ? 1 : 0) <= contextLimit ? prefix : "";
+  return { dropNotice, contextLimit: contextLimit - Buffer.byteLength(instruction), instruction };
 }
 
 /** SessionStart spends one Bun boot on context. Capture remains durable/pending;
@@ -249,8 +261,9 @@ async function sessionInParent(input: unknown, options: HookOptions, base: strin
   if (remaining() <= 0) { result.dropped = !pending; return result; }
   if (sessionSource(input) === "resume") {
     try {
-      const { dropNotice, contextLimit } = sessionNoticeAndLimit(base, cwd, options, !pending);
-      result.context = joinedContext(RESUME_HEADER, dropNotice, contextLimit);
+      const { dropNotice, contextLimit, instruction } = sessionNoticeAndLimit(base, cwd, options, !pending, RESUME_HEADER);
+      const context = joinedContext(RESUME_HEADER, dropNotice, contextLimit);
+      result.context = context ? instruction + context : "";
       result.valid = result.context.length > 0;
     } catch { /* fail open: no context */ }
     result.dropped = !pending;
@@ -278,12 +291,13 @@ async function sessionInParent(input: unknown, options: HookOptions, base: strin
     if (remaining() <= 0) return result;
     // The current SessionStart is durable in its bounded reserve. All replay and
     // retirement belong to a later non-SessionStart hook, never this brief deadline.
-    const { dropNotice, contextLimit } = sessionNoticeAndLimit(base, cwd, options, !pending);
+    const { dropNotice, contextLimit, instruction } = sessionNoticeAndLimit(base, cwd, options, !pending);
     const brief = await sessionStartBrief({ ...options, maxTokens: Math.max(1, contextLimit - Buffer.byteLength(dropNotice) - (dropNotice ? 1 : 0)), cwd, base, project, nativeSession: { signature }, projectFromCwd: true, timeRemaining: remaining });
     result.pending = !!pending && !result.captured;
     result.dropped = !pending;
     if (hookCaptureScope(cwd, base) !== scope || !await createStandalonePolicy(configuredPolicyOptions(base, cwd, options.policy)).screen({ context: brief.context })) return result;
-    result.context = joinedContext(brief.context, dropNotice, contextLimit);
+    const context = joinedContext(brief.context, dropNotice, contextLimit);
+    result.context = context ? instruction + context : "";
     result.valid = result.context.length > 0;
     return result;
   } catch { result.dropped = !pending; return result; }
@@ -333,6 +347,7 @@ export async function runHook(event: string, input: unknown, options: HookOption
   let base: string | undefined, captured = false, childRssKB = 0, childRawRssKB = 0, pending = false, dropped = false;
   let childSources = emptyRssSources();
   let transcriptProgress: HookTranscriptProgress | undefined;
+  let emittedCost = instructionCost("");
   try {
     base = canonicalPath(options.base ?? memoryHome());
     if (!(HOOK_EVENTS as readonly string[]).includes(event)) return { captured, ...(pending ? { pending: true as const } : {}), ...(dropped ? { dropped: true as const, dropReason: "spool_full" as const, dropCount: 1 } : {}), skipped: true };
@@ -346,10 +361,11 @@ export async function runHook(event: string, input: unknown, options: HookOption
     if (!result.valid) return { captured, ...(pending ? { pending: true as const } : {}), ...(dropped ? { dropped: true as const, dropReason: "spool_full" as const, dropCount: 1 } : {}), skipped: true };
     if (event !== "SessionStart") return { captured, ...(pending ? { pending: true as const } : {}), ...(dropped ? { dropped: true as const, dropReason: "spool_full" as const, dropCount: 1 } : {}), skipped: false };
     if (!await publicBefore(policy, { context: result.context }, deadline)) return { captured, ...(pending ? { pending: true as const } : {}), ...(dropped ? { dropped: true as const, dropReason: "spool_full" as const, dropCount: 1 } : {}), skipped: false };
+    emittedCost = instructionCost(result.context);
     return { captured, ...(pending ? { pending: true as const } : {}), ...(dropped ? { dropped: true as const, dropReason: "spool_full" as const, dropCount: 1 } : {}), skipped: false, output: { hookSpecificOutput: { hookEventName: "SessionStart", additionalContext: result.context } } };
   } catch { return { captured, ...(pending ? { pending: true as const } : {}), ...(dropped ? { dropped: true as const, dropReason: "spool_full" as const, dropCount: 1 } : {}), skipped: true }; }
   finally {
-    if (base) try { const self = hookRssReading(); appendMetrics(base, [{ at: new Date().toISOString(), kind: "hook", wallMs: performance.now() - started,
+    if (base) try { const self = hookRssReading(); appendMetrics(base, [{ at: new Date().toISOString(), kind: "hook", wallMs: performance.now() - started, ...emittedCost,
       rssMB: (self.kb + childRssKB) / 1024, rssSources: combineRssSources(rssSource(self), countedRssSources(childRssKB, childSources)), rssScope: "owned-images", rawRssMB: (process.resourceUsage().maxRSS + childRawRssKB) / 1024,
       ...(transcriptProgress ? { transcriptOffset: transcriptProgress.offset, transcriptStopReason: transcriptProgress.stopReason } : {}), ...(abandonedChildren ? { abandonedChildren } : {}), ...(drainSkipped ? { drainSkipped } : {}), ...(lastDrain ? { drainStartMs: lastDrain.startMs, drained: lastDrain.drained } : {}), ...(dropped ? { captureDrops: 1, captureDropReason: "spool_full" as const } : {}) }]); } catch { /* Metrics never change the native tool outcome. */ }
   }
@@ -363,11 +379,19 @@ export async function hookMain(args: readonly string[], startedAt = performance.
   let childRssKB = 0, childRawRssKB = 0, dropped = false;
   let childSources = emptyRssSources();
   let transcriptProgress: HookTranscriptProgress | undefined;
+  let emittedCost = instructionCost("");
   try {
     if (args.length !== 1) return "";
     if (args[0] === "jcode") {
       // #203: jcode observers have no stdin and discard stdout; the event and its cwd arrive in the environment.
       const jcode = jcodeHookCapture(process.env);
+      // #216: title and compaction summaries from the session journal's meta, before the turn's own capture so its drain commits them.
+      // Bounded (256 KiB, 40 ms work, never past the handler deadline) and fail open: a fault here never drops ordinary capture.
+      const target = jcodeJournalTarget(process.env, homedir());
+      if (target) try {
+        const { scanJcodeJournal } = await import("./hook-jcode-journal.ts");
+        transcriptProgress = await scanJcodeJournal(target, { base: canonicalPath(memoryHome()), workBudgetMs: 40, deadline: startedAt + deadlineMs - 50 }) ?? transcriptProgress;
+      } catch { transcriptProgress = { stopReason: "unavailable" }; }
       if (!jcode) return "";
       const result = await captureAndWork(jcode.event, jcode.input, { cwd: jcode.cwd, agent: "jcode" }, canonicalPath(memoryHome()), startedAt + deadlineMs - 3);
       if (result) { childRssKB = result.rssKB; childRawRssKB = result.rawRssKB; childSources = result.rssSources ?? emptyRssSources(); dropped = "dropped" in result && result.dropped === true; }
@@ -392,6 +416,7 @@ export async function hookMain(args: readonly string[], startedAt = performance.
       childRssKB = result.rssKB; childRawRssKB = result.rawRssKB; childSources = result.rssSources ?? emptyRssSources(); dropped = "dropped" in result && result.dropped === true;
       transcriptProgress = "transcript" in result ? result.transcript : undefined;
       if (!result.valid || args[0] !== "SessionStart") return "";
+      emittedCost = instructionCost(result.context);
       return JSON.stringify({ hookSpecificOutput: { hookEventName: "SessionStart", additionalContext: result.context } });
     }
     return "";
@@ -400,7 +425,7 @@ export async function hookMain(args: readonly string[], startedAt = performance.
     await cleanup?.();
     try {
       const self = hookRssReading();
-      appendMetrics(canonicalPath(memoryHome()), [{ at: new Date().toISOString(), kind: "hook", wallMs: performance.now() - startedAt,
+      appendMetrics(canonicalPath(memoryHome()), [{ at: new Date().toISOString(), kind: "hook", wallMs: performance.now() - startedAt, ...emittedCost,
         rssMB: (self.kb + childRssKB) / 1024, rssSources: combineRssSources(rssSource(self), countedRssSources(childRssKB, childSources)), rssScope: "owned-images", rawRssMB: (process.resourceUsage().maxRSS + childRawRssKB) / 1024,
         ...(transcriptProgress ? { transcriptOffset: transcriptProgress.offset, transcriptStopReason: transcriptProgress.stopReason } : {}), ...(abandonedChildren ? { abandonedChildren } : {}), ...(drainSkipped ? { drainSkipped } : {}), ...(lastDrain ? { drainStartMs: lastDrain.startMs, drained: lastDrain.drained } : {}), ...(dropped ? { captureDrops: 1, captureDropReason: "spool_full" as const } : {}) }]);
     } catch { /* Invalid input and unavailable homes still fail open. */ }

package/src/index.ts

@@ -78,3 +78,7 @@ export { readSyncPlacementWriterRoots } from "./memory/sync-placement-writer-roo
 export { readEffectiveSyncPlacementWriters, readEffectiveSyncPlacementWriterRoots } from "./memory/sync-placement-effective-writers.ts";
 export type { EffectiveSyncPlacementWriters } from "./memory/sync-placement-effective-writers.ts";
 export { readSetupWriterRoots, SetupWriterRootsError } from "./setup.ts";
+
+export { parseRecordLines, RECORD_INSTRUCTION, type ParsedRecord, type ParsedRecordTurn, type RecordKind, type RecordDropReason } from "./hook-record.ts";
+export { createPlacementAttestation, PlacementWriterContextError } from "./sync-placement-writer-context.ts";
+export type { PlacementWriterRootCategory, PlacementWriterContextPhase } from "./sync-placement-writer-context.ts";

package/src/memory/capture-input.ts

@@ -4,6 +4,15 @@ import { stripPrivateSpans } from "./private-spans.ts";
 
 export const CAPTURE_MAX_EXCERPT = 2000;
 export const CAPTURE_MAX_PATHS = 32;
+/** Claude transcript-only events use the existing format-3 transport, never native hook argv. */
+export const TRANSCRIPT_CAPTURE_EVENTS: readonly string[] = ["Title", "Recap", "Compact", "Record"];
+/** A whole-Record policy refusal, distinct from transient storage failures. No receipt or row was written. */
+export class RecordNormalizationRefusal extends Error {
+  constructor() {
+    super("Record capture would be changed by current caps or screening; check amem.config.json or CaptureStore options, then stage a complete Record that fits the current policy");
+    this.name = "RecordNormalizationRefusal";
+  }
+}
 export const TOOL_INPUT_LINE_BYTES = 512;
 const TOOL_INPUT_ORDER = ["command", "pattern", "query", "url", "description", "prompt", "skill", "subject"] as const;
 const TOOL_INPUT_OMIT = new Set(["content", "old_string", "new_string", "edits"]);
@@ -66,7 +75,7 @@ export function normalizeCaptureFields(input: CaptureFields, now: () => number =
   const at = new Date(input.at === undefined ? now() : Date.parse(input.at)).toISOString();
   const tool = str(input.tool, 64) ? input.tool! : null;
   const status = str(input.status, 64) ? input.status! : null;
-  const paths = (input.paths ?? []).map(String).filter((p) => p && !isDenied(p, caps.denyPaths ? [...caps.denyPaths] : [])).slice(0, maxPaths).map((p) => p.slice(0, 400));
+  const paths = (input.paths ?? []).map(String).filter((p) => p && !isDenied(input.event === "Record" ? p.split("#")[0]! : p, caps.denyPaths ? [...caps.denyPaths] : [])).slice(0, maxPaths).map((p) => p.slice(0, 400));
   // `<private>` spans go first: they are never screened, counted or stored. The cap applies to what is left.
   let excerpt = stripPrivateSpans(input.excerpt ?? "").slice(0, maxExcerpt);
   if (excerpt && screen(excerpt)) excerpt = "[secret-screened]";