@atomicmemory/core 1.0.0

package/dist/services/msr-aggregator.js

@@ -0,0 +1,97 @@
+/**
+ * MSR cross-conversation aggregator.
+ *
+ * Retrieval-side intervention for multi-session-reasoning queries. v39-multihop
+ * diagnostic on v26 MSR failures: gold facts WERE in the top-K but spread
+ * across 2-4 conversations; the answer LLM could not synthesize them and
+ * returned inflated counts ("Twenty-three" vs gold "Four").
+ *
+ * Strategy: group retrieved memories by `episode_id` (= conversation id in
+ * BEAM). For each group with >=2 memories, emit a 1-sentence summary via the
+ * configured chat LLM (cheap — defaults to Haiku). Groups with a single
+ * memory pass through verbatim (no LLM call). The concatenated
+ * `## CONVERSATION N SUMMARY` blocks become an additional channel BEFORE
+ * the standard OBSERVATIONS / TIMELINE / ENTITY_STATE blocks.
+ *
+ * Fail-closed: any LLM error during summarization throws — no silent
+ * fallback to raw text. Matches the AUDN mutation invariant.
+ */
+const DEFAULT_MAX_TOKENS = 80;
+const NO_EPISODE_KEY = '__no_episode__';
+/** Group retrieved memories by episode_id, preserving first-seen order. */
+function groupByEpisode(memories) {
+    const groups = new Map();
+    for (const memory of memories) {
+        const key = memory.episode_id ?? NO_EPISODE_KEY;
+        const existing = groups.get(key);
+        if (existing) {
+            existing.push(memory);
+        }
+        else {
+            groups.set(key, [memory]);
+        }
+    }
+    return Array.from(groups.entries()).map(([key, mems]) => ({ key, memories: mems }));
+}
+/** Build the LLM prompt for a single conversation-summary call. */
+function buildSummaryPrompt(query, memories) {
+    const factLines = memories.map((m, i) => `${i + 1}. ${m.content}`).join('\n');
+    const system = 'You summarize what was discussed in one conversation. Output exactly one ' +
+        'concise sentence (max ~30 words) that captures only what relates to the ' +
+        "user's question. Do not invent facts. Do not list — write one sentence.";
+    const user = `User's question: ${query}\n\n` +
+        `Facts retrieved from this conversation:\n${factLines}\n\n` +
+        'One-sentence summary of what was discussed in this conversation that ' +
+        "relates to the user's question:";
+    return [
+        { role: 'system', content: system },
+        { role: 'user', content: user },
+    ];
+}
+/**
+ * Summarize a single conversation group via the chat LLM. Fail-closed: if the
+ * LLM throws or returns an empty string, this re-throws with context — no
+ * silent fallback.
+ */
+async function summarizeGroup(group, query, deps) {
+    const messages = buildSummaryPrompt(query, group.memories);
+    const text = await deps.llm.chat(messages, {
+        temperature: 0,
+        maxTokens: deps.maxTokensPerSummary ?? DEFAULT_MAX_TOKENS,
+    });
+    const trimmed = text.trim();
+    if (trimmed.length === 0) {
+        throw new Error(`msr-aggregator: LLM returned empty summary for episode_id=${group.key}`);
+    }
+    return trimmed;
+}
+/**
+ * Render a single memory's content verbatim — used for groups with exactly
+ * one memory, where summarization would only add LLM cost without
+ * cross-source synthesis benefit.
+ */
+function renderPassthrough(group) {
+    return group.memories[0].content.trim();
+}
+/**
+ * Build the per-conversation aggregated string. Groups are 1-indexed by
+ * first-seen episode order. Multi-memory groups go through the LLM; single-
+ * memory groups pass through verbatim.
+ *
+ * Returns an empty string when there are no retrieved memories — caller
+ * should treat that as "no MSR channel to add" and skip the prefix.
+ */
+export async function aggregateByConversation(memories, query, deps) {
+    if (memories.length === 0)
+        return '';
+    const groups = groupByEpisode(memories);
+    const sections = [];
+    for (let i = 0; i < groups.length; i++) {
+        const group = groups[i];
+        const body = group.memories.length >= 2
+            ? await summarizeGroup(group, query, deps)
+            : renderPassthrough(group);
+        sections.push(`## CONVERSATION ${i + 1} SUMMARY\n${body}`);
+    }
+    return sections.join('\n\n');
+}

package/dist/services/msr-detector.d.ts

@@ -0,0 +1,35 @@
+/**
+ * MSR (Multi-Session Reasoning) query detector — pure regex, no LLM.
+ *
+ * Distinct from the Phase 2 deterministic specialist in
+ * `services/specialists/msr-specialist.ts`. That module is an ANSWER-side
+ * specialist: it short-circuits the answer LLM and emits a number-word.
+ *
+ * THIS module is a RETRIEVAL-side classifier: when true, the caller (see
+ * `memory-search.ts`) inserts a cross-conversation aggregation channel into
+ * the injection text BEFORE the answer LLM sees the retrieved chunks.
+ *
+ * MSR queries explicitly span multiple conversations or sessions, e.g.
+ * "across my conversations", "different X I mentioned", "throughout all my
+ * chats". Single-conversation queries (KU, IE, SUM, CR) return false.
+ *
+ * v39-multihop diagnostic on v26 MSR failures showed gold facts WERE in the
+ * top-K but spread across 2-4 conversations; the answer LLM could not
+ * synthesize across them and gave inflated or noisy counts.
+ */
+/**
+ * Returns true iff the query explicitly references cross-conversation /
+ * cross-session aggregation. Pure regex, deterministic, no side effects.
+ *
+ * Examples that return true:
+ *   - "How many different user roles ... across my sessions?"
+ *   - "How many different features ... across my weather app conversations?"
+ *   - "What different topics have I discussed across all my chats?"
+ *
+ * Examples that return false:
+ *   - "What's the latest version of my dashboard?" (KU)
+ *   - "When does my first sprint end?" (IE)
+ *   - "Summarize my budget tracker project" (SUM)
+ *   - "Have I ever worked on Flask routes?" (CR — single-conversation lookup)
+ */
+export declare function isMsrQuery(query: string): boolean;

package/dist/services/msr-detector.js

@@ -0,0 +1,65 @@
+/**
+ * MSR (Multi-Session Reasoning) query detector — pure regex, no LLM.
+ *
+ * Distinct from the Phase 2 deterministic specialist in
+ * `services/specialists/msr-specialist.ts`. That module is an ANSWER-side
+ * specialist: it short-circuits the answer LLM and emits a number-word.
+ *
+ * THIS module is a RETRIEVAL-side classifier: when true, the caller (see
+ * `memory-search.ts`) inserts a cross-conversation aggregation channel into
+ * the injection text BEFORE the answer LLM sees the retrieved chunks.
+ *
+ * MSR queries explicitly span multiple conversations or sessions, e.g.
+ * "across my conversations", "different X I mentioned", "throughout all my
+ * chats". Single-conversation queries (KU, IE, SUM, CR) return false.
+ *
+ * v39-multihop diagnostic on v26 MSR failures showed gold facts WERE in the
+ * top-K but spread across 2-4 conversations; the answer LLM could not
+ * synthesize across them and gave inflated or noisy counts.
+ */
+/**
+ * MSR trigger patterns. Each pattern targets a phrase that explicitly signals
+ * cross-conversation aggregation. Patterns are tested case-insensitively and
+ * combined via OR — any match returns true.
+ */
+const MSR_PATTERNS = [
+    // "across my conversations / sessions / chats / weather app conversations"
+    /\bacross (?:my |all (?:my )?)?(?:conversations?|sessions?|chats?)\b/i,
+    /\bacross (?:my |all (?:my )?)?\w+(?:\s+\w+)?\s+(?:conversations?|sessions?|chats?)\b/i,
+    // "throughout all my conversations / chats"
+    /\bthroughout (?:all )?(?:my )?(?:conversations?|sessions?|chats?)\b/i,
+    // "different X I mentioned / talked about / discussed"
+    /\bdifferent\b[^?.]*\b(?:mentioned|talked|discussed|brought up|wanted|tried)\b/i,
+    // "how many X did I talk about / discuss / mention"
+    /\bhow many\b[^?.]*\b(?:talked|discussed|mentioned|chatted|wrote)\b/i,
+    // "what (different) topics / features / concerns have I (ever) X across"
+    /\b(?:what|which)\b[^?.]*\bacross (?:my |all (?:my )?)?(?:conversations?|sessions?|chats?)\b/i,
+    // "across (my|all (my)?) sessions" with possessive forms
+    /\bacross\s+all\s+(?:my\s+)?(?:conversations?|sessions?|chats?)\b/i,
+    // "in (any of|all of) my conversations / chats"
+    /\bin (?:any|all) of (?:my )?(?:conversations?|sessions?|chats?)\b/i,
+];
+/**
+ * Returns true iff the query explicitly references cross-conversation /
+ * cross-session aggregation. Pure regex, deterministic, no side effects.
+ *
+ * Examples that return true:
+ *   - "How many different user roles ... across my sessions?"
+ *   - "How many different features ... across my weather app conversations?"
+ *   - "What different topics have I discussed across all my chats?"
+ *
+ * Examples that return false:
+ *   - "What's the latest version of my dashboard?" (KU)
+ *   - "When does my first sprint end?" (IE)
+ *   - "Summarize my budget tracker project" (SUM)
+ *   - "Have I ever worked on Flask routes?" (CR — single-conversation lookup)
+ */
+export function isMsrQuery(query) {
+    if (!query || query.length === 0)
+        return false;
+    for (const pattern of MSR_PATTERNS) {
+        if (pattern.test(query))
+            return true;
+    }
+    return false;
+}

package/dist/services/namespace-retrieval.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Namespace-Aware Retrieval — hierarchical scope narrowing for memories.
+ *
+ * Adds project/topic/scope-aware retrieval as a pre-filter before vector
+ * search. Memories are tagged with a slash-separated namespace path
+ * (e.g., "project/atomicmem/docs", "user/preferences/editor") and
+ * retrieval can be scoped to a namespace prefix.
+ *
+ * Namespace hierarchy (Phase 2 Canonical Taxonomy):
+ *   - "user/preferences/*"
+ *   - "user/memories/*"
+ *   - "project/{project}/docs/*"
+ *   - "project/{project}/decisions/*"
+ *   - "project/{project}/tasks/*"
+ *   - "agent/{agent}/skills/*"
+ *   - "agent/{agent}/task-memories/*"
+ *   - "workspace/{workspace}/shared/*"
+ *
+ * This implements Phase 2's "Canonical Namespaces" from the
+ * OpenViking integration design (2026-03-20).
+ */
+/** A slash-separated namespace path. */
+export type Namespace = string;
+/**
+ * Parse a namespace string into its hierarchical segments.
+ * "project/atomicmem/docs" → ["project", "atomicmem", "docs"]
+ */
+export declare function parseNamespace(ns: string): string[];
+/**
+ * Return all ancestor scopes from root to leaf.
+ * "project/atomicmem/docs" → ["project", "project/atomicmem", "project/atomicmem/docs"]
+ */
+export declare function getAncestorScopes(ns: string): string[];
+/**
+ * Check if a memory's namespace matches a query scope.
+ * A scope matches if the memory's namespace starts with the scope prefix.
+ */
+export declare function isInScope(memoryNamespace: string | null, queryScope: string | null): boolean;
+/**
+ * Build a SQL WHERE clause for namespace prefix matching.
+ * Uses LIKE with escaped delimiters for prefix matching.
+ */
+export declare function buildNamespaceClause(scope: string | null, paramOffset: number): {
+    clause: string;
+    params: unknown[];
+} | null;
+/**
+ * Use LLM to classify a memory into the canonical taxonomy.
+ */
+export declare function classifyNamespace(content: string, sourceSite: string, keywords: string[]): Promise<string>;
+/**
+ * Extract a legacy namespace suggestion from memory content.
+ * Retained for fallback and non-LLM paths.
+ */
+export declare function inferNamespace(content: string, sourceSite: string, keywords: string[]): string | null;
+/**
+ * Derive a namespace for a composite from the namespaces of its member atomics.
+ * Returns the most common non-null namespace. If all members are null, returns null.
+ */
+export declare function deriveMajorityNamespace(memberNamespaces: Array<string | null>): string | null;

package/dist/services/namespace-retrieval.js

@@ -0,0 +1,180 @@
+/**
+ * Namespace-Aware Retrieval — hierarchical scope narrowing for memories.
+ *
+ * Adds project/topic/scope-aware retrieval as a pre-filter before vector
+ * search. Memories are tagged with a slash-separated namespace path
+ * (e.g., "project/atomicmem/docs", "user/preferences/editor") and
+ * retrieval can be scoped to a namespace prefix.
+ *
+ * Namespace hierarchy (Phase 2 Canonical Taxonomy):
+ *   - "user/preferences/*"
+ *   - "user/memories/*"
+ *   - "project/{project}/docs/*"
+ *   - "project/{project}/decisions/*"
+ *   - "project/{project}/tasks/*"
+ *   - "agent/{agent}/skills/*"
+ *   - "agent/{agent}/task-memories/*"
+ *   - "workspace/{workspace}/shared/*"
+ *
+ * This implements Phase 2's "Canonical Namespaces" from the
+ * OpenViking integration design (2026-03-20).
+ */
+import { llm } from './llm.js';
+/**
+ * Parse a namespace string into its hierarchical segments.
+ * "project/atomicmem/docs" → ["project", "atomicmem", "docs"]
+ */
+export function parseNamespace(ns) {
+    if (!ns || ns.trim() === '')
+        return [];
+    // Support both dot and slash during transition
+    const delimiter = ns.includes('/') ? '/' : '.';
+    return ns.split(delimiter).filter(Boolean);
+}
+/**
+ * Return all ancestor scopes from root to leaf.
+ * "project/atomicmem/docs" → ["project", "project/atomicmem", "project/atomicmem/docs"]
+ */
+export function getAncestorScopes(ns) {
+    const segments = parseNamespace(ns);
+    return segments.map((_, index) => segments.slice(0, index + 1).join(ns.includes('/') ? '/' : '.'));
+}
+/**
+ * Check if a memory's namespace matches a query scope.
+ * A scope matches if the memory's namespace starts with the scope prefix.
+ */
+export function isInScope(memoryNamespace, queryScope) {
+    if (queryScope === null || queryScope === '')
+        return true;
+    if (memoryNamespace === null || memoryNamespace === '')
+        return true;
+    const scopeSegments = parseNamespace(queryScope);
+    const memorySegments = parseNamespace(memoryNamespace);
+    if (memorySegments.length < scopeSegments.length)
+        return false;
+    for (let i = 0; i < scopeSegments.length; i++) {
+        if (memorySegments[i].toLowerCase() !== scopeSegments[i].toLowerCase())
+            return false;
+    }
+    return true;
+}
+/**
+ * Build a SQL WHERE clause for namespace prefix matching.
+ * Uses LIKE with escaped delimiters for prefix matching.
+ */
+export function buildNamespaceClause(scope, paramOffset) {
+    if (!scope || scope.trim() === '')
+        return null;
+    const escaped = scope.replace(/[%_\\]/g, '\\$&');
+    // Support both dot and slash prefix matching
+    const delimiter = scope.includes('/') ? '/' : '.';
+    return {
+        clause: `(m.namespace IS NULL OR m.namespace = $${paramOffset + 1} OR m.namespace LIKE $${paramOffset + 2})`,
+        params: [scope, `${escaped}${delimiter}%`],
+    };
+}
+const CLASSIFICATION_PROMPT = `You are a memory classifier. Categorize the given memory into the most appropriate canonical namespace.
+
+TAXONOMY:
+- user/preferences: Likes, dislikes, editor settings, UI preferences
+- user/memories: Personal facts, life events, non-technical context
+- project/{name}/docs: Documentation, architectural plans, guides
+- project/{name}/decisions: Key technical or product decisions made
+- project/{name}/tasks: Task progress, TODOs, bugs
+- agent/{name}/skills: Capability descriptions, tool usage patterns
+- agent/{name}/task-memories: Private working memory for specific tasks
+- workspace/shared: General knowledge or facts shared across all agents
+
+RULES:
+- Respond ONLY with the namespace path (e.g. "project/atomicmem/decisions").
+- Replace {name} with the actual project or agent name found in context.
+- Use lowercase and slashes.
+- If unsure, default to "user/memories".
+
+MEMORY:
+{{content}}
+
+SOURCE SITE:
+{{sourceSite}}
+
+KEYWORDS:
+{{keywords}}`;
+/**
+ * Use LLM to classify a memory into the canonical taxonomy.
+ */
+export async function classifyNamespace(content, sourceSite, keywords) {
+    const prompt = CLASSIFICATION_PROMPT
+        .replace('{{content}}', content)
+        .replace('{{sourceSite}}', sourceSite)
+        .replace('{{keywords}}', keywords.join(', '));
+    const response = await llm.chat([
+        { role: 'system', content: 'You are a precise classification engine.' },
+        { role: 'user', content: prompt },
+    ], { temperature: 0, maxTokens: 50 });
+    return response.trim().toLowerCase();
+}
+/**
+ * Extract a legacy namespace suggestion from memory content.
+ * Retained for fallback and non-LLM paths.
+ */
+export function inferNamespace(content, sourceSite, keywords) {
+    const lower = content.toLowerCase();
+    const kwLower = keywords.map((k) => k.toLowerCase());
+    if (sourceSite && sourceSite !== 'unknown') {
+        const site = sourceSite.replace(/[^a-z0-9]/gi, '/').toLowerCase();
+        return `site/${site}`;
+    }
+    for (const kw of kwLower) {
+        if (PROJECT_INDICATORS.some((p) => kw.includes(p))) {
+            const projectName = extractProjectName(lower, kwLower);
+            if (projectName)
+                return `project/${projectName}/docs`;
+        }
+    }
+    for (const [category, terms] of Object.entries(TOPIC_INDICATORS)) {
+        if (terms.some((t) => lower.includes(t) || kwLower.includes(t))) {
+            return `topic/${category}`;
+        }
+    }
+    return null;
+}
+const PROJECT_INDICATORS = ['project', 'repo', 'repository', 'codebase', 'workspace'];
+const TOPIC_INDICATORS = {
+    databases: ['postgresql', 'postgres', 'mysql', 'mongodb', 'redis', 'database', 'sql', 'nosql'],
+    frontend: ['react', 'vue', 'angular', 'css', 'html', 'ui', 'ux', 'frontend'],
+    backend: ['api', 'server', 'express', 'fastapi', 'django', 'backend', 'endpoint'],
+    infrastructure: ['docker', 'kubernetes', 'aws', 'gcp', 'azure', 'terraform', 'ci/cd', 'deploy'],
+    testing: ['test', 'testing', 'vitest', 'jest', 'playwright', 'e2e', 'unit test'],
+    security: ['auth', 'authentication', 'encryption', 'security', 'oauth', 'jwt'],
+};
+/**
+ * Derive a namespace for a composite from the namespaces of its member atomics.
+ * Returns the most common non-null namespace. If all members are null, returns null.
+ */
+export function deriveMajorityNamespace(memberNamespaces) {
+    const counts = new Map();
+    for (const ns of memberNamespaces) {
+        if (ns === null)
+            continue;
+        counts.set(ns, (counts.get(ns) ?? 0) + 1);
+    }
+    if (counts.size === 0)
+        return null;
+    let best = null;
+    let bestCount = 0;
+    for (const [ns, count] of counts) {
+        if (count > bestCount) {
+            best = ns;
+            bestCount = count;
+        }
+    }
+    return best;
+}
+function extractProjectName(content, keywords) {
+    for (const kw of keywords) {
+        if (!PROJECT_INDICATORS.includes(kw) && kw.length > 2 && /^[a-z0-9-]+$/.test(kw)) {
+            return kw;
+        }
+    }
+    return null;
+}

package/dist/services/observation-date-extraction.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Observation-date extraction helpers.
+ *
+ * Keeps benchmark-only temporal prompt and post-processing behavior behind one
+ * default-off option so relative-date experiments can run by configuration.
+ */
+import type { ExtractedFact } from './extraction.js';
+export interface ExtractionOptions {
+    observationDateExtractionEnabled?: boolean;
+}
+export declare function buildExtractionUserMessage(conversationText: string, options?: ExtractionOptions): string;
+export declare function applyObservationDateAnchors(facts: ExtractedFact[], conversationText: string, options?: ExtractionOptions): ExtractedFact[];

package/dist/services/observation-date-extraction.js

@@ -0,0 +1,50 @@
+/**
+ * Observation-date extraction helpers.
+ *
+ * Keeps benchmark-only temporal prompt and post-processing behavior behind one
+ * default-off option so relative-date experiments can run by configuration.
+ */
+import { annotateRelativeTemporalText, extractRelativeTemporalAnchors, } from './relative-temporal.js';
+import { extractSessionTimestamp, parseSessionDate } from './session-date.js';
+export function buildExtractionUserMessage(conversationText, options = {}) {
+    if (!options.observationDateExtractionEnabled) {
+        return `Conversation to extract from:\n${conversationText}`;
+    }
+    const observationTimestamp = extractObservationTimestamp(conversationText);
+    if (!observationTimestamp) {
+        return `Conversation to extract from:\n${conversationText}`;
+    }
+    return [
+        `Observation timestamp: ${observationTimestamp}`,
+        'Use this timestamp to resolve relative dates in the conversation.',
+        'For relative phrases such as "last Friday", include the resolved absolute date in extracted facts when possible.',
+        '',
+        `Conversation to extract from:\n${conversationText}`,
+    ].join('\n');
+}
+export function applyObservationDateAnchors(facts, conversationText, options = {}) {
+    if (!options.observationDateExtractionEnabled)
+        return facts;
+    const observationDate = parseObservationDate(conversationText);
+    if (!observationDate)
+        return facts;
+    return facts.map((fact) => annotateFact(fact, observationDate));
+}
+function annotateFact(fact, observationDate) {
+    const annotatedFact = annotateRelativeTemporalText(fact.fact, observationDate);
+    if (annotatedFact === fact.fact)
+        return fact;
+    const anchorKeywords = extractRelativeTemporalAnchors(fact.fact, observationDate)
+        .map((anchor) => anchor.eventDate);
+    return {
+        ...fact,
+        fact: annotatedFact,
+        keywords: [...new Set([...fact.keywords, ...anchorKeywords])],
+    };
+}
+function parseObservationDate(conversationText) {
+    return parseSessionDate(conversationText);
+}
+function extractObservationTimestamp(conversationText) {
+    return extractSessionTimestamp(conversationText);
+}

package/dist/services/observation-service.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Observation network service — synthesizes entity profiles from scattered
+ * facts across the memory store. Part of the 4-network architecture
+ * (Hindsight-inspired).
+ *
+ * Observations are NOT created during ingest. Instead, ingest marks entities
+ * as "dirty" in the observation_dirty table. This service processes the
+ * dirty queue asynchronously, synthesizing profiles via LLM and storing
+ * them as network='observation' memories.
+ *
+ * Why async: Entity profile synthesis requires reading all facts about an
+ * entity and calling an LLM — too expensive for the ingest hot path.
+ */
+import { ObservationRepository } from '../db/repository-observation.js';
+import { MemoryRepository } from '../db/memory-repository.js';
+export declare class ObservationService {
+    private observationRepo;
+    private memoryRepo;
+    constructor(observationRepo: ObservationRepository, memoryRepo: MemoryRepository);
+    /** Mark entity subjects as needing profile regeneration. Fire-and-forget safe. */
+    markDirty(userId: string, entityNames: string[]): Promise<void>;
+    /**
+     * Process pending observation regeneration tasks.
+     * Call this from a background job or periodic timer.
+     */
+    regeneratePending(limit?: number): Promise<number>;
+}

package/dist/services/observation-service.js

@@ -0,0 +1,84 @@
+/**
+ * Observation network service — synthesizes entity profiles from scattered
+ * facts across the memory store. Part of the 4-network architecture
+ * (Hindsight-inspired).
+ *
+ * Observations are NOT created during ingest. Instead, ingest marks entities
+ * as "dirty" in the observation_dirty table. This service processes the
+ * dirty queue asynchronously, synthesizing profiles via LLM and storing
+ * them as network='observation' memories.
+ *
+ * Why async: Entity profile synthesis requires reading all facts about an
+ * entity and calling an LLM — too expensive for the ingest hot path.
+ */
+import { embedText } from './embedding.js';
+import { llm } from './llm.js';
+const SYNTHESIS_PROMPT = `You are a memory synthesis system. Given a set of facts about a subject, produce a comprehensive profile summary.
+
+RULES:
+- Synthesize all facts into a coherent profile of the subject
+- Include: key attributes, relationships, preferences, and notable activities
+- Maintain factual accuracy — do not infer beyond what the facts state
+- Write in third person (e.g., "The user works at Google" not "You work at Google")
+- Keep the summary concise: 2-4 sentences for simple subjects, up to 8 for complex ones
+- Include temporal context when available (e.g., "as of March 2026")
+
+Return ONLY the profile summary text, no formatting or labels.`;
+export class ObservationService {
+    observationRepo;
+    memoryRepo;
+    constructor(observationRepo, memoryRepo) {
+        this.observationRepo = observationRepo;
+        this.memoryRepo = memoryRepo;
+    }
+    /** Mark entity subjects as needing profile regeneration. Fire-and-forget safe. */
+    async markDirty(userId, entityNames) {
+        await this.observationRepo.markDirty(userId, entityNames);
+    }
+    /**
+     * Process pending observation regeneration tasks.
+     * Call this from a background job or periodic timer.
+     */
+    async regeneratePending(limit = 10) {
+        const pending = await this.observationRepo.getPending(limit);
+        let processed = 0;
+        for (const { userId, subject } of pending) {
+            const memories = await this.observationRepo.findMemoriesForSubject(userId, subject);
+            if (memories.length === 0) {
+                await this.observationRepo.clearDirty(userId, subject);
+                continue;
+            }
+            const factsText = memories.map((m, i) => `[${i + 1}] ${m.content}`).join('\n');
+            const prompt = `Subject: ${subject}\n\nFacts:\n${factsText}`;
+            const profileText = await llm.chat([
+                { role: 'system', content: SYNTHESIS_PROMPT },
+                { role: 'user', content: prompt },
+            ], { temperature: 0, maxTokens: 300 });
+            if (!profileText.trim()) {
+                await this.observationRepo.clearDirty(userId, subject);
+                continue;
+            }
+            const embedding = await embedText(profileText);
+            // Expire previous observation for this subject
+            const existingId = await this.observationRepo.findExistingObservation(userId, subject);
+            if (existingId) {
+                await this.memoryRepo.expireMemory(userId, existingId);
+            }
+            // Store new observation
+            await this.memoryRepo.storeMemory({
+                userId,
+                content: profileText,
+                embedding,
+                memoryType: 'semantic',
+                importance: 0.8,
+                sourceSite: 'observation-service',
+                keywords: subject,
+                network: 'observation',
+                observationSubject: subject,
+            });
+            await this.observationRepo.clearDirty(userId, subject);
+            processed++;
+        }
+        return processed;
+    }
+}

package/dist/services/packaging-observability.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Packaging and assembly observability helpers.
+ *
+ * Builds explicit summaries for the packaged context emitted by search()
+ * without changing candidate membership, ranking, or canonical storage.
+ */
+import type { SearchResult } from '../db/memory-repository.js';
+import type { RetrievalMode } from './memory-service-types.js';
+import type { AssemblyTraceSummary, PackagingTraceSummary } from './retrieval-trace.js';
+import type { TraceCollector } from './retrieval-trace.js';
+import type { TierAssignment } from './tiered-loading.js';
+export interface FinalizePackagingInput {
+    outputMemories: SearchResult[];
+    mode: RetrievalMode;
+    injectionText: string;
+    estimatedContextTokens?: number;
+    tierAssignments?: TierAssignment[];
+    tokenBudget?: number;
+}
+/**
+ * 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 declare function finalizePackagingTrace(activeTrace: TraceCollector, input: FinalizePackagingInput): {
+    packagingSummary: PackagingTraceSummary;
+    assemblySummary: AssemblyTraceSummary;
+};