engram-sdk 0.1.0 → 0.1.2

package/dist/temporal.js

@@ -0,0 +1,205 @@
+/**
+ * temporal.ts — Temporal Intelligence for Engram
+ *
+ * Handles fact supersession detection and recency-aware scoring.
+ * This module addresses the core weakness exposed by Letta's
+ * core-memory-update benchmark: when facts change over time,
+ * Engram needs to know which version is current.
+ *
+ * Three strategies (implement in order):
+ *
+ *   1. Contradiction detection at write time
+ *      When a new memory is stored, check if it contradicts an
+ *      existing memory about the same entity+topic. If so, mark
+ *      the old one as `superseded` and link them with an edge.
+ *
+ *   2. Recency boost in recall scoring
+ *      Add a time-decay multiplier so newer memories score higher
+ *      when content similarity is close. Small effect, but helps
+ *      break ties in favor of recent information.
+ *
+ *   3. Temporal spreading activation
+ *      Weight graph edges by recency — when an entity activates
+ *      connected memories, more recent connections fire stronger.
+ *
+ * Target: improve Letta core-memory-update from 41.9% → 65%+
+ *
+ * @module temporal
+ */
+export const DEFAULT_TEMPORAL_CONFIG = {
+    detectContradictions: true,
+    recencyBoost: {
+        enabled: true,
+        maxBoost: 0.15,
+        halfLifeDays: 7,
+    },
+    minEntityOverlap: 1,
+    contradictionSimilarityThreshold: 0.75,
+};
+// ── Strategy 1: Contradiction Detection ────────────────────
+/**
+ * Check if two memories contradict each other.
+ *
+ * Heuristic approach (no LLM call):
+ *   - Must share at least one entity
+ *   - Must share at least one topic OR have high semantic similarity
+ *   - Content must differ meaningfully (not just rephrasing)
+ *
+ * For higher accuracy, pass to LLM for verification.
+ */
+export function findContradictionCandidates(newMemory, existingMemories, config = DEFAULT_TEMPORAL_CONFIG) {
+    const newEntities = new Set(newMemory.entities?.map(e => e.toLowerCase()) ?? []);
+    const newTopics = new Set(newMemory.topics?.map(t => t.toLowerCase()) ?? []);
+    if (newEntities.size === 0)
+        return []; // Can't detect contradictions without entities
+    return existingMemories.filter(existing => {
+        if (existing.id === newMemory.id)
+            return false;
+        if (existing.status !== 'active')
+            return false;
+        // Must share entities
+        const existingEntities = new Set(existing.entities?.map(e => e.toLowerCase()) ?? []);
+        const sharedEntities = [...newEntities].filter(e => existingEntities.has(e));
+        if (sharedEntities.length < config.minEntityOverlap)
+            return false;
+        // Must share topics or be about the same subject
+        const existingTopics = new Set(existing.topics?.map(t => t.toLowerCase()) ?? []);
+        const sharedTopics = [...newTopics].filter(t => existingTopics.has(t));
+        const hasTopicOverlap = sharedTopics.length > 0;
+        // If no topic overlap, require higher entity overlap
+        if (!hasTopicOverlap && sharedEntities.length < 2)
+            return false;
+        // Content must actually differ (not just a duplicate)
+        if (existing.content === newMemory.content)
+            return false;
+        return true;
+    });
+}
+/**
+ * Use LLM to verify if two memories genuinely contradict each other.
+ *
+ * Returns null if no contradiction, or a ContradictionResult if confirmed.
+ *
+ * TODO: Implement with Gemini call
+ */
+export async function verifyContradiction(newMemory, oldMemory, llmCall) {
+    const prompt = `You are a fact-checking system. Determine if these two statements contradict each other (i.e., the newer one updates or corrects information in the older one).
+
+OLDER STATEMENT (written ${oldMemory.createdAt}):
+${oldMemory.content}
+
+NEWER STATEMENT (written ${newMemory.createdAt}):
+${newMemory.content}
+
+Shared entities: ${[...new Set([...(oldMemory.entities ?? []), ...(newMemory.entities ?? [])])].join(', ')}
+
+Respond in JSON:
+{
+  "contradicts": true/false,
+  "confidence": 0.0-1.0,
+  "explanation": "brief explanation of what changed, or why they don't contradict"
+}
+
+Only mark as contradicting if the newer statement genuinely updates, corrects, or replaces information in the older one. Additions or elaborations are NOT contradictions.`;
+    try {
+        const response = await llmCall(prompt);
+        const cleaned = response.replace(/```json\n?|\n?```/g, '').trim();
+        const result = JSON.parse(cleaned);
+        if (!result.contradicts)
+            return null;
+        const newEntities = new Set(newMemory.entities?.map(e => e.toLowerCase()) ?? []);
+        const oldEntities = new Set(oldMemory.entities?.map(e => e.toLowerCase()) ?? []);
+        const sharedEntities = [...newEntities].filter(e => oldEntities.has(e));
+        const newTopics = new Set(newMemory.topics?.map(t => t.toLowerCase()) ?? []);
+        const oldTopics = new Set(oldMemory.topics?.map(t => t.toLowerCase()) ?? []);
+        const sharedTopics = [...newTopics].filter(t => oldTopics.has(t));
+        return {
+            newMemoryId: newMemory.id,
+            oldMemoryId: oldMemory.id,
+            sharedEntities,
+            sharedTopics,
+            confidence: result.confidence ?? 0.7,
+            explanation: result.explanation ?? 'Fact updated',
+        };
+    }
+    catch {
+        return null; // LLM parse failure — skip
+    }
+}
+// ── Strategy 2: Recency Boost ──────────────────────────────
+/**
+ * Calculate a recency boost for a memory based on its age.
+ *
+ * Uses exponential decay: boost = maxBoost * 2^(-age/halfLife)
+ *
+ * Examples (with defaults: maxBoost=0.15, halfLife=7 days):
+ *   - Created today:     +0.15
+ *   - Created 7 days ago: +0.075
+ *   - Created 14 days ago: +0.0375
+ *   - Created 30 days ago: +0.009 (negligible)
+ *
+ * This is additive to the recall score, not multiplicative.
+ * It's small enough to not override strong semantic matches,
+ * but large enough to break ties between competing facts.
+ */
+export function calculateRecencyBoost(memory, config = DEFAULT_TEMPORAL_CONFIG.recencyBoost, now = new Date()) {
+    if (!config.enabled)
+        return 0;
+    const createdAt = new Date(memory.createdAt);
+    const ageDays = (now.getTime() - createdAt.getTime()) / (1000 * 60 * 60 * 24);
+    if (ageDays < 0)
+        return config.maxBoost; // Future date? Give max boost
+    if (ageDays === 0)
+        return config.maxBoost;
+    // Exponential decay: halves every halfLifeDays
+    return config.maxBoost * Math.pow(2, -ageDays / config.halfLifeDays);
+}
+// ── Strategy 3: Temporal Spreading Activation ──────────────
+/**
+ * Weight a graph edge by recency of the connected memory.
+ *
+ * When spreading activation traverses the memory graph,
+ * edges to more recent memories carry more activation energy.
+ *
+ * This naturally surfaces the latest version of a fact when
+ * multiple memories about the same entity exist.
+ *
+ * TODO: Integrate with vault.ts spreading activation
+ */
+export function temporalEdgeWeight(baseWeight, targetMemory, halfLifeDays = 14, now = new Date()) {
+    const ageDays = (now.getTime() - new Date(targetMemory.createdAt).getTime()) / (1000 * 60 * 60 * 24);
+    const recencyFactor = Math.pow(2, -ageDays / halfLifeDays);
+    // Blend: 70% original weight + 30% recency
+    return baseWeight * (0.7 + 0.3 * recencyFactor);
+}
+// ── Integration Points ─────────────────────────────────────
+//
+// To wire this into vault.ts:
+//
+// 1. CONTRADICTION DETECTION (in remember() after dedup):
+//    ```
+//    if (config.temporal?.detectContradictions) {
+//      const candidates = findContradictionCandidates(memory, nearbyMemories);
+//      for (const candidate of candidates) {
+//        const result = await verifyContradiction(memory, candidate, llmCall);
+//        if (result && result.confidence >= 0.7) {
+//          this.store.updateStatus(candidate.id, 'superseded');
+//          this.store.createEdge(memory.id, candidate.id, 'supersedes', result.confidence);
+//        }
+//      }
+//    }
+//    ```
+//
+// 2. RECENCY BOOST (in recall() scoring, step 8):
+//    ```
+//    const recencyBoost = calculateRecencyBoost(r.memory, config.temporal?.recencyBoost);
+//    r.score += recencyBoost;
+//    ```
+//
+// 3. TEMPORAL SPREADING ACTIVATION (in spreadingActivation()):
+//    ```
+//    const weight = temporalEdgeWeight(edge.weight, targetMemory);
+//    ```
+//
+// Each can be enabled independently via TemporalConfig.
+//# sourceMappingURL=temporal.js.map

package/dist/temporal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"temporal.js","sourceRoot":"","sources":["../src/temporal.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -70,13 +70,13 @@ export declare const RememberInputSchema: z.ZodObject<{
         agentId: z.ZodOptional<z.ZodString>;
         evidence: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
     }, "strip", z.ZodTypeAny, {
-        type: "conversation" | "observation" | "inference" | "consolidation" | "external" | "manual";
+        type: "consolidation" | "conversation" | "observation" | "inference" | "external" | "manual";
         sessionId?: string | undefined;
         agentId?: string | undefined;
         evidence?: string[] | undefined;
     }, {
         sessionId?: string | undefined;
-        type?: "conversation" | "observation" | "inference" | "consolidation" | "external" | "manual" | undefined;
+        type?: "consolidation" | "conversation" | "observation" | "inference" | "external" | "manual" | undefined;
         agentId?: string | undefined;
         evidence?: string[] | undefined;
     }>>;
@@ -92,7 +92,7 @@ export declare const RememberInputSchema: z.ZodObject<{
     visibility: "private" | "owner_agents" | "shared" | "public";
     summary?: string | undefined;
     source?: {
-        type: "conversation" | "observation" | "inference" | "consolidation" | "external" | "manual";
+        type: "consolidation" | "conversation" | "observation" | "inference" | "external" | "manual";
         sessionId?: string | undefined;
         agentId?: string | undefined;
         evidence?: string[] | undefined;
@@ -110,7 +110,7 @@ export declare const RememberInputSchema: z.ZodObject<{
     visibility?: "private" | "owner_agents" | "shared" | "public" | undefined;
     source?: {
         sessionId?: string | undefined;
-        type?: "conversation" | "observation" | "inference" | "consolidation" | "external" | "manual" | undefined;
+        type?: "consolidation" | "conversation" | "observation" | "inference" | "external" | "manual" | undefined;
         agentId?: string | undefined;
         evidence?: string[] | undefined;
     } | undefined;
@@ -191,6 +191,15 @@ export interface VaultConfig {
         model?: string;
         embeddingModel?: string;
     };
+    /** Temporal intelligence settings (contradiction detection, recency boost) */
+    temporal?: {
+        /** Enable contradiction detection at write time (default: true when LLM is configured) */
+        detectContradictions?: boolean;
+        /** Minimum entity overlap to consider contradiction (default: 1) */
+        minEntityOverlap?: number;
+        /** Similarity threshold for contradiction candidates (default: 0.75) */
+        contradictionSimilarityThreshold?: number;
+    };
     /** Decay settings */
     decay?: {
         /** Base half-life in hours for new memories (default: 168 = 1 week) */

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/vault.d.ts

@@ -17,6 +17,22 @@ export declare class Vault {
      * Only dedup within the same type (don't merge episodic into semantic).
      */
     private dedup;
+    /**
+     * Detect contradictions: when a new memory is stored, check if it
+     * updates or replaces an existing fact about the same entity.
+     *
+     * Uses a two-phase approach:
+     *   1. Fast heuristic filter (entity/topic overlap) — no LLM cost
+     *   2. LLM verification for top candidates — one call per candidate
+     *
+     * When a contradiction is confirmed, the old memory is marked as
+     * `superseded` and linked with a `supersedes` edge. This prevents
+     * stale facts from polluting recall results.
+     *
+     * Only runs when LLM is configured. Fails silently — contradiction
+     * detection is best-effort and should never break remember().
+     */
+    private detectContradictions;
     /** Compute embedding and store it — can be awaited if needed */
     computeAndStoreEmbedding(memoryId: string, content: string): Promise<void>;
     /** Batch compute embeddings for all memories missing them */

package/dist/vault.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"vault.d.ts","sourceRoot":"","sources":["../src/vault.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"vault.d.ts","sourceRoot":"","sources":["../src/vault.ts"],"names":[],"mappings":"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"}

package/dist/vault.js

@@ -2,6 +2,7 @@ import path from 'path';
 import { MemoryStore } from './store.js';
 import { RememberInputSchema, RecallInputSchema } from './types.js';
 import { extract } from './extract.js';
+import { calculateRecencyBoost, DEFAULT_TEMPORAL_CONFIG, findContradictionCandidates, verifyContradiction } from './temporal.js';
 // ============================================================
 // Vault — The public API for Engram
 // ============================================================
@@ -54,9 +55,14 @@ export class Vault {
                 .then(() => {
                 // Dedup check: if a very similar memory already exists, merge instead of keeping both
                 this.dedup(memory);
+            })
+                .then(() => {
+                // Contradiction detection: if this memory updates a previous fact,
+                // mark the old one as superseded. Only runs when LLM is configured.
+                return this.detectContradictions(memory);
             })
                 .catch(err => {
-                console.warn(`Failed to compute embedding for ${memory.id}:`, err);
+                console.warn(`Failed to process embedding/contradictions for ${memory.id}:`, err);
             })
                 .finally(() => {
                 this.pendingEmbeddings.delete(p);
@@ -112,6 +118,87 @@ export class Vault {
             // Dedup is best-effort; don't break remember() if it fails
         }
     }
+    /**
+     * Detect contradictions: when a new memory is stored, check if it
+     * updates or replaces an existing fact about the same entity.
+     *
+     * Uses a two-phase approach:
+     *   1. Fast heuristic filter (entity/topic overlap) — no LLM cost
+     *   2. LLM verification for top candidates — one call per candidate
+     *
+     * When a contradiction is confirmed, the old memory is marked as
+     * `superseded` and linked with a `supersedes` edge. This prevents
+     * stale facts from polluting recall results.
+     *
+     * Only runs when LLM is configured. Fails silently — contradiction
+     * detection is best-effort and should never break remember().
+     */
+    async detectContradictions(memory) {
+        // Skip if LLM not configured or detection disabled
+        if (!this.config.llm)
+            return;
+        if (this.config.temporal?.detectContradictions === false)
+            return;
+        // Skip if memory was already superseded by dedup
+        const current = this.store.getMemoryDirect(memory.id);
+        if (!current || current.status !== 'active')
+            return;
+        // Skip memories with no entities — can't detect contradictions without them
+        if (!memory.entities || memory.entities.length === 0)
+            return;
+        try {
+            // Phase 1: Find candidates via vector similarity + entity overlap
+            const embedding = this.store.getEmbedding(memory.id);
+            if (!embedding)
+                return;
+            // Wider search than dedup — we want topically similar, not identical
+            const similar = this.store.findSimilar(embedding, 0.5, 20);
+            const candidateIds = similar
+                .filter(s => s.memoryId !== memory.id)
+                .map(s => s.memoryId);
+            if (candidateIds.length === 0)
+                return;
+            const candidateMemories = this.store.getMemoriesDirect(candidateIds)
+                .filter(m => m.status === 'active');
+            // Phase 1b: Heuristic filter — must share entities
+            const threshold = this.config.temporal?.contradictionSimilarityThreshold ?? 0.75;
+            const minOverlap = this.config.temporal?.minEntityOverlap ?? 1;
+            const filtered = findContradictionCandidates(memory, candidateMemories, {
+                detectContradictions: true,
+                recencyBoost: DEFAULT_TEMPORAL_CONFIG.recencyBoost,
+                minEntityOverlap: minOverlap,
+                contradictionSimilarityThreshold: threshold,
+            });
+            if (filtered.length === 0)
+                return;
+            // Phase 2: LLM verification — check top 3 candidates max
+            const llmCall = (prompt) => this.callLLM(this.config.llm.model ?? 'gemini-2.0-flash', prompt, this.config.llm);
+            // Only check older memories — newer ones can't be superseded by this memory
+            const olderCandidates = filtered
+                .filter(c => new Date(c.createdAt) < new Date(memory.createdAt))
+                .slice(0, 3);
+            for (const candidate of olderCandidates) {
+                const result = await verifyContradiction(memory, candidate, llmCall);
+                if (result && result.confidence >= 0.7) {
+                    // Mark the old memory as superseded
+                    this.store.updateStatus(candidate.id, 'superseded');
+                    // Create a supersedes edge with the contradiction confidence
+                    this.store.createEdge(memory.id, candidate.id, 'supersedes', result.confidence);
+                    // Inherit the old memory's stability (it was a trusted fact)
+                    const oldStability = candidate.stability;
+                    if (oldStability > memory.stability) {
+                        // The new fact inherits some credibility from the old one
+                        this.store.updateMemory(memory.id, {
+                            salience: Math.min(1.0, memory.salience + 0.1),
+                        });
+                    }
+                }
+            }
+        }
+        catch {
+            // Contradiction detection is best-effort
+        }
+    }
     /** Compute embedding and store it — can be awaited if needed */
     async computeAndStoreEmbedding(memoryId, content) {
         if (!this.embedder)
@@ -343,6 +430,9 @@ export class Vault {
             // Superseded/archived penalty: shouldn't appear in results
             const statusPenalty = (r.memory.status === 'superseded' || r.memory.status === 'archived') ? 0.5 : 0;
             r.score = r.score * (0.5 + salienceBoost + stabilityBoost + typeBonus + confidenceBonus) - statusPenalty;
+            // Recency boost: newer memories get a small additive bump.
+            // Breaks ties between competing facts about the same entity.
+            r.score += calculateRecencyBoost(r.memory, DEFAULT_TEMPORAL_CONFIG.recencyBoost);
         }
         // 9. Sort by score and return top N
         results.sort((a, b) => b.score - a.score);