recallnest 2.2.1 → 2.5.4

package/src/__tests__/memory-evolution-b2-b3-e1.test.ts

@@ -0,0 +1,345 @@
+/**
+ * Tests for Memory Evolution Phase B-2 (Archive Strategy),
+ * B-3 (LLM Importance Assessment), and E-1 (Multi-factor Retrieval Scoring).
+ */
+import { describe, expect, test } from "bun:test";
+import {
+  parseEvolution,
+  computeDecayScore,
+  computeUsageAdjustedDecayScore,
+  buildArchivedMetadata,
+  isActiveMemory,
+  patchEvolution,
+  type EvolutionMetadata,
+} from "../memory-evolution.js";
+import {
+  maybeRunGc,
+  resetGcTimestamp,
+  DEFAULT_AUTO_GC_CONFIG,
+  type AutoGcConfig,
+} from "../auto-gc.js";
+
+// ---------------------------------------------------------------------------
+// B-2: Archive Strategy Tests
+// ---------------------------------------------------------------------------
+
+describe("B-2: Archive Strategy", () => {
+  test("buildArchivedMetadata sets status to archived", () => {
+    const meta = JSON.stringify({ evolution: { status: "active", version: 1 } });
+    const archived = buildArchivedMetadata(meta);
+    const evo = parseEvolution(archived);
+    expect(evo.status).toBe("archived");
+  });
+
+  test("archived memory is not active", () => {
+    const meta = JSON.stringify({ evolution: { status: "archived", version: 1 } });
+    expect(isActiveMemory(meta)).toBe(false);
+  });
+
+  test("active memory is active", () => {
+    const meta = JSON.stringify({ evolution: { status: "active", version: 1 } });
+    expect(isActiveMemory(meta)).toBe(true);
+  });
+
+  describe("auto-gc with evolution system", () => {
+    function makeStore(entries: Array<{
+      id: string;
+      importance: number;
+      timestamp: number;
+      metadata: string;
+    }>) {
+      const data = new Map(entries.map(e => [e.id, {
+        ...e,
+        text: "test",
+        vector: [1, 0, 0],
+        category: "events",
+        scope: "project:test",
+      }]));
+      const updates: Array<{ id: string; metadata: string }> = [];
+      return {
+        store: {
+          stats: async () => ({ totalCount: data.size, scopeCounts: {}, categoryCounts: {} }),
+          list: async () => Array.from(data.values()),
+          listPage: async (opts: { limit?: number; offset?: number } = {}) => {
+            const { limit = 1000, offset = 0 } = opts;
+            return Array.from(data.values()).slice(offset, offset + limit);
+          },
+          update: async (id: string, patch: { metadata: string }) => {
+            updates.push({ id, metadata: patch.metadata });
+            const entry = data.get(id);
+            if (!entry) return null;
+            entry.metadata = patch.metadata;
+            return entry;
+          },
+        },
+        updates,
+      };
+    }
+
+    test("archives low-decay-score memories", async () => {
+      resetGcTimestamp();
+      const now = Date.now();
+      const oldTimestamp = now - 120 * 86_400_000; // 120 days ago
+      const activeMeta = JSON.stringify({
+        evolution: {
+          status: "active",
+          version: 1,
+          accessCount: 0,
+          lastAccessedAt: null,
+          validFrom: oldTimestamp,
+          validUntil: null,
+        },
+      });
+
+      const { store, updates } = makeStore([
+        { id: "old-low", importance: 0.1, timestamp: oldTimestamp, metadata: activeMeta },
+      ]);
+
+      const config: AutoGcConfig = {
+        ...DEFAULT_AUTO_GC_CONFIG,
+        minMemoryCount: 1,
+        minHoursSinceLastGc: 0,
+        decayScoreThreshold: 0.2,
+        minAgeDays: 30,
+      };
+
+      const result = await maybeRunGc(store as any, config);
+      expect(result.triggered).toBe(true);
+      expect(result.archivedCount).toBe(1);
+      expect(updates.length).toBe(1);
+
+      const archivedEvo = parseEvolution(updates[0].metadata);
+      expect(archivedEvo.status).toBe("archived");
+    });
+
+    test("skips pinned memories (importance >= 0.95)", async () => {
+      resetGcTimestamp();
+      const now = Date.now();
+      const oldTimestamp = now - 120 * 86_400_000;
+      const activeMeta = JSON.stringify({
+        evolution: {
+          status: "active",
+          version: 1,
+          accessCount: 0,
+          lastAccessedAt: null,
+          validFrom: oldTimestamp,
+          validUntil: null,
+        },
+      });
+
+      const { store, updates } = makeStore([
+        { id: "pinned", importance: 0.95, timestamp: oldTimestamp, metadata: activeMeta },
+      ]);
+
+      const config: AutoGcConfig = {
+        ...DEFAULT_AUTO_GC_CONFIG,
+        minMemoryCount: 1,
+        minHoursSinceLastGc: 0,
+      };
+
+      const result = await maybeRunGc(store as any, config);
+      expect(result.triggered).toBe(true);
+      expect(result.archivedCount).toBe(0);
+      expect(updates.length).toBe(0);
+    });
+
+    test("usage-adjusted GC is gated and can archive cold high-frequency memories", async () => {
+      const savedUsageDecay = process.env.RECALLNEST_USAGE_DECAY;
+      const savedConstructive = process.env.RECALLNEST_CONSTRUCTIVE_RETRIEVAL;
+      try {
+        const now = Date.now();
+        const oldTimestamp = now - 180 * 86_400_000;
+        const coldMeta = JSON.stringify({
+          accessCount: 10,
+          evolution: {
+            status: "active",
+            version: 1,
+            accessCount: 10,
+            lastAccessedAt: now,
+            validFrom: oldTimestamp,
+            validUntil: null,
+          },
+        });
+        const config: AutoGcConfig = {
+          ...DEFAULT_AUTO_GC_CONFIG,
+          minMemoryCount: 1,
+          minHoursSinceLastGc: 0,
+          decayScoreThreshold: 0.15,
+          minAgeDays: 30,
+        };
+
+        delete process.env.RECALLNEST_USAGE_DECAY;
+        delete process.env.RECALLNEST_CONSTRUCTIVE_RETRIEVAL;
+        resetGcTimestamp();
+        const withoutFlag = makeStore([
+          { id: "cold-no-flag", importance: 0.05, timestamp: oldTimestamp, metadata: coldMeta },
+        ]);
+        const baseline = await maybeRunGc(withoutFlag.store as any, config);
+        expect(baseline.archivedCount).toBe(0);
+        expect(withoutFlag.updates).toHaveLength(0);
+
+        process.env.RECALLNEST_USAGE_DECAY = "true";
+        process.env.RECALLNEST_CONSTRUCTIVE_RETRIEVAL = "true";
+        resetGcTimestamp();
+        const withFlag = makeStore([
+          { id: "cold-with-flag", importance: 0.05, timestamp: oldTimestamp, metadata: coldMeta },
+        ]);
+        const adjusted = await maybeRunGc(withFlag.store as any, config);
+        expect(adjusted.archivedCount).toBe(1);
+        expect(withFlag.updates).toHaveLength(1);
+      } finally {
+        if (savedUsageDecay === undefined) delete process.env.RECALLNEST_USAGE_DECAY;
+        else process.env.RECALLNEST_USAGE_DECAY = savedUsageDecay;
+        if (savedConstructive === undefined) delete process.env.RECALLNEST_CONSTRUCTIVE_RETRIEVAL;
+        else process.env.RECALLNEST_CONSTRUCTIVE_RETRIEVAL = savedConstructive;
+      }
+    });
+
+    test("skips recently created memories", async () => {
+      resetGcTimestamp();
+      const recentMeta = JSON.stringify({
+        evolution: {
+          status: "active",
+          version: 1,
+          accessCount: 0,
+          lastAccessedAt: null,
+          validFrom: Date.now(),
+          validUntil: null,
+        },
+      });
+
+      const { store, updates } = makeStore([
+        { id: "recent", importance: 0.1, timestamp: Date.now(), metadata: recentMeta },
+      ]);
+
+      const config: AutoGcConfig = {
+        ...DEFAULT_AUTO_GC_CONFIG,
+        minMemoryCount: 1,
+        minHoursSinceLastGc: 0,
+        minAgeDays: 30,
+      };
+
+      const result = await maybeRunGc(store as any, config);
+      expect(result.triggered).toBe(true);
+      expect(result.archivedCount).toBe(0);
+    });
+
+    test("does not trigger when below memory threshold", async () => {
+      resetGcTimestamp();
+      const { store } = makeStore([
+        { id: "one", importance: 0.1, timestamp: Date.now() - 90 * 86_400_000, metadata: "{}" },
+      ]);
+
+      const result = await maybeRunGc(store as any, {
+        ...DEFAULT_AUTO_GC_CONFIG,
+        minMemoryCount: 1000,
+      });
+      expect(result.triggered).toBe(false);
+      expect(result.reason).toBe("below_memory_threshold");
+    });
+  });
+});
+
+// ---------------------------------------------------------------------------
+// E-1: Access Count Boost Tests (via computeDecayScore)
+// ---------------------------------------------------------------------------
+
+describe("E-1: Multi-factor Retrieval Scoring", () => {
+  test("higher accessCount produces higher decay score", () => {
+    const base: EvolutionMetadata = {
+      status: "active",
+      version: 1,
+      accessCount: 0,
+      lastAccessedAt: null,
+      supersededBy: null,
+      consolidatedInto: null,
+      sourceMemories: [],
+      validFrom: Date.now() - 30 * 86_400_000,
+      validUntil: null,
+    };
+    const lowAccess = computeDecayScore(base, 0.5);
+    const highAccess = computeDecayScore({ ...base, accessCount: 10, lastAccessedAt: Date.now() }, 0.5);
+    expect(highAccess).toBeGreaterThan(lowAccess);
+  });
+
+  test("higher importance produces higher decay score", () => {
+    const base: EvolutionMetadata = {
+      status: "active",
+      version: 1,
+      accessCount: 2,
+      lastAccessedAt: Date.now() - 86_400_000,
+      supersededBy: null,
+      consolidatedInto: null,
+      sourceMemories: [],
+      validFrom: Date.now() - 30 * 86_400_000,
+      validUntil: null,
+    };
+    const lowImportance = computeDecayScore(base, 0.3);
+    const highImportance = computeDecayScore(base, 0.9);
+    expect(highImportance).toBeGreaterThan(lowImportance);
+  });
+
+  test("older memories without access have lower decay scores", () => {
+    const recent: EvolutionMetadata = {
+      status: "active",
+      version: 1,
+      accessCount: 0,
+      lastAccessedAt: null,
+      supersededBy: null,
+      consolidatedInto: null,
+      sourceMemories: [],
+      validFrom: Date.now() - 7 * 86_400_000,
+      validUntil: null,
+    };
+    const old: EvolutionMetadata = {
+      ...recent,
+      validFrom: Date.now() - 180 * 86_400_000,
+    };
+    expect(computeDecayScore(recent, 0.5)).toBeGreaterThan(computeDecayScore(old, 0.5));
+  });
+});
+
+describe("P0 B-2: usage-adjusted GC scoring", () => {
+  const now = Date.now();
+  const oldColdEvo: EvolutionMetadata = {
+    status: "active",
+    version: 1,
+    accessCount: 10,
+    lastAccessedAt: now,
+    supersededBy: null,
+    supersedes: null,
+    evolutionNote: null,
+    consolidatedInto: null,
+    contributedToPattern: null,
+    sourceMemories: [],
+    validFrom: now - 180 * 86_400_000,
+    validUntil: null,
+    eventTime: null,
+  };
+
+  test("discounts frequency only for cold memories in GC scoring", () => {
+    const metadata = JSON.stringify({ accessCount: 10 });
+    const base = computeDecayScore(oldColdEvo, 0.05, now, metadata);
+    const adjusted = computeUsageAdjustedDecayScore(oldColdEvo, 0.05, now, metadata);
+
+    expect(base).toBeGreaterThan(0.15);
+    expect(adjusted).toBeLessThan(base);
+    expect(adjusted).toBeLessThan(0.15);
+  });
+
+  test("does not discount pending reminders or promoted memories", () => {
+    const pendingReminder = JSON.stringify({
+      accessCount: 10,
+      prospective: { status: "pending" },
+    });
+    const promoted = JSON.stringify({
+      accessCount: 10,
+      promotedTo: "memory:durable-target",
+    });
+
+    expect(computeUsageAdjustedDecayScore(oldColdEvo, 0.05, now, pendingReminder))
+      .toBe(computeDecayScore(oldColdEvo, 0.05, now, pendingReminder));
+    expect(computeUsageAdjustedDecayScore(oldColdEvo, 0.05, now, promoted))
+      .toBe(computeDecayScore(oldColdEvo, 0.05, now, promoted));
+  });
+});

package/src/__tests__/memory-evolution.test.ts

@@ -0,0 +1,271 @@
+import { describe, expect, test } from "bun:test";
+import {
+  defaultEvolution,
+  parseEvolution,
+  patchEvolution,
+  isActiveMemory,
+  recordAccess,
+  buildSupersedeMetadata,
+  buildConsolidatedMetadata,
+  buildArchivedMetadata,
+  computeDecayScore,
+  type EvolutionMetadata,
+} from "../memory-evolution.js";
+
+describe("memory-evolution", () => {
+  // -----------------------------------------------------------------------
+  // defaultEvolution
+  // -----------------------------------------------------------------------
+  describe("defaultEvolution", () => {
+    test("returns active status with version 1", () => {
+      const evo = defaultEvolution(1000);
+      expect(evo.status).toBe("active");
+      expect(evo.version).toBe(1);
+      expect(evo.accessCount).toBe(0);
+      expect(evo.lastAccessedAt).toBeNull();
+      expect(evo.supersededBy).toBeNull();
+      expect(evo.consolidatedInto).toBeNull();
+      expect(evo.sourceMemories).toEqual([]);
+      expect(evo.validFrom).toBe(1000);
+      expect(evo.validUntil).toBeNull();
+    });
+
+    test("uses Date.now() when no timestamp provided", () => {
+      const before = Date.now();
+      const evo = defaultEvolution();
+      expect(evo.validFrom).toBeGreaterThanOrEqual(before);
+      expect(evo.validFrom).toBeLessThanOrEqual(Date.now());
+    });
+  });
+
+  // -----------------------------------------------------------------------
+  // parseEvolution
+  // -----------------------------------------------------------------------
+  describe("parseEvolution", () => {
+    test("returns defaults for undefined metadata", () => {
+      const evo = parseEvolution(undefined, 2000);
+      expect(evo.status).toBe("active");
+      expect(evo.validFrom).toBe(2000);
+    });
+
+    test("returns defaults for empty string metadata", () => {
+      const evo = parseEvolution("", 2000);
+      expect(evo.status).toBe("active");
+    });
+
+    test("returns defaults for metadata without evolution field", () => {
+      const meta = JSON.stringify({ source: "manual", tags: [] });
+      const evo = parseEvolution(meta, 3000);
+      expect(evo.status).toBe("active");
+      expect(evo.validFrom).toBe(3000);
+    });
+
+    test("returns defaults for invalid JSON", () => {
+      const evo = parseEvolution("not json", 4000);
+      expect(evo.status).toBe("active");
+      expect(evo.validFrom).toBe(4000);
+    });
+
+    test("parses valid evolution metadata", () => {
+      const meta = JSON.stringify({
+        source: "agent",
+        evolution: {
+          status: "superseded",
+          version: 3,
+          accessCount: 42,
+          lastAccessedAt: 5000,
+          supersededBy: "abc-123",
+          consolidatedInto: null,
+          sourceMemories: ["x", "y"],
+          validFrom: 1000,
+          validUntil: 4000,
+        },
+      });
+      const evo = parseEvolution(meta);
+      expect(evo.status).toBe("superseded");
+      expect(evo.version).toBe(3);
+      expect(evo.accessCount).toBe(42);
+      expect(evo.lastAccessedAt).toBe(5000);
+      expect(evo.supersededBy).toBe("abc-123");
+      expect(evo.sourceMemories).toEqual(["x", "y"]);
+      expect(evo.validFrom).toBe(1000);
+      expect(evo.validUntil).toBe(4000);
+    });
+
+    test("fills missing fields with defaults", () => {
+      const meta = JSON.stringify({ evolution: { status: "archived" } });
+      const evo = parseEvolution(meta, 6000);
+      expect(evo.status).toBe("archived");
+      expect(evo.version).toBe(1);
+      expect(evo.accessCount).toBe(0);
+      expect(evo.validFrom).toBe(6000);
+    });
+  });
+
+  // -----------------------------------------------------------------------
+  // patchEvolution
+  // -----------------------------------------------------------------------
+  describe("patchEvolution", () => {
+    test("creates evolution on empty metadata", () => {
+      const patched = patchEvolution(undefined, { status: "archived" });
+      const parsed = JSON.parse(patched);
+      expect(parsed.evolution.status).toBe("archived");
+    });
+
+    test("merges into existing evolution", () => {
+      const original = JSON.stringify({
+        source: "manual",
+        evolution: { status: "active", version: 1, accessCount: 5 },
+      });
+      const patched = patchEvolution(original, { accessCount: 6, lastAccessedAt: 9000 });
+      const parsed = JSON.parse(patched);
+      expect(parsed.source).toBe("manual");
+      expect(parsed.evolution.status).toBe("active");
+      expect(parsed.evolution.version).toBe(1);
+      expect(parsed.evolution.accessCount).toBe(6);
+      expect(parsed.evolution.lastAccessedAt).toBe(9000);
+    });
+
+    test("preserves non-evolution fields", () => {
+      const original = JSON.stringify({ source: "agent", tags: ["a"], canonicalKey: "k1" });
+      const patched = patchEvolution(original, { status: "superseded" });
+      const parsed = JSON.parse(patched);
+      expect(parsed.source).toBe("agent");
+      expect(parsed.tags).toEqual(["a"]);
+      expect(parsed.canonicalKey).toBe("k1");
+    });
+  });
+
+  // -----------------------------------------------------------------------
+  // isActiveMemory
+  // -----------------------------------------------------------------------
+  describe("isActiveMemory", () => {
+    test("true for undefined metadata (backward compat)", () => {
+      expect(isActiveMemory(undefined)).toBe(true);
+    });
+
+    test("true for metadata without evolution", () => {
+      expect(isActiveMemory(JSON.stringify({ source: "manual" }))).toBe(true);
+    });
+
+    test("true for active status", () => {
+      const meta = JSON.stringify({ evolution: { status: "active" } });
+      expect(isActiveMemory(meta)).toBe(true);
+    });
+
+    test("false for superseded", () => {
+      const meta = JSON.stringify({ evolution: { status: "superseded" } });
+      expect(isActiveMemory(meta)).toBe(false);
+    });
+
+    test("false for archived", () => {
+      const meta = JSON.stringify({ evolution: { status: "archived" } });
+      expect(isActiveMemory(meta)).toBe(false);
+    });
+
+    test("false for consolidated", () => {
+      const meta = JSON.stringify({ evolution: { status: "consolidated" } });
+      expect(isActiveMemory(meta)).toBe(false);
+    });
+  });
+
+  // -----------------------------------------------------------------------
+  // recordAccess
+  // -----------------------------------------------------------------------
+  describe("recordAccess", () => {
+    test("increments count from 0 on undefined metadata", () => {
+      const updated = recordAccess(undefined);
+      const evo = parseEvolution(updated);
+      expect(evo.accessCount).toBe(1);
+      expect(evo.lastAccessedAt).toBeGreaterThan(0);
+    });
+
+    test("increments existing count", () => {
+      const original = JSON.stringify({
+        evolution: { accessCount: 5, lastAccessedAt: 1000 },
+      });
+      const updated = recordAccess(original);
+      const evo = parseEvolution(updated);
+      expect(evo.accessCount).toBe(6);
+      expect(evo.lastAccessedAt!).toBeGreaterThan(1000);
+    });
+  });
+
+  // -----------------------------------------------------------------------
+  // buildSupersedeMetadata / buildConsolidatedMetadata / buildArchivedMetadata
+  // -----------------------------------------------------------------------
+  describe("supersede/consolidate/archive helpers", () => {
+    test("buildSupersedeMetadata sets status and links", () => {
+      const original = JSON.stringify({ source: "manual", evolution: defaultEvolution(1000) });
+      const result = buildSupersedeMetadata(original, "new-id-123");
+      const evo = parseEvolution(result);
+      expect(evo.status).toBe("superseded");
+      expect(evo.supersededBy).toBe("new-id-123");
+      expect(evo.validUntil).toBeGreaterThan(0);
+    });
+
+    test("buildConsolidatedMetadata sets status and link", () => {
+      const result = buildConsolidatedMetadata(undefined, "consolidated-id");
+      const evo = parseEvolution(result);
+      expect(evo.status).toBe("consolidated");
+      expect(evo.consolidatedInto).toBe("consolidated-id");
+    });
+
+    test("buildArchivedMetadata sets status", () => {
+      const result = buildArchivedMetadata(undefined);
+      const evo = parseEvolution(result);
+      expect(evo.status).toBe("archived");
+    });
+  });
+
+  // -----------------------------------------------------------------------
+  // computeDecayScore
+  // -----------------------------------------------------------------------
+  describe("computeDecayScore", () => {
+    test("brand new high-importance memory scores high", () => {
+      const now = Date.now();
+      const evo: EvolutionMetadata = {
+        ...defaultEvolution(now),
+        accessCount: 0,
+      };
+      const score = computeDecayScore(evo, 1.0, now);
+      // 0.2 * 1.0 (fresh) + 0.3 * 0 (no access) * 0.5 + 0.5 * 1.0 = 0.7 + small freq
+      expect(score).toBeGreaterThan(0.6);
+      expect(score).toBeLessThanOrEqual(1.0);
+    });
+
+    test("old unaccessed low-importance memory scores low", () => {
+      const now = Date.now();
+      const evo: EvolutionMetadata = {
+        ...defaultEvolution(now - 365 * 86_400_000), // 1 year old
+        accessCount: 0,
+      };
+      const score = computeDecayScore(evo, 0.1, now);
+      expect(score).toBeLessThan(0.2);
+    });
+
+    test("frequently accessed memory gets frequency boost", () => {
+      const now = Date.now();
+      const evoNoAccess: EvolutionMetadata = {
+        ...defaultEvolution(now - 30 * 86_400_000),
+        accessCount: 0,
+      };
+      const evoHighAccess: EvolutionMetadata = {
+        ...defaultEvolution(now - 30 * 86_400_000),
+        accessCount: 100,
+        lastAccessedAt: now - 86_400_000, // yesterday
+      };
+      const scoreNo = computeDecayScore(evoNoAccess, 0.5, now);
+      const scoreHigh = computeDecayScore(evoHighAccess, 0.5, now);
+      expect(scoreHigh).toBeGreaterThan(scoreNo);
+    });
+
+    test("importance dominates scoring (0.5 weight)", () => {
+      const now = Date.now();
+      const evo = defaultEvolution(now);
+      const lowImp = computeDecayScore(evo, 0.1, now);
+      const highImp = computeDecayScore(evo, 1.0, now);
+      expect(highImp - lowImp).toBeGreaterThan(0.3); // 0.5 * (1.0 - 0.1) = 0.45
+    });
+  });
+});