Merge pull request #183 from CortexReach/feat/temporal-facts-pr1

feat: add temporal supersede semantics for mutable facts

Author: rwmjhb

package.json

@@ -36,7 +36,7 @@
     ]
   },
   "scripts": {
-    "test": "node test/embedder-error-hints.test.mjs && node test/migrate-legacy-schema.test.mjs && node --test test/config-session-strategy-migration.test.mjs && node --test test/recall-text-cleanup.test.mjs && node test/update-consistency-lancedb.test.mjs && node test/cli-smoke.mjs && node test/functional-e2e.mjs && node test/retriever-rerank-regression.mjs && node test/smart-memory-lifecycle.mjs && node test/smart-extractor-branches.mjs && node test/plugin-manifest-regression.mjs && node --test test/sync-plugin-version.test.mjs && node test/smart-metadata-v2.mjs && node test/vector-search-cosine.test.mjs && node test/context-support-e2e.mjs",
+    "test": "node test/embedder-error-hints.test.mjs && node test/migrate-legacy-schema.test.mjs && node --test test/config-session-strategy-migration.test.mjs && node --test test/recall-text-cleanup.test.mjs && node test/update-consistency-lancedb.test.mjs && node test/cli-smoke.mjs && node test/functional-e2e.mjs && node test/retriever-rerank-regression.mjs && node test/smart-memory-lifecycle.mjs && node test/smart-extractor-branches.mjs && node test/plugin-manifest-regression.mjs && node --test test/sync-plugin-version.test.mjs && node test/smart-metadata-v2.mjs && node test/vector-search-cosine.test.mjs && node test/context-support-e2e.mjs && node test/temporal-facts.test.mjs && node test/memory-update-supersede.test.mjs",
     "test:openclaw-host": "node test/openclaw-host-functional.mjs",
     "version": "node scripts/sync-plugin-version.mjs openclaw.plugin.json package.json && git add openclaw.plugin.json"
   },

src/extraction-prompts.ts

@@ -149,25 +149,27 @@ Please decide:
 - SKIP: Candidate memory duplicates existing memories, no need to save. Also SKIP if the candidate contains LESS information than an existing memory on the same topic (information degradation — e.g., candidate says "programming language preference" but existing memory already says "programming language preference: Python, TypeScript")
 - CREATE: This is completely new information not covered by any existing memory, should be created
 - MERGE: Candidate memory adds genuinely NEW details to an existing memory and should be merged
+- SUPERSEDE: Candidate states that the same mutable fact has changed over time. Keep the old memory as historical but no longer current, and create a new current memory.
 - SUPPORT: Candidate reinforces/confirms an existing memory in a specific context (e.g. "still prefers tea in the evening")
 - CONTEXTUALIZE: Candidate adds a situational nuance to an existing memory (e.g. existing: "likes coffee", candidate: "prefers tea at night" — different context, same topic)
 - CONTRADICT: Candidate directly contradicts an existing memory in a specific context (e.g. existing: "runs on weekends", candidate: "stopped running on weekends")
 
 IMPORTANT:
-- "events" and "cases" categories are independent records — they do NOT support MERGE/SUPPORT/CONTEXTUALIZE/CONTRADICT. For these categories, only use SKIP or CREATE.
+- "events" and "cases" categories are independent records — they do NOT support MERGE/SUPERSEDE/SUPPORT/CONTEXTUALIZE/CONTRADICT. For these categories, only use SKIP or CREATE.
 - If the candidate appears to be derived from a recall question (e.g., "Do you remember X?" / "你记得X吗？") and an existing memory already covers topic X with equal or more detail, you MUST choose SKIP.
 - A candidate with less information than an existing memory on the same topic should NEVER be CREATED or MERGED — always SKIP.
+- For "preferences" and "entities", use SUPERSEDE when the candidate replaces the current truth instead of adding detail or context. Example: existing "Preferred editor: VS Code", candidate "Preferred editor: Zed".
 - For SUPPORT/CONTEXTUALIZE/CONTRADICT, you MUST provide a context_label from this vocabulary: general, morning, evening, night, weekday, weekend, work, leisure, summer, winter, travel.
 
 Return JSON format:
 {
-  "decision": "skip|create|merge|support|contextualize|contradict",
+  "decision": "skip|create|merge|supersede|support|contextualize|contradict",
   "match_index": 1,
   "reason": "Decision reason",
   "context_label": "evening"
 }
 
-- If decision is "merge"/"support"/"contextualize"/"contradict", set "match_index" to the number of the existing memory (1-based).
+- If decision is "merge"/"supersede"/"support"/"contextualize"/"contradict", set "match_index" to the number of the existing memory (1-based).
 - Only include "context_label" for support/contextualize/contradict decisions.`;
 }
 

src/memory-categories.ts

@@ -26,6 +26,12 @@ export const MERGE_SUPPORTED_CATEGORIES = new Set<MemoryCategory>([
   "patterns",
 ]);
 
+/** Categories whose facts can be replaced over time without deleting history. */
+export const TEMPORAL_VERSIONED_CATEGORIES = new Set<MemoryCategory>([
+  "preferences",
+  "entities",
+]);
+
 /** Categories that are append-only (CREATE or SKIP only, no MERGE). */
 export const APPEND_ONLY_CATEGORIES = new Set<MemoryCategory>([
   "events",
@@ -44,7 +50,14 @@ export type CandidateMemory = {
 };
 
 /** Dedup decision from LLM. */
-export type DedupDecision = "create" | "merge" | "skip" | "support" | "contextualize" | "contradict";
+export type DedupDecision =
+  | "create"
+  | "merge"
+  | "skip"
+  | "support"
+  | "contextualize"
+  | "contradict"
+  | "supersede";
 
 export type DedupResult = {
   decision: DedupDecision;
@@ -58,6 +71,7 @@ export type ExtractionStats = {
   merged: number;
   skipped: number;
   supported?: number; // context-aware support count
+  superseded?: number; // temporal fact replacements
 };
 
 /** Validate and normalize a category string. */

src/retriever.ts

@@ -13,7 +13,12 @@ import {
 import { filterNoise } from "./noise-filter.js";
 import type { DecayEngine, DecayableMemory } from "./decay-engine.js";
 import type { TierManager } from "./tier-manager.js";
-import { toLifecycleMemory, getDecayableFromEntry } from "./smart-metadata.js";
+import {
+  getDecayableFromEntry,
+  isMemoryActiveAt,
+  parseSmartMetadata,
+  toLifecycleMemory,
+} from "./smart-metadata.js";
 
 // ============================================================================
 // Types & Configuration
@@ -302,6 +307,12 @@ export class MemoryRetriever {
     this.accessTracker = tracker;
   }
 
+  private filterActiveResults<T extends MemorySearchResult>(results: T[]): T[] {
+    return results.filter((result) =>
+      isMemoryActiveAt(parseSmartMetadata(result.entry.metadata, result.entry)),
+    );
+  }
+
   async retrieve(context: RetrievalContext): Promise<RetrievalResult[]> {
     const { query, limit, scopeFilter, category, source } = context;
     const safeLimit = clampInt(limit, 1, 20);
@@ -343,6 +354,7 @@ export class MemoryRetriever {
       limit,
       this.config.minScore,
       scopeFilter,
+      { excludeInactive: true },
     );
 
     // Filter by category if specified
@@ -458,6 +470,7 @@ export class MemoryRetriever {
       limit,
       0.1,
       scopeFilter,
+      { excludeInactive: true },
     );
 
     // Filter by category if specified
@@ -477,7 +490,7 @@ export class MemoryRetriever {
     scopeFilter?: string[],
     category?: string,
   ): Promise<Array<MemorySearchResult & { rank: number }>> {
-    const results = await this.store.bm25Search(query, limit, scopeFilter);
+    const results = await this.store.bm25Search(query, limit, scopeFilter, { excludeInactive: true });
 
     // Filter by category if specified
     const filtered = category

src/smart-extractor.ts

@@ -23,11 +23,21 @@ import {
   ALWAYS_MERGE_CATEGORIES,
   MERGE_SUPPORTED_CATEGORIES,
   MEMORY_CATEGORIES,
+  TEMPORAL_VERSIONED_CATEGORIES,
   normalizeCategory,
 } from "./memory-categories.js";
 import { isNoise } from "./noise-filter.js";
 import type { NoisePrototypeBank } from "./noise-prototypes.js";
-import { buildSmartMetadata, parseSmartMetadata, stringifySmartMetadata, parseSupportInfo, updateSupportStats } from "./smart-metadata.js";
+import {
+  appendRelation,
+  buildSmartMetadata,
+  deriveFactKey,
+  type MemoryRelation,
+  parseSmartMetadata,
+  stringifySmartMetadata,
+  parseSupportInfo,
+  updateSupportStats,
+} from "./smart-metadata.js";
 
 // ============================================================================
 // Constants
@@ -36,7 +46,15 @@ import { buildSmartMetadata, parseSmartMetadata, stringifySmartMetadata, parseSu
 const SIMILARITY_THRESHOLD = 0.7;
 const MAX_SIMILAR_FOR_PROMPT = 3;
 const MAX_MEMORIES_PER_EXTRACTION = 5;
-const VALID_DECISIONS = new Set<string>(["create", "merge", "skip", "support", "contextualize", "contradict"]);
+const VALID_DECISIONS = new Set<string>([
+  "create",
+  "merge",
+  "skip",
+  "support",
+  "contextualize",
+  "contradict",
+  "supersede",
+]);
 
 // ============================================================================
 // Smart Extractor
@@ -358,6 +376,27 @@ export class SmartExtractor {
         stats.skipped++;
         break;
 
+      case "supersede":
+        if (
+          dedupResult.matchId &&
+          TEMPORAL_VERSIONED_CATEGORIES.has(candidate.category)
+        ) {
+          await this.handleSupersede(
+            candidate,
+            vector,
+            dedupResult.matchId,
+            sessionKey,
+            targetScope,
+            scopeFilter,
+          );
+          stats.created++;
+          stats.superseded = (stats.superseded ?? 0) + 1;
+        } else {
+          await this.storeCandidate(candidate, vector, sessionKey, targetScope);
+          stats.created++;
+        }
+        break;
+
       case "support":
         if (dedupResult.matchId) {
           await this.handleSupport(dedupResult.matchId, scopeFilter, { session: sessionKey, timestamp: Date.now() }, dedupResult.reason, dedupResult.contextLabel);
@@ -380,8 +419,24 @@ export class SmartExtractor {
 
       case "contradict":
         if (dedupResult.matchId) {
-          await this.handleContradict(candidate, vector, dedupResult.matchId, sessionKey, targetScope, scopeFilter, dedupResult.contextLabel);
-          stats.created++;
+          if (
+            TEMPORAL_VERSIONED_CATEGORIES.has(candidate.category) &&
+            dedupResult.contextLabel === "general"
+          ) {
+            await this.handleSupersede(
+              candidate,
+              vector,
+              dedupResult.matchId,
+              sessionKey,
+              targetScope,
+              scopeFilter,
+            );
+            stats.created++;
+            stats.superseded = (stats.superseded ?? 0) + 1;
+          } else {
+            await this.handleContradict(candidate, vector, dedupResult.matchId, sessionKey, targetScope, scopeFilter, dedupResult.contextLabel);
+            stats.created++;
+          }
         } else {
           await this.storeCandidate(candidate, vector, sessionKey, targetScope);
           stats.created++;
@@ -402,20 +457,23 @@ export class SmartExtractor {
     candidateVector: number[],
     scopeFilter: string[],
   ): Promise<DedupResult> {
-    // Stage 1: Vector pre-filter — find similar memories
-    const similar = await this.store.vectorSearch(
+    // Stage 1: Vector pre-filter — find similar active memories.
+    // excludeInactive ensures the store over-fetches to fill N active slots,
+    // preventing superseded history from crowding out the current fact.
+    const activeSimilar = await this.store.vectorSearch(
       candidateVector,
       5,
       SIMILARITY_THRESHOLD,
       scopeFilter,
+      { excludeInactive: true },
     );
 
-    if (similar.length === 0) {
+    if (activeSimilar.length === 0) {
       return { decision: "create", reason: "No similar memories found" };
     }
 
     // Stage 2: LLM decision
-    return this.llmDedupDecision(candidate, similar);
+    return this.llmDedupDecision(candidate, activeSimilar);
   }
 
   private async llmDedupDecision(
@@ -468,15 +526,28 @@ export class SmartExtractor {
 
       // Resolve merge target from LLM's match_index (1-based)
       const idx = data.match_index;
-      const matchEntry =
-        typeof idx === "number" && idx >= 1 && idx <= topSimilar.length
-          ? topSimilar[idx - 1]
-          : topSimilar[0];
+      const hasValidIndex = typeof idx === "number" && idx >= 1 && idx <= topSimilar.length;
+      const matchEntry = hasValidIndex
+        ? topSimilar[idx - 1]
+        : topSimilar[0];
+
+      // For destructive decisions (supersede), missing match_index is
+      // unsafe — we could invalidate the wrong memory. Degrade to create.
+      const destructiveDecisions = new Set(["supersede", "contradict"]);
+      if (destructiveDecisions.has(decision) && !hasValidIndex) {
+        this.log(
+          `memory-pro: smart-extractor: ${decision} decision has missing/invalid match_index (${idx}), degrading to create`,
+        );
+        return {
+          decision: "create",
+          reason: `${decision} degraded: missing match_index`,
+        };
+      }
 
       return {
         decision,
         reason: data.reason ?? "",
-        matchId: ["merge", "support", "contextualize", "contradict"].includes(decision) ? matchEntry?.entry.id : undefined,
+        matchId: ["merge", "support", "contextualize", "contradict", "supersede"].includes(decision) ? matchEntry?.entry.id : undefined,
         contextLabel: typeof (data as any).context_label === "string" ? (data as any).context_label : undefined,
       };
     } catch (err) {
@@ -640,6 +711,83 @@ export class SmartExtractor {
     );
   }
 
+  /**
+   * Handle SUPERSEDE: preserve the old record as historical but mark it as no
+   * longer current, then create the new active fact.
+   */
+  private async handleSupersede(
+    candidate: CandidateMemory,
+    vector: number[],
+    matchId: string,
+    sessionKey: string,
+    targetScope: string,
+    scopeFilter: string[],
+  ): Promise<void> {
+    const existing = await this.store.getById(matchId, scopeFilter);
+    if (!existing) {
+      await this.storeCandidate(candidate, vector, sessionKey, targetScope);
+      return;
+    }
+
+    const now = Date.now();
+    const existingMeta = parseSmartMetadata(existing.metadata, existing);
+    const factKey =
+      existingMeta.fact_key ?? deriveFactKey(candidate.category, candidate.abstract);
+    const storeCategory = this.mapToStoreCategory(candidate.category);
+    const created = await this.store.store({
+      text: candidate.abstract,
+      vector,
+      category: storeCategory,
+      scope: targetScope,
+      importance: this.getDefaultImportance(candidate.category),
+      metadata: stringifySmartMetadata(
+        buildSmartMetadata(
+          {
+            text: candidate.abstract,
+            category: storeCategory,
+          },
+          {
+            l0_abstract: candidate.abstract,
+            l1_overview: candidate.overview,
+            l2_content: candidate.content,
+            memory_category: candidate.category,
+            tier: "working",
+            access_count: 0,
+            confidence: 0.7,
+            source_session: sessionKey,
+            valid_from: now,
+            fact_key: factKey,
+            supersedes: matchId,
+            relations: appendRelation([], {
+              type: "supersedes",
+              targetId: matchId,
+            }),
+          },
+        ),
+      ),
+    });
+
+    const invalidatedMetadata = buildSmartMetadata(existing, {
+      fact_key: factKey,
+      invalidated_at: now,
+      superseded_by: created.id,
+      relations: appendRelation(existingMeta.relations, {
+        type: "superseded_by",
+        targetId: created.id,
+      }),
+    });
+
+    await this.store.update(
+      matchId,
+      { metadata: stringifySmartMetadata(invalidatedMetadata) },
+      scopeFilter,
+    );
+
+    this.log(
+      `memory-pro: smart-extractor: superseded [${candidate.category}] ${matchId.slice(0, 8)} -> ${created.id.slice(0, 8)}`,
+    );
+  }
+
   // --------------------------------------------------------------------------
   // Context-Aware Handlers (support / contextualize / contradict)
   // --------------------------------------------------------------------------