recallnest 2.3.0 → 2.6.0

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

@@ -0,0 +1,282 @@
+import { describe, expect, it } from "bun:test";
+
+import {
+  buildStructuredMemoryBoundary,
+  buildDefaultCanonicalKey,
+  extractBoundaryMetadata,
+  extractMemoryProvenance,
+  extractPromotedFrom,
+  extractProvenanceHistory,
+  extractProvenanceHistoryCount,
+  resolveIngestBoundary,
+  shouldUseStableMemoryResult,
+} from "../memory-boundaries.js";
+
+describe("memory boundaries", () => {
+  it("downgrades transcript-derived profile facts into evidence events", () => {
+    const resolved = resolveIngestBoundary({
+      source: "cc",
+      scope: "cc:abc123",
+      category: "profile",
+    });
+
+    expect(resolved.category).toBe("events");
+    expect(resolved.boundary.layer).toBe("evidence");
+    expect(resolved.boundary.authority).toBe("transcript-ingest");
+    expect(resolved.boundary.downgradedFrom).toBe("profile");
+  });
+
+  // 端清单回归：memory-boundaries.ts 的 TRANSCRIPT_SOURCES / TRANSCRIPT_SCOPE_PREFIXES
+  // 历史上漏过两次（kimi 2026-07-19 进栈、antigravity 07-29 进栈，都到 08-01 才发现）。
+  // 根因不是"忘了改"，是**没有断言**——纯判断步骤没有测试撑着就会被跳过。
+  // ⚠️ 接入新端时：先在下面的清单里加一行让测试变红，再去改常量把它变绿。
+  it.each([
+    ["cc", "cc:abc123"],
+    ["codex", "codex:abc123"],
+    ["gemini", "gemini:abc123"],
+    ["kimi", "kimi:abc123"],
+    ["antigravity", "antigravity:abc123"],
+    ["minis", "minis:abc123"],
+  ])("downgrades transcript profile facts for end %s", (source, scope) => {
+    const resolved = resolveIngestBoundary({ source, scope, category: "profile" });
+
+    expect(resolved.boundary.layer).toBe("evidence");
+    expect(resolved.boundary.authority).toBe("transcript-ingest");
+    expect(resolved.category).toBe("events");
+  });
+
+  // 反向断言：确认上面那组不是同义反复（如果任何 source 都被降权，那组测试就永远绿、
+  // 等于没测）。一个不在清单里的来源必须**不**被当成 transcript。
+  it("does not downgrade sources outside the transcript end list", () => {
+    const resolved = resolveIngestBoundary({
+      source: "manual",
+      scope: "memory:pivot",
+      category: "profile",
+    });
+
+    expect(resolved.boundary.layer).not.toBe("evidence");
+    expect(resolved.category).toBe("profile");
+  });
+
+  it("keeps transcript cases searchable but marks them as evidence", () => {
+    const resolved = resolveIngestBoundary({
+      source: "codex",
+      scope: "codex:session1",
+      category: "cases",
+    });
+
+    expect(resolved.category).toBe("cases");
+    expect(resolved.boundary.layer).toBe("evidence");
+    expect(resolved.boundary.authority).toBe("transcript-ingest");
+    expect(resolved.boundary.originalCategory).toBe("cases");
+  });
+
+  it("marks structured memory as durable authority", () => {
+    const boundary = buildStructuredMemoryBoundary("preferences");
+
+    expect(boundary).toEqual({
+      layer: "durable",
+      authority: "structured-memory",
+      conflictPolicy: "latest-wins",
+      originalCategory: "preferences",
+      note: "Structured memory writes are the durable source inside RecallNest.",
+    });
+  });
+
+  it("builds slot-aware canonical keys for atomic brand-item preferences", () => {
+    expect(buildDefaultCanonicalKey({
+      category: "preferences",
+      text: "我喜欢吃麦当劳的麦辣鸡翅",
+    })).toBe("preferences:brand-item:麦当劳:麦辣鸡翅");
+
+    expect(buildDefaultCanonicalKey({
+      category: "preferences",
+      text: "User prefers concise, direct replies.",
+    })).toBe("preferences:reply-style:concise:direct");
+
+    expect(buildDefaultCanonicalKey({
+      category: "preferences",
+      text: "Uses Bun over Node.",
+    })).toBe("preferences:tool-choice:bun:over:node");
+
+    expect(buildDefaultCanonicalKey({
+      category: "preferences",
+      text: "我喜欢吃麦当劳的麦旋风、板烧鸡腿堡和麦辣鸡翅",
+    })).toBe("preferences:我喜欢吃麦当劳的麦旋风-板烧鸡腿堡和麦辣鸡翅");
+  });
+
+  it("builds distinct canonical keys for different implicit-usage preferences (#6 regression)", () => {
+    // 修复前 implicit-usage slot 无专属分支，落到 tool-choice 三元支、preferredTool/avoidedTool
+    // 均 undefined → 全部坍缩成 'preferences:implicit-usage:over'，不同隐式偏好在 latest-wins
+    // 下互相覆盖丢数据。现在用 slot.subject 区分。
+    const figma = buildDefaultCanonicalKey({ category: "preferences", text: "I use Figma for design" });
+    const python = buildDefaultCanonicalKey({ category: "preferences", text: "I use Python for scripting" });
+    const sony = buildDefaultCanonicalKey({ category: "preferences", text: "我有一台索尼相机" });
+
+    expect(figma).toBe("preferences:implicit-usage:figma");
+    expect(python).toBe("preferences:implicit-usage:python");
+    expect(new Set([figma, python, sony]).size).toBe(3);
+  });
+
+  it("rejects transcript/evidence stable recall and keeps durable stable recall", () => {
+    expect(shouldUseStableMemoryResult({
+      category: "preferences",
+      scope: "cc:session",
+      metadata: JSON.stringify({
+        boundary: {
+          layer: "evidence",
+          authority: "transcript-ingest",
+          conflictPolicy: "append-only",
+        },
+      }),
+    })).toBe(false);
+
+    expect(shouldUseStableMemoryResult({
+      category: "preferences",
+      scope: "memory:agent",
+      metadata: JSON.stringify({
+        boundary: buildStructuredMemoryBoundary("preferences"),
+      }),
+    })).toBe(true);
+  });
+
+  it("parses valid boundary metadata and ignores malformed payloads", () => {
+    expect(extractBoundaryMetadata(JSON.stringify({
+      boundary: buildStructuredMemoryBoundary("patterns"),
+    }))).toEqual(buildStructuredMemoryBoundary("patterns"));
+
+    expect(extractBoundaryMetadata("{not-json")).toBeNull();
+    expect(extractBoundaryMetadata(JSON.stringify({
+      boundary: { layer: "durable", authority: "oops" },
+    }))).toBeNull();
+  });
+
+  it("extracts promotedFrom provenance and canonical keys", () => {
+    const metadata = JSON.stringify({
+      canonicalKey: "user-reply-style",
+      boundary: buildStructuredMemoryBoundary("preferences"),
+      promotedFrom: {
+        memoryId: "12345678-1234-1234-1234-123456789abc",
+        scope: "cc:session1",
+        category: "events",
+        source: "cc",
+        boundary: {
+          layer: "evidence",
+          authority: "transcript-ingest",
+          conflictPolicy: "append-only",
+          originalCategory: "preferences",
+        },
+      },
+    });
+
+    expect(extractPromotedFrom(metadata)).toEqual({
+      memoryId: "12345678-1234-1234-1234-123456789abc",
+      scope: "cc:session1",
+      category: "events",
+      source: "cc",
+      boundary: {
+        layer: "evidence",
+        authority: "transcript-ingest",
+        conflictPolicy: "append-only",
+        originalCategory: "preferences",
+      },
+    });
+
+    expect(extractProvenanceHistory(metadata)).toEqual([{
+      memoryId: "12345678-1234-1234-1234-123456789abc",
+      scope: "cc:session1",
+      category: "events",
+      source: "cc",
+      boundary: {
+        layer: "evidence",
+        authority: "transcript-ingest",
+        conflictPolicy: "append-only",
+        originalCategory: "preferences",
+      },
+    }]);
+    expect(extractProvenanceHistoryCount(metadata)).toBe(1);
+
+    expect(extractMemoryProvenance({
+      scope: "memory:agent",
+      metadata,
+    })).toEqual({
+      boundary: buildStructuredMemoryBoundary("preferences"),
+      canonicalKey: "user-reply-style",
+      promotedFrom: {
+        memoryId: "12345678-1234-1234-1234-123456789abc",
+        scope: "cc:session1",
+        category: "events",
+        source: "cc",
+        boundary: {
+          layer: "evidence",
+          authority: "transcript-ingest",
+          conflictPolicy: "append-only",
+          originalCategory: "preferences",
+        },
+      },
+      provenanceHistory: [{
+        memoryId: "12345678-1234-1234-1234-123456789abc",
+        scope: "cc:session1",
+        category: "events",
+        source: "cc",
+        boundary: {
+          layer: "evidence",
+          authority: "transcript-ingest",
+          conflictPolicy: "append-only",
+          originalCategory: "preferences",
+        },
+      }],
+      provenanceHistoryCount: 1,
+    });
+  });
+
+  it("prefers explicit provenance history over fallback promotedFrom metadata", () => {
+    const metadata = JSON.stringify({
+      canonicalKey: "preferences:brand-item:麦当劳:麦辣鸡翅",
+      boundary: buildStructuredMemoryBoundary("preferences"),
+      promotedFrom: {
+        memoryId: "12345678-1234-1234-1234-123456789abc",
+        scope: "cc:session1",
+        category: "events",
+        source: "cc",
+      },
+      provenanceHistory: [
+        {
+          memoryId: "aaaaaaaa-1234-1234-1234-123456789abc",
+          scope: "cc:session-food-1",
+          category: "events",
+          source: "cc",
+          observedAt: "2026-03-17T04:00:00.000Z",
+        },
+        {
+          memoryId: "bbbbbbbb-1234-1234-1234-123456789abc",
+          scope: "cc:session-food-2",
+          category: "events",
+          source: "codex",
+          observedAt: "2026-03-17T05:00:00.000Z",
+        },
+      ],
+      provenanceHistoryCount: 2,
+    });
+
+    expect(extractProvenanceHistory(metadata)).toEqual([
+      {
+        memoryId: "aaaaaaaa-1234-1234-1234-123456789abc",
+        scope: "cc:session-food-1",
+        category: "events",
+        source: "cc",
+        observedAt: "2026-03-17T04:00:00.000Z",
+        boundary: null,
+      },
+      {
+        memoryId: "bbbbbbbb-1234-1234-1234-123456789abc",
+        scope: "cc:session-food-2",
+        category: "events",
+        source: "codex",
+        observedAt: "2026-03-17T05:00:00.000Z",
+        boundary: null,
+      },
+    ]);
+    expect(extractProvenanceHistoryCount(metadata)).toBe(2);
+  });
+});

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