@remnic/core 9.45.5 → 9.46.1

package/src/ambient-provenance.ts

@@ -0,0 +1,229 @@
+/**
+ * Ambient-capture provenance for extraction (issue #2294).
+ *
+ * Always-on capture devices — wearable recorders, room microphones — hand the
+ * extraction engine speech the user never authored: television and film
+ * dialogue, podcasts, radio, music with spoken segments, and conversations the
+ * user merely walked past. The extraction prompt otherwise reads every turn as
+ * first-person user input, so a scripted line about a relative's birthday or a
+ * medical diagnosis lands as a high-confidence personal fact and auto-promotes
+ * into recall. That output is plausible, personally relevant, and wrong, which
+ * makes it materially worse than a missed fact.
+ *
+ * This module owns both halves of the fix:
+ *
+ * 1. The prompt text that teaches the model to separate the user's own speech
+ *    from background media, drop high-consequence personal claims it cannot
+ *    attribute to the user, and score the remainder speculatively. One source
+ *    of truth, shared by the cloud, direct-client, and local-LLM prompts so the
+ *    three paths cannot drift.
+ * 2. A deterministic backstop — `clampAmbientCaptureConfidence` — for when the
+ *    model ignores the prompt anyway. It clamps ONLY high-impact personal facts
+ *    (family, milestones, medical) to the speculative ceiling. Clamping every
+ *    ambient fact would gut the wearable integration, which is explicitly not
+ *    the goal; clamping this class costs a birthday landing in the review queue
+ *    instead of active recall.
+ *
+ * The provenance signal itself is `BufferTurn.ambientCapture`, set by the
+ * ingesting subsystem (the wearable memory pass), never by tool arguments.
+ */
+
+import type { ExtractionResult } from "./types.js";
+
+/**
+ * Upper bound of the speculative confidence tier, matching the tier table in
+ * the extraction prompt ("Speculative (0.00-0.39)"). A fact at or below this
+ * value cannot auto-promote through the wearable trust bands.
+ */
+export const SPECULATIVE_CONFIDENCE_CEILING = 0.39;
+
+/**
+ * Appended to the speculative tier definition when the input is ambient
+ * capture, so the tier itself carries the rule rather than relying on the
+ * separate section below being obeyed in isolation.
+ */
+export const AMBIENT_SPECULATIVE_TIER_CLAUSE =
+  " Speculative also applies to any fact whose only evidence is ambient or background audio from an always-on capture device, even when the content is concrete and specific.";
+
+/**
+ * Full provenance section for the cloud and direct-client extraction prompts.
+ */
+export const AMBIENT_CAPTURE_PROMPT_SECTION = `
+Source provenance — always-on capture audio:
+- This transcript came from an always-on capture device (a wearable recorder or room microphone). It may contain audio the user did not author: television, film, podcasts, radio, advertisements, music with spoken segments, and conversations the user merely overheard or walked past.
+- Separate the user's own speech from background media before extracting anything. Narrative, scripted, performed, or third-person speech — a show's dialogue, a podcast host, an ad read, a lecture playing in the room — is media, not user input. Never attribute it to the user or to anyone the user knows.
+- High-consequence personal claims must be dropped entirely unless the user's own voice is clearly identifiable as their source: family relationships, personal milestones (births, birthdays, anniversaries, weddings, funerals, divorces), and any medical or health detail. Omit them; do not emit them at reduced confidence as a compromise.
+- When you cannot tell whether a statement was spoken by the user or captured passively, skip it or set its confidence in the speculative tier (0.00-0.39). Never resolve that doubt upward.`;
+
+/**
+ * Compact variant for the local-LLM prompt, which is deliberately small to fit
+ * 4k-8k context windows.
+ */
+export const AMBIENT_CAPTURE_PROMPT_SECTION_COMPACT = `
+Ambient capture:
+- This transcript came from an always-on capture device and may contain TV, film, podcast, music, or overheard speech the user did not author.
+- Treat narrative, scripted, or third-person speech as media, not user input.
+- Drop family, milestone (birth, birthday, anniversary, wedding, funeral), and medical claims unless the user's own voice is clearly the source.
+- Otherwise, when unsure whether the user said it, set confidence in the speculative tier (0.00-0.39).`;
+
+/**
+ * Single rule for prompts that already have their own rule list and only need
+ * the ambient warning (the meeting scribe, whose transcript is the same
+ * wearable audio).
+ */
+export const AMBIENT_CAPTURE_PROMPT_RULE =
+  "- The transcript may contain ambient audio nobody in the meeting authored: television, podcasts, music, or a passing conversation. Treat scripted, performed, or third-person speech as background media and never record it as a decision, commitment, or question.";
+
+/**
+ * Categories that are personal-claim-shaped by construction, independent of any
+ * vocabulary: `moment` is defined as an emotionally significant event or
+ * milestone, and on ambient audio a `relationship` claim is a link the model
+ * inferred between people it overheard. Non-lexical, so they still catch harm
+ * the term lists below miss.
+ */
+const HIGH_IMPACT_CATEGORIES: Record<string, true> = { moment: true, relationship: true };
+
+/**
+ * Kinship, milestone, and health vocabulary. Deliberately broad: a false
+ * positive costs one ambient fact a trip through the review queue, a false
+ * negative puts a fabricated medical claim into active recall. The list cannot
+ * be exhaustive and is not the primary defense — the prompt is, and the
+ * category signal above plus the trust-band cap in the wearable pass catch
+ * classes no word list enumerates. Extend it when a miss is observed.
+ *
+ * Word-bounded alternation only — no nesting, no backtracking risk.
+ */
+const HIGH_IMPACT_TOPIC_PATTERN =
+  /\b(?:mother|mothers|mom|moms|mum|father|fathers|dad|dads|sister|sisters|brother|brothers|son|sons|daughter|daughters|wife|wives|husband|husbands|spouse|fiance|fiancee|grandmother|grandfather|grandma|grandpa|grandparent|grandparents|grandson|granddaughter|grandchild|grandchildren|aunt|uncle|cousin|niece|nephew|stepmother|stepfather|stepson|stepdaughter|stepchild|godmother|godfather|birthday|birthdays|anniversary|anniversaries|wedding|weddings|honeymoon|married|marriage|divorce|divorced|widow|widowed|funeral|memorial service|engagement party|baby shower|christening|bar mitzvah|pregnant|pregnancy|miscarriage|miscarried|newborn|gave birth|stillbirth|infertility|ivf|menopause|diagnosis|diagnosed|prognosis|tested positive|cancer|carcinoma|leukemia|tumor|tumour|biopsy|chemotherapy|chemo|radiation therapy|remission|hospice|palliative|terminal illness|surgery|surgeon|hospital|hospitalized|hospitalised|icu|emergency room|ambulance|stroke|heart attack|cardiac|arrhythmia|afib|seizure|epilepsy|asthma|allergy|allergic|diabetes|diabetic|insulin|cholesterol|blood pressure|hypertension|dementia|alzheimer|alzheimers|parkinson|parkinsons|hiv|aids diagnosis|medication|medications|prescription|prescribed|dosage|symptom|symptoms|illness|disease|disorder|syndrome|therapy|therapist|psychiatrist|psychologist|antidepressant|depression|anxiety|bipolar|schizophrenia|adhd|autism|ptsd|overdose|relapse|sobriety|rehab|addiction|alcoholism|concussion|transplant|dialysis|immunocompromised|mental health|covid|covid-19|coronavirus|flu|influenza|pneumonia|bronchitis|infection|infected|fever|migraine|ulcer|hernia|appendicitis|sepsis|sick leave|urgent care|broken leg|broken arm|broken wrist|broken hip|broken rib|broken ribs|sprained|dislocated|torn ligament|torn acl|whiplash|burn unit|chronic pain|disability|wheelchair|hearing aid|blind in|vaccinated|vaccination|immunization|blood test|scan results|mri|ct scan|x-ray|deaf|deafness|blind|blindness|mute|nonverbal|paralyzed|paralysed|paraplegic|quadriplegic|amputee|amputation|prosthetic|multiple sclerosis|lupus|crohn|celiac|fibromyalgia|cystic fibrosis|sickle cell|cerebral palsy|down syndrome|muscular dystrophy|chronic fatigue|chronic illness|terminally ill|life support|coma|special needs|caregiver|nursing home|assisted living|treatment|treatments|in treatment|medical leave|oncologist|cardiologist|neurologist|pediatrician|pediatric|als|copd|epilepsy|seizures|hospitalization|infirm|frail|bedridden|home health|physical therapy|occupational therapy|speech therapy)\b/i;
+
+/**
+ * Bodily-harm and affliction SHAPES rather than nouns: "broke her leg", "tore
+ * his ACL", "caught something at the office". A vocabulary of conditions can
+ * never be complete, so this matches the sentence form instead — a verb of
+ * injury or contagion pointed at a person's POSSESSION. Articles are excluded
+ * on purpose: "the build broke the deploy pipeline" is not an injury.
+ */
+const AFFLICTION_SHAPE_PATTERN =
+  /\b(?:broke|broken|fractured|sprained|dislocated|tore|torn|bruised|burned|scalded|injured|hurt)\s+(?:his|her|their|my|your|our)\s+\w+|\b(?:caught|contracted|came down with|is recovering from|was rushed to|passed away|died of|died from)\b/i;
+
+/**
+ * Words that are personal only when someone possesses them: "child process",
+ * "parent component", "sibling node", and "customer family" are everyday
+ * technical speech, while "his child" and "Rachel's parents" are not.
+ */
+const POSSESSED_KINSHIP_PATTERN =
+  /(?:\b(?:my|your|his|her|their|our)|'s)\s+(?:child|children|kid|kids|parent|parents|partner|family|sibling|siblings|in-law|in-laws|relatives)\b/i;
+
+/** Tags that mark a fact as belonging to the same high-impact classes. */
+const HIGH_IMPACT_TAGS: Record<string, true> = {
+  disability: true,
+  family: true,
+  health: true,
+  medical: true,
+  medication: true,
+  diagnosis: true,
+  birthday: true,
+  anniversary: true,
+  marriage: true,
+  pregnancy: true,
+  "mental-health": true,
+};
+
+/**
+ * True when this claim is personal in a way whose fabrication causes real
+ * harm — a family relationship, a personal milestone, or a medical detail.
+ *
+ * Read by every ambient guard: the post-extraction confidence clamp below, the
+ * wearable trust-band cap, and the meeting trust-band cap. A fact this flags
+ * can never auto-approve, on any path, however the boosts add up.
+ *
+ * Takes the shape rather than `ExtractedFact` so meeting candidates — which
+ * carry no tags — pass without a synthetic empty array.
+ *
+ * `personRefs` comes from `collectPersonEntityRefs` over the same extraction:
+ * pass it whenever the entity list is available, so personhood is read from
+ * the extractor's own `type: "person"` metadata instead of inferred from how
+ * it happened to spell the ref.
+ */
+export function isHighImpactPersonalFact(
+  fact: {
+    category: string;
+    content: string;
+    tags?: readonly string[];
+    entityRef?: string;
+  },
+  personRefs?: ReadonlySet<string>,
+): boolean {
+  // The strongest non-lexical signal: a claim ABOUT A PERSON is high-impact
+  // whatever condition, relationship, or milestone the sentence names. This is
+  // what covers wording no list anticipates ("Dana is deaf").
+  if (isPersonRef(fact.entityRef, personRefs)) return true;
+  if (HIGH_IMPACT_CATEGORIES[fact.category] === true) return true;
+  if (HIGH_IMPACT_TOPIC_PATTERN.test(fact.content)) return true;
+  if (AFFLICTION_SHAPE_PATTERN.test(fact.content)) return true;
+  if (POSSESSED_KINSHIP_PATTERN.test(fact.content)) return true;
+  for (const tag of fact.tags ?? []) {
+    if (HIGH_IMPACT_TAGS[tag.trim().toLowerCase()] === true) return true;
+  }
+  return false;
+}
+
+/**
+ * Normalize an entity reference for comparison: casefold, strip a leading
+ * type prefix, and collapse separators. `Person-Jane_Doe`, `person:jane-doe`,
+ * and `jane doe` all reduce to `jane-doe`.
+ */
+function normalizeEntityRef(ref: string): string {
+  return ref
+    .trim()
+    .toLowerCase()
+    .replace(/^(?:person|people)[-:_\s]+/, "")
+    .replace(/[\s_]+/g, "-");
+}
+
+/**
+ * Names of every `type: "person"` entity in an extraction, normalized for
+ * lookup. Personhood is the extractor's own metadata, not a guess from the
+ * shape of `entityRef` — the prompt asks for `person-jane-doe` but the field is
+ * optional and models routinely emit a bare `jane-doe`.
+ */
+export function collectPersonEntityRefs(result: {
+  entities: ReadonlyArray<{ name: string; type: string }>;
+}): ReadonlySet<string> {
+  const refs = new Set<string>();
+  for (const entity of result.entities) {
+    if (entity.type !== "person") continue;
+    const normalized = normalizeEntityRef(entity.name);
+    if (normalized.length > 0) refs.add(normalized);
+  }
+  return refs;
+}
+
+/** True when this ref names a person, by metadata or by explicit prefix. */
+function isPersonRef(ref: string | undefined, personRefs?: ReadonlySet<string>): boolean {
+  if (ref === undefined || ref.trim().length === 0) return false;
+  if (/^(?:person|people)[-:_]/i.test(ref.trim())) return true;
+  return personRefs !== undefined && personRefs.has(normalizeEntityRef(ref));
+}
+
+/**
+ * Deterministic backstop applied after extraction on ambient-capture input:
+ * hold high-impact personal facts at or below the speculative ceiling so they
+ * cannot auto-promote to active recall on a model's unsupported confidence.
+ *
+ * Returns the input unchanged when nothing needs clamping, so the non-ambient
+ * path pays one predicate per fact and allocates nothing.
+ */
+export function clampAmbientCaptureConfidence(
+  result: ExtractionResult,
+): ExtractionResult {
+  let clampedAny = false;
+  const personRefs = collectPersonEntityRefs(result);
+  const facts = result.facts.map((fact) => {
+    if (fact.confidence <= SPECULATIVE_CONFIDENCE_CEILING) return fact;
+    if (!isHighImpactPersonalFact(fact, personRefs)) return fact;
+    clampedAny = true;
+    return { ...fact, confidence: SPECULATIVE_CONFIDENCE_CEILING };
+  });
+  return clampedAny ? { ...result, facts } : result;
+}

package/src/buffer-turn-helpers.ts

@@ -9,6 +9,18 @@ export interface BufferTurnOwner {
   sessionOwnerPrincipal?: string;
 }
 
+export interface AmbientCaptureProvenance {
+  /**
+   * True when this turn's content came from an always-on ambient capture
+   * device (a wearable recorder, a room microphone) and may therefore carry
+   * speech the user never authored: TV, podcasts, music, overheard
+   * conversation (issue #2294). Set by the ingesting subsystem, never from
+   * tool arguments — extraction reads it to warn the model about media audio
+   * and to clamp high-impact personal facts to the speculative tier.
+   */
+  ambientCapture?: boolean;
+}
+
 export function describeError(err: unknown): string {
   if (err instanceof Error) return err.message;
   if (err === null) return "null";
@@ -46,6 +58,9 @@ export function copyBufferTurn(turn: BufferTurn): BufferTurn {
   if (typeof turn.sourceConnector === "string") {
     copy.sourceConnector = turn.sourceConnector;
   }
+  if (typeof turn.ambientCapture === "boolean") {
+    copy.ambientCapture = turn.ambientCapture;
+  }
   return copy;
 }
 
@@ -61,7 +76,8 @@ export function bufferTurnsEqual(left: BufferTurn | undefined, right: BufferTurn
     left.providerThreadId === right.providerThreadId &&
     left.turnFingerprint === right.turnFingerprint &&
     left.persistProcessedFingerprint === right.persistProcessedFingerprint &&
-    left.sourceConnector === right.sourceConnector
+    left.sourceConnector === right.sourceConnector &&
+    left.ambientCapture === right.ambientCapture
   );
 }
 

package/src/compat/checks.test.ts

@@ -154,7 +154,11 @@ test("memory prompt section registration must be on the plugin api object", asyn
 
   const hookCheck = checkById(checks, "hook-registration-core");
   assert.equal(hookCheck.level, "error");
-  assert.match(hookCheck.message, /before_prompt_build|before_agent_start/);
+  assert.match(hookCheck.message, /before_prompt_build/);
+  assert.doesNotMatch(
+    `${hookCheck.message} ${hookCheck.remediation ?? ""}`,
+    /before_agent_start/,
+  );
 });
 
 test("memory prompt section registration on api satisfies recall hook requirement", async () => {
@@ -173,6 +177,46 @@ test("memory prompt section registration on api satisfies recall hook requiremen
   assert.equal(hookCheck.level, "ok");
 });
 
+test("memory prompt section remediation requests only missing required hooks", async () => {
+  const checks = await runFixture({
+    enginesNode: ">=22.12.0",
+    currentNodeVersion: "v22.12.0",
+    indexSource: [
+      "api.registerService({ start: async () => {} });",
+      "api.registerMemoryPromptSection(() => null);",
+      "registerCli(api, orchestrator);",
+    ].join("\n"),
+  });
+
+  const hookCheck = checkById(checks, "hook-registration-core");
+  assert.equal(hookCheck.level, "error");
+  assert.match(`${hookCheck.message} ${hookCheck.remediation ?? ""}`, /agent_end/);
+  assert.doesNotMatch(
+    `${hookCheck.message} ${hookCheck.remediation ?? ""}`,
+    /before_prompt_build|before_agent_start|gateway_start/,
+  );
+});
+
+test("memory prompt section remediation requests startup only when absent", async () => {
+  const checks = await runFixture({
+    enginesNode: ">=22.12.0",
+    currentNodeVersion: "v22.12.0",
+    indexSource: [
+      "api.on('agent_end', async () => {});",
+      "api.registerMemoryPromptSection(() => null);",
+      "registerCli(api, orchestrator);",
+    ].join("\n"),
+  });
+
+  const hookCheck = checkById(checks, "hook-registration-core");
+  assert.equal(hookCheck.level, "error");
+  assert.match(`${hookCheck.message} ${hookCheck.remediation ?? ""}`, /startup wiring/);
+  assert.doesNotMatch(
+    `${hookCheck.message} ${hookCheck.remediation ?? ""}`,
+    /before_prompt_build|before_agent_start/,
+  );
+});
+
 test("service start detection ignores nested start properties", async () => {
   const checks = await runFixture({
     enginesNode: ">=22.12.0",

package/src/compat/checks.ts

@@ -4,8 +4,7 @@ import type { CompatCheckOptions, CompatCheckResult, CompatReport, CompatRunner
 import { compareVersions } from "../version-utils.js";
 import { launchProcess } from "../runtime/child-process.js";
 
-const REQUIRED_HOOKS_LEGACY = ["before_agent_start", "agent_end"];
-const REQUIRED_HOOKS_NEW = ["before_prompt_build", "agent_end"];
+const REQUIRED_HOOKS = ["before_prompt_build", "agent_end"];
 const OPENCLAW_REMNIC_PLUGIN_ID = "openclaw-remnic";
 const OPENCLAW_REMNIC_LEGACY_PLUGIN_ID = "openclaw-engram";
 
@@ -698,22 +697,16 @@ export async function runCompatChecks(options: CompatCheckOptions): Promise<Comp
     const indexRaw = await readFile(indexPath, "utf-8");
     const structuralSource = stripCommentsAndStrings(indexRaw);
     const hooks = parseHookRegistrations(indexRaw);
-    const missingLegacy = REQUIRED_HOOKS_LEGACY.filter((hook) => !hooks.has(hook));
-    const missingNew = REQUIRED_HOOKS_NEW.filter((hook) => !hooks.has(hook));
+    const missingHooks = REQUIRED_HOOKS.filter((hook) => !hooks.has(hook));
     // registerMemoryPromptSection is a valid alternative to the recall hook only
     // when it is registered on the OpenClaw plugin API object.
     const hasMemoryPromptSection = hasMemoryPromptSectionRegistration(structuralSource);
-    const missingLegacyAdj = hasMemoryPromptSection
-      ? missingLegacy.filter((h) => h !== "before_agent_start")
-      : missingLegacy;
-    const missingNewAdj = hasMemoryPromptSection
-      ? missingNew.filter((h) => h !== "before_prompt_build")
-      : missingNew;
-    // Accept whichever hook set has fewer missing entries
-    const missingHooks = missingNewAdj.length <= missingLegacyAdj.length ? missingNewAdj : missingLegacyAdj;
+    const missingRequiredHooks = hasMemoryPromptSection
+      ? missingHooks.filter((hook) => hook !== "before_prompt_build")
+      : missingHooks;
     const hasGatewayStartHook = hooks.has("gateway_start");
     const hasServiceStart = hasServiceStartRegistration(structuralSource);
-    if (missingHooks.length === 0 && (hasGatewayStartHook || hasServiceStart)) {
+    if (missingRequiredHooks.length === 0 && (hasGatewayStartHook || hasServiceStart)) {
       checks.push({
         id: "hook-registration-core",
         title: "Core hook registration",
@@ -722,18 +715,25 @@ export async function runCompatChecks(options: CompatCheckOptions): Promise<Comp
       });
     } else {
       const missingParts: string[] = [];
-      if (missingHooks.length > 0) {
-        missingParts.push(`hooks: ${missingHooks.join(", ")}`);
+      if (missingRequiredHooks.length > 0) {
+        missingParts.push(`hooks: ${missingRequiredHooks.join(", ")}`);
       }
       if (!hasGatewayStartHook && !hasServiceStart) {
         missingParts.push("startup wiring: gateway_start hook or api.registerService({ start })");
       }
+      const remediationParts: string[] = [];
+      if (missingRequiredHooks.length > 0) {
+        remediationParts.push(`registers ${missingRequiredHooks.join(", ")}`);
+      }
+      if (!hasGatewayStartHook && !hasServiceStart) {
+        remediationParts.push("registers gateway_start or api.registerService({ start })");
+      }
       checks.push({
         id: "hook-registration-core",
         title: "Core hook registration",
         level: "error",
         message: `Missing expected registration(s): ${missingParts.join("; ")}`,
-        remediation: "Ensure src/index.ts registers before_prompt_build (or before_agent_start) and agent_end, plus either gateway_start or api.registerService({ start }).",
+        remediation: `Ensure src/index.ts ${remediationParts.join(" and ")}.`,
       });
     }
 

package/src/extraction-prompt.ts

@@ -0,0 +1,142 @@
+/**
+ * Extraction prompt construction (issue #1995 sibling extraction).
+ *
+ * The system prompt, its JSON response shape, and the placeholder table
+ * derived from that shape are prompt DATA, not engine behavior. They live here
+ * so `extraction.ts` holds the pipeline and one module owns the text every
+ * extraction path — local LLM, direct client, gateway fallback — sends.
+ */
+
+import { AMBIENT_CAPTURE_PROMPT_SECTION, AMBIENT_SPECULATIVE_TIER_CLAUSE } from "./ambient-provenance.js";
+import { resolveMemoryLifecycleCapabilities, resolveRecallAuxiliaryCapabilities } from "./capabilities.js";
+import type { PluginConfig } from "./types.js";
+
+export const EXTRACTION_RESPONSE_SHAPE = `{
+  "facts": [{
+    "category": "<category>",
+    "content": "<source-grounded statement>",
+    "confidence": 0.0,
+    "tags": ["<tag>"],
+    "entityRef": "<optional normalized-name>",
+    "promptedByQuestion": "<optional source-grounded question>",
+    "quote": "<optional exact contiguous source span>",
+    "scope": "<optional project-or-global>",
+    "structuredAttributes": {"<key>": "<value>"},
+    "procedureSteps": [{"order": 1, "intent": "<step>"}, {"order": 2, "intent": "<step>"}],
+    "reasoningTrace": {
+      "steps": [{"order": 1, "description": "<step>"}, {"order": 2, "description": "<step>"}],
+      "finalAnswer": "<answer>",
+      "observedOutcome": "<optional outcome>"
+    },
+    "eventTime": "<optional source temporal expression>"
+  }],
+  "entities": [{
+    "name": "<normalized-name>",
+    "type": "<entity-type>",
+    "facts": ["<source-grounded statement>"],
+    "promptedByQuestion": "<optional source-grounded question>",
+    "structuredSections": [{"key": "<section-key>", "title": "<section-title>", "facts": ["<source-grounded statement>"]}]
+  }],
+  "profileUpdates": ["<source-grounded profile update>"],
+  "questions": [{"question": "<source-grounded unresolved question>", "context": "<source-grounded context>", "priority": 0.0}],
+  "identityReflection": "<conversation-grounded agent reflection>",
+  "relationships": [{"source": "<normalized-name>", "target": "<normalized-name>", "label": "<source-grounded relationship>"}]
+}`;
+export const EXTRACTION_RESPONSE_PLACEHOLDERS: Record<string, true> = {};
+for (const placeholder of EXTRACTION_RESPONSE_SHAPE.match(/<[^<>\r\n]+>/g) ?? []) {
+  EXTRACTION_RESPONSE_PLACEHOLDERS[placeholder] = true;
+}
+
+/**
+ * Bi-temporal event-time extraction instruction (#1578 PR2). Emitted on
+ * every extraction entry path when `temporal.biTemporal` is on so the LLM
+ * emits an optional per-fact `eventTime` expression. The expression is
+ * resolved against the source turn timestamp at write time — never
+ * wall-clock — so replay/import of old transcripts anchors correctly.
+ * Returns an empty string when the gate is off (byte-identical prompt).
+ */
+export function eventTimePromptInstruction(config: PluginConfig): string {
+  if (!config.temporalBiTemporal) return "";
+  return `
+When a fact states when it became or stopped being true, copy that explicit temporal expression verbatim into "eventTime". Omit "eventTime" when no such expression appears; never infer dates.`;
+}
+
+/**
+ * Build extraction instructions shared between local and cloud LLM.
+ *
+ * `ambientCapture` marks input from an always-on recorder, which may carry
+ * speech the user never authored (issue #2294).
+ */
+export function buildExtractionInstructions(config: PluginConfig, existingEntities?: string[], ambientCapture = false): string {
+  const lifecycleCaps = resolveMemoryLifecycleCapabilities(config);
+  return `You are a memory extraction system. Analyze the following conversation and extract durable, reusable memories.
+
+Memory categories:
+- fact: Objective information about the world
+- preference: User likes, dislikes, or stylistic choices
+- correction: User correcting a mistake or misconception (highest priority)
+- entity: Information about a specific person, project, tool, or company
+- decision: A choice that was made with rationale
+- relationship: How two entities relate to each other (e.g., "Alice is Bob's manager", "Acme Corp uses Shopify")
+- principle: Durable rules, values, or operating beliefs (e.g., "never use Chat Completions API")
+- commitment: Promises, obligations, or deadlines (e.g., "deploy by Friday", "call accountant Monday")
+- moment: Emotionally significant events or milestones (e.g., "first successful deployment of engram")
+- skill: Capabilities the user or agent has demonstrated (e.g., "user is proficient with Kubernetes")${resolveRecallAuxiliaryCapabilities(config).causalRuleExtraction ? `
+- rule: Causal rules discovered through experience (format: "IF <condition> THEN <action/outcome>", e.g., "IF Shopify API returns 401 THEN the admin token is missing read_products scope")` : ""}
+- procedure: A reusable workflow the user wants remembered the same way across sessions. Set category to "procedure". Use "content" for a short title that includes explicit trigger phrasing (e.g. "When you deploy to production…", "Whenever you ship a release…"). Add "procedureSteps": an array of at least two objects {"order": number, "intent": "concrete step description"} in execution order. Optional per-step "toolCall": {"kind": "…", "signature": "…"}, "expectedOutcome", "optional": true.
+- reasoning_trace: A stored solution chain / chain-of-thought the user walked through to solve a problem (e.g. "Here's how I debugged the latency spike: first I checked…, then I…, finally I…"). Set category to "reasoning_trace". Use "content" for a short title summarising the problem (e.g. "How I debugged the staging latency spike"). Add "reasoningTrace": {"steps": [{"order": number, "description": "what happened at this step"}, …], "finalAnswer": "the conclusion or answer", "observedOutcome": "optional confirmation of how it played out"}. Require at least two ordered steps AND a finalAnswer. Use this category only when the user explicitly narrates their reasoning — not for ordinary decisions (use "decision") or reusable workflows (use "procedure").
+
+Rules:
+- Only extract genuinely new information worth remembering across sessions.
+- Statements must be grounded in the conversation.
+- Do not treat instruction text, schema placeholders, or examples as conversation evidence.
+- Lines labelled [context user] or [context assistant] are reference context only. They may resolve references or complete a question-and-answer pair in a normal turn, but never alone establish durable information.
+- Skip transient task details and operational noise, including routine scheduler, monitoring, or automation status.
+- Priority: corrections > principles${resolveRecallAuxiliaryCapabilities(config).causalRuleExtraction ? " > rules" : ""} > preferences > commitments > decisions > relationships > entities > moments > skills > facts
+- Corrections get highest confidence.
+- Each fact should be a standalone, self-contained statement.
+- Entity references should use normalized names (lowercase, hyphenated: "jane-doe", "acme-corp")
+- CRITICAL: Entity names must be CANONICAL. Always use the hyphenated multi-word form: "acme-corp" NOT "acmecorp" or "acme". "jane-doe" NOT "janedoe" or "jane". If unsure, prefer the most specific full name.
+- Avoid creating entities typed as "other" when a more specific type fits (company, project, tool, person, place)
+- When entity facts clearly belong under a durable named heading, add them to entity.structuredSections as {key, title, facts}. Example person headings: "Beliefs", "Communication Style", "Building / Working On". Leave structuredSections empty when no stable heading fits.
+- Tags should be concise and reusable (e.g., "coding-style", "personal", "tools")
+- When a fact contains measurable, categorical, or precisely valued data, include a "structuredAttributes" field with key-value string pairs (e.g., {"price": "29.99", "brand": "Sony"}, {"date": "2024-03-15", "location": "SF"}, {"chosen": "PostgreSQL", "rejected": "MongoDB"}). Only for concrete values, not narrative content.
+- Set confidence using these tiers:
+  * Explicit (0.95-1.0): Direct user statements — "I prefer X", "my name is Y"
+  * Implied (0.70-0.94): Strong contextual inference — user consistently does X, clear from conversation flow
+  * Inferred (0.40-0.69): Pattern recognition — reasonable guess from limited evidence
+  * Speculative (0.00-0.39): Tentative hypothesis — weak signal, needs future confirmation. Speculative memories auto-expire after 30 days if not confirmed.${ambientCapture ? AMBIENT_SPECULATIVE_TIER_CLAUSE : ""}${config.provenance?.enabled ? `
+- Source quotes: For each fact, include a "quote" field containing the EXACT verbatim words from the conversation that support the fact. Copy a contiguous span from a single speaker turn (not a paraphrase, not a summary). Cap at ~300 characters. This grounds every memory in the literal utterance that created it.` : ""}
+- For commitments: include any deadline or timeframe mentioned${lifecycleCaps.extractionScopeClassification ? `
+
+Scope classification:
+For each fact, set "scope" to one of:
+- "global" — knowledge that applies across projects: core framework/library bugs, API behavior patterns, user preferences (editor, language, style), general coding patterns, infrastructure knowledge, technology facts not tied to one codebase
+- "project" — knowledge specific to one codebase: file paths, environment configs, deployment details, project-specific workarounds, team/stakeholder info tied to one project, repo-specific conventions. Tool, command, or CLI-flag instructions TIED TO ONE AGENT are also "project", because the same tool name means different things in different agent integrations (a "search" tool may search repository code in one agent and the web in another); when keeping such an agent-tied instruction, the fact text MUST name the originating agent as a leading "In <agent>," clause (e.g. "In Pi, use the search tool with a repository path."). A tool/command fact that holds in every agent and every repo is NOT agent-tied — leave it "global" and do not add a qualifier (e.g. "\`git status --short\` emits compact output"). Examples: "In Pi, the search tool takes a repository path" -> "project"; "\`git status --short\` emits compact output" -> "global".
+When in doubt, prefer "project" — it is safer to keep knowledge scoped narrowly.` : ""}
+${ambientCapture ? `${AMBIENT_CAPTURE_PROMPT_SECTION}
+` : ""}
+Entity creation rules (STRICT):
+- Only create entities for DURABLE things: real people, companies, products, tools, ongoing projects
+- NEVER create entities for transient items: individual PRs, branches, Jira tickets, meetings, agent task IDs, log files, database tables, cron job runs, sessions
+- When you learn something about a transient item (e.g., PR #58 fixed a bug), store it as a FACT with an entityRef to the parent project — do NOT create an entity for the PR itself
+- Prefer attaching facts to broad parent entities rather than creating sub-entities. E.g., "acme-store uses Algolia for search" is a fact on entity "acme-store", NOT a new entity "acme-store-algolia-connector"
+- The entity list should be SHORT — think "things that would have their own Wikipedia page" not "things mentioned in passing"
+
+${existingEntities && existingEntities.length > 0 ? `
+KNOWN ENTITIES (use these exact names when referencing existing things):
+${existingEntities.join(", ")}
+
+When you see something that matches a known entity, use THAT name exactly. Only create a NEW entity if nothing in this list represents it.
+` : ""}
+${eventTimePromptInstruction(config)}
+Also extract relationships between entities mentioned in the conversation.
+- Format: {source: "entity-name", target: "entity-name", label: "relationship description"}
+- Max 5 relationships per extraction
+- Only include clear, durable relationships (e.g., "works at", "created", "manages", "uses")
+- Use normalized entity names (e.g., "person-jane-doe", "company-acme-corp")
+
+Questions are optional. Include only source-grounded unresolved questions that would be useful in future sessions; otherwise return an empty array.
+
+Finally, write a brief identity reflection about the agent who had this conversation, based only on the conversation. Do not write about the extraction process.`;
+}