@atomicmemory/core 1.0.0

package/dist/services/memory-lifecycle.js

@@ -0,0 +1,108 @@
+/**
+ * Memory lifecycle management: decay cycle and memory count cap.
+ *
+ * Decay cycle: Computes a retention score for each memory using the same
+ * three-signal formula as retrieval scoring (similarity excluded since there's
+ * no query). Memories below the retention threshold are archived (soft-deleted).
+ * This implements the Ebbinghaus forgetting curve for long-term store health.
+ *
+ * Memory count cap: Checks whether a user's active memory count exceeds
+ * a configured limit and returns a recommendation for whether consolidation
+ * or decay should run.
+ *
+ * Both features are pure functions over memory data + config — they compute
+ * what should happen but let the caller decide when to act.
+ */
+/** 30-day time constant in milliseconds, matching the SQL decay formula. */
+const DECAY_TAU_MS = 2_592_000_000;
+export const DEFAULT_DECAY_CONFIG = {
+    retentionThreshold: 0.2,
+    importanceWeight: 0.4,
+    recencyWeight: 0.4,
+    accessWeight: 0.2,
+    minAgeMs: 7 * 24 * 60 * 60 * 1000, // 7 days
+};
+/**
+ * Compute the retention score for a single memory.
+ *
+ * Formula: importanceWeight * importance + recencyWeight * recency + accessWeight * accessFreq
+ * Where recency = exp(-timeSinceAccess / TAU) and accessFreq = min(1, accessCount / 10).
+ */
+export function computeRetentionScore(memory, referenceTime, decayConfig) {
+    const elapsedMs = referenceTime.getTime() - memory.last_accessed_at.getTime();
+    const recency = Math.exp(-elapsedMs / DECAY_TAU_MS);
+    const accessFreq = Math.min(1.0, memory.access_count / 10);
+    const rawScore = (decayConfig.importanceWeight * memory.importance)
+        + (decayConfig.recencyWeight * recency)
+        + (decayConfig.accessWeight * accessFreq);
+    return rawScore * (memory.trust_score ?? 1.0);
+}
+/**
+ * Evaluate a batch of memories and identify those below the retention threshold.
+ * Does not modify any data — returns candidates for the caller to archive.
+ */
+export function evaluateDecayCandidates(memories, referenceTime, decayConfig = DEFAULT_DECAY_CONFIG) {
+    const eligible = memories.filter((m) => {
+        const ageMs = referenceTime.getTime() - m.created_at.getTime();
+        return ageMs >= decayConfig.minAgeMs;
+    });
+    const scored = eligible.map((m) => {
+        const retentionScore = computeRetentionScore(m, referenceTime, decayConfig);
+        const elapsedMs = referenceTime.getTime() - m.last_accessed_at.getTime();
+        return {
+            id: m.id,
+            content: m.content,
+            retentionScore,
+            importance: m.importance,
+            daysSinceAccess: elapsedMs / (24 * 60 * 60 * 1000),
+            accessCount: m.access_count,
+        };
+    });
+    const candidates = scored
+        .filter((s) => s.retentionScore < decayConfig.retentionThreshold)
+        .sort((a, b) => a.retentionScore - b.retentionScore);
+    const totalScore = scored.reduce((sum, s) => sum + s.retentionScore, 0);
+    const avgRetentionScore = scored.length > 0 ? totalScore / scored.length : 0;
+    return {
+        memoriesEvaluated: eligible.length,
+        candidatesForArchival: candidates,
+        retentionThreshold: decayConfig.retentionThreshold,
+        avgRetentionScore,
+    };
+}
+const DEFAULT_CAP_CONFIG = {
+    maxMemories: 5000,
+    warnRatio: 0.8,
+};
+/**
+ * Check whether a user's memory count is within the configured cap.
+ * Returns a status and recommendation for what lifecycle action to take.
+ */
+export function checkMemoryCap(activeMemories, capConfig = DEFAULT_CAP_CONFIG) {
+    const usageRatio = activeMemories / capConfig.maxMemories;
+    const status = resolveCapStatus(usageRatio, capConfig.warnRatio);
+    const recommendation = resolveRecommendation(status, usageRatio);
+    return {
+        activeMemories,
+        maxMemories: capConfig.maxMemories,
+        status,
+        usageRatio,
+        recommendation,
+    };
+}
+function resolveCapStatus(usageRatio, warnRatio) {
+    if (usageRatio >= 1.0)
+        return 'exceeded';
+    if (usageRatio >= warnRatio)
+        return 'warn';
+    return 'ok';
+}
+function resolveRecommendation(status, usageRatio) {
+    if (status === 'ok')
+        return 'none';
+    if (status === 'warn')
+        return 'consolidate';
+    if (usageRatio >= 1.2)
+        return 'consolidate-and-decay';
+    return 'decay';
+}

package/dist/services/memory-lineage.d.ts

@@ -0,0 +1,181 @@
+/**
+ * Internal claim-lineage emission seam for the existing lineage-producing write
+ * paths only.
+ *
+ * This module centralizes the current claim/version/evidence/canonical-object
+ * write sequences without changing their semantics. It deliberately models the
+ * current consolidation anomaly as its own variant: consolidation creates a
+ * claim/version pair but does not emit a mutation canonical memory object.
+ *
+ * Out of scope:
+ * - schema changes
+ * - new mutation types
+ * - workspace/scope behavior changes
+ * - routing lineage-bypassing paths through claim versions
+ */
+import type { ClaimSlotInput } from '../db/claim-repository.js';
+import type { IngestRuntimeConfig } from './memory-service-types.js';
+import type { ClaimTarget, FactInput } from './memory-service-types.js';
+type MutationType = 'add' | 'update' | 'supersede' | 'delete';
+type MutationProvenanceType = MutationType | 'clarify';
+type MutationCanonicalObjectRepo = {
+    storeCanonicalMemoryObject(input: {
+        userId: string;
+        objectFamily: 'ingested_fact';
+        canonicalPayload: ReturnType<typeof buildCanonicalPayload>;
+        provenance: {
+            episodeId: string;
+            sourceSite: string;
+            sourceUrl: string;
+        };
+        observedAt: Date | undefined;
+        lineage: {
+            mutationType: MutationType;
+            previousObjectId: string | null;
+            claimId?: string;
+            claimVersionId?: string;
+            previousVersionId?: string;
+            mutationReason?: string;
+            contradictionConfidence?: number | null;
+            actorModel?: string | null;
+        };
+    }): Promise<string>;
+};
+type LineageClaimsPort = {
+    createClaim(userId: string, claimType: string, validAt?: Date, claimSlot?: ClaimSlotInput | null): Promise<string>;
+    createClaimVersion(input: {
+        claimId: string;
+        userId: string;
+        memoryId?: string;
+        content: string;
+        embedding: number[];
+        importance: number;
+        sourceSite: string;
+        sourceUrl?: string;
+        episodeId?: string;
+        validFrom?: Date;
+        provenance?: {
+            mutationType?: MutationProvenanceType;
+            mutationReason?: string;
+            previousVersionId?: string;
+            actorModel?: string;
+            contradictionConfidence?: number;
+        };
+    }): Promise<string>;
+    setClaimCurrentVersion(claimId: string, versionId: string | null, status?: string, validAt?: Date): Promise<void>;
+    addEvidence(input: {
+        claimVersionId: string;
+        episodeId?: string;
+        memoryId?: string;
+        quoteText?: string;
+        speaker?: string;
+    }): Promise<void>;
+    createUpdateVersion(input: {
+        oldVersionId: string;
+        claimId: string;
+        userId: string;
+        memoryId: string;
+        content: string;
+        embedding: number[];
+        importance: number;
+        sourceSite: string;
+        sourceUrl?: string;
+        episodeId?: string;
+        validFrom?: Date;
+        mutationReason?: string;
+        actorModel?: string;
+    }): Promise<string>;
+    supersedeClaimVersion(userId: string, versionId: string, supersededByVersionId: string | null, validTo?: Date): Promise<void>;
+    invalidateClaim(userId: string, claimId: string, invalidAt?: Date, invalidatedByVersionId?: string | null, status?: string): Promise<void>;
+};
+type LineageDeps = {
+    claims: LineageClaimsPort;
+    repo?: MutationCanonicalObjectRepo;
+    config: Pick<IngestRuntimeConfig, 'llmModel'>;
+};
+type BackfillMemory = {
+    id: string;
+    content: string;
+    embedding: number[];
+    importance: number;
+    sourceSite: string;
+    sourceUrl: string;
+    episodeId?: string;
+    createdAt: Date;
+    memoryType: string;
+    cmoId: string | null;
+};
+type LineageEvent = {
+    kind: 'canonical-add';
+    userId: string;
+    fact: FactInput;
+    embedding: number[];
+    sourceSite: string;
+    sourceUrl: string;
+    episodeId: string;
+    logicalTimestamp: Date | undefined;
+    claimSlot: ClaimSlotInput | null;
+    createProjection: (cmoId: string) => Promise<string | null>;
+} | {
+    kind: 'claim-backfill';
+    userId: string;
+    memory: BackfillMemory;
+} | {
+    kind: 'consolidation-add';
+    userId: string;
+    memoryId: string;
+    content: string;
+    embedding: number[];
+    importance: number;
+    sourceSite: string;
+    mutationReason: string;
+} | {
+    kind: 'canonical-update';
+    userId: string;
+    fact: FactInput;
+    updatedContent: string;
+    updatedEmbedding: number[];
+    sourceSite: string;
+    sourceUrl: string;
+    episodeId: string;
+    logicalTimestamp: Date | undefined;
+    target: ClaimTarget;
+    contradictionConfidence?: number | null;
+} | {
+    kind: 'canonical-supersede';
+    userId: string;
+    fact: FactInput;
+    embedding: number[];
+    sourceSite: string;
+    sourceUrl: string;
+    episodeId: string;
+    logicalTimestamp: Date | undefined;
+    target: ClaimTarget;
+    newMemoryId: string;
+    contradictionConfidence?: number | null;
+} | {
+    kind: 'canonical-delete';
+    userId: string;
+    fact: FactInput;
+    sourceSite: string;
+    sourceUrl: string;
+    episodeId: string;
+    logicalTimestamp: Date | undefined;
+    target: ClaimTarget;
+    targetEmbedding: number[];
+    contradictionConfidence?: number | null;
+};
+export type LineageEmission = {
+    claimId: string;
+    versionId: string;
+    memoryId: string | null;
+    cmoId: string | null;
+};
+export declare function emitLineageEvent(deps: LineageDeps, event: LineageEvent): Promise<LineageEmission | null>;
+declare function buildCanonicalPayload(fact: FactInput): {
+    factText: string;
+    factType: "preference" | "project" | "knowledge" | "person" | "plan";
+    headline: string;
+    keywords: string[];
+};
+export {};

package/dist/services/memory-lineage.js

@@ -0,0 +1,232 @@
+/**
+ * Internal claim-lineage emission seam for the existing lineage-producing write
+ * paths only.
+ *
+ * This module centralizes the current claim/version/evidence/canonical-object
+ * write sequences without changing their semantics. It deliberately models the
+ * current consolidation anomaly as its own variant: consolidation creates a
+ * claim/version pair but does not emit a mutation canonical memory object.
+ *
+ * Out of scope:
+ * - schema changes
+ * - new mutation types
+ * - workspace/scope behavior changes
+ * - routing lineage-bypassing paths through claim versions
+ */
+export async function emitLineageEvent(deps, event) {
+    switch (event.kind) {
+        case 'canonical-add':
+            return emitCanonicalAdd(deps, event);
+        case 'claim-backfill':
+            return emitBackfill(deps, event);
+        case 'consolidation-add':
+            return emitConsolidationAdd(deps, event);
+        case 'canonical-update':
+            return emitCanonicalUpdate(deps, event);
+        case 'canonical-supersede':
+            return emitCanonicalSupersede(deps, event);
+        case 'canonical-delete':
+            return emitCanonicalDelete(deps, event);
+    }
+}
+function buildCanonicalPayload(fact) {
+    return {
+        factText: fact.fact,
+        factType: fact.type,
+        headline: fact.headline,
+        keywords: fact.keywords,
+    };
+}
+async function emitCanonicalAdd(deps, event) {
+    const cmoId = await requireRepo(deps).storeCanonicalMemoryObject({
+        userId: event.userId,
+        objectFamily: 'ingested_fact',
+        canonicalPayload: buildCanonicalPayload(event.fact),
+        provenance: { episodeId: event.episodeId, sourceSite: event.sourceSite, sourceUrl: event.sourceUrl },
+        observedAt: event.logicalTimestamp,
+        lineage: { mutationType: 'add', previousObjectId: null },
+    });
+    const memoryId = await event.createProjection(cmoId);
+    if (!memoryId)
+        return null;
+    const claimId = await deps.claims.createClaim(event.userId, event.fact.type, event.logicalTimestamp, event.claimSlot);
+    const versionId = await deps.claims.createClaimVersion({
+        claimId,
+        userId: event.userId,
+        memoryId,
+        content: event.fact.fact,
+        embedding: event.embedding,
+        importance: event.fact.importance,
+        sourceSite: event.sourceSite,
+        sourceUrl: event.sourceUrl,
+        episodeId: event.episodeId,
+        validFrom: event.logicalTimestamp,
+        provenance: { mutationType: 'add', actorModel: lineageActorModel(deps) },
+    });
+    await deps.claims.setClaimCurrentVersion(claimId, versionId, 'active', event.logicalTimestamp);
+    await deps.claims.addEvidence({ claimVersionId: versionId, episodeId: event.episodeId, memoryId, quoteText: event.fact.fact });
+    return { claimId, versionId, memoryId, cmoId };
+}
+async function emitBackfill(deps, event) {
+    const claimId = await deps.claims.createClaim(event.userId, event.memory.memoryType, event.memory.createdAt);
+    const versionId = await deps.claims.createClaimVersion({
+        claimId,
+        userId: event.userId,
+        memoryId: event.memory.id,
+        content: event.memory.content,
+        embedding: event.memory.embedding,
+        importance: event.memory.importance,
+        sourceSite: event.memory.sourceSite,
+        sourceUrl: event.memory.sourceUrl,
+        episodeId: event.memory.episodeId,
+        validFrom: event.memory.createdAt,
+    });
+    await deps.claims.setClaimCurrentVersion(claimId, versionId, 'active', event.memory.createdAt);
+    await deps.claims.addEvidence({
+        claimVersionId: versionId,
+        episodeId: event.memory.episodeId,
+        memoryId: event.memory.id,
+        quoteText: event.memory.content,
+    });
+    return { claimId, versionId, memoryId: event.memory.id, cmoId: event.memory.cmoId };
+}
+async function emitConsolidationAdd(deps, event) {
+    const claimId = await deps.claims.createClaim(event.userId, 'consolidated');
+    const versionId = await deps.claims.createClaimVersion({
+        claimId,
+        userId: event.userId,
+        memoryId: event.memoryId,
+        content: event.content,
+        embedding: event.embedding,
+        importance: event.importance,
+        sourceSite: event.sourceSite,
+        provenance: {
+            mutationType: 'add',
+            mutationReason: event.mutationReason,
+            actorModel: lineageActorModel(deps),
+        },
+    });
+    await deps.claims.setClaimCurrentVersion(claimId, versionId);
+    return { claimId, versionId, memoryId: event.memoryId, cmoId: null };
+}
+async function emitCanonicalUpdate(deps, event) {
+    const mutationReason = `Updated from: "${event.fact.fact.slice(0, 100)}"`;
+    const versionId = await deps.claims.createUpdateVersion({
+        oldVersionId: event.target.versionId,
+        claimId: event.target.claimId,
+        userId: event.userId,
+        memoryId: event.target.memoryId,
+        content: event.updatedContent,
+        embedding: event.updatedEmbedding,
+        importance: event.fact.importance,
+        sourceSite: event.sourceSite,
+        sourceUrl: event.sourceUrl,
+        episodeId: event.episodeId,
+        validFrom: event.logicalTimestamp,
+        mutationReason,
+        actorModel: lineageActorModel(deps),
+    });
+    await deps.claims.addEvidence({
+        claimVersionId: versionId,
+        episodeId: event.episodeId,
+        memoryId: event.target.memoryId,
+        quoteText: event.fact.fact,
+    });
+    const cmoId = await createMutationCanonicalObject(deps, event, versionId, mutationReason, {
+        ...event.fact,
+        fact: event.updatedContent,
+    });
+    return { claimId: event.target.claimId, versionId, memoryId: event.target.memoryId, cmoId };
+}
+async function emitCanonicalSupersede(deps, event) {
+    const mutationReason = `Superseded memory "${event.target.memoryId}" with new fact`;
+    const versionId = await deps.claims.createClaimVersion({
+        claimId: event.target.claimId,
+        userId: event.userId,
+        memoryId: event.newMemoryId,
+        content: event.fact.fact,
+        embedding: event.embedding,
+        importance: event.fact.importance,
+        sourceSite: event.sourceSite,
+        sourceUrl: event.sourceUrl,
+        episodeId: event.episodeId,
+        validFrom: event.logicalTimestamp,
+        provenance: {
+            mutationType: 'supersede',
+            mutationReason,
+            previousVersionId: event.target.versionId,
+            actorModel: lineageActorModel(deps),
+            contradictionConfidence: event.contradictionConfidence ?? undefined,
+        },
+    });
+    await deps.claims.supersedeClaimVersion(event.userId, event.target.versionId, versionId, event.logicalTimestamp ?? new Date());
+    await deps.claims.setClaimCurrentVersion(event.target.claimId, versionId, 'active', event.logicalTimestamp);
+    await deps.claims.addEvidence({
+        claimVersionId: versionId,
+        episodeId: event.episodeId,
+        memoryId: event.newMemoryId,
+        quoteText: event.fact.fact,
+    });
+    const cmoId = await createMutationCanonicalObject(deps, event, versionId, mutationReason, event.fact);
+    return { claimId: event.target.claimId, versionId, memoryId: event.newMemoryId, cmoId };
+}
+async function emitCanonicalDelete(deps, event) {
+    const mutationReason = `Deleted memory "${event.target.memoryId}" — fact: "${event.fact.fact.slice(0, 100)}"`;
+    const versionId = await deps.claims.createClaimVersion({
+        claimId: event.target.claimId,
+        userId: event.userId,
+        content: `[DELETED] ${event.fact.fact}`,
+        embedding: event.targetEmbedding,
+        importance: 0,
+        sourceSite: '',
+        sourceUrl: '',
+        episodeId: event.episodeId,
+        validFrom: event.logicalTimestamp,
+        provenance: {
+            mutationType: 'delete',
+            mutationReason,
+            previousVersionId: event.target.versionId,
+            actorModel: lineageActorModel(deps),
+            contradictionConfidence: event.contradictionConfidence ?? undefined,
+        },
+    });
+    await deps.claims.supersedeClaimVersion(event.userId, event.target.versionId, versionId, event.logicalTimestamp ?? new Date());
+    await deps.claims.invalidateClaim(event.userId, event.target.claimId, event.logicalTimestamp ?? new Date(), versionId);
+    const cmoId = await createMutationCanonicalObject(deps, event, versionId, mutationReason, event.fact);
+    return { claimId: event.target.claimId, versionId, memoryId: null, cmoId };
+}
+async function createMutationCanonicalObject(deps, event, claimVersionId, mutationReason, fact) {
+    return requireRepo(deps).storeCanonicalMemoryObject({
+        userId: event.userId,
+        objectFamily: 'ingested_fact',
+        canonicalPayload: buildCanonicalPayload(fact),
+        provenance: { episodeId: event.episodeId, sourceSite: event.sourceSite, sourceUrl: event.sourceUrl },
+        observedAt: event.logicalTimestamp,
+        lineage: {
+            mutationType: mutationTypeFor(event.kind),
+            previousObjectId: event.target.cmoId,
+            claimId: event.target.claimId,
+            claimVersionId,
+            previousVersionId: event.target.versionId,
+            mutationReason,
+            contradictionConfidence: event.contradictionConfidence ?? undefined,
+            actorModel: lineageActorModel(deps),
+        },
+    });
+}
+function mutationTypeFor(kind) {
+    if (kind === 'canonical-update')
+        return 'update';
+    if (kind === 'canonical-supersede')
+        return 'supersede';
+    return 'delete';
+}
+function requireRepo(deps) {
+    if (!deps.repo) {
+        throw new Error('Lineage event requires canonical object repository access');
+    }
+    return deps.repo;
+}
+function lineageActorModel(deps) {
+    return deps.config.llmModel;
+}

package/dist/services/memory-network.d.ts

@@ -0,0 +1,40 @@
+/**
+ * 4-Network memory separation (Hindsight-inspired).
+ *
+ * Classifies extracted facts into one of four memory networks:
+ * - world:       objective third-person facts about the external environment
+ * - experience:  first-person biographical records of user actions/interactions
+ * - opinion:     subjective beliefs with incrementally-updated confidence [0,1]
+ * - observation: synthesized entity profiles (generated async, never from extraction)
+ *
+ * Also implements opinion confidence evolution:
+ *   reinforce (+α), weaken (-α), contradict (-2α), clamped to [0,1].
+ */
+import type { ExtractedFact } from './extraction.js';
+export type MemoryNetwork = 'world' | 'experience' | 'opinion' | 'observation';
+export interface NetworkClassification {
+    network: MemoryNetwork;
+    opinionConfidence: number | null;
+}
+export type OpinionSignal = 'reinforce' | 'weaken' | 'contradict';
+/**
+ * Classify an extracted fact into the appropriate memory network.
+ * Observation is never produced by extraction — only by ObservationService.
+ */
+export declare function classifyNetwork(fact: ExtractedFact): NetworkClassification;
+/**
+ * Apply a confidence update signal to an opinion memory.
+ * Returns the new confidence, clamped to [0, 1].
+ *
+ * - reinforce:  evidence supports the opinion      → +α
+ * - weaken:     mild contradicting evidence         → -α
+ * - contradict: strong contradicting evidence       → -2α
+ */
+export declare function applyOpinionSignal(currentConfidence: number, signal: OpinionSignal): number;
+/**
+ * Map an AUDN action to the appropriate opinion signal.
+ * - NOOP → reinforce (same opinion seen again)
+ * - UPDATE → weaken (opinion modified, not replaced)
+ * - SUPERSEDE/DELETE → contradict (opinion replaced or removed)
+ */
+export declare function audnActionToOpinionSignal(action: string): OpinionSignal;

package/dist/services/memory-network.js

@@ -0,0 +1,75 @@
+/**
+ * 4-Network memory separation (Hindsight-inspired).
+ *
+ * Classifies extracted facts into one of four memory networks:
+ * - world:       objective third-person facts about the external environment
+ * - experience:  first-person biographical records of user actions/interactions
+ * - opinion:     subjective beliefs with incrementally-updated confidence [0,1]
+ * - observation: synthesized entity profiles (generated async, never from extraction)
+ *
+ * Also implements opinion confidence evolution:
+ *   reinforce (+α), weaken (-α), contradict (-2α), clamped to [0,1].
+ */
+/** Step size for opinion confidence updates. */
+const OPINION_ALPHA = 0.1;
+/** Default confidence assigned to newly-extracted opinions. */
+const OPINION_INITIAL_CONFIDENCE = 0.7;
+/** Signals indicating the user is expressing a subjective belief. */
+const OPINION_SIGNALS = [
+    'i think', 'i believe', 'i feel', 'i prefer', 'in my opinion',
+    'i find', 'i like', 'i dislike', 'i hate', 'i love',
+    'seems to me', 'i\'d rather', 'my favorite', 'i enjoy',
+    'overrated', 'underrated', 'better than', 'worse than',
+];
+/** Signals indicating an objective world fact (third-person, verifiable). */
+const WORLD_SIGNALS = [
+    'was released', 'is owned by', 'was founded', 'is headquartered',
+    'is the ceo', 'was acquired', 'is a product of', 'is developed by',
+    'version ', 'announced', 'launched', 'published', 'is written in',
+    'supports', 'is compatible with', 'requires', 'is licensed under',
+    'was invented', 'is maintained by', 'merged with',
+];
+/**
+ * Classify an extracted fact into the appropriate memory network.
+ * Observation is never produced by extraction — only by ObservationService.
+ */
+export function classifyNetwork(fact) {
+    const lower = fact.fact.toLowerCase();
+    // Preferences with subjective language → opinion network
+    if (fact.type === 'preference' || OPINION_SIGNALS.some((s) => lower.includes(s))) {
+        return { network: 'opinion', opinionConfidence: OPINION_INITIAL_CONFIDENCE };
+    }
+    // Knowledge facts with world signals → world network
+    if (fact.type === 'knowledge' && WORLD_SIGNALS.some((s) => lower.includes(s))) {
+        return { network: 'world', opinionConfidence: null };
+    }
+    // Everything else: experience (first-person biographical)
+    return { network: 'experience', opinionConfidence: null };
+}
+/**
+ * Apply a confidence update signal to an opinion memory.
+ * Returns the new confidence, clamped to [0, 1].
+ *
+ * - reinforce:  evidence supports the opinion      → +α
+ * - weaken:     mild contradicting evidence         → -α
+ * - contradict: strong contradicting evidence       → -2α
+ */
+export function applyOpinionSignal(currentConfidence, signal) {
+    const delta = signal === 'reinforce' ? OPINION_ALPHA
+        : signal === 'weaken' ? -OPINION_ALPHA
+            : -2 * OPINION_ALPHA;
+    return Math.max(0.0, Math.min(1.0, currentConfidence + delta));
+}
+/**
+ * Map an AUDN action to the appropriate opinion signal.
+ * - NOOP → reinforce (same opinion seen again)
+ * - UPDATE → weaken (opinion modified, not replaced)
+ * - SUPERSEDE/DELETE → contradict (opinion replaced or removed)
+ */
+export function audnActionToOpinionSignal(action) {
+    if (action === 'NOOP')
+        return 'reinforce';
+    if (action === 'UPDATE')
+        return 'weaken';
+    return 'contradict';
+}

package/dist/services/memory-search-types.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Shared internal types for the memory-search pipeline.
+ *
+ * These shapes are private to the search internals — kept out of
+ * `memory-service-types.ts` (which is the cross-module public surface)
+ * but split out from `memory-search.ts` so the TLL-augmentation sibling
+ * module (`tll-augmentation.ts`) can consume them without duplicating
+ * definitions or introducing a circular import.
+ */
+import type { SearchResult } from '../db/memory-repository.js';
+import type { ConsensusResult } from './consensus-validation.js';
+import type { RelevanceFilterDecision } from './relevance-policy.js';
+export interface RelevanceFilterSummary {
+    threshold: number | null;
+    source: string;
+    reason: string;
+    queryLabel: string;
+    removedIds: string[];
+    decisions: RelevanceFilterDecision[];
+}
+export interface PostProcessedSearch {
+    memories: SearchResult[];
+    consensusResult?: ConsensusResult;
+    relevanceFilter: RelevanceFilterSummary;
+}

package/dist/services/memory-search-types.js

@@ -0,0 +1,10 @@
+/**
+ * Shared internal types for the memory-search pipeline.
+ *
+ * These shapes are private to the search internals — kept out of
+ * `memory-service-types.ts` (which is the cross-module public surface)
+ * but split out from `memory-search.ts` so the TLL-augmentation sibling
+ * module (`tll-augmentation.ts`) can consume them without duplicating
+ * definitions or introducing a circular import.
+ */
+export {};