@atomicmemory/core 1.0.0

package/dist/services/supplemental-extraction.js

@@ -0,0 +1,116 @@
+/**
+ * Supplemental extraction coverage for high-signal deterministic facts.
+ * Merges quick extractor output into the main LLM extraction result when the
+ * supplemental fact adds missing entities, relations, or temporal detail.
+ */
+import { normalizeExtractedFacts } from './fact-normalization.js';
+import { quickExtractFacts } from './quick-extraction.js';
+import { containsRelativeTemporalPhrase } from './relative-temporal.js';
+const LITERAL_DETAIL_PATTERN = /\b(?:necklace|book|books|song|songs|music|musicians|fan|painting|paintings|photo|poster|posters|library|store|decor|furniture|flooring|pet|pets|cat|cats|dog|dogs|guinea pig|turtle|turtles|snake|snakes|workshop|poetry reading|sign|slipper|bowl)\b/i;
+const QUOTED_TEXT_PATTERN = /["“”][^"“”]{2,}["“”]/;
+const TEMPORAL_DETAIL_PATTERN = /\b(last year|last month|last week|last [a-z]+|today|tomorrow|first|second|before|after|deadline|deadlines|timeline|relative to|months later|weeks later|few days ago|for \d+ years?|for three years?|for two years?|for four years?|for five years?)\b/i;
+const EVENT_DETAIL_PATTERN = /\b(?:accepted|interview|internship|mentor(?:ed|ing)?|network(?:ing)?|social media|competition|investor(?:s)?|fashion editors|analytics tools|video presentation|website|collaborat(?:e|ion)|dance class|Shia Labeouf|trip|travel(?:ed|ling)?|retreat|phuket|doctor|doc|check-up|appointment|blog|car mods?|restor(?:e|ed|ing|ation))\b/i;
+export function mergeSupplementalFacts(primaryFacts, conversationText) {
+    const merged = [...primaryFacts];
+    const supplementalFacts = normalizeExtractedFacts(quickExtractFacts(conversationText));
+    for (const fact of supplementalFacts) {
+        const upgradeIndex = findUpgradeableFactIndex(merged, fact);
+        if (upgradeIndex >= 0) {
+            merged[upgradeIndex] = fact;
+            continue;
+        }
+        if (shouldIncludeSupplementalFact(merged, fact)) {
+            merged.push(fact);
+        }
+    }
+    return dedupeByNormalizedFact(merged);
+}
+function shouldIncludeSupplementalFact(existingFacts, candidate) {
+    const normalizedFact = normalizeFact(candidate.fact);
+    if (existingFacts.some((fact) => normalizeFact(fact.fact) === normalizedFact)) {
+        return false;
+    }
+    const candidateEntities = listNonUserEntities(candidate);
+    const candidateShape = buildCoverageShape(candidate);
+    const candidateAddsTemporalDetail = hasRelativeTemporalDetail(candidate.fact);
+    const candidateAddsLiteralDetail = hasLiteralDetail(candidate.fact);
+    const candidateAddsEventDetail = hasEventDetail(candidate.fact);
+    if (candidateEntities.length === 0 && !candidateAddsTemporalDetail && !candidateAddsLiteralDetail && !candidateAddsEventDetail) {
+        return false;
+    }
+    const shapeMatches = existingFacts.filter((fact) => buildCoverageShape(fact) === candidateShape);
+    if (shapeMatches.length === 0) {
+        return true;
+    }
+    if (!candidateAddsTemporalDetail && !candidateAddsLiteralDetail && !candidateAddsEventDetail) {
+        return false;
+    }
+    if (candidateAddsTemporalDetail) {
+        return shapeMatches.every((fact) => !hasRelativeTemporalDetail(fact.fact));
+    }
+    if (candidateAddsLiteralDetail) {
+        return shapeMatches.every((fact) => !hasLiteralDetail(fact.fact));
+    }
+    if (candidateAddsEventDetail) {
+        return shapeMatches.every((fact) => !hasEventDetail(fact.fact));
+    }
+    return false;
+}
+function findUpgradeableFactIndex(existingFacts, candidate) {
+    const candidateEntities = new Set(listNonUserEntities(candidate));
+    const candidateRelations = new Set(candidate.relations.map((relation) => relation.type));
+    const candidateAddsTemporalDetail = hasRelativeTemporalDetail(candidate.fact);
+    const candidateAddsLiteralDetail = hasLiteralDetail(candidate.fact);
+    const candidateAddsEventDetail = hasEventDetail(candidate.fact);
+    return existingFacts.findIndex((fact) => {
+        const existingEntities = listNonUserEntities(fact);
+        if (existingEntities.length === 0 || candidateEntities.size <= existingEntities.length) {
+            return false;
+        }
+        const entitiesCovered = existingEntities.every((entity) => candidateEntities.has(entity));
+        if (!entitiesCovered) {
+            return false;
+        }
+        const existingRelations = fact.relations.map((relation) => relation.type);
+        const relationsCovered = existingRelations.every((relation) => candidateRelations.has(relation));
+        if (!relationsCovered) {
+            return false;
+        }
+        if (candidate.fact.length <= fact.fact.length + 10) {
+            return false;
+        }
+        return candidateAddsTemporalDetail
+            || candidateAddsLiteralDetail
+            || candidateAddsEventDetail
+            || !hasRelativeTemporalDetail(fact.fact);
+    });
+}
+function buildCoverageShape(fact) {
+    const entities = listNonUserEntities(fact).join('|');
+    const relations = fact.relations.map((relation) => relation.type).sort().join('|');
+    return `${entities}::${relations}`;
+}
+function listNonUserEntities(fact) {
+    return [...new Set(fact.entities
+            .map((entity) => entity.name.trim().toLowerCase())
+            .filter((name) => name && name !== 'user'))].sort();
+}
+function hasRelativeTemporalDetail(text) {
+    return TEMPORAL_DETAIL_PATTERN.test(text) || containsRelativeTemporalPhrase(text);
+}
+function hasLiteralDetail(text) {
+    return LITERAL_DETAIL_PATTERN.test(text) || QUOTED_TEXT_PATTERN.test(text);
+}
+function hasEventDetail(text) {
+    return EVENT_DETAIL_PATTERN.test(text);
+}
+function dedupeByNormalizedFact(facts) {
+    const unique = new Map();
+    for (const fact of facts) {
+        unique.set(normalizeFact(fact.fact), fact);
+    }
+    return [...unique.values()];
+}
+function normalizeFact(text) {
+    return text.toLowerCase().replace(/\s+/g, ' ').trim();
+}

package/dist/services/tbc-execution.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Typed Belief Calculus (TBC) — Phase 2 executor.
+ *
+ * Bridges a `BeliefOperationDecision` produced by `decideBeliefOperator`
+ * to the existing AUDN ingest pipeline. Affirm / Update / Retract /
+ * Supersede route to the standard AUDN executor (`executeAudnDecision`).
+ * Promote / Demote / EvidenceFor / Counter are TBC-only and are handled
+ * inline against `MemoryStore.updateMemoryMetadata` — no schema change in
+ * this phase.
+ *
+ * Fail-closed: if the LLM resolver throws, the error propagates to the
+ * caller. We never fall back to `ADD` silently, matching AUDN semantics.
+ *
+ * Schema rule: Phase 2 writes belief state into existing JSONB metadata
+ * only. No new columns or tables are touched.
+ */
+import { type AudnTraceContext } from './memory-audn.js';
+import { BeliefOperator, type BeliefOperationDecision } from './typed-belief-calculus.js';
+import type { CandidateMemory } from './conflict-policy.js';
+import type { AudnFactContext, FactResult, MemoryServiceDeps, Outcome } from './memory-service-types.js';
+export type BeliefTier = 'standard' | 'directive' | 'demoted' | 'retracted';
+export interface DualWriteEdgeInput {
+    userId: string;
+    sourceId: string;
+    targetId: string;
+    edgeType: 'evidence_for' | 'counter' | 'supersedes' | 'promotes' | 'demotes';
+    weight: number;
+    rationale: string;
+}
+export interface DualWriteColumnUpdate {
+    userId: string;
+    memoryId: string;
+    confidence?: number;
+    beliefTier?: BeliefTier;
+    mutationType?: BeliefOperator;
+}
+export interface BeliefDualWriteHook {
+    appendEdge(input: DualWriteEdgeInput): Promise<void>;
+    updateColumns(input: DualWriteColumnUpdate): Promise<void>;
+}
+/** Install a dual-write hook. Pass `undefined` to clear (e.g., in tests). */
+export declare function setBeliefDualWriteHook(hook: BeliefDualWriteHook | undefined): void;
+/** Resolve a TBC decision via the LLM resolver and execute it. */
+export declare function resolveAndExecuteTbc(deps: MemoryServiceDeps, ctx: AudnFactContext, candidates: readonly CandidateMemory[], candidateIds: Set<string>, supersededTargets: Set<string>, traceContext: AudnTraceContext): Promise<FactResult>;
+/** Dispatch a TBC decision to the right executor branch. */
+export declare function executeTbcDecision(deps: MemoryServiceDeps, decision: BeliefOperationDecision, ctx: AudnFactContext, candidateIds: Set<string>): Promise<{
+    outcome: Outcome;
+    memoryId: string | null;
+}>;

package/dist/services/tbc-execution.js

@@ -0,0 +1,284 @@
+/**
+ * Typed Belief Calculus (TBC) — Phase 2 executor.
+ *
+ * Bridges a `BeliefOperationDecision` produced by `decideBeliefOperator`
+ * to the existing AUDN ingest pipeline. Affirm / Update / Retract /
+ * Supersede route to the standard AUDN executor (`executeAudnDecision`).
+ * Promote / Demote / EvidenceFor / Counter are TBC-only and are handled
+ * inline against `MemoryStore.updateMemoryMetadata` — no schema change in
+ * this phase.
+ *
+ * Fail-closed: if the LLM resolver throws, the error propagates to the
+ * caller. We never fall back to `ADD` silently, matching AUDN semantics.
+ *
+ * Schema rule: Phase 2 writes belief state into existing JSONB metadata
+ * only. No new columns or tables are touched.
+ */
+import { timed } from './timing.js';
+// fallow-ignore-next-line circular-dependencies
+import { executeAudnDecision } from './memory-audn.js';
+import { storeCanonicalFact } from './memory-storage.js';
+import { BeliefOperator, decideBeliefOperator, } from './typed-belief-calculus.js';
+const DEMOTE_DELTA_FLOOR = -1.0;
+let dualWriteHook;
+/** Install a dual-write hook. Pass `undefined` to clear (e.g., in tests). */
+export function setBeliefDualWriteHook(hook) {
+    dualWriteHook = hook;
+}
+async function dualWriteEdge(input) {
+    if (!dualWriteHook)
+        return;
+    await dualWriteHook.appendEdge(input);
+}
+async function dualWriteColumns(input) {
+    if (!dualWriteHook)
+        return;
+    await dualWriteHook.updateColumns(input);
+}
+/** Resolve a TBC decision via the LLM resolver and execute it. */
+export async function resolveAndExecuteTbc(deps, ctx, candidates, candidateIds, supersededTargets, traceContext) {
+    const decision = await timed('ingest.fact.tbc', () => decideBeliefOperator(ctx.fact, candidates));
+    const executed = await executeTbcDecision(deps, decision, ctx, candidateIds);
+    if (decision.operator === BeliefOperator.Supersede && executed.memoryId) {
+        supersededTargets.add(executed.memoryId);
+    }
+    return {
+        ...executed,
+        embedding: ctx.embedding,
+        trace: buildTbcTrace(traceContext, decision, executed),
+    };
+}
+/** Dispatch a TBC decision to the right executor branch. */
+export async function executeTbcDecision(deps, decision, ctx, candidateIds) {
+    switch (decision.operator) {
+        case BeliefOperator.Affirm:
+        case BeliefOperator.Update:
+        case BeliefOperator.Retract:
+        case BeliefOperator.Supersede:
+            return executeAudnDecision(deps, toAudnDecision(decision, ctx), candidateIds, ctx);
+        case BeliefOperator.Promote:
+            return executePromote(deps, decision, ctx);
+        case BeliefOperator.Demote:
+            return executeDemote(deps, decision, ctx);
+        case BeliefOperator.EvidenceFor:
+            return executeEdge(deps, decision, ctx, 'evidence_for');
+        case BeliefOperator.Counter:
+            return executeEdge(deps, decision, ctx, 'counter');
+    }
+}
+/** Build an AUDN-shape decision from a TBC decision for the four shared operators. */
+function toAudnDecision(decision, ctx) {
+    const action = mapToAudnAction(decision.operator);
+    const targetMemoryId = decision.target_claim_id ?? null;
+    const updatedContent = action === 'UPDATE' ? ctx.fact.fact : null;
+    return { action, targetMemoryId, updatedContent, contradictionConfidence: null, clarificationNote: null };
+}
+function mapToAudnAction(operator) {
+    if (operator === BeliefOperator.Affirm)
+        return 'NOOP';
+    if (operator === BeliefOperator.Update)
+        return 'UPDATE';
+    if (operator === BeliefOperator.Retract)
+        return 'DELETE';
+    if (operator === BeliefOperator.Supersede)
+        return 'SUPERSEDE';
+    throw new Error(`mapToAudnAction: ${operator} is TBC-only`);
+}
+/** Promote: write directive flag + mutation_type into existing target metadata. */
+async function executePromote(deps, decision, ctx) {
+    const targetId = requireTarget(decision, BeliefOperator.Promote);
+    const target = await deps.stores.memory.getMemory(targetId, ctx.userId);
+    if (!target) {
+        return storeCanonicalFact(deps, ctx);
+    }
+    const current = readBeliefMetadata(target.metadata);
+    const nextConfidence = clamp(currentConfidence(current) + Math.max(0, decision.confidence_delta));
+    const nextHistory = appendRevision(current.revision_history, {
+        operator: BeliefOperator.Promote,
+        confidence: nextConfidence,
+        content: target.content,
+        recordedAt: new Date().toISOString(),
+        rationale: decision.rationale,
+    });
+    await deps.stores.memory.updateMemoryMetadata(ctx.userId, targetId, {
+        ...target.metadata,
+        mutation_type: BeliefOperator.Promote,
+        directive: true,
+        confidence: nextConfidence,
+        revision_history: nextHistory,
+    });
+    // Phase 3 dual-write: column update + promotes edge from new claim → target
+    await dualWriteColumns({
+        userId: ctx.userId,
+        memoryId: targetId,
+        confidence: nextConfidence,
+        beliefTier: 'directive',
+        mutationType: BeliefOperator.Promote,
+    });
+    await dualWriteEdge({
+        userId: ctx.userId,
+        sourceId: targetId,
+        targetId,
+        edgeType: 'promotes',
+        weight: clamp(Math.max(0, decision.confidence_delta), 0, 1),
+        rationale: decision.rationale,
+    });
+    return { outcome: 'updated', memoryId: targetId };
+}
+/** Demote: lower confidence and record the soft-conflict revision. */
+async function executeDemote(deps, decision, ctx) {
+    const targetId = requireTarget(decision, BeliefOperator.Demote);
+    const target = await deps.stores.memory.getMemory(targetId, ctx.userId);
+    if (!target) {
+        return storeCanonicalFact(deps, ctx);
+    }
+    const current = readBeliefMetadata(target.metadata);
+    const delta = Math.min(0, Math.max(DEMOTE_DELTA_FLOOR, decision.confidence_delta));
+    const nextConfidence = clamp(currentConfidence(current) + delta);
+    const nextHistory = appendRevision(current.revision_history, {
+        operator: BeliefOperator.Demote,
+        confidence: nextConfidence,
+        content: target.content,
+        recordedAt: new Date().toISOString(),
+        rationale: decision.rationale,
+    });
+    await deps.stores.memory.updateMemoryMetadata(ctx.userId, targetId, {
+        ...target.metadata,
+        mutation_type: BeliefOperator.Demote,
+        confidence: nextConfidence,
+        revision_history: nextHistory,
+    });
+    // Phase 3 dual-write: column update + demotes edge with negative weight
+    await dualWriteColumns({
+        userId: ctx.userId,
+        memoryId: targetId,
+        confidence: nextConfidence,
+        beliefTier: 'demoted',
+        mutationType: BeliefOperator.Demote,
+    });
+    await dualWriteEdge({
+        userId: ctx.userId,
+        sourceId: targetId,
+        targetId,
+        edgeType: 'demotes',
+        weight: -clamp(Math.abs(delta), 0, 1),
+        rationale: decision.rationale,
+    });
+    return { outcome: 'updated', memoryId: targetId };
+}
+/** EvidenceFor / Counter: append a graph-only edge into the target's metadata. */
+async function executeEdge(deps, decision, ctx, edgeType) {
+    const operator = edgeType === 'evidence_for' ? BeliefOperator.EvidenceFor : BeliefOperator.Counter;
+    const targetId = requireTarget(decision, operator);
+    const target = await deps.stores.memory.getMemory(targetId, ctx.userId);
+    if (!target) {
+        return storeCanonicalFact(deps, ctx);
+    }
+    const current = readBeliefMetadata(target.metadata);
+    const weight = edgeType === 'evidence_for'
+        ? clamp(Math.max(0, decision.confidence_delta), 0, 1)
+        : -clamp(Math.abs(Math.min(0, decision.confidence_delta)), 0, 1);
+    const entry = {
+        operator,
+        confidence: currentConfidence(current),
+        content: null,
+        recordedAt: new Date().toISOString(),
+        rationale: decision.rationale,
+        weight,
+    };
+    const nextEdges = appendRevision(current.belief_edges, entry);
+    await deps.stores.memory.updateMemoryMetadata(ctx.userId, targetId, {
+        ...target.metadata,
+        mutation_type: operator,
+        belief_edges: nextEdges,
+    });
+    // Phase 3 dual-write: typed edge into belief_edges + mutation_type column.
+    // Source is the new claim (not yet stored as a row) — for now we record
+    // target → target with the rationale; Phase 4 will store the source claim
+    // first and link the edge to the new memory row.
+    await dualWriteColumns({
+        userId: ctx.userId,
+        memoryId: targetId,
+        mutationType: operator,
+    });
+    await dualWriteEdge({
+        userId: ctx.userId,
+        sourceId: targetId,
+        targetId,
+        edgeType,
+        weight,
+        rationale: decision.rationale,
+    });
+    return { outcome: 'updated', memoryId: targetId };
+}
+function readBeliefMetadata(metadata) {
+    return metadata;
+}
+function currentConfidence(meta) {
+    return typeof meta.confidence === 'number' && Number.isFinite(meta.confidence) ? meta.confidence : 1.0;
+}
+function appendRevision(prior, entry) {
+    return [entry, ...(prior ?? [])];
+}
+function clamp(value, min = 0, max = 1) {
+    if (!Number.isFinite(value))
+        return min;
+    return Math.max(min, Math.min(max, value));
+}
+function requireTarget(decision, operator) {
+    if (!decision.target_claim_id) {
+        throw new Error(`TBC ${operator} requires target_claim_id but resolver returned none`);
+    }
+    return decision.target_claim_id;
+}
+function reasonCodeForOperator(operator) {
+    const map = {
+        [BeliefOperator.Affirm]: 'tbc-affirm',
+        [BeliefOperator.Update]: 'tbc-update',
+        [BeliefOperator.Retract]: 'tbc-retract',
+        [BeliefOperator.Supersede]: 'tbc-supersede',
+        [BeliefOperator.Promote]: 'tbc-promote',
+        [BeliefOperator.Demote]: 'tbc-demote',
+        [BeliefOperator.EvidenceFor]: 'tbc-evidence-for',
+        [BeliefOperator.Counter]: 'tbc-counter',
+    };
+    return map[operator];
+}
+function actionForOperator(operator) {
+    if (operator === BeliefOperator.Affirm)
+        return 'NOOP';
+    if (operator === BeliefOperator.Update)
+        return 'UPDATE';
+    if (operator === BeliefOperator.Retract)
+        return 'DELETE';
+    if (operator === BeliefOperator.Supersede)
+        return 'SUPERSEDE';
+    return 'UPDATE';
+}
+function buildTbcTrace(traceContext, decision, result) {
+    return {
+        factText: traceContext.fact.fact,
+        headline: traceContext.fact.headline,
+        factType: traceContext.fact.type,
+        importance: traceContext.fact.importance,
+        ...(traceContext.logicalTimestamp ? { logicalTimestamp: traceContext.logicalTimestamp.toISOString() } : {}),
+        writeSecurity: {
+            allowed: traceContext.writeSecurity.allowed,
+            blockedBy: traceContext.writeSecurity.blockedBy,
+            trustScore: traceContext.writeSecurity.trust.score,
+        },
+        ...(traceContext.entropyResult ? { entropyGate: traceContext.entropyResult } : {}),
+        candidates: traceContext.candidates,
+        decision: {
+            source: 'tbc',
+            action: actionForOperator(decision.operator),
+            reasonCode: reasonCodeForOperator(decision.operator),
+            targetMemoryId: decision.target_claim_id ?? null,
+            candidateIds: traceContext.candidates.map((candidate) => candidate.id),
+            beliefOperator: decision.operator,
+        },
+        outcome: result.outcome,
+        memoryId: result.memoryId,
+        beliefOperator: decision.operator,
+    };
+}

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

@@ -0,0 +1,56 @@
+/**
+ * BEAM v38: write-time temporal classifier.
+ *
+ * Given a freshly-extracted memory text plus its observed timestamp, the
+ * classifier returns either:
+ *   - { stateKey, eventStart, eventEnd: null }  for stateful facts
+ *     (e.g. "user lives in Austin", "API response time is 200ms")
+ *   - null for non-stateful memories (events, one-time mentions)
+ *
+ * The classifier is a thin LLM wrapper that uses Anthropic forced
+ * tool-use for a deterministic JSON output. The prompt is small and
+ * cache-friendly. The classifier fails CLOSED — when the LLM call
+ * throws, the caller decides whether to abort the ingest or fall
+ * through; this module never silently returns null on a transport
+ * error. (See `classifyTemporalState` for the exact contract.)
+ */
+/** Output of the classifier when the memory describes a stateful fact. */
+export interface TemporalStateClassification {
+    /** Stable identifier for the evolving fact (e.g. `user:1:location`). */
+    stateKey: string;
+    /** When the fact became true (ISO string at the in-LLM API surface). */
+    eventStart: Date;
+    /**
+     * When the fact stopped being true. Always `null` at classification
+     * time — supersede logic lives in `memory-storage.ts`. Kept on the
+     * type for callers that destructure the row shape directly.
+     */
+    eventEnd: null;
+}
+/** Input bag for `classifyTemporalState`. */
+export interface TemporalClassifyInput {
+    /** Extracted memory text (`FactInput.fact`). */
+    memoryText: string;
+    /**
+     * Resolved observed_at for the conversation turn (logical timestamp).
+     * Used as the default eventStart when the model does not surface one.
+     */
+    observedAt: Date;
+    /**
+     * Stable per-user namespace used to scope the state_key. The classifier
+     * prepends `user:<userId>:` to the model-emitted key so two users with
+     * the same key string ("location") don't collide.
+     */
+    userId: string;
+    /** Anthropic model ID. Pinned by the caller (typically the reflect model). */
+    model: string;
+}
+/**
+ * Classify a single memory. Returns `null` for non-stateful memories or
+ * when the classifier rejects the model output (empty/invalid key).
+ *
+ * Throws on transport / API failures so the caller can fail closed.
+ */
+export declare function classifyTemporalState(input: TemporalClassifyInput): Promise<TemporalStateClassification | null>;
+/** Scope an LLM-emitted slug into the per-user namespace. */
+export declare function scopedKey(userId: string, slug: string): string;

package/dist/services/temporal-classifier.js

@@ -0,0 +1,94 @@
+/**
+ * BEAM v38: write-time temporal classifier.
+ *
+ * Given a freshly-extracted memory text plus its observed timestamp, the
+ * classifier returns either:
+ *   - { stateKey, eventStart, eventEnd: null }  for stateful facts
+ *     (e.g. "user lives in Austin", "API response time is 200ms")
+ *   - null for non-stateful memories (events, one-time mentions)
+ *
+ * The classifier is a thin LLM wrapper that uses Anthropic forced
+ * tool-use for a deterministic JSON output. The prompt is small and
+ * cache-friendly. The classifier fails CLOSED — when the LLM call
+ * throws, the caller decides whether to abort the ingest or fall
+ * through; this module never silently returns null on a transport
+ * error. (See `classifyTemporalState` for the exact contract.)
+ */
+import { callAnthropicTool } from './llm.js';
+const SYSTEM_PROMPT = `You are a temporal-state classifier. Given one extracted memory and the date it was observed, decide whether the memory describes a STATEFUL fact (an evolving value of some attribute for some subject) or a NON_STATEFUL event/mention/summary.
+
+STATEFUL examples:
+  "User lives in Austin, TX" → { kind: stateful, state_key: "location" }
+  "Alice's job title is Staff Engineer" → { kind: stateful, state_key: "job.title" }
+  "Dashboard API response time is 200ms" → { kind: stateful, state_key: "api.dashboard.response_time" }
+  "User's current diet is vegetarian" → { kind: stateful, state_key: "diet" }
+  "Project lead is Bob" → { kind: stateful, state_key: "project.lead" }
+
+NON_STATEFUL examples:
+  "User flew to Tokyo last week" → { kind: non_stateful }  (one-time event)
+  "Asked about pricing on March 3rd" → { kind: non_stateful }
+  "Discussed AUDN architecture in the standup" → { kind: non_stateful }
+  "Mentioned that Q3 was tough" → { kind: non_stateful }
+
+Rules:
+- state_key must be a slug: lowercase ascii letters, digits, underscores, and dots only.
+- state_key names the ATTRIBUTE, not the value. "lives in Austin" → "location", not "austin".
+- event_start_iso, when surfaced, must be ISO-8601 with timezone. Leave empty when unsure.
+- Be conservative: prefer non_stateful when the memory could be either.`;
+const TOOL_SCHEMA = {
+    name: 'emit_temporal_state',
+    description: 'Emit the classifier output as structured JSON.',
+    input_schema: {
+        type: 'object',
+        properties: {
+            kind: { type: 'string', enum: ['stateful', 'non_stateful'] },
+            state_key: { type: 'string' },
+            event_start_iso: { type: 'string' },
+            rationale: { type: 'string' },
+        },
+        required: ['kind', 'state_key', 'event_start_iso', 'rationale'],
+    },
+};
+// Slug: lowercase ascii + digits + underscore, joined by dots.
+const SLUG_PATTERN = /^[a-z0-9_]+(?:\.[a-z0-9_]+)*$/;
+/**
+ * Classify a single memory. Returns `null` for non-stateful memories or
+ * when the classifier rejects the model output (empty/invalid key).
+ *
+ * Throws on transport / API failures so the caller can fail closed.
+ */
+export async function classifyTemporalState(input) {
+    const userMessage = buildUserMessage(input);
+    const output = await callAnthropicTool(input.model, SYSTEM_PROMPT, userMessage, TOOL_SCHEMA);
+    return interpretToolOutput(output, input);
+}
+function buildUserMessage(input) {
+    const isoObserved = input.observedAt.toISOString();
+    return `Observed at: ${isoObserved}\nMemory: ${input.memoryText}\n\nReturn STATEFUL only when this memory describes a value that can later change. Otherwise NON_STATEFUL.`;
+}
+function interpretToolOutput(output, input) {
+    if (output.kind !== 'stateful')
+        return null;
+    const rawKey = (output.state_key ?? '').trim().toLowerCase();
+    if (!rawKey || !SLUG_PATTERN.test(rawKey))
+        return null;
+    const eventStart = parseIso(output.event_start_iso) ?? input.observedAt;
+    return {
+        stateKey: scopedKey(input.userId, rawKey),
+        eventStart,
+        eventEnd: null,
+    };
+}
+function parseIso(value) {
+    if (!value)
+        return null;
+    const trimmed = value.trim();
+    if (!trimmed)
+        return null;
+    const date = new Date(trimmed);
+    return Number.isNaN(date.getTime()) ? null : date;
+}
+/** Scope an LLM-emitted slug into the per-user namespace. */
+export function scopedKey(userId, slug) {
+    return `user:${userId}:${slug}`;
+}

package/dist/services/temporal-endpoint-evidence.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Query-aware temporal evidence formatting.
+ *
+ * Produces compact date-bearing evidence blocks for temporal questions. For
+ * repeated-event comparisons it emits explicit first/second endpoints; for
+ * broader temporal questions it emits a small set of high-overlap candidate
+ * memories with their dates.
+ */
+import type { SearchResult } from '../db/memory-repository.js';
+export declare function buildTemporalEvidenceBlock(memories: SearchResult[], query: string): string;
+/** Build endpoint lines for repeated-event temporal comparisons. */
+export declare function buildRepeatedEventEndpointBlock(memories: SearchResult[], query: string): string;