@remnic/core 9.45.4 → 9.46.0

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.`;
+}

package/src/extraction.ts

@@ -46,10 +46,10 @@ import {
 import { applyGroundingWithConnector, headerConnector, renderExtractionConversation, resolveSourceConnector, type ExtractionGroundingContext } from "./source-agent-qualifier.js";
 import { isMemoryCategory } from "./write-envelope.js";
 import { classifyExtractionThrownError, classifyFallbackParseFailure } from "./extraction-error-classification.js";
+import { AMBIENT_CAPTURE_PROMPT_SECTION_COMPACT, clampAmbientCaptureConfidence } from "./ambient-provenance.js";
+import { EXTRACTION_RESPONSE_PLACEHOLDERS, EXTRACTION_RESPONSE_SHAPE, buildExtractionInstructions, eventTimePromptInstruction } from "./extraction-prompt.js";
 export { classifyExtractionThrownError, classifyFallbackParseFailure } from "./extraction-error-classification.js";
-import { resolvePipelineProcessingCapabilities } from "./capabilities.js";
-import { resolveMemoryLifecycleCapabilities,
-  resolveLocalLlmCapabilities,resolveRecallAuxiliaryCapabilities } from "./capabilities.js";
+import { resolveLocalLlmCapabilities, resolveMemoryLifecycleCapabilities, resolvePipelineProcessingCapabilities, resolveRecallAuxiliaryCapabilities } from "./capabilities.js";
 
 type ExtractionQuestion = ExtractionResult["questions"][number];
 type ExtractedFactResult = ExtractionResult["facts"][number];
@@ -57,41 +57,6 @@ type ExtractedEntityResult = ExtractionResult["entities"][number];
 type ExtractedRelationshipResult = NonNullable<ExtractionResult["relationships"]>[number];
 
 const PROACTIVE_MIN_CONFIDENCE = 0.8;
-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>"}]
-}`;
-const EXTRACTION_RESPONSE_PLACEHOLDERS: Record<string, true> = {};
-for (const placeholder of EXTRACTION_RESPONSE_SHAPE.match(/<[^<>\r\n]+>/g) ?? []) {
-  EXTRACTION_RESPONSE_PLACEHOLDERS[placeholder] = true;
-}
 const CONSOLIDATION_RESPONSE_SCHEMA = `{
   "items": [
     {
@@ -674,16 +639,11 @@ export class ExtractionEngine {
     if (!shouldRunProactivePass(this.config, maxAdditional, this.shouldUseLocalLlm, this.localLlm)) return base;
 
     try {
-      const proactive = await this.generateProactiveQuestions(conversation, base, maxAdditional, signal);
+      const proactive = await this.generateProactiveQuestions(conversation, base, maxAdditional, ctx.ambientCapture === true, signal);
       if (proactive.length === 0) return base;
+      const ambient = ctx.ambientCapture === true;
       const proactiveAdditions = await this.answerProactiveQuestions(
-        conversation,
-        base,
-        proactive,
-        maxAdditional,
-        ctx.sourceConnector,
-        signal,
-      );
+        conversation, base, proactive, maxAdditional, ctx.sourceConnector, ambient, signal);
       const sanitizedAdditions = this.sanitizeExtractionResult(proactiveAdditions, ctx.messageTimestamp);
       const groundedAdditions = applyGroundingWithConnector(this.config, sanitizedAdditions, ctx);
       if (!this.hasExtractionOutputs(groundedAdditions)) return base;
@@ -733,6 +693,7 @@ export class ExtractionEngine {
     conversation: string,
     base: ExtractionResult,
     maxAdditional: number,
+    ambientCapture: boolean,
     signal?: AbortSignal,
   ): Promise<ExtractionQuestion[]> {
     const existingQuestionKeys = new Set(
@@ -751,7 +712,7 @@ export class ExtractionEngine {
 
     const prompt = [
       "You are doing a proactive second-pass memory extraction.",
-      `Generate up to ${maxAdditional} additional high-value follow-up questions not already covered.`,
+      `Generate up to ${maxAdditional} additional high-value follow-up questions not already covered.${ambientCapture ? AMBIENT_CAPTURE_PROMPT_SECTION_COMPACT : ""}`,
       "Return only valid JSON with this shape:",
       '{"questions":[{"question":"...","context":"...","priority":0.0}]}',
       "",
@@ -834,6 +795,7 @@ export class ExtractionEngine {
     proactiveQuestions: ExtractionQuestion[],
     maxAdditional: number,
     sourceConnector: string | undefined,
+    ambientCapture: boolean,
     signal?: AbortSignal,
   ): Promise<ExtractionResult> {
     const factsPreview = base.facts
@@ -852,7 +814,7 @@ export class ExtractionEngine {
     const prompt = [
       "You are answering proactive memory follow-up questions using only the provided buffered conversation.",
       `Return at most ${maxAdditional} additional high-confidence memory candidates that were omitted from the base extraction.`,
-      "Only include information directly supported by the conversation. Do not speculate. Do not repeat the base extraction.",
+      `Only include information directly supported by the conversation. Do not speculate. Do not repeat the base extraction.${ambientCapture ? AMBIENT_CAPTURE_PROMPT_SECTION_COMPACT : ""}`,
       "Return only valid JSON with this shape:",
       '{"facts":[{"category":"fact","content":"...","confidence":0.0,"tags":["..."],"entityRef":"optional","promptedByQuestion":"optional","quote":"optional verbatim span from a single turn"}],"profileUpdates":["..."],"entities":[{"name":"...","type":"person","facts":["..."],"structuredSections":[{"key":"beliefs","title":"Beliefs","facts":["..."]}],"promptedByQuestion":"optional"}],"relationships":[{"source":"...","target":"...","label":"...","promptedByQuestion":"optional"}]}',
       this.config.provenance?.enabled
@@ -862,7 +824,7 @@ export class ExtractionEngine {
       // paths so proactive-recovered facts also carry an optional eventTime
       // (chatgpt-codex thread on extraction.ts:1607). Returns "" when the
       // bi-temporal gate is off, keeping the prompt unchanged by default.
-      this.eventTimePromptInstruction(),
+      eventTimePromptInstruction(this.config),
       headerConnector(sourceConnector) !== undefined && resolveMemoryLifecycleCapabilities(this.config).extractionScopeClassification
         ? `Tool, command, or CLI-flag instructions tied to the ${sourceConnector} agent are "project" scope; when you recover one, begin the fact with a leading "In ${sourceConnector}, " clause naming that agent (e.g. "In ${sourceConnector}, use the search tool with a repository path.").`
         : "",
@@ -1093,6 +1055,11 @@ export class ExtractionEngine {
     return null;
   }
 
+  /**
+   * The one funnel every successful extraction path returns through — local
+   * LLM, direct client, and gateway fallback alike. The ambient clamp lives
+   * here so a new path cannot bypass it (issue #2294).
+   */
   private finalizeExtractionResult(
     result: ExtractionResult,
     turns: ReadonlyArray<{
@@ -1103,8 +1070,10 @@ export class ExtractionEngine {
       turnFingerprint?: string;
     }>,
     sourceConnector?: string,
+    ambientCapture = false,
   ): ExtractionResult {
-    const provenanced = attachExtractionProvenance(result, turns, this.config.provenance);
+    const clamped = ambientCapture ? clampAmbientCaptureConfidence(result) : result;
+    const provenanced = attachExtractionProvenance(clamped, turns, this.config.provenance);
     return sourceConnector === undefined ? provenanced : { ...provenanced, sourceConnector };
   }
 
@@ -1135,6 +1104,12 @@ export class ExtractionEngine {
     // operate on. result.sourceConnector carries it to persistence so the
     // orchestrator does not recompute over a different turn set (#2183).
     const resolvedConnector = resolveSourceConnector(boundedTurns);
+    // Ambient-capture provenance (issue #2294): true when any contributing turn
+    // came from an always-on recorder, so the prompt warns about media audio
+    // and the finalize chokepoint clamps high-impact personal facts.
+    const ambientCapture = boundedTurns.some(
+      (turn) => turn.ambientCapture === true && turn.extractionContextOnly !== true,
+    );
     // The header and qualifier strip/restore are gated on the scope-classification
     // capability; persistence records resolvedConnector regardless (trusted metadata).
     const sourceConnector = lifecycleCaps.extractionScopeClassification
@@ -1192,6 +1167,7 @@ export class ExtractionEngine {
       roleAssertionSources,
       messageTimestamp,
       sourceConnector,
+      ambientCapture,
       scopeClassificationEnabled: lifecycleCaps.extractionScopeClassification,
     };
 
@@ -1222,7 +1198,7 @@ export class ExtractionEngine {
       this.profiler.startSpan("local-llm", extractionTraceId);
       primaryExtractorAttempted = true;
       try {
-        const localResult = await this.extractWithLocalLlm(conversation, existingEntities, signal);
+        const localResult = await this.extractWithLocalLlm(conversation, existingEntities, signal, ambientCapture);
         throwIfExtractionAborted(signal);
         if (localResult) {
           const durationMs = Date.now() - startTime;
@@ -1232,7 +1208,7 @@ export class ExtractionEngine {
           const sanitized = this.sanitizeExtractionResult(localResult, messageTimestamp);
           const grounded = applyGroundingWithConnector(this.config, sanitized, groundingContext);
           const finalResult = await this.applyProactiveQuestionPass(conversation, grounded, groundingContext, signal);
-          return this.finalizeExtractionResult(finalResult, boundedTurns, resolvedConnector);
+          return this.finalizeExtractionResult(finalResult, boundedTurns, resolvedConnector, ambientCapture);
         }
         // Local failed, fall back if allowed
         if (!this.config.localLlmFallback) {
@@ -1272,7 +1248,7 @@ export class ExtractionEngine {
       this.profiler.startSpan("direct-client", extractionTraceId);
       primaryExtractorAttempted = true;
       try {
-        const directResult = await this.extractWithDirectClient(conversation, existingEntities, signal);
+        const directResult = await this.extractWithDirectClient(conversation, existingEntities, signal, ambientCapture);
         if (directResult) {
           const durationMs = Date.now() - startTime;
           this.profiler.endSpan("direct-client", extractionTraceId);
@@ -1281,7 +1257,7 @@ export class ExtractionEngine {
           const sanitized = this.sanitizeExtractionResult(directResult, messageTimestamp);
           const grounded = applyGroundingWithConnector(this.config, sanitized, groundingContext);
           const finalResult = await this.applyProactiveQuestionPass(conversation, grounded, groundingContext, signal);
-          return this.finalizeExtractionResult(finalResult, boundedTurns, resolvedConnector);
+          return this.finalizeExtractionResult(finalResult, boundedTurns, resolvedConnector, ambientCapture);
         }
         // Emit error event so Opik sees the direct client failure before fallback.
         // Wrapped in try/catch so a subscriber error doesn't break the fallback path.
@@ -1337,7 +1313,7 @@ export class ExtractionEngine {
     this.profiler.startSpan("gateway-fallback", extractionTraceId);
     try {
       const messages = [
-        { role: "system" as const, content: this.buildExtractionInstructions(existingEntities) },
+        { role: "system" as const, content: buildExtractionInstructions(this.config, existingEntities, ambientCapture) },
         { role: "user" as const, content: conversation },
       ];
 
@@ -1369,7 +1345,7 @@ export class ExtractionEngine {
         const sanitized = this.sanitizeExtractionResult(normalized, messageTimestamp);
         const grounded = applyGroundingWithConnector(this.config, sanitized, groundingContext);
         const finalResult = await this.applyProactiveQuestionPass(conversation, grounded, groundingContext, signal);
-        return this.finalizeExtractionResult(finalResult, boundedTurns, resolvedConnector);
+        return this.finalizeExtractionResult(finalResult, boundedTurns, resolvedConnector, ambientCapture);
       }
 
       this.emit({
@@ -1427,6 +1403,7 @@ export class ExtractionEngine {
     conversation: string,
     existingEntities?: string[],
     signal?: AbortSignal,
+    ambientCapture = false,
   ): Promise<ExtractionResult | null> {
     const lifecycleCaps = resolveMemoryLifecycleCapabilities(this.config);
     log.debug(
@@ -1473,8 +1450,8 @@ Rules:
 - Add structuredAttributes only for concrete values.
 - Include at most five durable relationships.${this.config.provenance?.enabled ? `
 - Each fact must include a quote copied verbatim from one contiguous conversation span.` : ""}${lifecycleCaps.extractionScopeClassification ? `
-- Set each fact scope to "global" for cross-project knowledge or "project" for codebase-specific knowledge. Tool, command, or CLI-flag instructions tied to one agent are "project" (the same tool name can mean different things across agents); when keeping one, begin the fact with a leading "In <agent>," clause naming that agent.` : ""}
-${this.eventTimePromptInstruction()}
+- Set each fact scope to "global" for cross-project knowledge or "project" for codebase-specific knowledge. Tool, command, or CLI-flag instructions tied to one agent are "project" (the same tool name can mean different things across agents); when keeping one, begin the fact with a leading "In <agent>," clause naming that agent.` : ""}${ambientCapture ? AMBIENT_CAPTURE_PROMPT_SECTION_COMPACT : ""}
+${eventTimePromptInstruction(this.config)}
 Return only valid JSON matching this shape. Placeholder text describes field shape only and is never source evidence:
 ${EXTRACTION_RESPONSE_SHAPE}
 
@@ -1550,6 +1527,7 @@ ${truncatedConversation}`;
     conversation: string,
     existingEntities?: string[],
     signal?: AbortSignal,
+    ambientCapture = false,
   ): Promise<ExtractionResult | null> {
     if (!this.client) return null;
 
@@ -1565,7 +1543,7 @@ ${truncatedConversation}`;
           {
             role: "system",
             content:
-              this.buildExtractionInstructions(existingEntities) +
+              buildExtractionInstructions(this.config, existingEntities, ambientCapture) +
               `\n\nReturn only valid JSON matching this shape. Placeholder text describes field shape only and is never source evidence:\n${EXTRACTION_RESPONSE_SHAPE}`,
           },
           { role: "user", content: conversation },
@@ -1641,95 +1619,6 @@ ${truncatedConversation}`;
     return this.normalizeExtractionResultPayload({ facts, entities, profileUpdates: [], questions: [] });
   }
 
-  /**
-   * 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).
-   */
-  private eventTimePromptInstruction(): string {
-    if (!this.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.
-   */
-  private buildExtractionInstructions(existingEntities?: string[]): string {
-    const lifecycleCaps = resolveMemoryLifecycleCapabilities(this.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(this.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(this.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.${this.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.` : ""}
-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.
-` : ""}
-${this.eventTimePromptInstruction()}
-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.`;
-  }
-
   async consolidate(
     newMemories: MemoryFile[],
     existingMemories: MemoryFile[],

package/src/index.ts

@@ -9,11 +9,6 @@
  * This package has ZERO OpenClaw imports — it can be consumed by
  * any host adapter (CLI, HTTP server, MCP server, etc.).
  *
- * Usage:
- *   import { Orchestrator, parseConfig } from "@remnic/core";
- *   const config = parseConfig({ memoryDir: "/tmp/mem" });
- *   const orch = new Orchestrator(config);
- *   await orch.initialize();
  */
 
 // ---------------------------------------------------------------------------
@@ -29,6 +24,7 @@ export { resolvePluginEntry, type PluginEntryResolverOptions } from "./plugin-en
 export { parseConfig, isOpenaiApiKeyDisabled, resolveEnvVars } from "./config.js";
 export { resolveRemnicConfigRecord } from "./config-record.js";
 export * from "./external-wiki.js";
+export * from "./external-wiki-cli.js";
 export {
   parseFlexibleIsoTimestamp,
   parseIsoOffsetTimestamp,

package/src/maintenance/first-start-migration.ts

@@ -278,7 +278,7 @@ export async function runFirstStartMigration(
         qmd,
         hotCollection: options.hotCollection ?? config.qmdCollection ?? "openclaw-engram",
         coldCollection: options.coldCollection ?? config.qmdColdCollection ?? "openclaw-engram-cold",
-    })
+      })
     : null;
   const coldCollection = options.coldCollection ?? config.qmdColdCollection ?? "openclaw-engram-cold";
 
@@ -287,17 +287,17 @@ export async function runFirstStartMigration(
       return abortedResult(candidateCount, demotedCount, failureCount);
     }
     try {
-      if (executor) {
-        await executor.migrateMemory({
-          memory,
-          fromTier: "hot",
-          toTier: "cold",
-          reason: "first-start-lifecycle-migration",
-        });
-      } else {
-        await storage.migrateMemoryToTier(memory, "cold");
+      const result = executor
+        ? await executor.migrateMemory({
+            memory,
+            fromTier: "hot",
+            toTier: "cold",
+            reason: "first-start-lifecycle-migration",
+          })
+        : await storage.migrateMemoryToTier(memory, "cold");
+      if (result.changed) {
+        demotedCount += 1;
       }
-      demotedCount += 1;
     } catch {
       const targetPath = storage.buildTierMemoryPath(memory, "cold");
       const [targetExists, sourceExists] = await Promise.all([

package/src/meetings/memory-gen.test.ts

@@ -129,6 +129,32 @@ test("episode write is idempotent — an identical episode is skipped", async ()
   assert.equal(writer.writes.length, 1);
 });
 
+test("an episode whose provider title is a personal claim is held for review (#2294)", async () => {
+  // The episode is a recall anchor written active, but its title comes from the
+  // provider's read of the same ambient audio — so a title lifted from a
+  // television scene must not enter recall on the anchor.
+  const writer = new FakeWriter();
+  await writeMeetingEpisodeMemory(record({ title: "Dana's cancer diagnosis" }), writer);
+  assert.equal(writer.writes[0]!.extras.status, "pending_review");
+
+  const clean = new FakeWriter();
+  await writeMeetingEpisodeMemory(record({ title: "Sprint planning" }), clean);
+  assert.equal(clean.writes[0]!.extras.status, "active", "an ordinary title is unaffected");
+});
+
+test("an audio-only episode is held for review — detection alone is not corroboration (#2294)", async () => {
+  // `audio` detection is a heuristic over speech with no app span behind it, so
+  // fifteen minutes of television with two voices yields an episode asserting a
+  // meeting happened with the show's speakers as attendees.
+  const writer = new FakeWriter();
+  await writeMeetingEpisodeMemory(record({ app: undefined, detectionSource: "audio" }), writer);
+  assert.equal(writer.writes[0]!.extras.status, "pending_review");
+
+  const corroborated = new FakeWriter();
+  await writeMeetingEpisodeMemory(record({ detectionSource: "app+audio" }), corroborated);
+  assert.equal(corroborated.writes[0]!.extras.status, "active");
+});
+
 test("an audio-only meeting omits the meetingApp attribute and the app suffix", async () => {
   const writer = new FakeWriter();
   const audioOnly = record({ app: undefined, detectionSource: "audio" });
@@ -206,6 +232,31 @@ test("summaryMode smart routes a high-trust decision to active with meeting prov
   assert.ok(writer.writes.some((w) => w.envelope.category === "commitment"), "a commitment fact was written");
 });
 
+test("a high-impact personal claim never goes active, however the trust adds up (#2294)", async () => {
+  // A meeting transcript is the same always-on capture audio a wearable
+  // records, so a fabricated medical line can arrive in it. At the extractor's
+  // fixed 0.9 confidence, 0.9 * 0.85 = 0.765 clears the 0.7 auto-approve line;
+  // the ambient cap must hold it in the review queue anyway.
+  const writer = new FakeWriter();
+  const extractor = spyExtractor("Meeting summary.", [
+    { content: "Dana was diagnosed with cancer last month", category: "decision", confidence: 0.9 },
+    { content: "Team decided to ship v2 on Friday", category: "decision", confidence: 0.9 },
+  ]);
+
+  const res = await generateMeetingSummaryFacts(TRANSCRIPT_RECORD(), meetingConfig({ summaryMode: "smart" }), {
+    extractor,
+    writer,
+  });
+
+  assert.equal(res.dropped, 0, "the cap downgrades rather than drops");
+  const medical = writer.writes.find((w) => w.envelope.content.includes("diagnosed"));
+  assert.ok(medical, "the medical claim was written");
+  assert.equal(medical!.extras.status, "pending_review");
+  const ordinary = writer.writes.find((w) => w.envelope.content.includes("ship v2"));
+  assert.ok(ordinary, "the ordinary decision was written");
+  assert.equal(ordinary!.extras.status, "active", "ordinary meeting facts are unaffected");
+});
+
 test("summaryMode smart drops a low-trust candidate but corroboration promotes it to review", async () => {
   // conf 0.5 * sourceTrust 0.85 = 0.425 < reviewTrust 0.45 -> drop.
   const lowConf: MeetingFactCandidate[] = [{ content: "maybe we will refactor later", category: "fact", confidence: 0.5 }];