@graphorin/memory 0.5.0

package/dist/context-engine/engine.d.ts

@@ -0,0 +1,258 @@
+import { ContentAnnotation } from "./annotations.js";
+import { ContextLocalePack, PartialContextLocalePack } from "./locale-packs/types.js";
+import { AutoRecallStrategy, AutoRecallTriggerResult } from "./auto-recall.js";
+import { ContextTokenCounter } from "./token-counter.js";
+import { CompactionConfig, CompactionResult, CompactionSource, CompactionSummarizer } from "./compaction/types.js";
+import { PrivacyDecisionReason } from "./privacy-filter.js";
+import { MemoryBaseMode, SkillMetadataCard } from "./templates/composer.js";
+import { AllocationResult } from "./token-budget.js";
+import { Memory } from "../facade.js";
+import { LocalProviderTrust, Message, MessageContent, Sensitivity, SessionScope, TokenCounter } from "@graphorin/core";
+
+//#region src/context-engine/engine.d.ts
+
+/**
+ * Per-layer cap configuration. Mirrors the documented
+ * `ContextEngineConfig.layers.*` fields.
+ *
+ * @stable
+ */
+interface LayerConfig {
+  readonly enabled?: boolean;
+  readonly cap?: number;
+}
+/**
+ * Auto-recall config knob. `false` disables; `{ topK }` enables
+ * the heuristic with a bounded top-K.
+ *
+ * @stable
+ */
+type AutoRecallConfig = false | {
+  readonly topK?: number;
+  /**
+   * Minimum fused score a hit must reach to be injected. **Default `0`**
+   * (CE-4) — `topK` already bounds the volume. The scale is
+   * reranker-dependent: the default RRF reranker fuses the FTS + vector
+   * candidate lists as `1/(60 + rank)` per list, so scores top out near
+   * `2/(60 + 1) ≈ 0.033` — any positive default would silently drop every
+   * hit. Set this only when calibrating against a known reranker's scale.
+   */
+  readonly threshold?: number;
+  readonly strategy?: AutoRecallStrategy;
+};
+/**
+ * Privacy block of the engine config.
+ *
+ * @stable
+ */
+interface PrivacyConfig {
+  readonly cloudUploadConsent?: boolean;
+  readonly defaultSensitivity?: Sensitivity;
+  readonly providerAcceptsSensitivity?: ReadonlyArray<Sensitivity>;
+  readonly providerTrust?: LocalProviderTrust;
+}
+/**
+ * Configuration accepted by {@link createContextEngine}.
+ *
+ * @stable
+ */
+interface ContextEngineConfig {
+  /**
+   * Layer 1 base-template mode. `'full'` (default) ships the
+   * verbose ~250-350 token narrative aimed at general LLMs;
+   * `'minimal'` opts top-tier models into the ~80-120 token
+   * compact form.
+   */
+  readonly memoryBaseMode?: MemoryBaseMode;
+  /** Default `'en'`. Pluggable via `defineContextLocalePack`. */
+  readonly locale?: string | ContextLocalePack | PartialContextLocalePack;
+  /** Per-layer enable / cap overrides. */
+  readonly layers?: {
+    readonly identity?: LayerConfig;
+    readonly memoryMetadata?: LayerConfig;
+    readonly activeRules?: LayerConfig;
+    readonly activeSkills?: LayerConfig;
+    readonly workingBlocks?: LayerConfig;
+    readonly autoRecall?: LayerConfig & {
+      readonly topK?: number;
+      readonly threshold?: number;
+    };
+  };
+  /** Auto-recall trigger configuration. Default `false`. */
+  readonly factsAutoRecall?: AutoRecallConfig;
+  /** Privacy-filter configuration. */
+  readonly privacy?: PrivacyConfig;
+  /** Hard token budget. Default `Number.POSITIVE_INFINITY` (no global cap). */
+  readonly maxContextTokens?: number;
+  /** Tokens reserved for the model's response. Default `4096`. */
+  readonly reservedForResponse?: number;
+  /** Tokens reserved for the compaction summarizer call. Default `8192`. */
+  readonly reservedForCompaction?: number;
+  /** Pluggable token counter. Default heuristic (chars/4). */
+  readonly tokenCounter?: TokenCounter | ContextTokenCounter;
+  /** Auto-compaction configuration (RB-46). */
+  readonly compaction?: false | CompactionConfig;
+  /** Active provider's context window; required when compaction is enabled. */
+  readonly providerContextWindow?: number;
+  /** Default summarizer adapter the auto-trigger uses. */
+  readonly summarizer?: CompactionSummarizer;
+  /** Wall clock for tests + deterministic compaction. */
+  readonly now?: () => number;
+}
+/**
+ * Per-call runtime context handed to {@link ContextEngine.assemble}.
+ *
+ * @stable
+ */
+interface AssembleInput {
+  readonly scope: SessionScope;
+  readonly agentId: string;
+  readonly sessionId: string;
+  readonly runId: string;
+  readonly agentInstructions?: string;
+  readonly skills?: ReadonlyArray<SkillMetadataCard>;
+  readonly proceduralActivation?: {
+    readonly topic?: string;
+    readonly tags?: ReadonlyArray<string>;
+  };
+  readonly lastUserMessage?: string;
+  readonly autoRecallStrategyOverride?: AutoRecallStrategy;
+  /**
+   * Optional inbound-trust annotations carried by upstream
+   * messages (`session_messages` rows tagged by Phase 12 / Phase
+   * 07 / Phase 09). When at least one part has `inboundTrust !==
+   * 'trusted' && inboundTrust !== 'n/a'`, the per-step preamble
+   * fires (see RB-43 / DEC-159).
+   */
+  readonly upstreamAnnotations?: ReadonlyArray<ContentAnnotation>;
+}
+/**
+ * Single annotated `MessageContent` part assembled by the engine.
+ *
+ * @stable
+ */
+interface AnnotatedPart {
+  readonly content: MessageContent;
+  readonly annotation: ContentAnnotation;
+}
+/**
+ * Output of {@link ContextEngine.assemble}.
+ *
+ * @stable
+ */
+interface AssembledPrompt {
+  /** Single system message ready for `provider.stream(...)`. */
+  readonly systemMessage: {
+    readonly role: 'system';
+    readonly content: string;
+  };
+  /**
+   * Per-part annotations, in the same order as the assembled
+   * system content. Span-only — never serialized to the wire payload.
+   */
+  readonly annotations: ReadonlyArray<AnnotatedPart>;
+  /**
+   * Per-layer allocation snapshot. Surfaced for tests + diagnostics.
+   */
+  readonly layerAllocation: AllocationResult;
+  /** Whether the per-step inbound preamble fragment fired this assembly. */
+  readonly inboundPreambleFired: boolean;
+  /** Privacy-filter counters surfaced to the metadata block. */
+  readonly privacyCounters: Readonly<Record<PrivacyDecisionReason, number>>;
+  /** Resolved locale id (`'en'` for the default; custom otherwise). */
+  readonly localeId: string;
+  /** Resolved memory base mode. */
+  readonly memoryBaseMode: MemoryBaseMode;
+  /** Whether auto-recall was triggered this assembly. */
+  readonly autoRecall: AutoRecallTriggerResult;
+}
+/**
+ * Public surface of the {@link ContextEngine} instance returned by
+ * {@link createContextEngine}.
+ *
+ * @stable
+ */
+interface ContextEngine {
+  /** Assemble the layered system prompt for a single step. */
+  assemble(memory: Memory, input: AssembleInput): Promise<AssembledPrompt>;
+  /**
+   * Trigger evaluation primitive used by Phase 12 (agent runtime)
+   * at the top of every step. Returns `true` when the in-flight
+   * buffer's token count crosses the per-provider trigger
+   * threshold. Pass `precomputedTokens` to amortize the count
+   * via the per-message cache surfaced by
+   * `SessionMemoryStoreExt.totalCachedTokens(scope)` (DEC-131) —
+   * the production hot path is an O(1) comparison when the cache
+   * is warm.
+   */
+  shouldCompact(messages: ReadonlyArray<Message>, options?: {
+    readonly precomputedTokens?: number;
+  }): Promise<boolean>;
+  /**
+   * Run a compaction call. Phase 12 calls this when the trigger
+   * fires (`source: 'auto-trigger'`) or the operator invokes
+   * `agent.compact(...)` (`source: 'manual'`).
+   */
+  compactNow(input: {
+    readonly scope: SessionScope;
+    readonly runId: string;
+    readonly sessionId: string;
+    readonly agentId: string;
+    readonly source: CompactionSource;
+    readonly messages: ReadonlyArray<Message>;
+    readonly memory: Memory;
+    readonly summarizer?: CompactionSummarizer;
+    /** Per-call override of the strategy's preserve-recent count (CE-3). */
+    readonly preserveRecentTurns?: number;
+    /** Topic/tags narrowing for the procedural-rules re-anchor hook (CE-6). */
+    readonly procedural?: {
+      readonly topic?: string;
+      readonly tags?: ReadonlyArray<string>;
+    };
+    readonly signal?: AbortSignal;
+  }): Promise<{
+    readonly result: CompactionResult;
+    readonly extraContent: ReadonlyArray<MessageContent>;
+    readonly hookFailures: ReadonlyArray<{
+      readonly hookName: string;
+      readonly reason: string;
+    }>;
+  }>;
+  /** Resolved configuration snapshot. */
+  config(): ResolvedContextEngineConfig;
+}
+/**
+ * Resolved configuration snapshot returned by
+ * {@link ContextEngine.config}.
+ *
+ * @stable
+ */
+interface ResolvedContextEngineConfig {
+  readonly memoryBaseMode: MemoryBaseMode;
+  readonly localeId: string;
+  readonly maxContextTokens: number;
+  readonly reservedForResponse: number;
+  readonly reservedForCompaction: number;
+  readonly compactionEnabled: boolean;
+  /**
+   * Whether compaction can actually fire (CE-12): `compactionEnabled` **and** a
+   * `providerContextWindow` was supplied. `compactionEnabled: true` with
+   * `compactionEffective: false` is the honest signal that compaction is
+   * configured-on but a no-op for want of a context window.
+   */
+  readonly compactionEffective: boolean;
+  readonly compactionThresholdTokens: number;
+  readonly providerContextWindow: number | null;
+  readonly providerTrust: LocalProviderTrust;
+  readonly cloudUploadConsent: boolean;
+  readonly defaultSensitivity: Sensitivity;
+}
+/**
+ * Build a ContextEngine instance from the supplied configuration.
+ *
+ * @stable
+ */
+declare function createContextEngine(config?: ContextEngineConfig): ContextEngine;
+//#endregion
+export { AnnotatedPart, AssembleInput, AssembledPrompt, AutoRecallConfig, ContextEngine, ContextEngineConfig, LayerConfig, PrivacyConfig, ResolvedContextEngineConfig, createContextEngine };
+//# sourceMappingURL=engine.d.ts.map

package/dist/context-engine/engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","names":[],"sources":["../../src/context-engine/engine.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;;;;;;;;AAwLA;AACkB,UA3FD,WAAA,CA2FC;EAKgB,SAAA,OAAA,CAAA,EAAA,OAAA;EAAd,SAAA,GAAA,CAAA,EAAA,MAAA;;;;;;AAsBpB;AAUA;AAOsC,KA5H1B,gBAAA,GA4H0B,KAAA,GAAA;EAAd,SAAA,IAAA,CAAA,EAAA,MAAA;EAII;;;;;;;AAmB5B;EAEmB,SAAA,SAAA,CAAA,EAAA,MAAA;EAAe,SAAA,QAAA,CAAA,EAxIR,kBAwIQ;CAAwB;;;;;;AAyBrC,UAzJJ,aAAA,CAyJI;EACgB,SAAA,kBAAA,CAAA,EAAA,OAAA;EAAd,SAAA,kBAAA,CAAA,EAxJS,WAwJT;EACF,SAAA,0BAAA,CAAA,EAxJmB,aAwJnB,CAxJiC,WAwJjC,CAAA;EACK,SAAA,aAAA,CAAA,EAxJC,kBAwJD;;;;;;;AAMpB,UAtJW,mBAAA,CAsJX;EAMM;;AASZ;;;;EAkB0C,SAAA,cAAA,CAAA,EAhLd,cAgLc;EAgE1B;6BA9Oa,oBAAoB;;;wBAGzB;8BACM;2BACH;4BACC;6BACC;0BACH;;;;;;6BAGG;;qBAER;;;;;;;;0BAQK,eAAe;;gCAET;;;;wBAIR;;;;;;;;;UAUP,aAAA;kBACC;;;;;oBAKE,cAAc;;;oBAGd;;;wCAGoB;;;;;;;;iCAQP,cAAc;;;;;;;UAQ9B,aAAA;oBACG;uBACG;;;;;;;UAQN,eAAA;;;;;;;;;;wBAOO,cAAc;;;;4BAIV;;;;4BAIA,SAAS,OAAO;;;;2BAIjB;;uBAEJ;;;;;;;;UASN,aAAA;;mBAEE,eAAe,gBAAgB,QAAQ;;;;;;;;;;;0BAY5C,cAAc;;MAEvB;;;;;;;oBAOe;;;;qBAIC;uBACE,cAAc;qBAChB;0BACK;;;;;;sBAI2C;;sBAC/C;MAChB;qBACe;2BACM,cAAc;2BACd;;;;;;YAGf;;;;;;;;UASK,2BAAA;2BACU;;;;;;;;;;;;;;;0BAeD;;+BAEK;;;;;;;iBAgEf,mBAAA,UAA4B,sBAA2B"}

package/dist/context-engine/engine.js

@@ -0,0 +1,424 @@
+import { annotate, shouldFireInboundPreamble } from "./annotations.js";
+import { defaultLocaleHeuristicStrategy } from "./auto-recall.js";
+import { HEURISTIC_TOKEN_COUNTER, adaptTokenCounter, countMessageTokens } from "./token-counter.js";
+import { DEFAULT_PRESERVE_RECENT_TURNS, executeCompaction } from "./compaction/compactor.js";
+import { reanchorPersonaBlock } from "./compaction/hooks/reanchor-persona-block.js";
+import { reanchorPinnedFacts } from "./compaction/hooks/reanchor-pinned-facts.js";
+import { reanchorProjectRules } from "./compaction/hooks/reanchor-project-rules.js";
+import { resolveAutoCompactionDefault, resolveTriggerThreshold } from "./compaction/thresholds.js";
+import "./compaction/index.js";
+import { enLocalePack } from "./locale-packs/en.js";
+import "./locale-packs/index.js";
+import { resolveLocalePack } from "./locale-packs/resolver.js";
+import { renderMetadataBlock } from "./metadata.js";
+import { decide } from "./privacy-filter.js";
+import { composeInboundPreamble, composeLayer1, composeLayer2, composeLayer4Skills } from "./templates/composer.js";
+import { allocate } from "./token-budget.js";
+
+//#region src/context-engine/engine.ts
+const DEFAULT_LAYER_CAPS = {
+	identity: void 0,
+	memoryMetadata: void 0,
+	activeRules: void 0,
+	activeSkills: void 0,
+	workingBlocks: void 0,
+	autoRecall: void 0
+};
+let compactionIneffectiveWarned = false;
+let heuristicCounterWarned = false;
+/** Emit the "compaction enabled but ineffective" warning at most once (CE-12). */
+function warnCompactionIneffective(message) {
+	if (compactionIneffectiveWarned) return;
+	compactionIneffectiveWarned = true;
+	process.stderr.write(`[graphorin/memory] ${message}\n`);
+}
+/**
+* Emission order for the assembled layers — deliberately **distinct from the
+* truncation priority ladder** (CE-9). Allocation still trims by
+* `DEFAULT_LAYER_PRIORITY` (lowest priority first), but layers are *emitted* in
+* this order so the volatile blocks that change every turn (`memoryMetadata`'s
+* counts, `autoRecall`'s injected facts) sit **after** the stable Layer 1-4
+* prefix (identity / rules / blocks / skills). That keeps the provider's — and a
+* local llama.cpp / vLLM server's — KV-cache breakpoint real: the prefix stays
+* byte-identical across turns even as the message count and recalled facts move.
+*/
+const LAYER_EMIT_ORDER = Object.freeze({
+	identity: 0,
+	activeRules: 1,
+	workingBlocks: 2,
+	activeSkills: 3,
+	memoryMetadata: 4,
+	autoRecall: 5
+});
+/**
+* Build a ContextEngine instance from the supplied configuration.
+*
+* @stable
+*/
+function createContextEngine(config = {}) {
+	const memoryBaseMode = config.memoryBaseMode ?? "full";
+	const localeInput = config.locale;
+	const localePack = resolvePackInput(localeInput);
+	const localeId = localePack.id;
+	const layerCfg = config.layers ?? {};
+	const layersEnabled = {
+		identity: layerCfg.identity?.enabled ?? true,
+		memoryMetadata: layerCfg.memoryMetadata?.enabled ?? true,
+		activeRules: layerCfg.activeRules?.enabled ?? true,
+		activeSkills: layerCfg.activeSkills?.enabled ?? true,
+		workingBlocks: layerCfg.workingBlocks?.enabled ?? true,
+		autoRecall: layerCfg.autoRecall?.enabled ?? true
+	};
+	const layerCaps = {
+		identity: layerCfg.identity?.cap ?? DEFAULT_LAYER_CAPS.identity,
+		memoryMetadata: layerCfg.memoryMetadata?.cap ?? DEFAULT_LAYER_CAPS.memoryMetadata,
+		activeRules: layerCfg.activeRules?.cap ?? DEFAULT_LAYER_CAPS.activeRules,
+		activeSkills: layerCfg.activeSkills?.cap ?? DEFAULT_LAYER_CAPS.activeSkills,
+		workingBlocks: layerCfg.workingBlocks?.cap ?? DEFAULT_LAYER_CAPS.workingBlocks,
+		autoRecall: layerCfg.autoRecall?.cap ?? DEFAULT_LAYER_CAPS.autoRecall
+	};
+	const factsAutoRecall = config.factsAutoRecall ?? false;
+	const reservedForResponse = config.reservedForResponse ?? 4096;
+	const reservedForCompaction = config.reservedForCompaction ?? 8192;
+	const maxContextTokens = config.maxContextTokens ?? Number.POSITIVE_INFINITY;
+	const tokenCounter = config.tokenCounter ? "count" in config.tokenCounter ? adaptTokenCounter(config.tokenCounter) : config.tokenCounter : HEURISTIC_TOKEN_COUNTER;
+	if (config.tokenCounter === void 0 && typeof config.providerContextWindow === "number" && !heuristicCounterWarned) {
+		heuristicCounterWarned = true;
+		process.stderr.write("[graphorin/memory] context-engine token counts use the built-in heuristic (chars/4 + dense-script). For production budgeting against a real provider window, pass `contextEngine.tokenCounter` (e.g. the provider package JsTiktokenCounter).\n");
+	}
+	const privacy = config.privacy ?? {};
+	const defaultSensitivity = privacy.defaultSensitivity ?? "internal";
+	const providerTrust = privacy.providerTrust ?? "public-tls";
+	const cloudUploadConsent = privacy.cloudUploadConsent ?? false;
+	const heuristicStrategy = defaultLocaleHeuristicStrategy(localePack);
+	const compactionInput = config.compaction;
+	const compactionAutoDefault = resolveAutoCompactionDefault(providerTrust);
+	const compactionEnabled = compactionInput === false ? false : compactionInput === void 0 ? compactionAutoDefault === "enabled" : compactionInput.trigger !== "never";
+	const providerContextWindow = config.providerContextWindow ?? null;
+	const triggerSpec = compactionInput === false || compactionInput === void 0 ? void 0 : compactionInput.trigger;
+	const compactionThresholdTokens = compactionEnabled && providerContextWindow !== null ? resolveTriggerThreshold({
+		contextWindow: providerContextWindow,
+		...triggerSpec !== void 0 ? { trigger: triggerSpec } : {},
+		reservedForResponse,
+		reservedForCompaction
+	}) : Number.POSITIVE_INFINITY;
+	const compactionEffective = compactionEnabled && providerContextWindow !== null;
+	if (compactionEnabled && providerContextWindow === null) {
+		const message = "context-engine compaction is enabled but `providerContextWindow` is not set, so the trigger threshold is Infinity and compaction will never fire. Pass `providerContextWindow` (your model's context window, in tokens) — auto-detection from the provider is not implemented.";
+		if (compactionInput !== void 0 && compactionInput !== false) throw new Error(`[graphorin/memory] ${message}`);
+		warnCompactionIneffective(message);
+	}
+	const compactionStrategy = compactionInput === false || compactionInput === void 0 || compactionInput.strategy === void 0 ? {
+		kind: "summarize-old-preserve-recent",
+		preserveRecentTurns: 6,
+		templateName: "summary-9-section"
+	} : compactionInput.strategy;
+	const compactionMinReclaimTokens = triggerSpec !== void 0 && triggerSpec !== "never" ? Math.max(0, triggerSpec.minReclaimTokens ?? 0) : 0;
+	const reclaimPreserveTurns = compactionStrategy.kind === "summarize-old-preserve-recent" ? compactionStrategy.preserveRecentTurns ?? DEFAULT_PRESERVE_RECENT_TURNS : compactionStrategy.kind === "clear-old-tool-results" && typeof compactionStrategy.summarizeFallback === "object" ? compactionStrategy.summarizeFallback.preserveRecentTurns ?? DEFAULT_PRESERVE_RECENT_TURNS : DEFAULT_PRESERVE_RECENT_TURNS;
+	const compactionHooks = resolveDefaultHooks(compactionInput === false || compactionInput === void 0 ? void 0 : compactionInput.postCompactionHooks);
+	const summarizer = config.summarizer;
+	const now = config.now ?? Date.now;
+	const resolvedConfig = Object.freeze({
+		memoryBaseMode,
+		localeId,
+		maxContextTokens,
+		reservedForResponse,
+		reservedForCompaction,
+		compactionEnabled,
+		compactionEffective,
+		compactionThresholdTokens,
+		providerContextWindow,
+		providerTrust,
+		cloudUploadConsent,
+		defaultSensitivity
+	});
+	async function assemble(memory, input) {
+		const layer1Text = layersEnabled.identity ? composeLayer1(localePack, memoryBaseMode) : "";
+		const layer2Text = composeLayer2(input.agentInstructions);
+		const blocks = await memory.working.list(input.scope);
+		const blocksKept = [];
+		const privacyCounters = {
+			allowed: 0,
+			"no-cloud-upload-consent": 0,
+			"provider-rejects-internal": 0,
+			"provider-rejects-secret": 0
+		};
+		for (const block of blocks) {
+			const decision = decide(block.sensitivity, {
+				...privacy.providerAcceptsSensitivity !== void 0 ? { providerAcceptsSensitivity: privacy.providerAcceptsSensitivity } : {},
+				providerTrust,
+				cloudUploadConsent,
+				defaultSensitivity
+			});
+			privacyCounters[decision.reason] += 1;
+			if (decision.decision === "pass") blocksKept.push(block);
+		}
+		const layer3Text = layersEnabled.workingBlocks ? renderWorkingBlocks(blocksKept) : "";
+		const rules = await memory.procedural.activate(input.scope, input.proceduralActivation ?? {});
+		const rulesKept = [];
+		for (const rule of rules) {
+			const decision = decide(rule.sensitivity, {
+				...privacy.providerAcceptsSensitivity !== void 0 ? { providerAcceptsSensitivity: privacy.providerAcceptsSensitivity } : {},
+				providerTrust,
+				cloudUploadConsent,
+				defaultSensitivity
+			});
+			privacyCounters[decision.reason] += 1;
+			if (decision.decision === "pass") rulesKept.push(rule);
+		}
+		const layer4RulesText = layersEnabled.activeRules ? renderProceduralRules(rulesKept) : "";
+		const layer4SkillsText = layersEnabled.activeSkills ? composeLayer4Skills(input.skills ?? []) : "";
+		const meta = await memory.metadata(input.scope);
+		const layer5Text = layersEnabled.memoryMetadata ? renderMetadataBlock(enrichMetadataTags(meta, localeId, memory.embedderId())) : "";
+		let autoRecall = { factsTriggered: false };
+		let layer6Text = "";
+		if (factsAutoRecall !== false && layersEnabled.autoRecall) {
+			autoRecall = (input.autoRecallStrategyOverride ?? factsAutoRecall.strategy ?? heuristicStrategy)({
+				locale: localeId,
+				lastUserMessage: input.lastUserMessage ?? ""
+			});
+			if (autoRecall.factsTriggered) {
+				const topK = factsAutoRecall.topK ?? layerCfg.autoRecall?.topK ?? 5;
+				const threshold = factsAutoRecall.threshold ?? layerCfg.autoRecall?.threshold ?? 0;
+				const hits = await memory.semantic.search(input.scope, input.lastUserMessage ?? "", { topK }).catch(() => []);
+				const facts = [];
+				for (const hit of hits) {
+					if (hit.score < threshold) continue;
+					const decision = decide(hit.record.sensitivity, {
+						...privacy.providerAcceptsSensitivity !== void 0 ? { providerAcceptsSensitivity: privacy.providerAcceptsSensitivity } : {},
+						providerTrust,
+						cloudUploadConsent,
+						defaultSensitivity
+					});
+					privacyCounters[decision.reason] += 1;
+					if (decision.decision === "pass") facts.push(hit.record);
+				}
+				layer6Text = renderAutoRecalledFacts(facts);
+			}
+		}
+		const allocation = await allocate([
+			buildCandidate("identity", layer1Text.length > 0 && layer2Text.length > 0 ? `${layer1Text}\n\n${layer2Text}` : layer1Text + layer2Text, layerCaps.identity),
+			buildCandidate("memoryMetadata", layer5Text, layerCaps.memoryMetadata),
+			buildCandidate("activeRules", layer4RulesText, layerCaps.activeRules),
+			buildCandidate("workingBlocks", layer3Text, layerCaps.workingBlocks),
+			buildCandidate("activeSkills", layer4SkillsText, layerCaps.activeSkills),
+			buildCandidate("autoRecall", layer6Text, layerCaps.autoRecall)
+		].filter((c) => c.text.length > 0), maxContextTokens, tokenCounter);
+		const preambleFired = shouldFireInboundPreamble(input.upstreamAnnotations ?? []);
+		const preambleText = preambleFired ? composeInboundPreamble(localePack) : "";
+		const assembledLayers = allocation.layers.filter((l) => l.text.length > 0).sort((a, b) => LAYER_EMIT_ORDER[a.id] - LAYER_EMIT_ORDER[b.id]);
+		const finalParts = assembledLayers.map((l) => l.text);
+		if (preambleText.length > 0) finalParts.push(preambleText);
+		const systemContent = finalParts.join("\n\n");
+		const annotations = assembledLayers.map((layer) => ({
+			content: {
+				type: "text",
+				text: layer.text
+			},
+			annotation: annotationForLayer(layer)
+		}));
+		if (preambleText.length > 0) annotations.push({
+			content: {
+				type: "text",
+				text: preambleText
+			},
+			annotation: annotate("system:framework", "n/a")
+		});
+		return Object.freeze({
+			systemMessage: Object.freeze({
+				role: "system",
+				content: systemContent
+			}),
+			annotations: Object.freeze(annotations),
+			layerAllocation: allocation,
+			inboundPreambleFired: preambleFired,
+			privacyCounters: Object.freeze(privacyCounters),
+			localeId,
+			memoryBaseMode,
+			autoRecall
+		});
+	}
+	let lastCompactionAfterTokens = null;
+	const REARM_GROWTH_TOKENS = 256;
+	async function shouldCompact(messages, options = {}) {
+		if (!compactionEnabled) return false;
+		if (compactionThresholdTokens === Number.POSITIVE_INFINITY) return false;
+		const total = options.precomputedTokens ?? await countMessageTokens(messages, tokenCounter);
+		if (total < compactionThresholdTokens) return false;
+		if (lastCompactionAfterTokens !== null && total <= lastCompactionAfterTokens + REARM_GROWTH_TOKENS) return false;
+		if (compactionMinReclaimTokens > 0) {
+			const olderCount = Math.max(0, messages.length - reclaimPreserveTurns);
+			if (olderCount === 0) return false;
+			if (await countMessageTokens(messages.slice(0, olderCount), tokenCounter) < compactionMinReclaimTokens) return false;
+		}
+		return true;
+	}
+	async function compactNow(callInput) {
+		const activeSummarizer = callInput.summarizer ?? summarizer;
+		if (activeSummarizer === void 0) throw new TypeError("[graphorin/memory] ContextEngine.compactNow: no summarizer configured. Pass `summarizer` to createContextEngine({...}) or to compactNow({...}).");
+		const result = await executeCompaction({
+			messages: callInput.messages,
+			source: callInput.source,
+			strategy: callInput.preserveRecentTurns !== void 0 && compactionStrategy.kind === "summarize-old-preserve-recent" ? {
+				...compactionStrategy,
+				preserveRecentTurns: callInput.preserveRecentTurns
+			} : compactionStrategy,
+			localePack,
+			summarizer: activeSummarizer,
+			tokenCounter,
+			thresholdTokens: compactionThresholdTokens,
+			runId: callInput.runId,
+			sessionId: callInput.sessionId,
+			agentId: callInput.agentId,
+			scope: callInput.scope,
+			providerTrust,
+			now,
+			...callInput.signal !== void 0 ? { signal: callInput.signal } : {}
+		});
+		const ctx = {
+			result,
+			scope: callInput.scope,
+			runId: callInput.runId,
+			sessionId: callInput.sessionId,
+			agentId: callInput.agentId,
+			source: callInput.source
+		};
+		const hookFailures = [];
+		const extraContent = [];
+		let hooksFired = 0;
+		for (const hook of compactionHooks) try {
+			const parts = await hook.resolveContent({
+				memory: callInput.memory,
+				scope: callInput.scope,
+				...callInput.procedural !== void 0 ? { procedural: callInput.procedural } : {}
+			}, ctx);
+			extraContent.push(...parts);
+			hooksFired += 1;
+		} catch (err) {
+			hookFailures.push({
+				hookName: hook.id,
+				reason: err instanceof Error ? err.name : "UnknownError"
+			});
+		}
+		const enrichedResult = Object.freeze({
+			...result,
+			hooksFiredCount: hooksFired
+		});
+		lastCompactionAfterTokens = enrichedResult.afterTokens;
+		if (compactionThresholdTokens !== Number.POSITIVE_INFINITY && enrichedResult.afterTokens >= compactionThresholdTokens) process.stderr.write(`[graphorin/memory] compaction finished at ${enrichedResult.afterTokens} tokens — still at/above the ${compactionThresholdTokens}-token trigger (oversized preserved turns?). The immediate re-trigger is suppressed until the buffer grows.\n`);
+		return Object.freeze({
+			result: enrichedResult,
+			extraContent: Object.freeze(extraContent),
+			hookFailures: Object.freeze(hookFailures)
+		});
+	}
+	return Object.freeze({
+		assemble,
+		shouldCompact,
+		compactNow,
+		config() {
+			return resolvedConfig;
+		}
+	});
+}
+function buildCandidate(id, text, cap) {
+	if (cap !== void 0) return {
+		id,
+		text,
+		cap
+	};
+	return {
+		id,
+		text
+	};
+}
+function annotationForLayer(layer) {
+	switch (layer.id) {
+		case "identity": return annotate("system:framework", "n/a");
+		case "memoryMetadata":
+		case "activeRules":
+		case "workingBlocks":
+		case "activeSkills":
+		case "autoRecall": return annotate("memory:tier-filtered", "n/a");
+		default: return annotate("system:framework", "n/a");
+	}
+}
+function renderWorkingBlocks(blocks) {
+	if (blocks.length === 0) return "";
+	const lines = ["<memory_blocks>"];
+	for (const block of blocks) {
+		const description = block.description !== void 0 ? ` description="${escapeXmlAttr(block.description)}"` : "";
+		lines.push(`  <block label="${escapeXmlAttr(block.label)}"${description}>`);
+		lines.push(`    ${escapeXmlText(block.value)}`);
+		lines.push("  </block>");
+	}
+	lines.push("</memory_blocks>");
+	return lines.join("\n");
+}
+function renderProceduralRules(rules) {
+	if (rules.length === 0) return "";
+	const lines = ["<memory_rules>"];
+	for (const rule of rules) lines.push(`  <rule priority="${rule.priority}">${escapeXmlText(rule.text)}</rule>`);
+	lines.push("</memory_rules>");
+	return lines.join("\n");
+}
+function renderAutoRecalledFacts(facts) {
+	if (facts.length === 0) return "";
+	const lines = ["<auto_recalled_facts>"];
+	for (const fact of facts) {
+		const tagsAttr = fact.tags !== void 0 ? ` tags="${escapeXmlAttr((fact.tags ?? []).join(","))}"` : "";
+		lines.push(`  <fact id="${escapeXmlAttr(fact.id)}"${tagsAttr}>${escapeXmlText(fact.text)}</fact>`);
+	}
+	lines.push("</auto_recalled_facts>");
+	return lines.join("\n");
+}
+function escapeXmlAttr(value) {
+	return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+function escapeXmlText(value) {
+	return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+function resolvePackInput(input) {
+	if (input === void 0) return enLocalePack;
+	if (typeof input === "string") {
+		if (input === enLocalePack.id) return enLocalePack;
+		return resolveLocalePack({ id: input });
+	}
+	return resolveLocalePack(input);
+}
+function resolveDefaultHooks(input) {
+	if (input === void 0) return Object.freeze([
+		reanchorProjectRules(),
+		reanchorPersonaBlock(),
+		reanchorPinnedFacts({ pinnedFactIds: [] })
+	]);
+	return Object.freeze(input.map((hook, idx) => {
+		if (typeof hook === "function") return {
+			id: `customHook_${idx}`,
+			async resolveContent(_deps, ctx) {
+				if (ctx === void 0) throw new TypeError("[graphorin/memory] post-compaction hooks require the compaction context — call through ContextEngine.compactNow(...).");
+				return await hook(ctx);
+			}
+		};
+		return hook;
+	}));
+}
+/**
+* Augment a {@link MemoryMetadata} snapshot with the active locale +
+* embedder tags so the rendered metadata block carries the
+* additional context the model uses for reasoning. Pure: the
+* original `meta` reference is not mutated.
+*/
+function enrichMetadataTags(meta, localeId, embedderId) {
+	const baseTags = meta.tags !== void 0 ? [...meta.tags] : [];
+	if (!baseTags.some((tag) => tag.startsWith("locale:"))) baseTags.push(`locale:${localeId}`);
+	if (embedderId !== null && !baseTags.some((tag) => tag.startsWith("embedder:"))) baseTags.push(`embedder:${embedderId}`);
+	return {
+		...meta,
+		tags: Object.freeze(baseTags)
+	};
+}
+
+//#endregion
+export { createContextEngine };
+//# sourceMappingURL=engine.js.map