@atomicmemory/core 1.0.0

package/dist/services/session-date.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Shared parser for transcript-level session dates.
+ *
+ * Benchmark and SDK callers can include a first-line header:
+ *   - `[Session date: ...]` — preferred explicit form
+ *   - `[<time_anchor> | Turn N]` or `[<time_anchor>]` — BEAM transcript form
+ *     where `<time_anchor>` is `Month-Day-Year` or any Date-parseable string
+ *
+ * Core uses this date as the logical observation timestamp for extraction,
+ * storage backdating, and context packaging.
+ *
+ * IMPORTANT: BEAM transcripts also produce bare turn markers like `[Turn 43]`
+ * when the loader splits a session mid-stream. The captured `Turn 43` would
+ * pass `Date.parse()` (which interprets the trailing number as a year — e.g.
+ * 2043). To prevent year corruption we require the captured anchor to look
+ * dated (contains a month name OR a 4-digit year) before passing to Date.parse.
+ */
+export declare function extractSessionTimestamp(conversationText: string): string | null;
+export declare function parseSessionDate(conversationText: string): Date | null;
+export declare function resolveSessionDate(explicitTimestamp: Date | undefined, conversationText: string): Date | undefined;

package/dist/services/session-date.js

@@ -0,0 +1,61 @@
+/**
+ * Shared parser for transcript-level session dates.
+ *
+ * Benchmark and SDK callers can include a first-line header:
+ *   - `[Session date: ...]` — preferred explicit form
+ *   - `[<time_anchor> | Turn N]` or `[<time_anchor>]` — BEAM transcript form
+ *     where `<time_anchor>` is `Month-Day-Year` or any Date-parseable string
+ *
+ * Core uses this date as the logical observation timestamp for extraction,
+ * storage backdating, and context packaging.
+ *
+ * IMPORTANT: BEAM transcripts also produce bare turn markers like `[Turn 43]`
+ * when the loader splits a session mid-stream. The captured `Turn 43` would
+ * pass `Date.parse()` (which interprets the trailing number as a year — e.g.
+ * 2043). To prevent year corruption we require the captured anchor to look
+ * dated (contains a month name OR a 4-digit year) before passing to Date.parse.
+ */
+const SESSION_DATE_PATTERN = /^\[Session date:\s*([^\]]+)\]/i;
+const BEAM_ANCHOR_PATTERN = /^\[([^|\]]+?)(?:\s*\|\s*Turn\s+\d+)?\]\s/i;
+// Lookahead validators for what counts as a real date string. Together they
+// reject `Turn 43`, `Turn 134`, `code block`, etc.
+const HAS_YEAR_4 = /\b\d{4}\b/;
+const HAS_MONTH_NAME = /\b(jan(uary)?|feb(ruary)?|mar(ch)?|apr(il)?|may|jun(e)?|jul(y)?|aug(ust)?|sep(t|tember)?|oct(ober)?|nov(ember)?|dec(ember)?)\b/i;
+const STARTS_WITH_TURN = /^\s*turn\b/i;
+export function extractSessionTimestamp(conversationText) {
+    const firstLine = conversationText.split('\n', 1)[0] ?? '';
+    const explicit = firstLine.match(SESSION_DATE_PATTERN);
+    if (explicit?.[1])
+        return explicit[1].trim();
+    const beam = firstLine.match(BEAM_ANCHOR_PATTERN);
+    if (!beam?.[1])
+        return null;
+    const candidate = beam[1].trim();
+    // Reject bare turn markers and other non-date captures.
+    if (STARTS_WITH_TURN.test(candidate))
+        return null;
+    if (!HAS_YEAR_4.test(candidate) && !HAS_MONTH_NAME.test(candidate))
+        return null;
+    return normalizeAnchor(candidate);
+}
+/**
+ * BEAM anchors look like `March-15-2024`. JS Date.parse() accepts
+ * `March 15 2024` (spaces) but rejects the hyphenated form. Replace
+ * inner hyphens with spaces so Date.parse() succeeds. Other formats
+ * (ISO, RFC) pass through unchanged.
+ */
+function normalizeAnchor(anchor) {
+    if (/^[A-Za-z]+-\d{1,2}-\d{4}$/.test(anchor))
+        return anchor.replace(/-/g, ' ');
+    return anchor;
+}
+export function parseSessionDate(conversationText) {
+    const timestamp = extractSessionTimestamp(conversationText);
+    if (!timestamp)
+        return null;
+    const parsed = new Date(timestamp);
+    return Number.isNaN(parsed.getTime()) ? null : parsed;
+}
+export function resolveSessionDate(explicitTimestamp, conversationText) {
+    return explicitTimestamp ?? parseSessionDate(conversationText) ?? undefined;
+}

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

@@ -0,0 +1,53 @@
+/**
+ * Multi-session answer-bearing packaging policy.
+ *
+ * Groups retrieved memories by source session (episode_id) and promotes
+ * answer-bearing atoms — those containing currencies, durations/dates,
+ * past-attendance language, or named participants — above generic
+ * advisory/recommendation content within each session group.
+ *
+ * Session groups are ordered chronologically by earliest memory.
+ * When all memories share one session (or have no episode_id),
+ * falls back to pure chronological sort to avoid unnecessary churn.
+ */
+import type { SearchResult } from '../db/repository-types.js';
+/**
+ * Detect whether a memory's content is answer-bearing: contains specific
+ * retrievable facts (currencies, durations, attendance, named participants)
+ * rather than generic advisory prose.
+ */
+export declare function isAnswerBearing(content: string): boolean;
+/**
+ * Detect whether a memory is advisory-only: matches generic advisory patterns
+ * AND does NOT match any answer-bearing pattern. Answer-bearing always wins.
+ */
+export declare function isAdvisoryOnly(content: string): boolean;
+/**
+ * Budget-aware trim that drops advisory atoms first.
+ * Answer-bearing memories always occupy first slots; advisory fills remainder.
+ */
+export declare function trimToAnswerBearingBudget(memories: SearchResult[], maxResults: number): SearchResult[];
+/**
+ * Three-tier within-session priority for a single memory.
+ *
+ *   Tier 1 — Direct answer: amounts, dates, counts, outcomes, scored results.
+ *            These are the facts most likely to directly answer a question.
+ *   Tier 2 — Supporting facts: participants, locations, state transitions,
+ *            attendance. Provide context for tier-1 facts.
+ *   Tier 3 — Advisory/context: everything else (recommendations, planning,
+ *            meta-conversation, or neutral prose).
+ *
+ * Chronological order is preserved within each tier.
+ */
+export declare function withinSessionTier(content: string): 1 | 2 | 3;
+/**
+ * Sort memories with session-aware answer-bearing promotion.
+ *
+ * When memories span multiple sessions (distinct episode_ids):
+ *   1. Group by episode_id
+ *   2. Promote answer-bearing atoms within each group
+ *   3. Order groups chronologically by earliest memory
+ *
+ * When all memories share one session, falls back to chronological sort.
+ */
+export declare function sortBySessionPriority(memories: SearchResult[]): SearchResult[];

package/dist/services/session-packaging.js

@@ -0,0 +1,182 @@
+/**
+ * Multi-session answer-bearing packaging policy.
+ *
+ * Groups retrieved memories by source session (episode_id) and promotes
+ * answer-bearing atoms — those containing currencies, durations/dates,
+ * past-attendance language, or named participants — above generic
+ * advisory/recommendation content within each session group.
+ *
+ * Session groups are ordered chronologically by earliest memory.
+ * When all memories share one session (or have no episode_id),
+ * falls back to pure chronological sort to avoid unnecessary churn.
+ */
+/** Currency amounts: $500, €200, 1000 dollars */
+const CURRENCY_PATTERN = /(?:\$|€|£|¥)\s*[\d,]+(?:\.\d+)?|\b\d[\d,]*(?:\.\d+)?\s*(?:dollars?|euros?|pounds?|USD|EUR|GBP|yen|yuan)\b/i;
+/** Durations: "3 months", "2 weeks"; named dates: "January 15" */
+const DURATION_DATE_PATTERN = /\b\d+\s*(?:hours?|days?|weeks?|months?|years?|minutes?|seconds?)\b|\b(?:January|February|March|April|May|June|July|August|September|October|November|December)\s+\d{1,2}\b/i;
+/** Past-attendance verbs indicating the user did something. */
+const ATTENDANCE_PATTERN = /\b(?:attended|visited|went\s+to|traveled\s+to|participated\s+in|joined|enrolled|signed\s+up|registered|completed|graduated|moved\s+to|flew\s+to|arrived)\b/i;
+/** Multi-word proper nouns: "Dr. Smith", "John Carter", "Miss Bee Providore" */
+const NAMED_PARTICIPANT_PATTERN = /\b(?:Dr\.?\s+[A-Z][a-z]+|[A-Z][a-z]+(?:\s+[A-Z][a-z]+)+)\b/;
+/** Explicit year references: "in 2023", "since 2019" */
+const YEAR_REFERENCE_PATTERN = /\b(?:in|since|from|until|before|after|around)\s+\d{4}\b/i;
+/** Specific people counts: "15 participants", "200 employees" */
+const QUANTITY_PATTERN = /\b\d+\s*(?:people|participants|attendees|members|students|employees|guests|speakers|teams?)\b/i;
+/** Explicit counts: "3 times", "5 occasions" */
+const EXPLICIT_COUNT_PATTERN = /\b\d+\s*(?:times|occasions|instances|sessions)\b/i;
+/** Location with proper noun: "at Stanford", "in Berlin" */
+const LOCATION_SPECIFICITY_PATTERN = /\b(?:at|in|near|from)\s+[A-Z][a-z]+(?:\s+[A-Z][a-z]+)*\b/;
+/** State transitions: "switched from X to Y" */
+const STATE_TRANSITION_PATTERN = /\b(?:switched|changed|moved|migrated|upgraded|transitioned)\s+(?:from|to)\b/i;
+/** Scored/measured results: "scored 170", "rated 4.5" */
+const COMPARATIVE_RESULT_PATTERN = /\b(?:scored|rated|ranked|received|earned|achieved)\s+\d/i;
+/** Concrete event outcomes: accepted, completed, won, passed, etc. */
+const EVENT_OUTCOME_PATTERN = /\b(?:accepted|completed|finished|passed|failed|won|lost|received|submitted|launched|published|hired|fired|promoted|resigned|retired|delivered|shipped)\b/i;
+/** Generic advisory prose from the assistant. */
+const ADVISORY_RECOMMENDATION_PATTERN = /\b(?:(?:assistant|AI)\s+(?:recommended|suggested|advised))\b/i;
+/** Vague planning without anchoring specifics. */
+const VAGUE_PLANNING_PATTERN = /\b(?:plans?\s+to|wants?\s+to|considering|thinking\s+about)\b/i;
+/** Meta-conversation summaries. */
+const META_CONVERSATION_PATTERN = /\b(?:discussed|talked\s+about|conversation\s+about)\b/i;
+/**
+ * Detect whether a memory's content is answer-bearing: contains specific
+ * retrievable facts (currencies, durations, attendance, named participants)
+ * rather than generic advisory prose.
+ */
+export function isAnswerBearing(content) {
+    return (CURRENCY_PATTERN.test(content) ||
+        DURATION_DATE_PATTERN.test(content) ||
+        ATTENDANCE_PATTERN.test(content) ||
+        NAMED_PARTICIPANT_PATTERN.test(content) ||
+        YEAR_REFERENCE_PATTERN.test(content) ||
+        QUANTITY_PATTERN.test(content) ||
+        EXPLICIT_COUNT_PATTERN.test(content) ||
+        LOCATION_SPECIFICITY_PATTERN.test(content) ||
+        STATE_TRANSITION_PATTERN.test(content) ||
+        COMPARATIVE_RESULT_PATTERN.test(content) ||
+        EVENT_OUTCOME_PATTERN.test(content));
+}
+/**
+ * Detect whether a memory is advisory-only: matches generic advisory patterns
+ * AND does NOT match any answer-bearing pattern. Answer-bearing always wins.
+ */
+export function isAdvisoryOnly(content) {
+    if (isAnswerBearing(content))
+        return false;
+    return (ADVISORY_RECOMMENDATION_PATTERN.test(content) ||
+        VAGUE_PLANNING_PATTERN.test(content) ||
+        META_CONVERSATION_PATTERN.test(content));
+}
+/**
+ * Budget-aware trim that drops advisory atoms first.
+ * Answer-bearing memories always occupy first slots; advisory fills remainder.
+ */
+export function trimToAnswerBearingBudget(memories, maxResults) {
+    if (memories.length <= maxResults)
+        return sortBySessionPriority(memories);
+    const answerBearingPool = [];
+    const advisoryPool = [];
+    for (const m of memories) {
+        if (isAnswerBearing(m.content)) {
+            answerBearingPool.push(m);
+        }
+        else {
+            advisoryPool.push(m);
+        }
+    }
+    const byScore = (a, b) => b.score - a.score;
+    answerBearingPool.sort(byScore);
+    advisoryPool.sort(byScore);
+    const selected = answerBearingPool.slice(0, maxResults);
+    const remaining = maxResults - selected.length;
+    if (remaining > 0) {
+        selected.push(...advisoryPool.slice(0, remaining));
+    }
+    return sortBySessionPriority(selected);
+}
+/** Chronological sort by created_at ascending. */
+function sortChronologically(memories) {
+    return [...memories].sort((a, b) => a.created_at.getTime() - b.created_at.getTime());
+}
+/**
+ * Three-tier within-session priority for a single memory.
+ *
+ *   Tier 1 — Direct answer: amounts, dates, counts, outcomes, scored results.
+ *            These are the facts most likely to directly answer a question.
+ *   Tier 2 — Supporting facts: participants, locations, state transitions,
+ *            attendance. Provide context for tier-1 facts.
+ *   Tier 3 — Advisory/context: everything else (recommendations, planning,
+ *            meta-conversation, or neutral prose).
+ *
+ * Chronological order is preserved within each tier.
+ */
+export function withinSessionTier(content) {
+    if (CURRENCY_PATTERN.test(content) ||
+        DURATION_DATE_PATTERN.test(content) ||
+        EXPLICIT_COUNT_PATTERN.test(content) ||
+        QUANTITY_PATTERN.test(content) ||
+        COMPARATIVE_RESULT_PATTERN.test(content) ||
+        YEAR_REFERENCE_PATTERN.test(content) ||
+        EVENT_OUTCOME_PATTERN.test(content)) {
+        return 1;
+    }
+    if (ATTENDANCE_PATTERN.test(content) ||
+        NAMED_PARTICIPANT_PATTERN.test(content) ||
+        LOCATION_SPECIFICITY_PATTERN.test(content) ||
+        STATE_TRANSITION_PATTERN.test(content)) {
+        return 2;
+    }
+    return 3;
+}
+/**
+ * Within a single session group, promote answer-bearing atoms above
+ * advisory atoms using a three-tier ordering. Chronological order is
+ * preserved within each tier.
+ */
+function promoteAnswerBearing(memories) {
+    const tier1 = [];
+    const tier2 = [];
+    const tier3 = [];
+    for (const m of memories) {
+        const tier = withinSessionTier(m.content);
+        if (tier === 1)
+            tier1.push(m);
+        else if (tier === 2)
+            tier2.push(m);
+        else
+            tier3.push(m);
+    }
+    return [
+        ...sortChronologically(tier1),
+        ...sortChronologically(tier2),
+        ...sortChronologically(tier3),
+    ];
+}
+/**
+ * Sort memories with session-aware answer-bearing promotion.
+ *
+ * When memories span multiple sessions (distinct episode_ids):
+ *   1. Group by episode_id
+ *   2. Promote answer-bearing atoms within each group
+ *   3. Order groups chronologically by earliest memory
+ *
+ * When all memories share one session, falls back to chronological sort.
+ */
+export function sortBySessionPriority(memories) {
+    if (memories.length <= 1)
+        return [...memories];
+    const episodes = new Set(memories.map((m) => m.episode_id));
+    if (episodes.size <= 1)
+        return sortChronologically(memories);
+    const groups = new Map();
+    for (const m of memories) {
+        const key = m.episode_id ?? 'no-session';
+        if (!groups.has(key))
+            groups.set(key, []);
+        groups.get(key).push(m);
+    }
+    const sortedGroups = [...groups.values()]
+        .map(promoteAnswerBearing)
+        .sort((a, b) => a[0].created_at.getTime() - b[0].created_at.getTime());
+    return sortedGroups.flat();
+}

package/dist/services/session-summary-generator.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Session + conversation summary generation for hierarchical retrieval (T2.2).
+ *
+ * Called at end-of-session ingest (session summary) and end-of-conversation
+ * ingest (conversation summary). Output is persisted to `session_summaries`
+ * and `conv_summaries` tables; embeddings are computed by the caller using
+ * the existing `embedText` pipeline.
+ *
+ * Cost-aware: small sessions (< MIN_FACTS_FOR_LLM facts) skip the LLM call
+ * and return a deterministic concat. Saves cost on tiny conversational
+ * fragments and keeps unit-test cost at zero.
+ *
+ * No new LLM provider — reuses the shared LLMProvider interface from llm.ts.
+ * Activated by `hierarchicalRetrievalEnabled=true` in IngestRuntimeConfig.
+ */
+import type { LLMProvider } from './llm.js';
+export interface SessionSummary {
+    summary: string;
+    topics: string[];
+    /** True when the LLM was invoked; false when the deterministic-skip path fired. */
+    llmInvoked: boolean;
+}
+export interface ConvSummary {
+    summary: string;
+    llmInvoked: boolean;
+}
+export interface SummaryGenerationOptions {
+    /** Random seed forwarded to the LLM provider when supported (for determinism). */
+    seed?: number;
+    /** Optional override for the small-session deterministic-skip threshold. */
+    minFactsForLlm?: number;
+}
+/**
+ * Generate a topical summary for one session.
+ *
+ * Returns `{summary, topics}`:
+ *  - summary  : ~100-token natural-language sketch ("kickoff: API design, auth choices")
+ *  - topics   : up to MAX_TOPICS short noun-phrase tags ("api design", "auth", "kickoff")
+ *
+ * For sessions with fewer than `minFactsForLlm` facts, returns a deterministic
+ * concat of the first 3 facts plus their first-noun-phrase as topics — this
+ * keeps unit tests free of LLM mocks and is empirically as good as a tiny LLM
+ * summary on short sessions.
+ */
+export declare function generateSessionSummary(sessionFacts: string[], llm: LLMProvider, opts?: SummaryGenerationOptions): Promise<SessionSummary>;
+/**
+ * Generate a conversation-level summary by rolling up session summaries.
+ *
+ * `sessionSummaries` are passed in chronological order. Output is ~200-token
+ * natural-language overview ("project kickoff through API redesign;
+ * decisions on Postgres + JWT auth; outstanding question on rate-limit").
+ */
+export declare function generateConvSummary(sessionSummaries: string[], llm: LLMProvider, opts?: SummaryGenerationOptions): Promise<ConvSummary>;

package/dist/services/session-summary-generator.js

@@ -0,0 +1,134 @@
+/**
+ * Session + conversation summary generation for hierarchical retrieval (T2.2).
+ *
+ * Called at end-of-session ingest (session summary) and end-of-conversation
+ * ingest (conversation summary). Output is persisted to `session_summaries`
+ * and `conv_summaries` tables; embeddings are computed by the caller using
+ * the existing `embedText` pipeline.
+ *
+ * Cost-aware: small sessions (< MIN_FACTS_FOR_LLM facts) skip the LLM call
+ * and return a deterministic concat. Saves cost on tiny conversational
+ * fragments and keeps unit-test cost at zero.
+ *
+ * No new LLM provider — reuses the shared LLMProvider interface from llm.ts.
+ * Activated by `hierarchicalRetrievalEnabled=true` in IngestRuntimeConfig.
+ */
+const MIN_FACTS_FOR_LLM = 5;
+const SESSION_SUMMARY_MAX_TOKENS = 150;
+const CONV_SUMMARY_MAX_TOKENS = 280;
+const MAX_TOPICS = 8;
+/**
+ * Generate a topical summary for one session.
+ *
+ * Returns `{summary, topics}`:
+ *  - summary  : ~100-token natural-language sketch ("kickoff: API design, auth choices")
+ *  - topics   : up to MAX_TOPICS short noun-phrase tags ("api design", "auth", "kickoff")
+ *
+ * For sessions with fewer than `minFactsForLlm` facts, returns a deterministic
+ * concat of the first 3 facts plus their first-noun-phrase as topics — this
+ * keeps unit tests free of LLM mocks and is empirically as good as a tiny LLM
+ * summary on short sessions.
+ */
+export async function generateSessionSummary(sessionFacts, llm, opts = {}) {
+    const minFacts = opts.minFactsForLlm ?? MIN_FACTS_FOR_LLM;
+    if (sessionFacts.length < minFacts) {
+        return deterministicSessionSummary(sessionFacts);
+    }
+    const userMsg = buildSessionPrompt(sessionFacts);
+    const raw = await llm.chat([
+        { role: 'system', content: SESSION_SYSTEM_PROMPT },
+        { role: 'user', content: userMsg },
+    ], { maxTokens: SESSION_SUMMARY_MAX_TOKENS, jsonMode: true, seed: opts.seed });
+    return parseSessionResponse(raw, sessionFacts);
+}
+/**
+ * Generate a conversation-level summary by rolling up session summaries.
+ *
+ * `sessionSummaries` are passed in chronological order. Output is ~200-token
+ * natural-language overview ("project kickoff through API redesign;
+ * decisions on Postgres + JWT auth; outstanding question on rate-limit").
+ */
+export async function generateConvSummary(sessionSummaries, llm, opts = {}) {
+    const minFacts = opts.minFactsForLlm ?? MIN_FACTS_FOR_LLM;
+    if (sessionSummaries.length < minFacts) {
+        return {
+            summary: sessionSummaries.join(' / ').slice(0, 600),
+            llmInvoked: false,
+        };
+    }
+    const userMsg = buildConvPrompt(sessionSummaries);
+    const raw = await llm.chat([
+        { role: 'system', content: CONV_SYSTEM_PROMPT },
+        { role: 'user', content: userMsg },
+    ], { maxTokens: CONV_SUMMARY_MAX_TOKENS, jsonMode: true, seed: opts.seed });
+    return { summary: parseConvResponse(raw), llmInvoked: true };
+}
+// ---------------------------------------------------------------------------
+// Prompts
+// ---------------------------------------------------------------------------
+const SESSION_SYSTEM_PROMPT = 'You produce a structured summary of one conversation session. ' +
+    'Output ONLY valid JSON of the form {"summary": "...", "topics": ["...", "..."]}. ' +
+    'The "summary" field is one to two sentences (≤ 100 tokens) describing what was ' +
+    'discussed and any decisions reached. The "topics" field is up to 8 short noun-phrase ' +
+    'tags. No prose outside the JSON.';
+const CONV_SYSTEM_PROMPT = 'You produce a structured summary of an entire conversation by rolling up its session ' +
+    'summaries. Output ONLY valid JSON of the form {"summary": "..."}. The "summary" field ' +
+    'is two to four sentences (≤ 200 tokens) covering the conversation arc. No prose ' +
+    'outside the JSON.';
+function buildSessionPrompt(facts) {
+    const enumerated = facts.slice(0, 50).map((f, i) => `${i + 1}. ${f}`).join('\n');
+    return `Session facts:\n${enumerated}\n\nReturn JSON {summary, topics}.`;
+}
+function buildConvPrompt(summaries) {
+    const enumerated = summaries.map((s, i) => `Session ${i + 1}: ${s}`).join('\n');
+    return `Session summaries (chronological):\n${enumerated}\n\nReturn JSON {summary}.`;
+}
+// ---------------------------------------------------------------------------
+// Deterministic-skip path
+// ---------------------------------------------------------------------------
+function deterministicSessionSummary(facts) {
+    const lead = facts.slice(0, 3).join(' / ').slice(0, 400);
+    const topics = extractDeterministicTopics(facts);
+    return { summary: lead, topics, llmInvoked: false };
+}
+function extractDeterministicTopics(facts) {
+    const tokens = facts
+        .flatMap((f) => f.toLowerCase().split(/\W+/))
+        .filter((t) => t.length >= 4);
+    const counts = new Map();
+    for (const t of tokens)
+        counts.set(t, (counts.get(t) ?? 0) + 1);
+    return Array.from(counts.entries())
+        .sort((a, b) => b[1] - a[1])
+        .slice(0, MAX_TOPICS)
+        .map(([word]) => word);
+}
+function parseSessionResponse(raw, fallbackFacts) {
+    const parsed = tryParseJson(raw);
+    if (!parsed || typeof parsed.summary !== 'string') {
+        return { ...deterministicSessionSummary(fallbackFacts), llmInvoked: true };
+    }
+    const topics = Array.isArray(parsed.topics)
+        ? parsed.topics.filter((t) => typeof t === 'string').slice(0, MAX_TOPICS)
+        : [];
+    return { summary: parsed.summary, topics, llmInvoked: true };
+}
+function parseConvResponse(raw) {
+    const parsed = tryParseJson(raw);
+    if (parsed && typeof parsed.summary === 'string')
+        return parsed.summary;
+    // Fail-safe: return raw text trimmed
+    return raw.trim().slice(0, 600);
+}
+function tryParseJson(raw) {
+    const trimmed = raw.trim();
+    // Tolerate ```json fenced blocks
+    const fence = trimmed.match(/^```(?:json)?\s*([\s\S]*?)```$/);
+    const body = fence ? fence[1].trim() : trimmed;
+    try {
+        return JSON.parse(body);
+    }
+    catch {
+        return null;
+    }
+}

package/dist/services/specialists/cr-specialist.d.ts

@@ -0,0 +1,52 @@
+/**
+ * CR (Contradiction Resolution) specialist.
+ *
+ * Replaces the deleted Layer 3 counter-edge-surface module which was
+ * broken (the [CONTRADICTS] marker confused Haiku into picking the wrong
+ * side). The new approach: explicit FACT A / FACT B framing via tool-use
+ * so the LLM produces BEAM's canonical "you said X but also Y" answer.
+ *
+ * Flow:
+ *   1) Pattern-match the query (e.g. "have I ever", "did I ever")
+ *   2) Query belief_edges for COUNTER edges among the retrieved top-K
+ *   3) Fetch BOTH sides of each edge
+ *   4) Call Haiku with explicit fact_a/fact_b framing via tool-use
+ *   5) Return the LLM's answer (which should follow the BEAM canonical shape)
+ */
+import type { BeliefEdgesRepository } from '../../db/belief-edges-repository.js';
+import type { MemoryRepository } from '../../db/memory-repository.js';
+/** Pattern check: should the CR specialist handle this query? */
+export declare function shouldInvokeCrSpecialist(query: string): boolean;
+export interface CrMemoryInput {
+    id: string;
+    text: string;
+}
+export interface CrSpecialistDeps {
+    /** Top-K retrieved memories from the shared search spine. */
+    memories: ReadonlyArray<CrMemoryInput>;
+    /** Original user query. */
+    query: string;
+    /** User ID scoping all DB lookups. */
+    userId: string;
+    /** Anthropic model ID (e.g. 'claude-haiku-4-5'). */
+    model: string;
+    /** BeliefEdgesRepository — null when TBC is disabled. */
+    beliefEdges: BeliefEdgesRepository | null;
+    /** MemoryRepository for fetching sides not present in top-K. */
+    memoryRepo: MemoryRepository;
+}
+export interface CrSpecialistResult {
+    /** The LLM answer in canonical "You said X but also Y" shape. */
+    answer: string;
+    /** Whether the specialist handled the query (false = fall through to spine). */
+    handled: boolean;
+    /** Number of bilateral contradiction pairs found. */
+    contradictionsFound: number;
+}
+/**
+ * Run the CR specialist.
+ *
+ * Returns handled=false when the query doesn't match the CR pattern,
+ * so callers can fall through to the standard search spine.
+ */
+export declare function runCrSpecialist(deps: CrSpecialistDeps): Promise<CrSpecialistResult>;

package/dist/services/specialists/cr-specialist.js

@@ -0,0 +1,121 @@
+/**
+ * CR (Contradiction Resolution) specialist.
+ *
+ * Replaces the deleted Layer 3 counter-edge-surface module which was
+ * broken (the [CONTRADICTS] marker confused Haiku into picking the wrong
+ * side). The new approach: explicit FACT A / FACT B framing via tool-use
+ * so the LLM produces BEAM's canonical "you said X but also Y" answer.
+ *
+ * Flow:
+ *   1) Pattern-match the query (e.g. "have I ever", "did I ever")
+ *   2) Query belief_edges for COUNTER edges among the retrieved top-K
+ *   3) Fetch BOTH sides of each edge
+ *   4) Call Haiku with explicit fact_a/fact_b framing via tool-use
+ *   5) Return the LLM's answer (which should follow the BEAM canonical shape)
+ */
+import { callAnthropicTool } from '../llm.js';
+/** Pattern check: should the CR specialist handle this query? */
+export function shouldInvokeCrSpecialist(query) {
+    // BEAM CR phrasings: "have I ever / did I ever / am I / do I / conflicting / contradict"
+    return /\b(have I (ever|already|previously)|did I (ever|already|previously)|am I (currently|now)|conflicting|contradict)\b/i.test(query);
+}
+const CR_TOOL_SCHEMA = {
+    name: 'answer_contradiction',
+    description: 'Answer a contradiction-resolution question by surfacing both conflicting facts.',
+    input_schema: {
+        type: 'object',
+        properties: {
+            both_sides_present: { type: 'boolean' },
+            answer_text: {
+                type: 'string',
+                description: 'BEAM canonical shape: "You said X but also Y. Could you clarify which is correct?"',
+            },
+        },
+        required: ['both_sides_present', 'answer_text'],
+    },
+};
+/** Resolve the text for a single memory side (top-K cache first, then DB). */
+async function resolveMemoryText(userId, id, topK, memoryRepo) {
+    const cached = topK.find(m => m.id === id);
+    if (cached)
+        return cached.text;
+    const row = await memoryRepo.getMemory(id, userId);
+    return row?.content ?? '';
+}
+/** Query COUNTER edges and resolve both sides into ContradictionPair[]. */
+async function fetchContradictions(deps) {
+    if (!deps.beliefEdges)
+        return [];
+    const topIds = deps.memories.map(m => m.id);
+    if (topIds.length === 0)
+        return [];
+    const edges = await deps.beliefEdges.findCounterEdgesForMemories(deps.userId, topIds);
+    if (edges.length === 0)
+        return [];
+    const pairs = [];
+    const seen = new Set();
+    for (const e of edges) {
+        const key = [e.sourceId, e.targetId].sort().join('|');
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        const [factA, factB] = await Promise.all([
+            resolveMemoryText(deps.userId, e.sourceId, deps.memories, deps.memoryRepo),
+            resolveMemoryText(deps.userId, e.targetId, deps.memories, deps.memoryRepo),
+        ]);
+        if (factA && factB) {
+            pairs.push({ factA, factB });
+        }
+    }
+    return pairs;
+}
+/** Build system prompt for CR tool-use call. */
+function buildSystemPrompt() {
+    return [
+        'You are answering a contradiction-resolution question.',
+        'The user\'s memory contains two conflicting facts about the same topic.',
+        'Surface both sides explicitly using this canonical shape:',
+        '',
+        '"You said X but also Y. Could you clarify which is correct?"',
+        '',
+        'Where X and Y are the two contradicting claims.',
+        'Call the answer_contradiction tool. Do NOT free-text.',
+    ].join('\n');
+}
+/** Build user message listing contradicting fact pairs. */
+function buildUserMessage(query, pairs) {
+    const lines = [
+        `User question: ${query}`,
+        '',
+        'Contradicting facts:',
+        ...pairs.flatMap((p, i) => [
+            `Pair ${i + 1}:`,
+            `  FACT A: ${p.factA}`,
+            `  FACT B (contradicts A): ${p.factB}`,
+        ]),
+    ];
+    return lines.join('\n');
+}
+/**
+ * Run the CR specialist.
+ *
+ * Returns handled=false when the query doesn't match the CR pattern,
+ * so callers can fall through to the standard search spine.
+ */
+export async function runCrSpecialist(deps) {
+    if (!shouldInvokeCrSpecialist(deps.query)) {
+        return { answer: '', handled: false, contradictionsFound: 0 };
+    }
+    const pairs = await fetchContradictions(deps);
+    if (pairs.length === 0) {
+        return { answer: '', handled: true, contradictionsFound: 0 };
+    }
+    const system = buildSystemPrompt();
+    const userText = buildUserMessage(deps.query, pairs);
+    const tool = await callAnthropicTool(deps.model, system, userText, CR_TOOL_SCHEMA);
+    return {
+        answer: tool.answer_text,
+        handled: true,
+        contradictionsFound: pairs.length,
+    };
+}