@atomicmemory/core 1.0.0

package/dist/services/temporal-query-expansion.js

@@ -0,0 +1,131 @@
+/**
+ * Deterministic query expansion for temporal-order questions.
+ * Pulls exact keyword candidates and nearby session memories when the query
+ * asks about sequence, relative timing, or duration.
+ */
+import { buildTemporalFingerprint } from './temporal-fingerprint.js';
+const TEMPORAL_MARKERS = [
+    'before',
+    'after',
+    'when',
+    'timeline',
+    'order',
+    'sequence',
+    'relative',
+    'how long',
+    'first',
+    'second',
+];
+const STOP_WORDS = new Set([
+    'what', 'when', 'where', 'which', 'who', 'whom', 'whose', 'why', 'how',
+    'did', 'does', 'do', 'was', 'were', 'is', 'are', 'the', 'a', 'an', 'and',
+    'or', 'to', 'of', 'in', 'for', 'on', 'with', 'between', 'these', 'those',
+    'this', 'that', 'their', 'they', 'them', 'therefore', 'developer', 'student',
+    'order', 'changes', 'made', 'project', 'relative', 'timeline', 'receive', 'from',
+]);
+const HIGH_SIGNAL_PATTERNS = [
+    /\bDr\.?\s+[A-Z][a-z]+\b/g,
+    /\b[A-Z]{2,}\s+\d{4}\b/g,
+    /\b(?:career advice|application timeline|application deadlines|first paper|second submission|finance tracker)\b/gi,
+    /\bdotctl\b/gi,
+];
+const MAX_TEMPORAL_ANCHORS = 4;
+export function isTemporalOrderingQuery(query) {
+    const lower = query.toLowerCase();
+    return TEMPORAL_MARKERS.some((marker) => lower.includes(marker));
+}
+export function extractTemporalQueryKeywords(query) {
+    if (!isTemporalOrderingQuery(query)) {
+        return [];
+    }
+    const phrases = collectPatternMatches(query);
+    const tokens = tokenizeQuery(query);
+    const keywords = [...phrases, ...tokens];
+    return [...new Set(keywords.map((keyword) => keyword.trim()).filter(Boolean))].slice(0, 10);
+}
+export async function expandTemporalQuery(repo, userId, query, queryEmbedding, excludeIds, limit, referenceTime) {
+    const keywords = extractTemporalQueryKeywords(query);
+    if (keywords.length === 0) {
+        return { memories: [], keywords, anchorIds: [] };
+    }
+    const keywordHits = await repo.findKeywordCandidates(userId, keywords, limit);
+    const keywordIds = keywordHits.map((memory) => memory.id);
+    const initialAnchorIds = selectAnchorIds(keywordHits, new Set(keywordIds.filter((id) => excludeIds.has(id))), limit);
+    const anchorIds = initialAnchorIds.length >= Math.min(MAX_TEMPORAL_ANCHORS, limit)
+        ? initialAnchorIds
+        : [
+            ...initialAnchorIds,
+            ...selectAnchorIds(keywordHits, new Set(keywordIds.filter((id) => !excludeIds.has(id))), Math.min(MAX_TEMPORAL_ANCHORS, limit) - initialAnchorIds.length),
+        ];
+    const expansionIds = keywordIds.filter((id) => !excludeIds.has(id));
+    if (anchorIds.length === 0) {
+        return { memories: [], keywords, anchorIds: [] };
+    }
+    const anchorMemories = await repo.fetchMemoriesByIds(userId, anchorIds, queryEmbedding, referenceTime);
+    const expansionSet = new Set(expansionIds);
+    const keywordMemories = anchorMemories.filter((memory) => expansionSet.has(memory.id));
+    const temporalNeighbors = await repo.findTemporalNeighbors(userId, anchorMemories.map((memory) => memory.created_at), queryEmbedding, 30, new Set([...excludeIds, ...anchorIds]), limit, referenceTime);
+    return {
+        memories: [...keywordMemories, ...temporalNeighbors],
+        keywords,
+        anchorIds,
+    };
+}
+function collectPatternMatches(query) {
+    const matches = [];
+    for (const pattern of HIGH_SIGNAL_PATTERNS) {
+        const regex = new RegExp(pattern.source, pattern.flags);
+        let match;
+        while ((match = regex.exec(query)) !== null) {
+            matches.push(match[0]);
+        }
+    }
+    return matches;
+}
+function tokenizeQuery(query) {
+    const words = query.match(/[A-Za-z0-9.]+/g) ?? [];
+    const filtered = words.filter((word) => isUsefulKeyword(word));
+    const bigrams = buildBigrams(filtered);
+    return [...filtered, ...bigrams];
+}
+function selectAnchorIds(keywordHits, keywordMemoryIds, limit) {
+    const seenFingerprints = new Set();
+    const anchorIds = [];
+    for (const hit of keywordHits) {
+        if (!keywordMemoryIds.has(hit.id)) {
+            continue;
+        }
+        const fingerprint = buildTemporalFingerprint(hit.content);
+        if (seenFingerprints.has(fingerprint)) {
+            continue;
+        }
+        seenFingerprints.add(fingerprint);
+        anchorIds.push(hit.id);
+        if (anchorIds.length >= Math.min(MAX_TEMPORAL_ANCHORS, limit)) {
+            break;
+        }
+    }
+    return anchorIds;
+}
+function isUsefulKeyword(word) {
+    const lower = word.toLowerCase();
+    if (STOP_WORDS.has(lower))
+        return false;
+    if (isCompactHighSignalToken(word))
+        return true;
+    if (lower.length < 4)
+        return false;
+    return true;
+}
+function buildBigrams(words) {
+    const bigrams = [];
+    for (let i = 0; i < words.length - 1; i++) {
+        if (bigrams.length >= 4)
+            break;
+        bigrams.push(`${words[i]} ${words[i + 1]}`);
+    }
+    return bigrams;
+}
+function isCompactHighSignalToken(word) {
+    return /^[A-Z]{3,}$/.test(word) || /[A-Z]/.test(word.slice(1));
+}

package/dist/services/temporal-rerank.d.ts

@@ -0,0 +1,22 @@
+/**
+ * BEAM v38: read-time temporal-state reranker.
+ *
+ * Adds a small additive boost to candidates with an active state
+ * (`event_end IS NULL`) and a small deboost to candidates whose state
+ * has been superseded (`event_end IS NOT NULL`). Pure reranking — the
+ * candidate set is unchanged, never filtered. This mirrors Mem0's
+ * "rerank, never filter" temporal-reasoning design principle.
+ *
+ * Only runs when:
+ *   - `temporalStateEnabled` is true at the call site, and
+ *   - the query intent is `CURRENT_STATE`.
+ *
+ * Memories without a `state_key` (most of the corpus, especially while
+ * the layer is being adopted) are untouched.
+ */
+import type { SearchResult } from '../db/repository-types.js';
+/**
+ * Apply the additive state rerank in place. Returns a new array, sorted
+ * by the post-boost score (descending), so callers can drop straight in.
+ */
+export declare function applyTemporalStateRerank(results: SearchResult[]): SearchResult[];

package/dist/services/temporal-rerank.js

@@ -0,0 +1,47 @@
+/**
+ * BEAM v38: read-time temporal-state reranker.
+ *
+ * Adds a small additive boost to candidates with an active state
+ * (`event_end IS NULL`) and a small deboost to candidates whose state
+ * has been superseded (`event_end IS NOT NULL`). Pure reranking — the
+ * candidate set is unchanged, never filtered. This mirrors Mem0's
+ * "rerank, never filter" temporal-reasoning design principle.
+ *
+ * Only runs when:
+ *   - `temporalStateEnabled` is true at the call site, and
+ *   - the query intent is `CURRENT_STATE`.
+ *
+ * Memories without a `state_key` (most of the corpus, especially while
+ * the layer is being adopted) are untouched.
+ */
+/**
+ * Boost added to active state memories. Small enough that strong semantic
+ * matches still win, large enough to flip ties between active and
+ * superseded versions of the same fact.
+ */
+const ACTIVE_STATE_BOOST = 0.1;
+/** Symmetric deboost for superseded state memories. */
+const SUPERSEDED_STATE_DEBOOST = 0.1;
+/**
+ * Apply the additive state rerank in place. Returns a new array, sorted
+ * by the post-boost score (descending), so callers can drop straight in.
+ */
+export function applyTemporalStateRerank(results) {
+    if (results.length === 0)
+        return results;
+    const reranked = results.map((row) => {
+        const boost = computeStateBoost(row);
+        if (boost === 0)
+            return row;
+        return { ...row, score: row.score + boost };
+    });
+    return reranked.sort((a, b) => b.score - a.score);
+}
+function computeStateBoost(row) {
+    if (!row.state_key)
+        return 0;
+    if (row.event_end === null || row.event_end === undefined) {
+        return ACTIVE_STATE_BOOST;
+    }
+    return -SUPERSEDED_STATE_DEBOOST;
+}

package/dist/services/temporal-result-protection.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Protect exact temporal keyword hits from being dropped by late-stage
+ * reranking or MMR. Temporal comparison questions often need one or two
+ * specific event memories to survive alongside broader context.
+ */
+import type { SearchResult } from '../db/memory-repository.js';
+export declare function preserveProtectedResults(selected: SearchResult[], candidates: SearchResult[], protectedFingerprints: string[], limit: number): SearchResult[];

package/dist/services/temporal-result-protection.js

@@ -0,0 +1,60 @@
+/**
+ * Protect exact temporal keyword hits from being dropped by late-stage
+ * reranking or MMR. Temporal comparison questions often need one or two
+ * specific event memories to survive alongside broader context.
+ */
+import { buildTemporalFingerprint } from './temporal-fingerprint.js';
+export function preserveProtectedResults(selected, candidates, protectedFingerprints, limit) {
+    if (protectedFingerprints.length === 0 || selected.length === 0) {
+        return selected.slice(0, limit);
+    }
+    const selectedFingerprints = new Set(selected.map((result) => buildTemporalFingerprint(result.content)));
+    const protectedSet = new Set(protectedFingerprints);
+    const protectedResults = candidates.filter((result) => protectedSet.has(buildTemporalFingerprint(result.content)));
+    if (protectedResults.length === 0) {
+        return selected.slice(0, limit);
+    }
+    const dedupedProtectedResults = dedupeByFingerprint(protectedResults);
+    const finalResults = [...selected];
+    for (const protectedResult of dedupedProtectedResults) {
+        const fingerprint = buildTemporalFingerprint(protectedResult.content);
+        if (selectedFingerprints.has(fingerprint)) {
+            continue;
+        }
+        const replacementIndex = findReplacementIndex(finalResults, protectedSet);
+        if (replacementIndex === -1) {
+            break;
+        }
+        finalResults[replacementIndex] = protectedResult;
+        selectedFingerprints.add(fingerprint);
+    }
+    return finalResults
+        .sort((left, right) => right.score - left.score)
+        .slice(0, limit);
+}
+function dedupeByFingerprint(results) {
+    const byFingerprint = new Map();
+    for (const result of results) {
+        const fingerprint = buildTemporalFingerprint(result.content);
+        const existing = byFingerprint.get(fingerprint);
+        if (!existing || result.score > existing.score) {
+            byFingerprint.set(fingerprint, result);
+        }
+    }
+    return [...byFingerprint.values()];
+}
+function findReplacementIndex(results, protectedFingerprints) {
+    let replacementIndex = -1;
+    let lowestScore = Infinity;
+    for (let i = 0; i < results.length; i++) {
+        const result = results[i];
+        if (protectedFingerprints.has(buildTemporalFingerprint(result.content))) {
+            continue;
+        }
+        if (result.score < lowestScore) {
+            lowestScore = result.score;
+            replacementIndex = i;
+        }
+    }
+    return replacementIndex;
+}

package/dist/services/temporal-state-write.d.ts

@@ -0,0 +1,57 @@
+/**
+ * BEAM v38: write-time temporal-state pipeline (classifier + supersede).
+ *
+ * Two helpers split the path so `memory-storage.ts` can:
+ *   1. classify BEFORE storing (so state_key / event_start land on the
+ *      new memory row directly), and
+ *   2. supersede AFTER storing (so the new row is excluded from the
+ *      UPDATE via its own id).
+ *
+ * Failure modes:
+ *   - LLM classifier throws: re-thrown. The ingest path decides whether
+ *     to abort. We do NOT silently drop the signal.
+ *   - LLM returns non_stateful: helper returns null; caller skips the
+ *     supersede sweep and the row stores with NULL state_key.
+ *   - Supersede UPDATE throws: re-thrown. Fail-closed.
+ */
+import type pg from 'pg';
+import { type TemporalStateClassification } from './temporal-classifier.js';
+/** Input bundle for the pre-store classifier call. */
+export interface TemporalClassifyForWriteInput {
+    /** User scope (used to namespace the state_key slug). */
+    userId: string;
+    /** Extracted fact text. */
+    memoryText: string;
+    /** Logical observed_at — used as event_start when the LLM does not. */
+    observedAt: Date;
+    /** Anthropic model ID for the classifier. */
+    model: string;
+}
+/** Re-export so callers don't depend on the classifier module directly. */
+export type { TemporalStateClassification };
+/**
+ * Classify a single memory's temporal state. Returns null when the
+ * memory is non-stateful or the classifier rejects the model output.
+ * Throws on transport / API failures so the caller fails closed.
+ */
+export declare function classifyTemporalStateForWrite(input: TemporalClassifyForWriteInput): Promise<TemporalStateClassification | null>;
+/** Input bundle for the post-store supersede call. */
+export interface SupersedeAfterStoreInput {
+    /** Postgres pool — used for the UPDATE. */
+    pool: pg.Pool;
+    /** User scope. */
+    userId: string;
+    /** Stable state key chosen by the classifier. */
+    stateKey: string;
+    /** Newly stored memory's id (excluded from the UPDATE). */
+    newMemoryId: string;
+    /** New row's event_start, used as event_end for displaced rows. */
+    eventStart: Date;
+}
+/**
+ * UPDATE every prior, non-deleted memory with the same (user_id, state_key)
+ * so it closes its `event_end` window at the new row's event_start.
+ * Returns the count of rows touched. Re-throws on driver errors so the
+ * ingest can fail closed.
+ */
+export declare function supersedeAfterStore(input: SupersedeAfterStoreInput): Promise<number>;

package/dist/services/temporal-state-write.js

@@ -0,0 +1,45 @@
+/**
+ * BEAM v38: write-time temporal-state pipeline (classifier + supersede).
+ *
+ * Two helpers split the path so `memory-storage.ts` can:
+ *   1. classify BEFORE storing (so state_key / event_start land on the
+ *      new memory row directly), and
+ *   2. supersede AFTER storing (so the new row is excluded from the
+ *      UPDATE via its own id).
+ *
+ * Failure modes:
+ *   - LLM classifier throws: re-thrown. The ingest path decides whether
+ *     to abort. We do NOT silently drop the signal.
+ *   - LLM returns non_stateful: helper returns null; caller skips the
+ *     supersede sweep and the row stores with NULL state_key.
+ *   - Supersede UPDATE throws: re-thrown. Fail-closed.
+ */
+import { classifyTemporalState } from './temporal-classifier.js';
+import { supersedePriorStateMemories } from '../db/repository-temporal-state.js';
+/**
+ * Classify a single memory's temporal state. Returns null when the
+ * memory is non-stateful or the classifier rejects the model output.
+ * Throws on transport / API failures so the caller fails closed.
+ */
+export async function classifyTemporalStateForWrite(input) {
+    return classifyTemporalState({
+        memoryText: input.memoryText,
+        observedAt: input.observedAt,
+        userId: input.userId,
+        model: input.model,
+    });
+}
+/**
+ * UPDATE every prior, non-deleted memory with the same (user_id, state_key)
+ * so it closes its `event_end` window at the new row's event_start.
+ * Returns the count of rows touched. Re-throws on driver errors so the
+ * ingest can fail closed.
+ */
+export async function supersedeAfterStore(input) {
+    return supersedePriorStateMemories(input.pool, {
+        userId: input.userId,
+        stateKey: input.stateKey,
+        newMemoryId: input.newMemoryId,
+        eventEnd: input.eventStart,
+    });
+}

package/dist/services/tiered-context.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Tiered Context Loading — L0/L1/L2 style multi-resolution memory representations.
+ *
+ * Extends the existing staged loading with a proper three-tier model:
+ *   - L0 (~10 words): Headline/abstract — compact preview for browsing and listing.
+ *     Stored in the `summary` column, generated at extraction time.
+ *   - L1 (~1-3 sentences): Overview — mid-level summary preserving key details.
+ *     Generated on demand or at ingest time. Good for planning/reasoning.
+ *   - L2 (full content): Complete memory content. Used for detailed drill-in.
+ *
+ * Token budget model:
+ *   Given a total injection budget, the tier selector assigns each memory
+ *   a tier based on its relevance score. High-relevance memories get L2,
+ *   mid-relevance get L1, low-relevance get L0. This maximizes information
+ *   density within the budget.
+ *
+ * Inspired by OpenViking's three-tier model (82% token reduction on LoCoMo10).
+ * Phase 2 roadmap item: "Tiered context loading" (OpenViking review, 2026-03-16).
+ */
+/** Memory content at different resolution levels. */
+export interface TieredContent {
+    l0: string;
+    l1: string | null;
+    l2: string;
+}
+/** Tier assignment for a single memory in a retrieval result set. */
+export interface TierAssignment {
+    memoryId: string;
+    tier: ContextTier;
+    content: string;
+    estimatedTokens: number;
+}
+export type ContextTier = 'L0' | 'L1' | 'L2';
+/** Score thresholds for tier assignment. */
+export interface TierThresholds {
+    l2MinScore: number;
+    l1MinScore: number;
+}
+export declare const DEFAULT_TIER_THRESHOLDS: TierThresholds;
+/** Rank-based tier counts (used with selectRanksForQuery). */
+export interface TierRanks {
+    l2Count: number;
+    l1Count: number;
+}
+/**
+ * Generate an L1 overview from full content.
+ * Uses a simple extractive approach: takes the first 2-3 sentences.
+ * No LLM call required — deterministic and fast.
+ */
+export declare function generateL1Overview(content: string): string;
+/**
+ * Build tiered content from a memory's existing fields.
+ * L0 = summary/headline, L1 = generated overview, L2 = full content.
+ */
+export declare function buildTieredContent(content: string, summary: string): TieredContent;
+/**
+ * Assign context tiers to a set of scored memories within a token budget.
+ *
+ * Algorithm:
+ *   1. Sort memories by score (descending).
+ *   2. Greedily assign the highest affordable tier to each memory.
+ *   3. If budget runs out, remaining memories get L0.
+ *
+ * Returns assignments in the original order.
+ */
+export declare function assignTiers(memories: Array<{
+    id: string;
+    score: number;
+    content: string;
+    summary: string;
+}>, tokenBudget: number, thresholds?: TierThresholds): TierAssignment[];
+/**
+ * Format tiered memory assignments into XML injection text.
+ * Each memory includes its tier level so the consuming LLM knows
+ * which memories have full detail vs summaries.
+ */
+export declare function formatTieredInjection(assignments: TierAssignment[]): string;
+/**
+ * Estimate token count using the ~4 chars per token heuristic.
+ * Good enough for budget allocation; not meant to be exact.
+ */
+export declare function estimateTokens(text: string): number;
+/**
+ * Calculate token savings from tiered loading vs all-L2.
+ * Returns the percentage of tokens saved.
+ */
+export declare function calculateTokenSavings(assignments: TierAssignment[], fullContentLengths: number[]): number;

package/dist/services/tiered-context.js

@@ -0,0 +1,214 @@
+/**
+ * Tiered Context Loading — L0/L1/L2 style multi-resolution memory representations.
+ *
+ * Extends the existing staged loading with a proper three-tier model:
+ *   - L0 (~10 words): Headline/abstract — compact preview for browsing and listing.
+ *     Stored in the `summary` column, generated at extraction time.
+ *   - L1 (~1-3 sentences): Overview — mid-level summary preserving key details.
+ *     Generated on demand or at ingest time. Good for planning/reasoning.
+ *   - L2 (full content): Complete memory content. Used for detailed drill-in.
+ *
+ * Token budget model:
+ *   Given a total injection budget, the tier selector assigns each memory
+ *   a tier based on its relevance score. High-relevance memories get L2,
+ *   mid-relevance get L1, low-relevance get L0. This maximizes information
+ *   density within the budget.
+ *
+ * Inspired by OpenViking's three-tier model (82% token reduction on LoCoMo10).
+ * Phase 2 roadmap item: "Tiered context loading" (OpenViking review, 2026-03-16).
+ */
+import { escapeXml } from '../xml-escape.js';
+export const DEFAULT_TIER_THRESHOLDS = {
+    l2MinScore: 0.70,
+    l1MinScore: 0.40,
+};
+/** Approximate token budget per tier (used for budget allocation). */
+const TIER_TOKEN_ESTIMATES = {
+    L0: 15,
+    L1: 80,
+    L2: 200,
+};
+const DEFAULT_TIER_RANKS = {
+    l2Count: 2,
+    l1Count: 2,
+};
+/** Promoted ranks for multi-fact queries: all L2, no truncation. */
+const PROMOTED_TIER_RANKS = {
+    l2Count: 10,
+    l1Count: 0,
+};
+/**
+ * Multi-fact query patterns that need full context across memories.
+ * These queries ask to connect, enumerate, or synthesize multiple facts.
+ */
+const MULTI_FACT_PATTERNS = [
+    /\bconnection\b/i,
+    /\brelationship\b/i,
+    /\brelate\b/i,
+    /\bboth\b/i,
+    /\ball\b/i,
+    /\bfull\b.*\b(stack|list|set|trajectory|history)\b/i,
+    /\btwo\b.*\b(projects?|papers?|tools?|colleagues?)\b/i,
+    /\bcompare\b/i,
+    /\btogether\b/i,
+    /\bin what order\b/i,
+    /\bhow many\b/i,
+    /\bwhat are the\b.*\band\b/i,
+];
+/**
+ * Detect whether a query needs full content from all memories.
+ * Returns promoted ranks for multi-fact queries, default ranks otherwise.
+ */
+function selectRanksForQuery(query) {
+    const needsPromotion = MULTI_FACT_PATTERNS.some((pattern) => pattern.test(query));
+    return needsPromotion ? PROMOTED_TIER_RANKS : DEFAULT_TIER_RANKS;
+}
+/**
+ * Generate an L1 overview from full content.
+ * Uses a simple extractive approach: takes the first 2-3 sentences.
+ * No LLM call required — deterministic and fast.
+ */
+export function generateL1Overview(content) {
+    const sentences = splitSentences(content);
+    if (sentences.length <= 2)
+        return content;
+    const targetLength = 3;
+    const overview = sentences.slice(0, targetLength).join(' ');
+    if (overview.length > 300) {
+        return sentences.slice(0, 2).join(' ');
+    }
+    return overview;
+}
+/**
+ * Build tiered content from a memory's existing fields.
+ * L0 = summary/headline, L1 = generated overview, L2 = full content.
+ */
+export function buildTieredContent(content, summary) {
+    const l0 = summary || truncateToHeadline(content);
+    const l1 = generateL1Overview(content);
+    const l1IsSameAsL2 = l1 === content;
+    return {
+        l0,
+        l1: l1IsSameAsL2 ? null : l1,
+        l2: content,
+    };
+}
+/**
+ * Assign context tiers to a set of scored memories within a token budget.
+ *
+ * Algorithm:
+ *   1. Sort memories by score (descending).
+ *   2. Greedily assign the highest affordable tier to each memory.
+ *   3. If budget runs out, remaining memories get L0.
+ *
+ * Returns assignments in the original order.
+ */
+export function assignTiers(memories, tokenBudget, thresholds = DEFAULT_TIER_THRESHOLDS) {
+    if (memories.length === 0)
+        return [];
+    const indexed = memories.map((m, i) => ({ ...m, originalIndex: i }));
+    indexed.sort((a, b) => b.score - a.score);
+    let remainingBudget = tokenBudget;
+    const assignments = [];
+    for (const memory of indexed) {
+        const tiered = buildTieredContent(memory.content, memory.summary);
+        const { tier, content, tokens } = selectTierForBudget(memory.score, tiered, remainingBudget, thresholds);
+        remainingBudget -= tokens;
+        assignments.push({
+            memoryId: memory.id,
+            tier,
+            content,
+            estimatedTokens: tokens,
+            originalIndex: memory.originalIndex,
+        });
+    }
+    assignments.sort((a, b) => a.originalIndex - b.originalIndex);
+    return assignments.map(({ originalIndex: _, ...rest }) => rest);
+}
+/**
+ * Select the highest-quality tier that fits within the remaining budget.
+ */
+function selectTierForBudget(score, tiered, remainingBudget, thresholds) {
+    const l2Tokens = estimateTokens(tiered.l2);
+    if (score >= thresholds.l2MinScore && l2Tokens <= remainingBudget) {
+        return { tier: 'L2', content: tiered.l2, tokens: l2Tokens };
+    }
+    if (tiered.l1 !== null) {
+        const l1Tokens = estimateTokens(tiered.l1);
+        if (score >= thresholds.l1MinScore && l1Tokens <= remainingBudget) {
+            return { tier: 'L1', content: tiered.l1, tokens: l1Tokens };
+        }
+    }
+    const l0Tokens = estimateTokens(tiered.l0);
+    return { tier: 'L0', content: tiered.l0, tokens: l0Tokens };
+}
+/**
+ * Format tiered memory assignments into XML injection text.
+ * Each memory includes its tier level so the consuming LLM knows
+ * which memories have full detail vs summaries.
+ */
+export function formatTieredInjection(assignments) {
+    if (assignments.length === 0)
+        return '';
+    const tierCounts = countTiers(assignments);
+    const totalTokens = assignments.reduce((sum, a) => sum + a.estimatedTokens, 0);
+    const expandableIds = assignments
+        .filter((a) => a.tier !== 'L2')
+        .map((a) => a.memoryId);
+    const lines = assignments.map((a, i) => {
+        const tierAttr = `tier="${a.tier}"`;
+        return `<memory index="${i + 1}" memory_id="${a.memoryId}" ${tierAttr}>\n${escapeXml(a.content)}\n</memory>`;
+    });
+    const header = [
+        `<atomicmem_context count="${assignments.length}"`,
+        `mode="tiered"`,
+        `tokens="~${totalTokens}"`,
+        `tiers="L0:${tierCounts.L0},L1:${tierCounts.L1},L2:${tierCounts.L2}"`,
+        expandableIds.length > 0 ? `expand_ids="${expandableIds.join(',')}"` : '',
+    ].filter(Boolean).join(' ');
+    const parts = [`${header}>`];
+    parts.push(lines.join('\n'));
+    if (expandableIds.length > 0) {
+        parts.push('<expand_hint>Request expansion by ID for full content of L0/L1 memories.</expand_hint>');
+    }
+    parts.push('</atomicmem_context>');
+    return parts.join('\n');
+}
+/**
+ * Estimate token count using the ~4 chars per token heuristic.
+ * Good enough for budget allocation; not meant to be exact.
+ */
+export function estimateTokens(text) {
+    return Math.max(1, Math.ceil(text.length / 4));
+}
+/**
+ * Calculate token savings from tiered loading vs all-L2.
+ * Returns the percentage of tokens saved.
+ */
+export function calculateTokenSavings(assignments, fullContentLengths) {
+    if (assignments.length === 0 || fullContentLengths.length === 0)
+        return 0;
+    const fullTokens = fullContentLengths.reduce((sum, len) => sum + estimateTokens(Array(len).fill('x').join('')), 0);
+    const tieredTokens = assignments.reduce((sum, a) => sum + a.estimatedTokens, 0);
+    if (fullTokens === 0)
+        return 0;
+    return ((fullTokens - tieredTokens) / fullTokens) * 100;
+}
+function countTiers(assignments) {
+    const counts = { L0: 0, L1: 0, L2: 0 };
+    for (const a of assignments)
+        counts[a.tier]++;
+    return counts;
+}
+function splitSentences(text) {
+    return text
+        .split(/(?<=[.!?])\s+/)
+        .map((s) => s.trim())
+        .filter(Boolean);
+}
+function truncateToHeadline(content) {
+    const words = content.split(/\s+/);
+    if (words.length <= 10)
+        return content;
+    return words.slice(0, 10).join(' ') + '...';
+}