recallnest 1.4.1 → 2.2.0

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
+    });
+  });
+});

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

@@ -0,0 +1,271 @@
+import { describe, expect, it } from "bun:test";
+import { runMemoryLint, formatMemoryLintReport, computeHealthScore, type MemoryLintReport } from "../memory-lint.js";
+import type { MemoryEntry, MemoryStore } from "../store.js";
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function makeEntry(overrides: Partial<MemoryEntry> & { id: string }): MemoryEntry {
+  return {
+    text: "test memory",
+    vector: [1, 0, 0, 0, 0],
+    category: "events",
+    scope: "project:test",
+    importance: 0.7,
+    timestamp: Date.now(),
+    metadata: JSON.stringify({
+      evolution: {
+        status: "active",
+        version: 1,
+        accessCount: 0,
+        lastAccessedAt: null,
+        supersededBy: null,
+        supersedes: null,
+        evolutionNote: null,
+        consolidatedInto: null,
+        contributedToPattern: null,
+        sourceMemories: [],
+        validFrom: Date.now(),
+        validUntil: null,
+      },
+    }),
+    ...overrides,
+  };
+}
+
+function createMockStore(entries: MemoryEntry[]): Pick<MemoryStore, "list"> {
+  return {
+    async list() { return entries; },
+  } as Pick<MemoryStore, "list">;
+}
+
+// ---------------------------------------------------------------------------
+// runMemoryLint
+// ---------------------------------------------------------------------------
+
+describe("runMemoryLint", () => {
+  it("returns all-clear for healthy data", async () => {
+    const entries = [
+      makeEntry({ id: "a1", text: "User prefers dark mode", category: "preferences", vector: [1, 0, 0, 0, 0] }),
+      makeEntry({ id: "a2", text: "Project uses Bun runtime", category: "entities", vector: [0, 1, 0, 0, 0] }),
+    ];
+    const store = createMockStore(entries);
+    const report = await runMemoryLint({ store });
+
+    expect(report.healthScore).toBe(100);
+    expect(report.findings).toHaveLength(0);
+    expect(report.summary.contradictions).toBe(0);
+    expect(report.summary.duplicates).toBe(0);
+    expect(report.totalScanned).toBe(2);
+  });
+
+  it("detects contradictions in same scope+category", async () => {
+    const entries = [
+      makeEntry({ id: "c1", text: "Always use Bun for scripts", scope: "project:x", category: "patterns" }),
+      makeEntry({ id: "c2", text: "Never use Bun for scripts", scope: "project:x", category: "patterns" }),
+    ];
+    const store = createMockStore(entries);
+    const report = await runMemoryLint({ store });
+
+    expect(report.summary.contradictions).toBeGreaterThanOrEqual(1);
+    const finding = report.findings.find(f => f.check === "contradiction");
+    expect(finding).toBeDefined();
+    expect(finding!.memoryIds).toContain("c1");
+    expect(finding!.memoryIds).toContain("c2");
+  });
+
+  it("detects duplicates by vector similarity", async () => {
+    const vec = [0.5, 0.5, 0.5, 0.5, 0.5];
+    const entries = [
+      makeEntry({ id: "d1", text: "Docker port is 4318", vector: vec, scope: "project:x", category: "entities" }),
+      makeEntry({ id: "d2", text: "Docker port is 4318 config", vector: vec, scope: "project:x", category: "entities" }),
+    ];
+    const store = createMockStore(entries);
+    const report = await runMemoryLint({ store });
+
+    expect(report.summary.duplicates).toBeGreaterThanOrEqual(1);
+    const finding = report.findings.find(f => f.check === "duplicate");
+    expect(finding).toBeDefined();
+  });
+
+  it("detects stale memories (old, never accessed)", async () => {
+    const oldTimestamp = Date.now() - 120 * 24 * 60 * 60 * 1000; // 120 days ago
+    const entries = [
+      makeEntry({
+        id: "s1",
+        text: "Some old fact",
+        timestamp: oldTimestamp,
+        metadata: JSON.stringify({
+          evolution: {
+            status: "active",
+            version: 1,
+            accessCount: 0,
+            lastAccessedAt: null,
+            supersededBy: null,
+            supersedes: null,
+            evolutionNote: null,
+            consolidatedInto: null,
+            contributedToPattern: null,
+            sourceMemories: [],
+            validFrom: oldTimestamp,
+            validUntil: null,
+          },
+        }),
+      }),
+    ];
+    const store = createMockStore(entries);
+    const report = await runMemoryLint({ store });
+
+    expect(report.summary.staleMemories).toBe(1);
+    const finding = report.findings.find(f => f.check === "stale");
+    expect(finding).toBeDefined();
+    expect(finding!.severity).toBe("info");
+  });
+
+  it("detects orphans with missing scope", async () => {
+    const entries = [
+      makeEntry({ id: "o1", text: "Orphan memory", scope: "" }),
+      makeEntry({ id: "o2", text: "Schema entry", scope: "__schema__" }),
+    ];
+    const store = createMockStore(entries);
+    const report = await runMemoryLint({ store });
+
+    expect(report.summary.orphans).toBe(2);
+  });
+
+  it("detects broken consolidation links", async () => {
+    const entries = [
+      makeEntry({
+        id: "b1",
+        text: "Points to deleted",
+        metadata: JSON.stringify({
+          evolution: {
+            status: "active",
+            version: 1,
+            accessCount: 5,
+            lastAccessedAt: Date.now(),
+            supersededBy: null,
+            supersedes: null,
+            evolutionNote: null,
+            consolidatedInto: "nonexistent-id-12345",
+            contributedToPattern: null,
+            sourceMemories: [],
+            validFrom: Date.now(),
+            validUntil: null,
+          },
+        }),
+      }),
+    ];
+    const store = createMockStore(entries);
+    const report = await runMemoryLint({ store });
+
+    expect(report.summary.orphans).toBe(1);
+    const finding = report.findings.find(f => f.check === "orphan" && f.severity === "warning");
+    expect(finding).toBeDefined();
+  });
+
+  it("skips non-active entries", async () => {
+    const entries = [
+      makeEntry({
+        id: "arc1",
+        text: "Archived memory",
+        scope: "",
+        metadata: JSON.stringify({
+          evolution: {
+            status: "archived",
+            version: 1,
+            accessCount: 0,
+            lastAccessedAt: null,
+            supersededBy: null,
+            supersedes: null,
+            evolutionNote: null,
+            consolidatedInto: null,
+            contributedToPattern: null,
+            sourceMemories: [],
+            validFrom: Date.now(),
+            validUntil: null,
+          },
+        }),
+      }),
+    ];
+    const store = createMockStore(entries);
+    const report = await runMemoryLint({ store });
+
+    // Archived entry should be skipped, so no orphan finding
+    expect(report.totalScanned).toBe(0);
+    expect(report.findings).toHaveLength(0);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// computeHealthScore
+// ---------------------------------------------------------------------------
+
+describe("computeHealthScore", () => {
+  it("returns 100 when no issues", () => {
+    expect(computeHealthScore({ contradictions: 0, duplicates: 0, staleMemories: 0, orphans: 0 }, 100)).toBe(100);
+  });
+
+  it("deducts correctly for mixed findings", () => {
+    // 1 contradiction (-10) + 2 duplicates (-10) + 4 stale (-2) + 1 orphan (-3) = -25 → 75
+    expect(computeHealthScore({ contradictions: 1, duplicates: 2, staleMemories: 4, orphans: 1 }, 100)).toBe(75);
+  });
+
+  it("clamps to 0", () => {
+    expect(computeHealthScore({ contradictions: 20, duplicates: 0, staleMemories: 0, orphans: 0 }, 10)).toBe(0);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// formatMemoryLintReport
+// ---------------------------------------------------------------------------
+
+describe("formatMemoryLintReport", () => {
+  it("shows all-clear when no findings", () => {
+    const report: MemoryLintReport = {
+      findings: [],
+      healthScore: 100,
+      totalScanned: 50,
+      timestamp: "2026-04-08T12:00:00Z",
+      summary: { contradictions: 0, duplicates: 0, staleMemories: 0, orphans: 0 },
+    };
+    const output = formatMemoryLintReport(report);
+    expect(output).toContain("All Clear");
+    expect(output).toContain("100/100");
+  });
+
+  it("includes findings when present", () => {
+    const report: MemoryLintReport = {
+      findings: [
+        { check: "contradiction", severity: "warning", detail: '"A" vs "B"', memoryIds: ["id1", "id2"] },
+      ],
+      healthScore: 90,
+      totalScanned: 100,
+      timestamp: "2026-04-08T12:00:00Z",
+      summary: { contradictions: 1, duplicates: 0, staleMemories: 0, orphans: 0 },
+    };
+    const output = formatMemoryLintReport(report);
+    expect(output).toContain("Contradictions (1)");
+    expect(output).toContain("90/100");
+  });
+
+  it("summarizes stale when count > 5", () => {
+    const staleFindings = Array.from({ length: 10 }, (_, i) => ({
+      check: "stale" as const,
+      severity: "info" as const,
+      detail: `${100 + i}d old`,
+      memoryIds: [`stale${i}`],
+    }));
+    const report: MemoryLintReport = {
+      findings: staleFindings,
+      healthScore: 95,
+      totalScanned: 200,
+      timestamp: "2026-04-08T12:00:00Z",
+      summary: { contradictions: 0, duplicates: 0, staleMemories: 10, orphans: 0 },
+    };
+    const output = formatMemoryLintReport(report);
+    expect(output).toContain("Stale (10)");
+    expect(output).toContain("10 memories not accessed");
+  });
+});