agent-working-memory 0.16.1 → 0.18.1

package/src/types/engram.ts

@@ -72,6 +72,24 @@ export interface Engram {
   validFrom?: string | null;      // ISO date/datetime
   validTo?: string | null;        // ISO date/datetime — set when a fact expires/superseded by time
 
+  /**
+   * When `stage` last changed, ISO. **Null means it has never transitioned** —
+   * readers fall back to `createdAt`, so no backfill is required.
+   *
+   * The table carried `created_at`, `last_accessed` and `retracted_at` and nothing
+   * that recorded when a lifecycle decision was taken, which made fade regret and
+   * archive regret — "was this needed after we hid it?" — impossible to compute after
+   * the fact, for a store that is 60.7% archived. Written in `updateStage`, which is
+   * the single chokepoint all six consolidation transitions go through
+   * (`consolidation.ts` fade, three archive branches, prune, staging promote), so it
+   * cannot be forgotten at a new call site.
+   *
+   * ISO string rather than Date, like validFrom/validTo and unlike createdAt: it is
+   * written by one UPDATE and read by analysis queries, never used in scoring math.
+   * Log-only — nothing in retrieval reads it.
+   */
+  stageChangedAt?: string | null;
+
   // Task management (null = not a task)
   taskStatus: TaskStatus | null;
   taskPriority: TaskPriority | null;
@@ -226,6 +244,14 @@ export interface ActivationResult {
    * generated and dropped, and every retrieval_feedback row was orphaned.
    */
   activationEventId?: string;
+  /**
+   * Other memories in THIS recall's result set that look like a different
+   * version of the same fact (same subject, a differing time / date / money /
+   * number / status), with which is newer. Detected over the returned set
+   * only — see src/core/conflicts.ts. Absent or empty when none. Harnesses
+   * should treat it as "confirm against the source before stating a value".
+   */
+  conflictsWith?: Array<{ id: string; newer: boolean; slot: 'time' | 'date' | 'money' | 'number' | 'status' }>;
   /**
    * Confidence-adaptive content preview (Paper 3: cognitive teaming).
    * Set when the query opts in via `granularity: 'compact' | 'auto'`.
@@ -247,6 +273,10 @@ export interface PhaseScores {
   confidenceGate: number;
   composite: number;
   rerankerScore: number;   // Cross-encoder relevance (0-1), 0 if reranker disabled
+  /** Phase 8c's factor (0.15) when the memory is superseded, expired or not yet
+   *  valid; absent otherwise. Phase 9b (rerank2) multiplies its sort key by it
+   *  so a stale memory cannot outrank its successor there either. */
+  stalePenalty?: number;
 }
 
 /**