@atomicmemory/core 1.0.0

package/dist/services/packaging-observability.js

@@ -0,0 +1,146 @@
+/**
+ * Packaging and assembly observability helpers.
+ *
+ * Builds explicit summaries for the packaged context emitted by search()
+ * without changing candidate membership, ranking, or canonical storage.
+ */
+import { isAnswerBearing, sortBySessionPriority } from './session-packaging.js';
+import { estimateTokens } from './tiered-loading.js';
+import { buildTimelinePack, spansMultipleDates } from './timeline-pack.js';
+import { deduplicateCompositeMembersHard } from './composite-dedup.js';
+function buildPackagingTraceSummary(candidateMemories, includedMemories, mode, injectionText, estimatedTokenCost) {
+    const groups = groupByNamespace(includedMemories);
+    const packageType = resolvePackageType(groups, mode);
+    const ordered = orderIncludedMemories(groups, mode);
+    const includedIds = ordered.map((memory) => memory.id);
+    const includedSet = new Set(includedIds);
+    return {
+        packageType,
+        includedIds,
+        droppedIds: candidateMemories.map((memory) => memory.id).filter((id) => !includedSet.has(id)),
+        evidenceRoles: buildEvidenceRoles(groups, ordered, mode),
+        episodeCount: countDistinctEpisodes(includedMemories),
+        dateCount: countDistinctDates(includedMemories),
+        hasCurrentMarker: packageType === 'timeline-pack',
+        hasConflictBlock: false,
+        tokenCost: estimatedTokenCost ?? estimateTokens(injectionText),
+    };
+}
+function buildAssemblyTraceSummary(packaging, tokenBudget) {
+    return {
+        finalIds: packaging.includedIds,
+        finalTokenCost: packaging.tokenCost,
+        tokenBudget: tokenBudget ?? null,
+        primaryEvidencePosition: resolvePrimaryEvidencePosition(packaging),
+        blocks: resolveAssemblyBlocks(packaging.packageType),
+    };
+}
+function groupByNamespace(memories) {
+    const groups = new Map();
+    for (const memory of memories) {
+        const namespace = memory.namespace || 'general';
+        const existing = groups.get(namespace);
+        if (existing) {
+            existing.push(memory);
+            continue;
+        }
+        groups.set(namespace, [memory]);
+    }
+    return [...groups.entries()].map(([namespace, grouped]) => ({ namespace, memories: grouped }));
+}
+function resolvePackageType(groups, mode) {
+    if (mode !== 'flat')
+        return 'tiered';
+    return groups.some((group) => spansMultipleDates(group.memories)) ? 'timeline-pack' : 'subject-pack';
+}
+function orderIncludedMemories(groups, mode) {
+    if (mode !== 'flat') {
+        return [...groups.flatMap((group) => group.memories)]
+            .sort((left, right) => left.created_at.getTime() - right.created_at.getTime());
+    }
+    return groups.flatMap((group) => orderGroup(group));
+}
+function orderGroup(group) {
+    if (spansMultipleDates(group.memories)) {
+        return buildTimelinePack(group.namespace, group.memories)
+            .entries
+            .map((entry) => group.memories.find((memory) => memory.id === entry.memoryId))
+            .filter((memory) => memory !== undefined);
+    }
+    return sortBySessionPriority(group.memories);
+}
+function buildEvidenceRoles(groups, ordered, mode) {
+    const timelineNamespaces = new Set(getTimelineNamespaces(groups, mode));
+    const timelineLatestIds = new Set(getTimelineLatestIds(groups, mode));
+    return Object.fromEntries(ordered.map((memory) => [
+        memory.id,
+        resolveEvidenceRole(memory, mode, timelineNamespaces, timelineLatestIds),
+    ]));
+}
+function getTimelineNamespaces(groups, mode) {
+    if (mode !== 'flat')
+        return [];
+    return groups.filter((group) => spansMultipleDates(group.memories)).map((group) => group.namespace);
+}
+function getTimelineLatestIds(groups, mode) {
+    if (mode !== 'flat')
+        return [];
+    return groups
+        .filter((group) => spansMultipleDates(group.memories))
+        .map((group) => buildTimelinePack(group.namespace, group.memories).latestEntryId);
+}
+function resolveEvidenceRole(memory, mode, timelineNamespaces, timelineLatestIds) {
+    if (timelineLatestIds.has(memory.id))
+        return 'primary';
+    if (mode !== 'flat')
+        return isAnswerBearing(memory.content) ? 'primary' : 'contextual';
+    const isTimelineMemory = timelineNamespaces.has(memory.namespace || 'general');
+    if (isAnswerBearing(memory.content))
+        return isTimelineMemory ? 'historical' : 'primary';
+    if (isTimelineMemory)
+        return 'contextual';
+    return 'supporting';
+}
+function countDistinctEpisodes(memories) {
+    return new Set(memories.map((memory) => memory.episode_id).filter(Boolean)).size;
+}
+function countDistinctDates(memories) {
+    return new Set(memories.map((memory) => memory.created_at.toISOString().slice(0, 10))).size;
+}
+function resolvePrimaryEvidencePosition(packaging) {
+    const position = packaging.includedIds.findIndex((id) => packaging.evidenceRoles[id] === 'primary');
+    return position === -1 ? null : position + 1;
+}
+function resolveAssemblyBlocks(packageType) {
+    if (packageType === 'tiered')
+        return ['tiered'];
+    if (packageType === 'timeline-pack')
+        return ['timeline'];
+    return ['subject'];
+}
+/**
+ * Build packaging + assembly summaries, emit the tiered-packaging trace
+ * event when in tiered mode, and attach both summaries to the active
+ * trace. Returns the summaries so the caller can include them in the
+ * retrieval result. Does NOT finalize the trace — caller owns that.
+ */
+export function finalizePackagingTrace(activeTrace, input) {
+    const packagedForSummary = input.mode === 'flat'
+        ? input.outputMemories
+        : deduplicateCompositeMembersHard(input.outputMemories);
+    const packagingSummary = buildPackagingTraceSummary(input.outputMemories, packagedForSummary, input.mode, input.injectionText, input.estimatedContextTokens);
+    const assemblySummary = buildAssemblyTraceSummary(packagingSummary, input.mode === 'flat' ? undefined : input.tokenBudget);
+    if (input.mode === 'tiered') {
+        activeTrace.event('tiered-packaging', {
+            budget: input.tokenBudget ?? null,
+            estimatedTokens: input.estimatedContextTokens,
+            tierDistribution: input.tierAssignments?.reduce((acc, a) => {
+                acc[a.tier] = (acc[a.tier] || 0) + 1;
+                return acc;
+            }, {}),
+        });
+    }
+    activeTrace.setPackagingSummary(packagingSummary);
+    activeTrace.setAssemblySummary(assemblySummary);
+    return { packagingSummary, assemblySummary };
+}

package/dist/services/query-expansion.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Query expansion via entity graph bridging.
+ *
+ * Two modes:
+ * 1. **Query augmentation** (zero-LLM): Embeds the query, matches against
+ *    entity embeddings, appends top entity names to the query text before
+ *    the main vector search. Sub-millisecond cost, improves cold-path
+ *    retrieval by grounding generic queries in user-specific context.
+ *
+ * 2. **LLM-based expansion**: Extracts entity names and concepts from the
+ *    query via LLM, looks them up in the entity graph, traverses relations,
+ *    and returns memory IDs that are conceptually related but not
+ *    embedding-adjacent.
+ *
+ * Example (augmentation): "How should I implement caching?" → matches
+ * entities [Python, Redis, FastAPI] → augmented query becomes
+ * "How should I implement caching? [context: Python, Redis, FastAPI]"
+ */
+import type { CoreRuntimeConfig } from '../app/runtime-container.js';
+import type { SearchResult } from '../db/repository-types.js';
+import type { SearchStore, EntityStore } from '../db/stores.js';
+type SearchExpansionRuntimeConfig = Pick<CoreRuntimeConfig, 'queryExpansionMinSimilarity' | 'queryAugmentationMaxEntities' | 'queryAugmentationMinSimilarity'>;
+export interface QueryExpansionResult {
+    extractedEntities: string[];
+    extractedConcepts: string[];
+    matchedEntityIds: string[];
+    expandedMemoryIds: string[];
+}
+/** Parse LLM response into structured terms. Pure function for testability. */
+export declare function parseQueryTerms(response: string): {
+    entities: string[];
+    concepts: string[];
+};
+/**
+ * Run full query expansion: extract terms → find entities → traverse
+ * relations → retrieve bridging memories.
+ */
+export declare function expandQueryViaEntities(entityRepo: EntityStore, repo: SearchStore, userId: string, query: string, queryEmbedding: number[], excludeIds: Set<string>, budget: number, runtimeConfig?: SearchExpansionRuntimeConfig): Promise<{
+    memories: SearchResult[];
+    expansion: QueryExpansionResult;
+}>;
+export interface QueryAugmentationResult {
+    originalQuery: string;
+    augmentedQuery: string;
+    matchedEntities: Array<{
+        name: string;
+        entityType: string;
+        similarity: number;
+    }>;
+}
+/**
+ * Augment a query with entity names from the memory graph.
+ *
+ * Uses the query embedding (already computed) to find semantically matching
+ * entities, then appends their names as context hints to the query text.
+ * This grounds generic queries in the user's specific context without any
+ * LLM call.
+ *
+ * Returns the augmented query string and metadata about matched entities.
+ * If no entities match above threshold, returns the original query unchanged.
+ */
+export declare function augmentQueryWithEntities(entityRepo: EntityStore, userId: string, query: string, queryEmbedding: number[], runtimeConfig?: SearchExpansionRuntimeConfig): Promise<QueryAugmentationResult>;
+/**
+ * Extract capitalized multi-word phrases and proper nouns from a query.
+ * These are candidate entity names for exact-match co-retrieval.
+ *
+ * Matches patterns like "Acme Corp", "New Zealand", "Studio Ghibli",
+ * single capitalized words like "Redis", and quoted phrases.
+ */
+export declare function extractNamedEntityCandidates(query: string): string[];
+/**
+ * Co-retrieve all memories linked to entities whose names appear in the query.
+ * Uses exact name matching (case-insensitive) — no embedding or LLM needed.
+ *
+ * This ensures that when a user asks about "Acme Corp", all memories linked
+ * to the Acme Corp entity are included in the result set, even if their
+ * content embeddings don't match the query semantically.
+ */
+export declare function coRetrieveByEntityNames(entityRepo: EntityStore, repo: SearchStore, userId: string, query: string, queryEmbedding: number[], excludeIds: Set<string>, budget: number): Promise<{
+    memories: SearchResult[];
+    matchedNames: string[];
+}>;
+export {};

package/dist/services/query-expansion.js

@@ -0,0 +1,242 @@
+/**
+ * Query expansion via entity graph bridging.
+ *
+ * Two modes:
+ * 1. **Query augmentation** (zero-LLM): Embeds the query, matches against
+ *    entity embeddings, appends top entity names to the query text before
+ *    the main vector search. Sub-millisecond cost, improves cold-path
+ *    retrieval by grounding generic queries in user-specific context.
+ *
+ * 2. **LLM-based expansion**: Extracts entity names and concepts from the
+ *    query via LLM, looks them up in the entity graph, traverses relations,
+ *    and returns memory IDs that are conceptually related but not
+ *    embedding-adjacent.
+ *
+ * Example (augmentation): "How should I implement caching?" → matches
+ * entities [Python, Redis, FastAPI] → augmented query becomes
+ * "How should I implement caching? [context: Python, Redis, FastAPI]"
+ */
+import { config } from '../config.js';
+import { llm } from './llm.js';
+import { embedText } from './embedding.js';
+const ENTITY_EXTRACTION_PROMPT = 'Extract entity names and conceptual topics from this search query. ' +
+    'Return a JSON object with two arrays: ' +
+    '"entities" (specific named things: tools, people, projects, places, organizations) and ' +
+    '"concepts" (abstract topics: caching, deployment, testing, fitness, cooking). ' +
+    'Be thorough — include implicit references. ' +
+    'Example: "How should I cache my API?" → {"entities":["API"],"concepts":["caching","performance"]}. ' +
+    'Return ONLY valid JSON, no explanation.';
+/** Extract entity names and concepts from a query using the LLM. */
+async function extractQueryTerms(query) {
+    const response = await llm.chat([
+        { role: 'system', content: ENTITY_EXTRACTION_PROMPT },
+        { role: 'user', content: query },
+    ], { temperature: 0, maxTokens: 200 });
+    return parseQueryTerms(response);
+}
+/** Parse LLM response into structured terms. Pure function for testability. */
+export function parseQueryTerms(response) {
+    const fallback = { entities: [], concepts: [] };
+    try {
+        const parsed = JSON.parse(response.trim());
+        const entities = Array.isArray(parsed.entities)
+            ? parsed.entities.filter((e) => typeof e === 'string' && e.trim().length > 0)
+            : [];
+        const concepts = Array.isArray(parsed.concepts)
+            ? parsed.concepts.filter((c) => typeof c === 'string' && c.trim().length > 0)
+            : [];
+        return { entities, concepts };
+    }
+    catch {
+        return fallback;
+    }
+}
+/**
+ * Search entities by name (case-insensitive substring match).
+ * Returns entity IDs that match any of the provided terms.
+ */
+async function findEntitiesByTerms(entityRepo, userId, terms, limit, runtimeConfig = config) {
+    if (terms.length === 0)
+        return [];
+    const allIds = new Set();
+    for (const term of terms) {
+        const embedding = await embedText(term);
+        const matches = await entityRepo.searchEntities(userId, embedding, limit, runtimeConfig.queryExpansionMinSimilarity);
+        for (const match of matches) {
+            allIds.add(match.id);
+        }
+    }
+    return [...allIds];
+}
+/**
+ * Run full query expansion: extract terms → find entities → traverse
+ * relations → retrieve bridging memories.
+ */
+export async function expandQueryViaEntities(entityRepo, repo, userId, query, queryEmbedding, excludeIds, budget, runtimeConfig = config) {
+    const { entities, concepts } = await extractQueryTerms(query);
+    const allTerms = [...entities, ...concepts];
+    if (allTerms.length === 0) {
+        return {
+            memories: [],
+            expansion: { extractedEntities: entities, extractedConcepts: concepts, matchedEntityIds: [], expandedMemoryIds: [] },
+        };
+    }
+    const matchedEntityIds = await findEntitiesByTerms(entityRepo, userId, allTerms, 10, runtimeConfig);
+    if (matchedEntityIds.length === 0) {
+        return {
+            memories: [],
+            expansion: { extractedEntities: entities, extractedConcepts: concepts, matchedEntityIds: [], expandedMemoryIds: [] },
+        };
+    }
+    const relatedEntityIds = await entityRepo.findRelatedEntityIds(userId, matchedEntityIds, new Set(matchedEntityIds), budget);
+    const allEntityIds = [...matchedEntityIds, ...relatedEntityIds];
+    const memoryIds = await entityRepo.findMemoryIdsByEntities(userId, allEntityIds, excludeIds, budget);
+    if (memoryIds.length === 0) {
+        return {
+            memories: [],
+            expansion: { extractedEntities: entities, extractedConcepts: concepts, matchedEntityIds, expandedMemoryIds: [] },
+        };
+    }
+    const memories = await repo.fetchMemoriesByIds(userId, memoryIds, queryEmbedding);
+    return {
+        memories,
+        expansion: {
+            extractedEntities: entities,
+            extractedConcepts: concepts,
+            matchedEntityIds,
+            expandedMemoryIds: memoryIds,
+        },
+    };
+}
+/**
+ * Augment a query with entity names from the memory graph.
+ *
+ * Uses the query embedding (already computed) to find semantically matching
+ * entities, then appends their names as context hints to the query text.
+ * This grounds generic queries in the user's specific context without any
+ * LLM call.
+ *
+ * Returns the augmented query string and metadata about matched entities.
+ * If no entities match above threshold, returns the original query unchanged.
+ */
+export async function augmentQueryWithEntities(entityRepo, userId, query, queryEmbedding, runtimeConfig = config) {
+    const matches = await entityRepo.searchEntities(userId, queryEmbedding, runtimeConfig.queryAugmentationMaxEntities, runtimeConfig.queryAugmentationMinSimilarity);
+    const matchedEntities = matches.map((e) => ({
+        name: e.name,
+        entityType: e.entity_type,
+        similarity: e.similarity,
+    }));
+    if (matchedEntities.length === 0) {
+        return { originalQuery: query, augmentedQuery: query, matchedEntities: [] };
+    }
+    const entityNames = matchedEntities.map((e) => e.name);
+    const augmentedQuery = `${query} [context: ${entityNames.join(', ')}]`;
+    return { originalQuery: query, augmentedQuery, matchedEntities };
+}
+// ─── Entity Name Co-Retrieval ─────────────────────────────────────────
+/** Common English words that appear capitalized but aren't entity names. */
+const STOP_WORDS = new Set([
+    'the', 'a', 'an', 'is', 'are', 'was', 'were', 'be', 'been', 'being',
+    'have', 'has', 'had', 'do', 'does', 'did', 'will', 'would', 'could',
+    'should', 'may', 'might', 'can', 'shall', 'must', 'need', 'dare',
+    'to', 'of', 'in', 'for', 'on', 'with', 'at', 'by', 'from', 'as',
+    'into', 'through', 'during', 'before', 'after', 'above', 'below',
+    'and', 'but', 'or', 'nor', 'not', 'so', 'yet', 'both', 'either',
+    'what', 'which', 'who', 'whom', 'this', 'that', 'these', 'those',
+    'how', 'when', 'where', 'why', 'if', 'then', 'than', 'because',
+    'while', 'although', 'though', 'unless', 'until', 'whether',
+    'it', 'its', 'he', 'she', 'they', 'we', 'you', 'i', 'me', 'my',
+    'about', 'also', 'just', 'like', 'more', 'most', 'much', 'no',
+    'yes', 'all', 'any', 'each', 'every', 'some', 'such', 'very',
+    'ask', 'tell', 'give', 'get', 'make', 'take', 'see', 'know',
+]);
+/**
+ * Extract capitalized multi-word phrases and proper nouns from a query.
+ * These are candidate entity names for exact-match co-retrieval.
+ *
+ * Matches patterns like "Acme Corp", "New Zealand", "Studio Ghibli",
+ * single capitalized words like "Redis", and quoted phrases.
+ */
+export function extractNamedEntityCandidates(query) {
+    const candidates = new Set();
+    collectQuotedPhrases(query, candidates);
+    collectMultiWordNames(query, candidates);
+    collectSingleCapitalizedWords(query, candidates);
+    return [...candidates].filter((c) => c.length >= 2);
+}
+/** Extract quoted strings as entity candidates. */
+function collectQuotedPhrases(query, candidates) {
+    const quoted = query.match(/["']([^"']+)["']/g);
+    if (!quoted)
+        return;
+    for (const q of quoted) {
+        candidates.add(q.replace(/["']/g, '').trim());
+    }
+}
+/** Extract capitalized multi-word sequences, stripping stop words. */
+function collectMultiWordNames(query, candidates) {
+    const multiWord = query.match(/\b[A-Z][a-z]+(?:\s+[A-Z][a-z]+)+\b/g);
+    if (!multiWord)
+        return;
+    for (const m of multiWord) {
+        const cleaned = stripStopWords(m);
+        if (cleaned.length >= 2)
+            candidates.add(cleaned);
+    }
+}
+/** Extract single capitalized words that are not sentence-starters or stop words. */
+function collectSingleCapitalizedWords(query, candidates) {
+    const words = query.split(/\s+/);
+    for (let i = 0; i < words.length; i++) {
+        const word = words[i].replace(/[?.,!;:]/g, '');
+        if (!word || word.length <= 1)
+            continue;
+        const isCapitalized = /^[A-Z][a-z]*$/.test(word);
+        const isSentenceStart = i === 0 || /[.!?]$/.test(words[i - 1] ?? '');
+        if (isCapitalized && !isSentenceStart && !STOP_WORDS.has(word.toLowerCase())) {
+            candidates.add(word);
+        }
+    }
+}
+/** Strip leading and trailing stop words from a multi-word phrase. */
+function stripStopWords(phrase) {
+    const words = phrase.split(/\s+/);
+    let start = 0;
+    let end = words.length - 1;
+    while (start <= end && STOP_WORDS.has(words[start].toLowerCase()))
+        start++;
+    while (end >= start && STOP_WORDS.has(words[end].toLowerCase()))
+        end--;
+    return words.slice(start, end + 1).join(' ');
+}
+/**
+ * Co-retrieve all memories linked to entities whose names appear in the query.
+ * Uses exact name matching (case-insensitive) — no embedding or LLM needed.
+ *
+ * This ensures that when a user asks about "Acme Corp", all memories linked
+ * to the Acme Corp entity are included in the result set, even if their
+ * content embeddings don't match the query semantically.
+ */
+export async function coRetrieveByEntityNames(entityRepo, repo, userId, query, queryEmbedding, excludeIds, budget) {
+    const candidates = extractNamedEntityCandidates(query);
+    if (candidates.length === 0)
+        return { memories: [], matchedNames: [] };
+    const matchedEntityIds = [];
+    const matchedNames = [];
+    for (const name of candidates) {
+        const entities = await entityRepo.findEntitiesByName(userId, name);
+        for (const entity of entities) {
+            matchedEntityIds.push(entity.id);
+            if (!matchedNames.includes(entity.name)) {
+                matchedNames.push(entity.name);
+            }
+        }
+    }
+    if (matchedEntityIds.length === 0)
+        return { memories: [], matchedNames: [] };
+    const memoryIds = await entityRepo.findMemoryIdsByEntities(userId, matchedEntityIds, excludeIds, budget);
+    if (memoryIds.length === 0)
+        return { memories: [], matchedNames };
+    const memories = await repo.fetchMemoriesByIds(userId, memoryIds, queryEmbedding);
+    return { memories, matchedNames };
+}

package/dist/services/query-keyword-matches.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Shared query keyword matching utilities for retrieval-time reranking.
+ */
+/** Collapse light verb-form differences so event matching is less brittle. */
+export declare function normalizeKeywordToken(token: string): string;
+export declare function countKeywordMatches(content: string, keywords: string[]): number;

package/dist/services/query-keyword-matches.js

@@ -0,0 +1,56 @@
+/**
+ * Shared query keyword matching utilities for retrieval-time reranking.
+ */
+const IRREGULAR_KEYWORD_NORMALIZATION = {
+    won: 'win',
+    winning: 'win',
+    met: 'meet',
+    meeting: 'meet',
+    began: 'begin',
+    begun: 'begin',
+    started: 'start',
+    starting: 'start',
+    moved: 'move',
+    moving: 'move',
+    dated: 'date',
+    dating: 'date',
+    adopted: 'adopt',
+    adopting: 'adopt',
+    adoption: 'adopt',
+    expanded: 'expand',
+    expanding: 'expand',
+};
+const KEYWORD_STEM_SUFFIXES = ['ing', 'ed', 'es', 's'];
+/** Collapse light verb-form differences so event matching is less brittle. */
+export function normalizeKeywordToken(token) {
+    const irregular = IRREGULAR_KEYWORD_NORMALIZATION[token];
+    if (irregular)
+        return irregular;
+    for (const suffix of KEYWORD_STEM_SUFFIXES) {
+        if (token.length > suffix.length + 2 && token.endsWith(suffix)) {
+            return token.slice(0, -suffix.length);
+        }
+    }
+    return token;
+}
+/** Normalize free text into a whitespace-joined token string. */
+function normalizeKeywordText(text) {
+    return text
+        .toLowerCase()
+        .replace(/\b([a-z]+)'s\b/g, '$1')
+        .replace(/[^a-z0-9\s-]/g, ' ')
+        .split(/\s+/)
+        .filter(Boolean)
+        .map(normalizeKeywordToken)
+        .join(' ');
+}
+export function countKeywordMatches(content, keywords) {
+    const normalizedContent = normalizeKeywordText(content);
+    const contentTokens = new Set(normalizedContent.split(/\s+/).filter(Boolean));
+    const normalizedKeywords = [...new Set(keywords
+            .map(normalizeKeywordText)
+            .filter(Boolean))];
+    return normalizedKeywords.filter((keyword) => (keyword.includes(' ')
+        ? normalizedContent.includes(keyword)
+        : contentTokens.has(keyword))).length;
+}

package/dist/services/query-term-visibility.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Query-term visibility preservation for tiered context packaging.
+ *
+ * Tiered loading can compress a memory to L0/L1 and hide exact words from the
+ * user query. This helper upgrades only those compressed memories whose richer
+ * tiers reveal missing query terms without exceeding the caller's token budget.
+ *
+ * Returns the (possibly upgraded) assignments AND a list of memory ids whose
+ * reveal-bearing upgrade was rejected solely because of the token budget.
+ * Those ids feed `meta.budget_constrained` so callers can report budget
+ * pressure on visibility, separately from allocator-level pressure.
+ */
+import type { SearchResult } from '../db/memory-repository.js';
+import type { TierAssignment } from './tiered-loading.js';
+export interface VisibilityResult {
+    assignments: TierAssignment[];
+    /**
+     * Memory ids where a query-term-revealing upgrade existed but was
+     * skipped because `extra > remainingBudget`. A larger budget would
+     * have made these terms visible.
+     */
+    budgetBlockedVisibilityIds: string[];
+}
+/** Upgrade compressed memories when exact query terms are otherwise hidden. */
+export declare function preserveQueryTermVisibility(memories: SearchResult[], assignments: TierAssignment[], query: string, tokenBudget: number): VisibilityResult;
+export declare function sumAssignmentTokens(assignments: Array<{
+    estimatedTokens: number;
+}>): number;

package/dist/services/query-term-visibility.js

@@ -0,0 +1,100 @@
+/**
+ * Query-term visibility preservation for tiered context packaging.
+ *
+ * Tiered loading can compress a memory to L0/L1 and hide exact words from the
+ * user query. This helper upgrades only those compressed memories whose richer
+ * tiers reveal missing query terms without exceeding the caller's token budget.
+ *
+ * Returns the (possibly upgraded) assignments AND a list of memory ids whose
+ * reveal-bearing upgrade was rejected solely because of the token budget.
+ * Those ids feed `meta.budget_constrained` so callers can report budget
+ * pressure on visibility, separately from allocator-level pressure.
+ */
+import { estimateTokens, getContentAtTier } from './tiered-loading.js';
+const QUERY_TERM_MIN_LENGTH = 4;
+const QUERY_TERM_STOP_WORDS = new Set([
+    'what', 'when', 'where', 'which', 'with', 'from', 'that', 'this',
+    'recently', 'attend', 'attended', 'does', 'have', 'has', 'did',
+]);
+/** Upgrade compressed memories when exact query terms are otherwise hidden. */
+export function preserveQueryTermVisibility(memories, assignments, query, tokenBudget) {
+    const terms = extractQueryVisibilityTerms(query);
+    if (terms.length === 0)
+        return { assignments, budgetBlockedVisibilityIds: [] };
+    const nextAssignments = assignments.map((assignment) => ({ ...assignment }));
+    const budgetBlockedVisibilityIds = [];
+    let remaining = tokenBudget - sumAssignmentTokens(nextAssignments);
+    for (const memory of memories) {
+        const index = nextAssignments.findIndex((assignment) => assignment.memoryId === memory.id);
+        if (index === -1 || nextAssignments[index].tier === 'L2')
+            continue;
+        const decision = chooseVisibleTier(memory, nextAssignments[index], terms, remaining);
+        if (decision.kind === 'no-reveal')
+            continue;
+        if (decision.kind === 'budget-blocked') {
+            budgetBlockedVisibilityIds.push(memory.id);
+            continue;
+        }
+        remaining -= decision.upgrade.estimatedTokens - nextAssignments[index].estimatedTokens;
+        nextAssignments[index] = decision.upgrade;
+    }
+    return { assignments: nextAssignments, budgetBlockedVisibilityIds };
+}
+export function sumAssignmentTokens(assignments) {
+    return assignments.reduce((sum, assignment) => sum + assignment.estimatedTokens, 0);
+}
+/**
+ * Pick the affordable tier that reveals the most missing query terms.
+ * Tie-break by lower extra tokens. If every revealing tier exceeds the
+ * remaining budget, return `budget-blocked` so callers can flag visibility
+ * pressure separately from allocator pressure.
+ */
+function chooseVisibleTier(memory, assignment, terms, remainingBudget) {
+    const current = getContentAtTier(memory, assignment.tier).toLowerCase();
+    const fullContent = memory.content.toLowerCase();
+    const missingTerms = terms.filter((term) => !current.includes(term) && fullContent.includes(term));
+    if (missingTerms.length === 0)
+        return { kind: 'no-reveal' };
+    const candidates = collectRevealCandidates(memory, assignment, missingTerms);
+    if (candidates.length === 0)
+        return { kind: 'no-reveal' };
+    const affordable = candidates.filter((candidate) => candidate.extra <= remainingBudget);
+    if (affordable.length === 0)
+        return { kind: 'budget-blocked' };
+    affordable.sort((a, b) => (b.reveals - a.reveals) || (a.extra - b.extra));
+    const best = affordable[0];
+    return {
+        kind: 'upgrade',
+        upgrade: { memoryId: memory.id, tier: best.tier, estimatedTokens: best.tokens },
+    };
+}
+function collectRevealCandidates(memory, assignment, missingTerms) {
+    const candidates = [];
+    for (const tier of ['L1', 'L2']) {
+        if (tier === assignment.tier)
+            continue;
+        const content = getContentAtTier(memory, tier).toLowerCase();
+        const reveals = missingTerms.reduce((count, term) => content.includes(term) ? count + 1 : count, 0);
+        if (reveals === 0)
+            continue;
+        const tokens = estimateTokens(content);
+        const extra = tokens - assignment.estimatedTokens;
+        // Allow zero-extra upgrades: a richer tier with the same token cost
+        // is a strict win when it reveals a missing query term. Skip only
+        // strict downgrades (extra < 0), which would silently shrink the
+        // representation and surprise callers reading the tier label.
+        if (extra < 0)
+            continue;
+        candidates.push({ tier, tokens, extra, reveals });
+    }
+    return candidates;
+}
+function extractQueryVisibilityTerms(query) {
+    const terms = query
+        .toLowerCase()
+        .replace(/[^a-z0-9\s]/g, ' ')
+        .split(/\s+/)
+        .filter((term) => term.length >= QUERY_TERM_MIN_LENGTH)
+        .filter((term) => !QUERY_TERM_STOP_WORDS.has(term));
+    return [...new Set(terms)];
+}