@graphorin/memory 0.5.0

package/dist/consolidator/phases/reflect.js

@@ -0,0 +1,287 @@
+import { withMemorySpan } from "../../internal/spans.js";
+import { newMemoryId } from "../../internal/id.js";
+
+//#region src/consolidator/phases/reflect.ts
+/** ExpeL starting salience for a freshly-synthesized insight. */
+const STARTING_SALIENCE = 2;
+/** How many recent episode summaries to show the salient-questions prompt. */
+const RECENT_CONTEXT_LIMIT = 20;
+const QUESTIONS_SYSTEM_PROMPT = [
+	"You are the reflection step (salient-questions) of a long-running personal-assistant memory.",
+	"Given a list of recent memories, name the few most salient, high-level questions whose",
+	"answers would most improve understanding of the user. Do NOT answer them; ask only what the",
+	"memories collectively raise. Return strictly JSON: { \"questions\": string[] }."
+].join(" ");
+const INSIGHT_SYSTEM_PROMPT = [
+	"You are the reflection step (insight-synthesis) of a long-running personal-assistant memory.",
+	"Given a salient question and the supporting evidence, synthesize ONE concise, higher-order",
+	"insight that the evidence collectively supports. Ground it ONLY in the supplied evidence; if",
+	"the evidence is insufficient, return an empty string. Do NOT invent facts. Return strictly",
+	"JSON: { \"insight\": string }."
+].join(" ");
+/**
+* Run the reflection pass. Idempotent w.r.t. failures — a parse miss or
+* empty synthesis simply yields no insight. Never throws on model
+* output; only storage errors propagate.
+*/
+async function runReflectionPass(deps) {
+	return withMemorySpan(deps.tracer, "memory.consolidate.reflect", deps.scope, { "consolidator.phase": "reflect" }, async (span) => {
+		const empty = (over = {}) => ({
+			triggered: false,
+			accumulatedImportance: 0,
+			questionsAsked: 0,
+			insightsCreated: 0,
+			tokens: 0,
+			costUsd: 0,
+			nextWatermark: deps.reflectionWatermark ?? null,
+			...over
+		});
+		if (deps.episodic === null) {
+			span.setAttributes({ "consolidator.reflect.skipped": "no-episodic" });
+			return empty();
+		}
+		if (deps.budget.snapshot().paused) {
+			span.setAttributes({ "consolidator.reflect.skipped": "budget" });
+			return empty();
+		}
+		const recentEpisodes = await deps.episodic.listRecent(deps.scope, 50, { includeQuarantined: true });
+		const watermark = deps.reflectionWatermark ?? null;
+		const fresh = watermark === null ? recentEpisodes : recentEpisodes.filter((e) => Date.parse(e.endedAt) > watermark);
+		const accumulated = fresh.reduce((sum, episode) => sum + (episode.importance ?? 0), 0);
+		span.setAttributes({
+			"consolidator.reflect.accumulated_importance": accumulated,
+			"consolidator.reflect.threshold": deps.importanceThreshold
+		});
+		if (accumulated < deps.importanceThreshold) {
+			span.setAttributes({ "consolidator.reflect.triggered": 0 });
+			return empty({ accumulatedImportance: accumulated });
+		}
+		const advancedWatermark = fresh.reduce((max, episode) => Math.max(max, Date.parse(episode.endedAt)), watermark ?? Number.NEGATIVE_INFINITY);
+		let tokens = 0;
+		let costUsd = 0;
+		const record = (usage) => {
+			const t = (usage.promptTokens ?? 0) + (usage.completionTokens ?? 0) + (usage.reasoningTokens ?? 0);
+			const c = deps.priceUsage?.({
+				promptTokens: usage.promptTokens ?? 0,
+				completionTokens: usage.completionTokens ?? 0
+			}) ?? 0;
+			tokens += t;
+			costUsd += c;
+			deps.budget.record({
+				phase: "deep",
+				tokens: t,
+				costUsd: c
+			});
+		};
+		const recentSummaries = fresh.slice(0, RECENT_CONTEXT_LIMIT).map((episode) => `- ${episode.summary}`).join("\n");
+		const questionsRes = await deps.provider.generate(buildQuestionsRequest(deps, recentSummaries));
+		record(questionsRes.usage);
+		const questions = parseQuestions(questionsRes.text).slice(0, Math.max(0, deps.maxQuestions));
+		span.setAttributes({ "consolidator.reflect.questions": questions.length });
+		const seenInsights = new Set((await deps.insights.list(deps.scope, {
+			includeQuarantined: true,
+			limit: 200
+		})).map((i) => normalizeInsightText(i.text)));
+		const nowFn = typeof deps.now === "function" ? deps.now : Date.now;
+		let insightsCreated = 0;
+		const created = [];
+		for (const question of questions) {
+			if (deps.budget.snapshot().paused) break;
+			const factHits = await deps.semantic.search(deps.scope, question, { topK: 5 });
+			const epHits = await deps.episodic.search(deps.scope, question, {
+				topK: 5,
+				includeQuarantined: true
+			});
+			const evidence = dedupeEvidence([...factHits.map((h) => ({
+				id: h.record.id,
+				text: h.record.text
+			})), ...epHits.map((h) => ({
+				id: h.record.id,
+				text: h.record.summary
+			}))]);
+			if (evidence.length === 0) continue;
+			if (deps.budget.snapshot().paused) break;
+			const insightRes = await deps.provider.generate(buildInsightRequest(deps, question, evidence));
+			record(insightRes.usage);
+			const text = parseInsight(insightRes.text);
+			if (text === null) continue;
+			const normalized = normalizeInsightText(text);
+			if (seenInsights.has(normalized)) continue;
+			seenInsights.add(normalized);
+			const iso = new Date(nowFn()).toISOString();
+			const insightId = newMemoryId("ins");
+			await deps.insights.insert({
+				id: insightId,
+				kind: "insight",
+				userId: deps.scope.userId,
+				...deps.scope.sessionId !== void 0 ? { sessionId: deps.scope.sessionId } : {},
+				...deps.scope.agentId !== void 0 ? { agentId: deps.scope.agentId } : {},
+				text,
+				cites: evidence.map((e) => e.id),
+				salience: STARTING_SALIENCE,
+				provenance: "reflection",
+				status: "quarantined",
+				sensitivity: "internal",
+				createdAt: iso,
+				updatedAt: iso
+			});
+			created.push(insightId);
+			insightsCreated += 1;
+		}
+		const freshIds = new Set(created);
+		for (const existing of await deps.insights.list(deps.scope, {
+			includeQuarantined: true,
+			limit: 500
+		})) {
+			if (freshIds.has(existing.id)) continue;
+			await deps.insights.bumpSalience(existing.id, -1, "reflection-pass-decay");
+		}
+		await deps.insights.prune(deps.scope);
+		span.setAttributes({
+			"consolidator.reflect.triggered": 1,
+			"consolidator.reflect.insights_created": insightsCreated,
+			"consolidator.reflect.tokens": tokens,
+			"consolidator.reflect.cost.usd": costUsd
+		});
+		return {
+			triggered: true,
+			accumulatedImportance: accumulated,
+			questionsAsked: questions.length,
+			insightsCreated,
+			tokens,
+			costUsd,
+			nextWatermark: Number.isFinite(advancedWatermark) ? advancedWatermark : watermark
+		};
+	});
+}
+/**
+* Normalise an insight for exact-dedup comparison — lowercased, punctuation
+* stripped, whitespace collapsed. Two insights that differ only in casing or
+* trailing punctuation collapse to the same key.
+*
+* @internal
+*/
+function normalizeInsightText(text) {
+	return text.toLowerCase().replace(/[^\p{L}\p{N}\s]/gu, " ").replace(/\s+/gu, " ").trim();
+}
+function buildQuestionsRequest(deps, recentSummaries) {
+	return {
+		messages: [{
+			role: "user",
+			content: [
+				"Recent memories:",
+				recentSummaries.length > 0 ? recentSummaries : "(none)",
+				"",
+				`Name up to ${deps.maxQuestions} salient questions.`
+			].join("\n")
+		}],
+		systemMessage: QUESTIONS_SYSTEM_PROMPT,
+		temperature: 0,
+		maxTokens: 512,
+		metadata: scopeMetadata(deps.scope),
+		outputType: { kind: "structured" }
+	};
+}
+function buildInsightRequest(deps, question, evidence) {
+	const evidenceBlock = evidence.map((e, i) => `[${i + 1}] (id=${e.id}) ${e.text}`).join("\n");
+	return {
+		messages: [{
+			role: "user",
+			content: [
+				`Question: ${question}`,
+				"",
+				"Evidence:",
+				evidenceBlock
+			].join("\n")
+		}],
+		systemMessage: INSIGHT_SYSTEM_PROMPT,
+		temperature: 0,
+		maxTokens: 512,
+		metadata: scopeMetadata(deps.scope),
+		outputType: { kind: "structured" }
+	};
+}
+function scopeMetadata(scope) {
+	return {
+		userId: scope.userId,
+		...scope.sessionId !== void 0 ? { sessionId: scope.sessionId } : {},
+		...scope.agentId !== void 0 ? { agentId: scope.agentId } : {}
+	};
+}
+function dedupeEvidence(items) {
+	const seen = /* @__PURE__ */ new Set();
+	const out = [];
+	for (const e of items) {
+		if (e.id.length === 0 || seen.has(e.id)) continue;
+		seen.add(e.id);
+		out.push(e);
+	}
+	return out;
+}
+/**
+* Parse the salient-questions response — accepts `{ questions: [...] }`
+* or a bare `[...]`, tolerating chatty / fenced output. Returns the
+* trimmed, non-empty string questions (possibly `[]`).
+*
+* @internal
+*/
+function parseQuestions(text) {
+	if (text === void 0 || text.length === 0) return [];
+	const parsed = tryParse(stripFence(text).trim());
+	if (parsed === void 0) return [];
+	const arr = Array.isArray(parsed) ? parsed : isRecord(parsed) && Array.isArray(parsed.questions) ? parsed.questions : null;
+	if (arr === null) return [];
+	return arr.filter((q) => typeof q === "string" && q.trim().length > 0).map((q) => q.trim());
+}
+/**
+* Parse the insight-synthesis response — accepts `{ insight: string }`
+* (or `{ text: string }`), tolerating chatty / fenced output. Returns
+* the trimmed insight text, or `null` when absent / empty (insufficient
+* evidence ⇒ no insight).
+*
+* @internal
+*/
+function parseInsight(text) {
+	if (text === void 0 || text.length === 0) return null;
+	const parsed = tryParse(stripFence(text).trim());
+	if (!isRecord(parsed)) return null;
+	const raw = typeof parsed.insight === "string" ? parsed.insight : null;
+	const fallback = typeof parsed.text === "string" ? parsed.text : null;
+	const value = raw ?? fallback;
+	if (value === null || value.trim().length === 0) return null;
+	return value.trim();
+}
+function tryParse(candidate) {
+	if (candidate.length === 0) return void 0;
+	try {
+		return JSON.parse(candidate);
+	} catch {
+		const obj = sliceBetween(candidate, "{", "}");
+		if (obj !== null) try {
+			return JSON.parse(obj);
+		} catch {}
+		const arr = sliceBetween(candidate, "[", "]");
+		if (arr !== null) try {
+			return JSON.parse(arr);
+		} catch {
+			return;
+		}
+		return;
+	}
+}
+function isRecord(value) {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function stripFence(text) {
+	return /^```[^\n]*\n([\s\S]*?)\n```/u.exec(text.trim())?.[1] ?? text;
+}
+function sliceBetween(text, open, close) {
+	const start = text.indexOf(open);
+	const end = text.lastIndexOf(close);
+	if (start < 0 || end < start) return null;
+	return text.slice(start, end + 1);
+}
+
+//#endregion
+export { runReflectionPass };
+//# sourceMappingURL=reflect.js.map

package/dist/consolidator/phases/reflect.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reflect.js","names":["created: string[]","out: Evidence[]"],"sources":["../../../src/consolidator/phases/reflect.ts"],"sourcesContent":["/**\n * Reflection pass (P1-1) — the deep phase's higher-order synthesis\n * step, following the Generative-Agents recipe. When the accumulated\n * importance of recent episodes crosses a threshold, ask the model for\n * the few most salient questions, retrieve evidence for each, and\n * synthesize an **insight** the evidence supports — recorded\n * quarantined, `provenance: 'reflection'`, and **citing the retrieved\n * memory ids** (citations are set by the framework from the actual\n * evidence, never chosen by the model, so they can never be\n * hallucinated). Insights start at ExpeL salience `2`; the pass prunes\n * any that have decayed to `0`.\n *\n * Runs after the deep-phase conflict drain (wired in the runtime\n * dispatch), reusing the same budget / lock / run-audit envelope. The\n * conflict-resolution logic in `deep.ts` is untouched.\n *\n * @packageDocumentation\n */\n\nimport type { Provider, ProviderRequest, SessionScope, Tracer } from '@graphorin/core';\nimport { newMemoryId } from '../../internal/id.js';\nimport { withMemorySpan } from '../../internal/spans.js';\nimport type { InsightMemoryStoreExt } from '../../internal/storage-adapter.js';\nimport type { EpisodicMemory } from '../../tiers/episodic-memory.js';\nimport type { SemanticMemory } from '../../tiers/semantic-memory.js';\nimport type { BudgetTracker } from '../budget.js';\n\n/** ExpeL starting salience for a freshly-synthesized insight. */\nconst STARTING_SALIENCE = 2;\n\n/** How many recent episode summaries to show the salient-questions prompt. */\nconst RECENT_CONTEXT_LIMIT = 20;\n\n/** Inputs accepted by {@link runReflectionPass}. */\nexport interface ReflectionDeps {\n  readonly provider: Provider;\n  readonly tracer: Tracer;\n  readonly scope: SessionScope;\n  /** Tier used to retrieve fact evidence for each salient question. */\n  readonly semantic: SemanticMemory;\n  /** Importance source + episode-evidence retrieval. `null` ⇒ pass is a no-op. */\n  readonly episodic: EpisodicMemory | null;\n  /** Insight write + salience surface. */\n  readonly insights: InsightMemoryStoreExt;\n  readonly budget: BudgetTracker;\n  /** Reflection fires only when accumulated episode importance ≥ this. */\n  readonly importanceThreshold: number;\n  /**\n   * `ended_at` (epoch ms) of the newest episode a prior pass already reflected\n   * on (MCON-13). The gate accumulates importance only from strictly-newer\n   * episodes, so a deep run with no new episodes never re-fires. `null` /\n   * absent ⇒ nothing reflected yet (accumulate over all recent episodes).\n   */\n  readonly reflectionWatermark?: number | null;\n  /** Upper bound on salient questions asked per pass. */\n  readonly maxQuestions: number;\n  readonly priceUsage?: (usage: { promptTokens: number; completionTokens: number }) => number;\n  /** Override the wall clock — used by tests. */\n  readonly now?: () => number;\n}\n\n/** Summary returned by {@link runReflectionPass}. */\nexport interface ReflectionOutcome {\n  /** True when accumulated importance crossed the threshold and the pass ran. */\n  readonly triggered: boolean;\n  readonly accumulatedImportance: number;\n  readonly questionsAsked: number;\n  readonly insightsCreated: number;\n  readonly tokens: number;\n  readonly costUsd: number;\n  /**\n   * Watermark to persist for the next pass (MCON-13): the `ended_at` (epoch\n   * ms) of the newest episode this pass reflected on, or the incoming\n   * watermark unchanged when the pass did not fire. The runtime persists it\n   * to `consolidator_state`.\n   */\n  readonly nextWatermark: number | null;\n}\n\nconst QUESTIONS_SYSTEM_PROMPT = [\n  'You are the reflection step (salient-questions) of a long-running personal-assistant memory.',\n  'Given a list of recent memories, name the few most salient, high-level questions whose',\n  'answers would most improve understanding of the user. Do NOT answer them; ask only what the',\n  'memories collectively raise. Return strictly JSON: { \"questions\": string[] }.',\n].join(' ');\n\nconst INSIGHT_SYSTEM_PROMPT = [\n  'You are the reflection step (insight-synthesis) of a long-running personal-assistant memory.',\n  'Given a salient question and the supporting evidence, synthesize ONE concise, higher-order',\n  'insight that the evidence collectively supports. Ground it ONLY in the supplied evidence; if',\n  'the evidence is insufficient, return an empty string. Do NOT invent facts. Return strictly',\n  'JSON: { \"insight\": string }.',\n].join(' ');\n\ninterface Evidence {\n  readonly id: string;\n  readonly text: string;\n}\n\n/**\n * Run the reflection pass. Idempotent w.r.t. failures — a parse miss or\n * empty synthesis simply yields no insight. Never throws on model\n * output; only storage errors propagate.\n */\nexport async function runReflectionPass(deps: ReflectionDeps): Promise<ReflectionOutcome> {\n  return withMemorySpan(\n    deps.tracer,\n    'memory.consolidate.reflect',\n    deps.scope,\n    { 'consolidator.phase': 'reflect' },\n    async (span) => {\n      const empty = (over: Partial<ReflectionOutcome> = {}): ReflectionOutcome => ({\n        triggered: false,\n        accumulatedImportance: 0,\n        questionsAsked: 0,\n        insightsCreated: 0,\n        tokens: 0,\n        costUsd: 0,\n        nextWatermark: deps.reflectionWatermark ?? null,\n        ...over,\n      });\n\n      if (deps.episodic === null) {\n        span.setAttributes({ 'consolidator.reflect.skipped': 'no-episodic' });\n        return empty();\n      }\n      if (deps.budget.snapshot().paused) {\n        span.setAttributes({ 'consolidator.reflect.skipped': 'budget' });\n        return empty();\n      }\n\n      // 1. Accumulated-importance gate. Recency, not relevance: list the most\n      //    recent episodes (MCON-1 — the old `'*'` FTS probe matched zero rows\n      //    on real SQLite). Auto-formed episodes (P1-2) land\n      //    quarantined, so importance accrues there — include them. Only count\n      //    episodes newer than the watermark so a pass with no new episodes\n      //    never re-fires the paid synthesis (MCON-13).\n      const recentEpisodes = await deps.episodic.listRecent(deps.scope, 50, {\n        includeQuarantined: true,\n      });\n      const watermark = deps.reflectionWatermark ?? null;\n      const fresh =\n        watermark === null\n          ? recentEpisodes\n          : recentEpisodes.filter((e) => Date.parse(e.endedAt) > watermark);\n      const accumulated = fresh.reduce((sum, episode) => sum + (episode.importance ?? 0), 0);\n      span.setAttributes({\n        'consolidator.reflect.accumulated_importance': accumulated,\n        'consolidator.reflect.threshold': deps.importanceThreshold,\n      });\n      if (accumulated < deps.importanceThreshold) {\n        span.setAttributes({ 'consolidator.reflect.triggered': 0 });\n        return empty({ accumulatedImportance: accumulated });\n      }\n      // The newest episode this pass will reflect on — persisted as the next\n      // watermark so subsequent passes skip everything up to here.\n      const advancedWatermark = fresh.reduce(\n        (max, episode) => Math.max(max, Date.parse(episode.endedAt)),\n        watermark ?? Number.NEGATIVE_INFINITY,\n      );\n\n      let tokens = 0;\n      let costUsd = 0;\n      const record = (usage: {\n        promptTokens?: number;\n        completionTokens?: number;\n        reasoningTokens?: number;\n      }): void => {\n        const t =\n          (usage.promptTokens ?? 0) + (usage.completionTokens ?? 0) + (usage.reasoningTokens ?? 0);\n        const c =\n          deps.priceUsage?.({\n            promptTokens: usage.promptTokens ?? 0,\n            completionTokens: usage.completionTokens ?? 0,\n          }) ?? 0;\n        tokens += t;\n        costUsd += c;\n        deps.budget.record({ phase: 'deep', tokens: t, costUsd: c });\n      };\n\n      // 2. Salient questions over the new (post-watermark) memories.\n      const recentSummaries = fresh\n        .slice(0, RECENT_CONTEXT_LIMIT)\n        .map((episode) => `- ${episode.summary}`)\n        .join('\\n');\n      const questionsRes = await deps.provider.generate(\n        buildQuestionsRequest(deps, recentSummaries),\n      );\n      record(questionsRes.usage);\n      const questions = parseQuestions(questionsRes.text).slice(0, Math.max(0, deps.maxQuestions));\n      span.setAttributes({ 'consolidator.reflect.questions': questions.length });\n\n      // Pre-filter new insights against already-stored ones so a re-fire over\n      // overlapping evidence does not write near-duplicates (MCON-13). Offline\n      // and embedding-free: normalised exact match, the insight analogue of\n      // the conflict pipeline's stage-1 dedup.\n      const seenInsights = new Set(\n        (await deps.insights.list(deps.scope, { includeQuarantined: true, limit: 200 })).map((i) =>\n          normalizeInsightText(i.text),\n        ),\n      );\n\n      const nowFn = typeof deps.now === 'function' ? deps.now : Date.now;\n      let insightsCreated = 0;\n      const created: string[] = [];\n      for (const question of questions) {\n        if (deps.budget.snapshot().paused) break;\n\n        // 3. Retrieve evidence. Facts are trustworthy (active only);\n        //    episodes include the quarantined auto-formed ones.\n        const factHits = await deps.semantic.search(deps.scope, question, { topK: 5 });\n        const epHits = await deps.episodic.search(deps.scope, question, {\n          topK: 5,\n          includeQuarantined: true,\n        });\n        const evidence = dedupeEvidence([\n          ...factHits.map((h) => ({ id: h.record.id, text: h.record.text })),\n          ...epHits.map((h) => ({ id: h.record.id, text: h.record.summary })),\n        ]);\n        // Citations are mandatory — no evidence ⇒ no insight.\n        if (evidence.length === 0) continue;\n\n        // 4. Synthesize an insight grounded in that evidence.\n        if (deps.budget.snapshot().paused) break;\n        const insightRes = await deps.provider.generate(\n          buildInsightRequest(deps, question, evidence),\n        );\n        record(insightRes.usage);\n        const text = parseInsight(insightRes.text);\n        if (text === null) continue;\n\n        // Skip near-duplicates of an already-stored insight (and of one just\n        // written this pass).\n        const normalized = normalizeInsightText(text);\n        if (seenInsights.has(normalized)) continue;\n        seenInsights.add(normalized);\n\n        const iso = new Date(nowFn()).toISOString();\n        const insightId = newMemoryId('ins');\n        await deps.insights.insert({\n          id: insightId,\n          kind: 'insight',\n          userId: deps.scope.userId,\n          ...(deps.scope.sessionId !== undefined ? { sessionId: deps.scope.sessionId } : {}),\n          ...(deps.scope.agentId !== undefined ? { agentId: deps.scope.agentId } : {}),\n          text,\n          // cites = the actual retrieved evidence ids (framework-set).\n          cites: evidence.map((e) => e.id),\n          salience: STARTING_SALIENCE,\n          provenance: 'reflection',\n          status: 'quarantined',\n          sensitivity: 'internal',\n          createdAt: iso,\n          updatedAt: iso,\n        });\n        created.push(insightId);\n        insightsCreated += 1;\n      }\n\n      // 5. ExpeL forgetting (MCON-16): decay every existing insight by 1\n      // per reflection pass. Retrieval bumps +1 (InsightMemory.search),\n      // so an insight recalled since the last pass nets level-or-better\n      // while an unused one slides toward the prune floor — starting\n      // salience 2 ⇒ pruned after two idle passes. Fresh insights from\n      // THIS pass are exempt (they were inserted above at full salience\n      // and have had no retrieval window yet).\n      const freshIds = new Set(created);\n      for (const existing of await deps.insights.list(deps.scope, {\n        includeQuarantined: true,\n        limit: 500,\n      })) {\n        if (freshIds.has(existing.id)) continue;\n        await deps.insights.bumpSalience(existing.id, -1, 'reflection-pass-decay');\n      }\n      await deps.insights.prune(deps.scope);\n\n      span.setAttributes({\n        'consolidator.reflect.triggered': 1,\n        'consolidator.reflect.insights_created': insightsCreated,\n        'consolidator.reflect.tokens': tokens,\n        'consolidator.reflect.cost.usd': costUsd,\n      });\n      return {\n        triggered: true,\n        accumulatedImportance: accumulated,\n        questionsAsked: questions.length,\n        insightsCreated,\n        tokens,\n        costUsd,\n        // Advance past everything reflected on this pass. `advancedWatermark`\n        // is finite here (the gate fired ⇒ `fresh` is non-empty).\n        nextWatermark: Number.isFinite(advancedWatermark) ? advancedWatermark : watermark,\n      };\n    },\n  );\n}\n\n/**\n * Normalise an insight for exact-dedup comparison — lowercased, punctuation\n * stripped, whitespace collapsed. Two insights that differ only in casing or\n * trailing punctuation collapse to the same key.\n *\n * @internal\n */\nexport function normalizeInsightText(text: string): string {\n  return text\n    .toLowerCase()\n    .replace(/[^\\p{L}\\p{N}\\s]/gu, ' ')\n    .replace(/\\s+/gu, ' ')\n    .trim();\n}\n\nfunction buildQuestionsRequest(deps: ReflectionDeps, recentSummaries: string): ProviderRequest {\n  const userBlock = [\n    'Recent memories:',\n    recentSummaries.length > 0 ? recentSummaries : '(none)',\n    '',\n    `Name up to ${deps.maxQuestions} salient questions.`,\n  ].join('\\n');\n  return {\n    messages: [{ role: 'user', content: userBlock }],\n    systemMessage: QUESTIONS_SYSTEM_PROMPT,\n    temperature: 0,\n    // MCON-14: per-call output cap — a short question list.\n    maxTokens: 512,\n    metadata: scopeMetadata(deps.scope),\n    outputType: { kind: 'structured' },\n  };\n}\n\nfunction buildInsightRequest(\n  deps: ReflectionDeps,\n  question: string,\n  evidence: ReadonlyArray<Evidence>,\n): ProviderRequest {\n  const evidenceBlock = evidence.map((e, i) => `[${i + 1}] (id=${e.id}) ${e.text}`).join('\\n');\n  const userBlock = [`Question: ${question}`, '', 'Evidence:', evidenceBlock].join('\\n');\n  return {\n    messages: [{ role: 'user', content: userBlock }],\n    systemMessage: INSIGHT_SYSTEM_PROMPT,\n    temperature: 0,\n    // MCON-14: per-call output cap — one insight object.\n    maxTokens: 512,\n    metadata: scopeMetadata(deps.scope),\n    outputType: { kind: 'structured' },\n  };\n}\n\nfunction scopeMetadata(scope: SessionScope): Record<string, string> {\n  return {\n    userId: scope.userId,\n    ...(scope.sessionId !== undefined ? { sessionId: scope.sessionId } : {}),\n    ...(scope.agentId !== undefined ? { agentId: scope.agentId } : {}),\n  };\n}\n\nfunction dedupeEvidence(items: ReadonlyArray<Evidence>): Evidence[] {\n  const seen = new Set<string>();\n  const out: Evidence[] = [];\n  for (const e of items) {\n    if (e.id.length === 0 || seen.has(e.id)) continue;\n    seen.add(e.id);\n    out.push(e);\n  }\n  return out;\n}\n\n/**\n * Parse the salient-questions response — accepts `{ questions: [...] }`\n * or a bare `[...]`, tolerating chatty / fenced output. Returns the\n * trimmed, non-empty string questions (possibly `[]`).\n *\n * @internal\n */\nexport function parseQuestions(text: string | undefined): string[] {\n  if (text === undefined || text.length === 0) return [];\n  const candidate = stripFence(text).trim();\n  const parsed = tryParse(candidate);\n  if (parsed === undefined) return [];\n  const arr = Array.isArray(parsed)\n    ? parsed\n    : isRecord(parsed) && Array.isArray(parsed.questions)\n      ? parsed.questions\n      : null;\n  if (arr === null) return [];\n  return arr\n    .filter((q): q is string => typeof q === 'string' && q.trim().length > 0)\n    .map((q) => q.trim());\n}\n\n/**\n * Parse the insight-synthesis response — accepts `{ insight: string }`\n * (or `{ text: string }`), tolerating chatty / fenced output. Returns\n * the trimmed insight text, or `null` when absent / empty (insufficient\n * evidence ⇒ no insight).\n *\n * @internal\n */\nexport function parseInsight(text: string | undefined): string | null {\n  if (text === undefined || text.length === 0) return null;\n  const candidate = stripFence(text).trim();\n  const parsed = tryParse(candidate);\n  if (!isRecord(parsed)) return null;\n  const raw = typeof parsed.insight === 'string' ? parsed.insight : null;\n  const fallback = typeof parsed.text === 'string' ? parsed.text : null;\n  const value = raw ?? fallback;\n  if (value === null || value.trim().length === 0) return null;\n  return value.trim();\n}\n\nfunction tryParse(candidate: string): unknown {\n  if (candidate.length === 0) return undefined;\n  try {\n    return JSON.parse(candidate);\n  } catch {\n    const obj = sliceBetween(candidate, '{', '}');\n    if (obj !== null) {\n      try {\n        return JSON.parse(obj);\n      } catch {\n        // fall through to array attempt\n      }\n    }\n    const arr = sliceBetween(candidate, '[', ']');\n    if (arr !== null) {\n      try {\n        return JSON.parse(arr);\n      } catch {\n        return undefined;\n      }\n    }\n    return undefined;\n  }\n}\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n  return value !== null && typeof value === 'object' && !Array.isArray(value);\n}\n\nfunction stripFence(text: string): string {\n  const match = /^```[^\\n]*\\n([\\s\\S]*?)\\n```/u.exec(text.trim());\n  return match?.[1] ?? text;\n}\n\nfunction sliceBetween(text: string, open: string, close: string): string | null {\n  const start = text.indexOf(open);\n  const end = text.lastIndexOf(close);\n  if (start < 0 || end < start) return null;\n  return text.slice(start, end + 1);\n}\n"],"mappings":"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"}

package/dist/consolidator/phases/standard.d.ts

@@ -0,0 +1,8 @@
+import "../../internal/storage-adapter.js";
+import "../../internal/contextualize.js";
+import "../../tiers/episodic-memory.js";
+import "../../tiers/semantic-memory.js";
+import "../types.js";
+import "../budget.js";
+import "../noise-filter.js";
+import { Provider, SessionScope, Tracer } from "@graphorin/core";