@snoai/memory 0.0.0-stage → 1.0.0

package/dist/internal/engine/bindings/memory-tool-schemas.d.ts

@@ -0,0 +1,109 @@
+import { p as LlmRoutingConfig, r as LlmClient } from "../../../plugin-config-schema-C0UUbOmG.js";
+import { h as MemoryCategory, r as AggregationQuery } from "../../../types-DxKqU60b.js";
+import { n as Locale } from "../../../locales-JxGmkG6t.js";
+import { t as Embedder } from "../../../embedding-provider-client-vynZMuit.js";
+import { t as MemoryRetriever } from "../../../retriever-Ruk3zp7_.js";
+import { C as MemoryStore } from "../../../memory-store-base-XRA4S9Xl.js";
+import { t as MemoryScopePolicy } from "../../../memory-scope-policy-1gg5QlWZ.js";
+import { t as z } from "../../../memory-tool-dependencies-N69chrQc.js";
+//#region src/engine/bindings/memory-tool-schemas.d.ts
+export declare const recallParamsSchema: z.ZodType<{
+  query: string;
+  external_reference?: string | undefined;
+  external_reference_visibility?: "public" | "private" | undefined;
+  top_k?: number | undefined;
+  min_score?: number | undefined;
+  scope?: string | undefined;
+  category?: MemoryCategory | undefined;
+  include_metadata?: boolean | undefined;
+  include_history?: boolean | undefined;
+  include_refused?: boolean | undefined;
+  token_budget?: number | undefined;
+  aggregation?: AggregationQuery | undefined;
+}, unknown>;
+export declare const storeParamsSchema: z.ZodType<{
+  content: string;
+  category?: MemoryCategory | undefined;
+  scope?: string | undefined;
+  importance?: number | undefined;
+  metadata?: Record<string, unknown> | undefined;
+}, unknown>;
+export declare const forgetParamsSchema: z.ZodType<{
+  id?: string | undefined;
+  query?: string | undefined;
+  suppress_key?: {
+    subject: string;
+    attribute: string;
+  } | undefined;
+  suppress_content?: string | undefined;
+  scope?: string | undefined;
+  min_score?: number | undefined;
+  max_delete?: number | undefined;
+  confirm?: boolean | undefined;
+}, unknown>;
+export declare const updateParamsSchema: z.ZodType<{
+  id: string;
+  text?: string | undefined;
+  category?: MemoryCategory | undefined;
+  importance?: number | undefined;
+  metadata?: Record<string, unknown> | undefined;
+  timestamp?: number | undefined;
+}, unknown>;
+export declare const statsParamsSchema: z.ZodType<{
+  scope?: string | undefined;
+}, unknown>;
+export declare const listParamsSchema: z.ZodType<{
+  scope?: string | undefined;
+  category?: MemoryCategory | undefined;
+  limit?: number | undefined;
+  offset?: number | undefined;
+  importance_min?: number | undefined;
+}, unknown>;
+export interface ToolContext {
+  recallSession?: {
+    sessionId: string;
+    turn: number;
+    history: Map<string, Map<string, number>>;
+  };
+  retriever: MemoryRetriever;
+  store: MemoryStore;
+  scopePolicy: MemoryScopePolicy;
+  embedder: Embedder;
+  agentId?: string;
+  stateDir: string;
+  workspaceDir?: string;
+  selfImprovementEnabled?: boolean;
+  language?: Locale;
+  sessionTimestamp?: number;
+  sessionKey?: string;
+  sessionTimezone?: string;
+  /**
+   * Invalidates the reflection slice cache (TTL-bounded, built by the
+   * memoryReflection strategy). Set only when that strategy is active; the
+   * reflection-resolve tool calls it so a freshly resolved item stops being
+   * injected before the cache would otherwise expire.
+   */
+  clearReflectionSliceCache?: () => void;
+  /**
+   * Mode-routed LLM client for manual profile stores, built from the
+   * deployment config at registration. Absent (or routed off per request)
+   * means the profile writer's deterministic fallbacks run.
+   */
+  profileToolLlm?: LlmClient;
+  /** Product-mode routing slice; gates the profile conflict scan. */
+  llmRouting?: LlmRoutingConfig;
+  /**
+   * The host operator (the contract's `scope.host.systemCaller`), whose repairs write with
+   * offline-family authority the way maintenance does; a skin or agent never carries this.
+   */
+  systemCaller?: boolean;
+}
+export type ToolResult = {
+  isError?: boolean;
+  content: Array<{
+    type: "text";
+    text: string;
+  }>;
+  details: Record<string, unknown>;
+};
+//#endregion

package/dist/internal/engine/bindings/memory-tool-schemas.js

@@ -0,0 +1,75 @@
+import { AGGREGATION_OPERATIONS, MEMORY_CATEGORIES } from "../shared/types.js";
+import { n as z } from "../../../memory-tool-dependencies-CLODycUw.js";
+//#region src/engine/bindings/memory-tool-schemas.ts
+const TOOL_CATEGORY_INPUTS = [...MEMORY_CATEGORIES];
+const toolCategoryInputSchema = z.enum(TOOL_CATEGORY_INPUTS);
+const recallParamsSchema = z.object({
+	query: z.string().min(1),
+	external_reference: z.string().optional(),
+	external_reference_visibility: z.enum(["public", "private"]).optional(),
+	top_k: z.number().int().optional(),
+	min_score: z.number().optional(),
+	scope: z.string().optional(),
+	category: toolCategoryInputSchema.optional(),
+	include_metadata: z.boolean().optional(),
+	include_history: z.boolean().optional(),
+	include_refused: z.boolean().optional(),
+	token_budget: z.number().int().optional(),
+	aggregation: z.object({
+		operation: z.enum(AGGREGATION_OPERATIONS),
+		terms: z.array(z.string().trim().min(1).max(128)).min(1).max(8)
+	}).strict().optional()
+});
+const storeParamsSchema = z.object({
+	content: z.string().min(1),
+	category: toolCategoryInputSchema.optional(),
+	scope: z.string().optional(),
+	importance: z.number().optional(),
+	metadata: z.record(z.string(), z.unknown()).optional()
+});
+const forgetParamsSchema = z.object({
+	id: z.string().trim().min(1).optional(),
+	query: z.string().trim().min(1).optional(),
+	suppress_key: z.object({
+		subject: z.string().trim().min(1),
+		attribute: z.string().trim().min(1)
+	}).strict().optional(),
+	suppress_content: z.string().min(1).optional(),
+	scope: z.string().optional(),
+	min_score: z.number().optional(),
+	max_delete: z.number().int().positive().optional(),
+	confirm: z.boolean().optional()
+}).superRefine((value, context) => {
+	if ([
+		value.id,
+		value.query,
+		value.suppress_key,
+		value.suppress_content
+	].filter(Boolean).length !== 1) context.addIssue({
+		code: "custom",
+		message: "Exactly one forget action is required"
+	});
+	if ((value.suppress_key || value.suppress_content) && !value.scope?.trim()) context.addIssue({
+		code: "custom",
+		message: "Suppression requires scope",
+		path: ["scope"]
+	});
+});
+const updateParamsSchema = z.object({
+	id: z.string().min(1),
+	text: z.string().trim().min(1).optional(),
+	category: toolCategoryInputSchema.optional(),
+	importance: z.number().optional(),
+	metadata: z.record(z.string(), z.unknown()).optional(),
+	timestamp: z.number().int().nonnegative().optional()
+}).refine((value) => value.text !== void 0 || value.category !== void 0 || value.importance !== void 0 || value.metadata !== void 0 || value.timestamp !== void 0, { message: "At least one update field is required" });
+const statsParamsSchema = z.object({ scope: z.string().optional() });
+const listParamsSchema = z.object({
+	scope: z.string().optional(),
+	category: toolCategoryInputSchema.optional(),
+	limit: z.number().int().optional(),
+	offset: z.number().int().optional(),
+	importance_min: z.number().optional()
+});
+//#endregion
+export { forgetParamsSchema, listParamsSchema, recallParamsSchema, statsParamsSchema, storeParamsSchema, updateParamsSchema };

package/dist/internal/engine/bindings/memory-update-tool.d.ts

@@ -0,0 +1,5 @@
+import { resolveAgentAccess } from "./memory-tool-access.js";
+import { ToolContext, ToolResult } from "./memory-tool-schemas.js";
+//#region src/engine/bindings/memory-update-tool.d.ts
+export declare function executeMemoryUpdateTool(ctx: ToolContext, _access: ReturnType<typeof resolveAgentAccess>, _toolCallId: unknown, params: unknown): Promise<ToolResult>;
+//#endregion

package/dist/internal/engine/bindings/memory-update-tool.js

@@ -0,0 +1,127 @@
+import "../i18n/locales.js";
+import { normalizeCategory } from "../shared/types.js";
+import { StorageError } from "../shared/errors.js";
+import { h as deriveFactKey } from "../../../memory-metadata-codec-DL1sbJiN.js";
+import { clamp01 } from "../shared/utils.js";
+import { stripEnvelopeMetadata } from "../extraction/extraction-text-sanitizer.js";
+import { a as serializeIntervalMetadata, o as resolveMemoryDate } from "../../../memory-temporality-classifier-CKiTAHXe.js";
+import { t as appendAuditEntry } from "../../../runtime-audit-log-BCeujlEp.js";
+import "../../../memory-tool-dependencies-CLODycUw.js";
+import { parseEntryMetadata } from "./memory-tool-formatting.js";
+import { makeResult, runWithAudit } from "./memory-tool-results.js";
+import { updateParamsSchema } from "./memory-tool-schemas.js";
+//#region src/engine/bindings/memory-update-tool.ts
+async function executeMemoryUpdateTool(ctx, _access, _toolCallId, params) {
+	return runWithAudit(ctx, "memory_update", void 0, async () => {
+		const parsed = updateParamsSchema.parse(params);
+		const existing = ctx.store.getById(parsed.id);
+		if (!existing) return makeResult(`Memory entry not found: ${parsed.id}`, {}, true);
+		const existingCategory = normalizeCategory(existing.category) ?? "episodic";
+		const changes = { writerAuthority: "offline-family" };
+		let strippedNewText;
+		if (parsed.text !== void 0) {
+			strippedNewText = stripEnvelopeMetadata(parsed.text);
+			if (strippedNewText.length !== parsed.text.length) appendAuditEntry(ctx.stateDir, {
+				event: "envelope_strip",
+				tool: "memory_update",
+				resultStatus: "ok",
+				decision: "stripped",
+				details: {
+					beforeChars: parsed.text.length,
+					afterChars: strippedNewText.length
+				}
+			});
+			if (!strippedNewText.trim()) return makeResult("Skipped: updated text is purely envelope metadata.", { resultStatus: "skipped" });
+			changes.text = strippedNewText;
+		}
+		const requestedCategory = parsed.category !== void 0 ? normalizeCategory(parsed.category) : void 0;
+		if (requestedCategory !== void 0) changes.category = requestedCategory;
+		if (parsed.importance !== void 0) changes.importance = clamp01(parsed.importance, existing.importance);
+		if (parsed.timestamp !== void 0) {
+			changes.timestamp = parsed.timestamp;
+			changes.timezone = existing.timezone;
+		}
+		const effectiveCategory = requestedCategory ?? existingCategory;
+		if (parsed.metadata !== void 0 || parsed.text !== void 0) {
+			const nextMeta = parsed.metadata !== void 0 ? {
+				...parseEntryMetadata(existing),
+				...parsed.metadata
+			} : parseEntryMetadata(existing);
+			if (strippedNewText !== void 0) {
+				const dateResolution = await resolveMemoryDate({
+					text: strippedNewText,
+					sessionTimestamp: ctx.sessionTimestamp,
+					sessionTimezone: ctx.sessionTimezone,
+					locale: ctx.language ?? "en",
+					llm: ctx.profileToolLlm,
+					routing: ctx.llmRouting
+				});
+				const userProvidedTemporalType = parsed.metadata !== void 0 && "memory_temporal_type" in parsed.metadata;
+				const userProvidedTemporalStatus = parsed.metadata !== void 0 && "temporal_resolution_status" in parsed.metadata;
+				const userProvidedTemporalPhrase = parsed.metadata !== void 0 && "temporal_phrase" in parsed.metadata;
+				const userProvidedValidUntil = parsed.metadata !== void 0 && "valid_until" in parsed.metadata;
+				const userProvidedValidFrom = parsed.metadata !== void 0 && "valid_from" in parsed.metadata;
+				const userProvidedEventAt = parsed.metadata !== void 0 && "event_at" in parsed.metadata;
+				const temporalMetadata = serializeIntervalMetadata(effectiveCategory, dateResolution.interval);
+				for (const field of [
+					"temporal_date",
+					"temporal_precision",
+					"temporal_timezone"
+				]) {
+					if (parsed.metadata !== void 0 && field in parsed.metadata) continue;
+					if (temporalMetadata[field] !== void 0) nextMeta[field] = temporalMetadata[field];
+					else delete nextMeta[field];
+				}
+				if (!userProvidedTemporalType) nextMeta.memory_temporal_type = temporalMetadata.memory_temporal_type;
+				if (!userProvidedTemporalStatus) nextMeta.temporal_resolution_status = temporalMetadata.temporal_resolution_status;
+				if (!userProvidedTemporalPhrase) {
+					if (temporalMetadata.temporal_phrase) nextMeta.temporal_phrase = temporalMetadata.temporal_phrase;
+					else delete nextMeta.temporal_phrase;
+				}
+				if (!userProvidedValidUntil) {
+					if (temporalMetadata.valid_until !== void 0) nextMeta.valid_until = temporalMetadata.valid_until;
+					else delete nextMeta.valid_until;
+				}
+				if (!userProvidedValidFrom) {
+					if (temporalMetadata.valid_from !== void 0) nextMeta.valid_from = temporalMetadata.valid_from;
+					else delete nextMeta.valid_from;
+				}
+				if (!userProvidedEventAt) {
+					if (temporalMetadata.event_at !== void 0) nextMeta.event_at = temporalMetadata.event_at;
+					else delete nextMeta.event_at;
+				}
+				const userProvidedL0 = parsed.metadata !== void 0 && "l0_abstract" in parsed.metadata;
+				const userProvidedL1 = parsed.metadata !== void 0 && "l1_overview" in parsed.metadata;
+				const userProvidedL2 = parsed.metadata !== void 0 && "l2_content" in parsed.metadata;
+				const userProvidedFactKey = parsed.metadata !== void 0 && "fact_key" in parsed.metadata;
+				if (!userProvidedL0) nextMeta.l0_abstract = strippedNewText;
+				if (!userProvidedL1) nextMeta.l1_overview = `- ${strippedNewText}`;
+				if (!userProvidedL2) nextMeta.l2_content = strippedNewText;
+				if (!userProvidedFactKey) {
+					const derivedFactKey = deriveFactKey({
+						kind: effectiveCategory,
+						section_name: nextMeta.section_name,
+						anti_pattern_signature: nextMeta.anti_pattern_signature
+					});
+					if (derivedFactKey) nextMeta.fact_key = derivedFactKey;
+					else delete nextMeta.fact_key;
+				}
+			}
+			const userProvidedConfidence = parsed.metadata !== void 0 && "confidence" in parsed.metadata;
+			if (parsed.importance !== void 0 && !userProvidedConfidence) nextMeta.confidence = clamp01(parsed.importance, existing.importance);
+			changes.metadata = JSON.stringify(nextMeta);
+			changes.expectedMetadata = existing.metadata;
+		}
+		if (parsed.importance !== void 0 && parsed.text === void 0 && parsed.metadata === void 0) {
+			const meta = parseEntryMetadata(existing);
+			meta.confidence = clamp01(parsed.importance, existing.importance);
+			changes.metadata = JSON.stringify(meta);
+			changes.expectedMetadata = existing.metadata;
+		}
+		const updated = await ctx.store.update(parsed.id, changes);
+		if (!updated) throw new StorageError(`Failed to update memory: ${parsed.id}`);
+		return makeResult(`Updated memory: ${parsed.id}`, { id: updated.id });
+	});
+}
+//#endregion
+export { executeMemoryUpdateTool };

package/dist/internal/engine/bindings/sno-station-mem-ambient-learning-hook.d.ts

@@ -0,0 +1,14 @@
+import { t as PluginConfig } from "../../../plugin-config-schema-C0UUbOmG.js";
+import { t as Embedder } from "../../../embedding-provider-client-vynZMuit.js";
+import { C as MemoryStore } from "../../../memory-store-base-XRA4S9Xl.js";
+import { n as createScopePolicy } from "../../../memory-scope-policy-1gg5QlWZ.js";
+import { PluginHookAgentContext, PluginHookAgentEndEvent } from "./sno-station-mem-hook-types.js";
+import { r as AtomicInsightDistiller } from "../../../atomic-memory-extraction-BpOUWPJM.js";
+import { t as SnoStationMemPluginApi } from "../../../sno-station-mem-runtime-dependencies-Bu-MiqPX.js";
+//#region src/engine/bindings/sno-station-mem-ambient-learning-hook.d.ts
+/** Runs atomic extraction after a successful top-level agent conversation. */
+export type AmbientCaptureOutcome = "skipped" | "success" | "partial" | "failed";
+export declare function onAgentEnd(api: SnoStationMemPluginApi, config: PluginConfig, store: MemoryStore, _embedder: Embedder, scopePolicy: ReturnType<typeof createScopePolicy>, insightDistiller: AtomicInsightDistiller | undefined, event: PluginHookAgentEndEvent, ctx: PluginHookAgentContext, stateDir: string, reasonOut?: {
+  value?: string;
+}): Promise<AmbientCaptureOutcome>;
+//#endregion

package/dist/internal/engine/bindings/sno-station-mem-ambient-learning-hook.js

@@ -0,0 +1,248 @@
+import { DEFAULT_IMPORTANCE } from "../../config/index.js";
+import { redactSecrets } from "../security/redact.js";
+import { t as checkMemoryOperation } from "../../../operation-cancellation-CTKWwNHk.js";
+import { n as modelCallDestination } from "../../../model-call-table-CspopkBg.js";
+import { t as normalizeAmbientLearningText } from "../../../ambient-learning-text-normalizer-CxjATmMp.js";
+import { a as serializeIntervalMetadata, i as parseSessionTimestamp, s as unresolvedMemoryDate } from "../../../memory-temporality-classifier-CKiTAHXe.js";
+import { t as appendAuditEntry } from "../../../runtime-audit-log-BCeujlEp.js";
+import { resolveHookAgentId } from "./sno-station-mem-runtime-mode.js";
+import { c as shouldSkipReflectionMessage } from "../../../daily-log-generator-CH_KuWHs.js";
+import "../../../sno-station-mem-runtime-dependencies-DjLOhB45.js";
+import { buildConversationText, deriveSessionDateTime, extractAllMessageTexts, isAmbientLearningMessage, transcriptSessionDateTime } from "./sno-station-mem-message-transcript.js";
+import { createLogger, currentLogContext, withLogContext } from "@snoai/utils/logger";
+import { randomUUID } from "node:crypto";
+//#region src/engine/bindings/sno-station-mem-ambient-learning-hook.ts
+/** @file sno-station-mem-ambient-learning-hook.ts
+* @purpose Routes successful agent conversations through atomic memory extraction.
+* @boundary The agent_end hook path only; registration and service lifecycle are elsewhere.
+*/
+const log = createLogger("sno-station-mem:ambient-learning");
+async function runLocalFirstCapture(input) {
+	const { api, config, store, event, ctx, stateDir, scope, sessionKey } = input;
+	const writerAgentId = resolveHookAgentId(ctx.agentId, sessionKey).agentId;
+	const entries = event.messages.flatMap((message) => {
+		if (!isAmbientLearningMessage(message)) return [];
+		if (message.role === "assistant" && !config.captureAssistant) return [];
+		return extractAllMessageTexts(message).flatMap((raw) => {
+			const normalized = normalizeAmbientLearningText(message.role, raw, shouldSkipReflectionMessage);
+			return normalized ? [{
+				role: message.role,
+				text: normalized.trim()
+			}] : [];
+		});
+	});
+	const seen = /* @__PURE__ */ new Set();
+	const sessionDateTime = transcriptSessionDateTime(event.messages) ?? deriveSessionDateTime(event.messages, config.captureAssistant);
+	const sessionTimestamp = parseSessionTimestamp(sessionDateTime);
+	let stored = 0;
+	let failures = 0;
+	for (const entry of entries) {
+		checkMemoryOperation();
+		if (!entry.text || seen.has(entry.text)) continue;
+		seen.add(entry.text);
+		try {
+			const date = unresolvedMemoryDate({
+				text: entry.text,
+				sessionDateTime,
+				sessionTimezone: ctx.sessionTimezone,
+				locale: config.language
+			});
+			await store.store({
+				text: entry.text,
+				category: "episodic",
+				projectId: scope,
+				importance: DEFAULT_IMPORTANCE,
+				...date.timestamp !== void 0 ? { timestamp: date.timestamp } : sessionTimestamp !== void 0 ? { timestamp: sessionTimestamp } : {},
+				timezone: date.timezone,
+				metadata: JSON.stringify({
+					memory_category: "episodic",
+					capture_mode: "local-first",
+					...writerAgentId ? { writer_agent_id: writerAgentId } : {},
+					role: entry.role,
+					...sessionKey ? { session_key: sessionKey } : {},
+					...serializeIntervalMetadata("episodic", date.interval)
+				})
+			});
+			stored += 1;
+		} catch (error) {
+			checkMemoryOperation();
+			failures += 1;
+			log.warn("Local capture write failed", { error }, {
+				event_name: "memory.capture.write.failed",
+				file: "packages/memory/src/engine/bindings/sno-station-mem-ambient-learning-hook.ts",
+				function: "runLocalFirstCapture",
+				site_id: "memory.capture.local.write.failed"
+			});
+		}
+	}
+	appendAuditEntry(stateDir, {
+		event: "hook_trigger",
+		hook: "agent_end",
+		resultStatus: failures === 0 ? "ok" : "partial",
+		details: {
+			mode: config.mode,
+			candidates: entries.length,
+			stored,
+			failures
+		}
+	});
+	let outcome = "success";
+	if (failures > 0) outcome = stored > 0 ? "partial" : "failed";
+	log.info("Local memory capture completed", {
+		outcome,
+		persisted_count: stored,
+		failed_count: failures,
+		input_count: entries.length
+	}, {
+		event_name: "memory.capture.completed",
+		file: "packages/memory/src/engine/bindings/sno-station-mem-ambient-learning-hook.ts",
+		function: "runLocalFirstCapture",
+		site_id: "memory.capture.local.completed"
+	});
+	return {
+		stored,
+		failures
+	};
+}
+async function onAgentEnd(api, config, store, _embedder, scopePolicy, insightDistiller, event, ctx, stateDir, reasonOut) {
+	const sessionKey = typeof ctx.sessionKey === "string" ? ctx.sessionKey : "";
+	return withLogContext({
+		operation_id: currentLogContext().operation_id ?? randomUUID(),
+		session_reference: sessionKey
+	}, async () => {
+		const started = performance.now();
+		let outcome = "skipped";
+		let reason = "guard_not_admitted";
+		try {
+			if (!config.ambientLearning) {
+				reason = "ambient_learning_disabled";
+				return outcome;
+			}
+			if (sessionKey.includes(":subagent:")) {
+				reason = "skipped_subagent";
+				appendAuditEntry(stateDir, {
+					event: "ambient_learning",
+					hook: "agent_end",
+					resultStatus: "skipped",
+					decision: "skipped_subagent",
+					details: { sessionKey }
+				});
+				return outcome;
+			}
+			const resolvedAgentId = resolveHookAgentId(ctx.agentId, sessionKey).agentId;
+			const scope = scopePolicy.getDefaultScope(resolvedAgentId);
+			if (!config.modelCalls) throw new Error("modelCalls unavailable");
+			if (modelCallDestination("E1", config.mode, config.modelCalls) === "off") {
+				const { stored, failures } = await runLocalFirstCapture({
+					api,
+					config,
+					store,
+					event,
+					ctx,
+					stateDir,
+					scope,
+					sessionKey
+				});
+				outcome = "success";
+				if (failures > 0) outcome = stored > 0 ? "partial" : "failed";
+				return outcome;
+			}
+			if (!insightDistiller) {
+				reason = "atomic_extractor_unavailable";
+				appendAuditEntry(stateDir, {
+					event: "ambient_learning",
+					hook: "agent_end",
+					resultStatus: "skipped",
+					decision: "atomic_extractor_unavailable",
+					details: { mode: config.mode }
+				});
+				return outcome;
+			}
+			const conversationText = buildConversationText(event.messages, config.captureAssistant).text;
+			const sessionDateTime = transcriptSessionDateTime(event.messages) ?? deriveSessionDateTime(event.messages, config.captureAssistant);
+			if (!conversationText.trim()) {
+				reason = "rejected_empty_conversation";
+				appendAuditEntry(stateDir, {
+					event: "ambient_learning",
+					hook: "agent_end",
+					resultStatus: "skipped",
+					decision: "rejected_empty_conversation",
+					details: { mode: config.mode }
+				});
+				return outcome;
+			}
+			try {
+				const stats = await insightDistiller.extractAndPersist(conversationText, sessionKey, {
+					scope,
+					writerAgentId: resolvedAgentId,
+					sessionDateTime,
+					sessionTimezone: ctx.sessionTimezone
+				});
+				const failures = (stats.llmFailures ?? 0) > 0;
+				const partial = failures && stats.created > 0;
+				outcome = failures ? partial ? "partial" : "failed" : "success";
+				reason = "extraction_returned";
+				const details = failures ? {
+					created: stats.created,
+					merged: stats.merged,
+					skipped: stats.skipped,
+					llmFailures: stats.llmFailures,
+					todoTransitionsWithoutSourceCount: stats.todoTransitionsWithoutSourceCount,
+					fallback: "disabled"
+				} : {
+					created: stats.created,
+					merged: stats.merged,
+					skipped: stats.skipped,
+					todoTransitionsWithoutSourceCount: stats.todoTransitionsWithoutSourceCount,
+					conversationChars: conversationText.length,
+					sessionDateTime,
+					sessionTimezone: ctx.sessionTimezone
+				};
+				appendAuditEntry(stateDir, {
+					event: "ambient_learning",
+					hook: "agent_end",
+					resultStatus: failures ? partial ? "partial" : "error" : "ok",
+					decision: failures ? "llm_distill_failed" : "llm_distill_extracted",
+					details
+				});
+			} catch (error) {
+				checkMemoryOperation();
+				const rawMessage = error instanceof Error ? error.message : String(error);
+				const safeMessage = redactSecrets(rawMessage).slice(0, 200);
+				outcome = "failed";
+				reason = "extraction_failed";
+				log.warn("Ambient extraction failed", { error }, {
+					event_name: "memory.capture.hook.failed",
+					file: "packages/memory/src/engine/bindings/sno-station-mem-ambient-learning-hook.ts",
+					function: "onAgentEnd",
+					site_id: "memory.capture.hook.failed"
+				});
+				appendAuditEntry(stateDir, {
+					event: "ambient_learning",
+					hook: "agent_end",
+					resultStatus: "partial",
+					decision: "llm_distill_failed",
+					details: {
+						error: safeMessage,
+						fallback: "disabled"
+					}
+				});
+			}
+		} finally {
+			if (reasonOut) reasonOut.value = reason;
+			log.info("Ambient capture hook completed", {
+				outcome,
+				reason_code: reason,
+				duration_ms: performance.now() - started
+			}, {
+				event_name: "memory.capture.hook.completed",
+				file: "packages/memory/src/engine/bindings/sno-station-mem-ambient-learning-hook.ts",
+				function: "onAgentEnd",
+				site_id: "memory.capture.hook.completed"
+			});
+		}
+		return outcome;
+	});
+}
+//#endregion
+export { onAgentEnd };

package/dist/internal/engine/bindings/sno-station-mem-auto-recall-hook.d.ts

@@ -0,0 +1,12 @@
+import { t as PluginConfig } from "../../../plugin-config-schema-C0UUbOmG.js";
+import { t as MemoryRetriever } from "../../../retriever-Ruk3zp7_.js";
+import { C as MemoryStore } from "../../../memory-store-base-XRA4S9Xl.js";
+import { r as MemoryTelemetryUsageOutbox } from "../../../memory-telemetry-outbox-ddTdImt7.js";
+import { n as createScopePolicy } from "../../../memory-scope-policy-1gg5QlWZ.js";
+import { PluginHookAgentContext, PluginHookBeforeAgentStartEvent, PluginHookBeforeAgentStartResult } from "./sno-station-mem-hook-types.js";
+import { t as SnoStationMemPluginApi } from "../../../sno-station-mem-runtime-dependencies-Bu-MiqPX.js";
+//#region src/engine/bindings/sno-station-mem-auto-recall-hook.d.ts
+export declare function extractAutoRecallQuery(prompt: string): string;
+/** Injects relevant memories into the next agent turn after scope and cache checks. */
+export declare function onBeforeAgentStart(api: SnoStationMemPluginApi, config: PluginConfig, retriever: MemoryRetriever, _store: MemoryStore, scopePolicy: ReturnType<typeof createScopePolicy>, recallHistory: Map<string, Map<string, number>>, turnCounter: Map<string, number>, event: PluginHookBeforeAgentStartEvent, ctx: PluginHookAgentContext, stateDir: string, telemetryUsage?: MemoryTelemetryUsageOutbox, signal?: AbortSignal): Promise<PluginHookBeforeAgentStartResult | undefined>;
+//#endregion