recallnest 2.2.1 → 2.5.4

package/src/__tests__/memory-health-rebalance.test.ts

@@ -0,0 +1,144 @@
+import { describe, expect, it } from "bun:test";
+
+import {
+  buildMemoryHealthRebalancePlan,
+  computeRebalancedImportance,
+  getMemoryHealthAccessCount,
+  getStoredMemoryTier,
+  parseMemoryHealthMetadata,
+  resolveRebalancedTier,
+  summarizeMemoryHealthPlans,
+} from "../memory-health-rebalance.js";
+
+const datasetStats = {
+  maxAccessCount: 19,
+  minTimestamp: Date.parse("2026-03-02T00:00:00.000Z"),
+  maxTimestamp: Date.parse("2026-03-19T00:00:00.000Z"),
+};
+
+describe("memory health rebalance", () => {
+  it("parses metadata safely and supports both accessCount key styles", () => {
+    expect(parseMemoryHealthMetadata("{")).toEqual({});
+    expect(getMemoryHealthAccessCount({ accessCount: 3 })).toBe(3);
+    expect(getMemoryHealthAccessCount({ access_count: 4 })).toBe(4);
+    expect(getStoredMemoryTier({ tier: "working" })).toBe("working");
+    expect(getStoredMemoryTier({ tier: "unknown" })).toBe("unknown");
+  });
+
+  it("demotes dead memories to peripheral even when they already had a hotter tier", () => {
+    const plan = buildMemoryHealthRebalancePlan({
+      id: "dead-memory",
+      importance: 0.8,
+      timestamp: datasetStats.minTimestamp,
+      metadata: JSON.stringify({ tier: "working", accessCount: 0 }),
+    }, datasetStats);
+
+    expect(resolveRebalancedTier("working", 0)).toBe("peripheral");
+    expect(plan.targetTier).toBe("peripheral");
+    expect(plan.deadMemoryRow).toBe(true);
+    expect(plan.deadMemoryDemoted).toBe(true);
+    expect(plan.nextImportance).toBeGreaterThanOrEqual(0.3);
+    expect(plan.nextImportance).toBeLessThanOrEqual(0.5);
+    expect(plan.nextMetadata.tier).toBe("peripheral");
+    expect(plan.nextMetadata.importance).toBe(plan.nextImportance);
+  });
+
+  it("backfills unknown tiers from access counts", () => {
+    const corePlan = buildMemoryHealthRebalancePlan({
+      id: "unknown-core",
+      importance: 0.7,
+      timestamp: datasetStats.maxTimestamp,
+      metadata: JSON.stringify({ accessCount: 6 }),
+    }, datasetStats);
+    const workingPlan = buildMemoryHealthRebalancePlan({
+      id: "unknown-working",
+      importance: 0.7,
+      timestamp: datasetStats.maxTimestamp,
+      metadata: JSON.stringify({ accessCount: 3 }),
+    }, datasetStats);
+
+    expect(corePlan.currentTier).toBe("unknown");
+    expect(corePlan.targetTier).toBe("core");
+    expect(corePlan.tierBackfilled).toBe(true);
+    expect(corePlan.nextImportance).toBeGreaterThanOrEqual(0.85);
+    expect(corePlan.nextImportance).toBeLessThanOrEqual(0.95);
+
+    expect(workingPlan.targetTier).toBe("working");
+    expect(workingPlan.nextImportance).toBeGreaterThanOrEqual(0.6);
+    expect(workingPlan.nextImportance).toBeLessThanOrEqual(0.8);
+  });
+
+  it("keeps existing non-dead tiers and only reshapes importance within the tier band", () => {
+    const lowPlan = buildMemoryHealthRebalancePlan({
+      id: "working-low",
+      importance: 0.6,
+      timestamp: datasetStats.minTimestamp,
+      metadata: JSON.stringify({ tier: "working", accessCount: 2 }),
+    }, datasetStats);
+    const highPlan = buildMemoryHealthRebalancePlan({
+      id: "working-high",
+      importance: 0.8,
+      timestamp: datasetStats.maxTimestamp,
+      metadata: JSON.stringify({ tier: "working", accessCount: 5 }),
+    }, datasetStats);
+
+    expect(lowPlan.targetTier).toBe("working");
+    expect(highPlan.targetTier).toBe("working");
+    expect(lowPlan.nextImportance).toBeLessThan(highPlan.nextImportance);
+    expect(lowPlan.nextImportance).toBeGreaterThanOrEqual(0.6);
+    expect(highPlan.nextImportance).toBeLessThanOrEqual(0.8);
+  });
+
+  it("uses access_count and existing importance together instead of hard-overwriting values", () => {
+    const cooler = computeRebalancedImportance(0.6, "core", 6, 19, 0.2);
+    const hotter = computeRebalancedImportance(0.9, "core", 19, 19, 0.9);
+
+    expect(cooler).toBeGreaterThanOrEqual(0.85);
+    expect(hotter).toBeLessThanOrEqual(0.95);
+    expect(hotter).toBeGreaterThan(cooler);
+  });
+
+  it("uses recency to spread dead peripheral memories within the peripheral band", () => {
+    const older = buildMemoryHealthRebalancePlan({
+      id: "dead-old",
+      importance: 0.35,
+      timestamp: datasetStats.minTimestamp,
+      metadata: JSON.stringify({ accessCount: 0 }),
+    }, datasetStats);
+    const newer = buildMemoryHealthRebalancePlan({
+      id: "dead-new",
+      importance: 0.35,
+      timestamp: datasetStats.maxTimestamp,
+      metadata: JSON.stringify({ accessCount: 0 }),
+    }, datasetStats);
+
+    expect(older.targetTier).toBe("peripheral");
+    expect(newer.targetTier).toBe("peripheral");
+    expect(older.nextImportance).toBeGreaterThanOrEqual(0.3);
+    expect(newer.nextImportance).toBeLessThanOrEqual(0.5);
+    expect(newer.nextImportance).toBeGreaterThan(older.nextImportance);
+  });
+
+  it("summarizes rebalance plans for reporting", () => {
+    const summary = summarizeMemoryHealthPlans([
+      buildMemoryHealthRebalancePlan({
+        id: "a",
+        importance: 0.7,
+        timestamp: datasetStats.minTimestamp,
+        metadata: JSON.stringify({ accessCount: 0 }),
+      }, datasetStats),
+      buildMemoryHealthRebalancePlan({
+        id: "b",
+        importance: 0.7,
+        timestamp: datasetStats.maxTimestamp,
+        metadata: JSON.stringify({ tier: "working", accessCount: 4 }),
+      }, datasetStats),
+    ]);
+
+    expect(summary.totalRows).toBe(2);
+    expect(summary.changedRows).toBe(2);
+    expect(summary.deadMemoryRows).toBe(1);
+    expect(summary.tierBackfills).toBe(1);
+    expect(summary.importanceChanges).toBe(2);
+  });
+});

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

@@ -0,0 +1,421 @@
+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" | "getVectors"> {
+  return {
+    // 复刻真实 store:list() 为性能不返回向量(vector: []),lint 需经 getVectors 补回。
+    // 旧 mock 直接返回带向量的 entry,与生产行为不符,曾掩盖矛盾/去重在生产哑火的 bug。
+    async list() { return entries.map(e => ({ ...e, vector: [] })); },
+    async getVectors(ids: string[]) {
+      const map = new Map<string, number[]>();
+      for (const e of entries) {
+        if (ids.includes(e.id) && e.vector.length > 0) map.set(e.id, e.vector);
+      }
+      return map;
+    },
+  } as Pick<MemoryStore, "list" | "getVectors">;
+}
+
+// ---------------------------------------------------------------------------
+// Cold memories (P0 B-1 observation)
+// ---------------------------------------------------------------------------
+
+describe("cold memory lint (P0 B-1)", () => {
+  it("aggregates cold memories into a single info finding with top ids (flag on)", async () => {
+    process.env.RECALLNEST_CONSTRUCTIVE_RETRIEVAL = "true";
+    try {
+    const coldMeta = (n: number) => JSON.stringify({
+      accessCount: n,
+      evolution: { status: "active", version: 1 },
+    });
+    // 向量彼此正交、文本不同,避免触发 duplicate/contradiction 干扰
+    const entries = [
+      makeEntry({ id: "cold-a", text: "alpha topic", vector: [1, 0, 0, 0, 0], metadata: coldMeta(12) }),
+      makeEntry({ id: "cold-b", text: "beta topic", vector: [0, 1, 0, 0, 0], metadata: coldMeta(7) }),
+      makeEntry({ id: "warm-c", text: "gamma topic", vector: [0, 0, 1, 0, 0], metadata: JSON.stringify({ accessCount: 9, usage: { useCount: 2 }, evolution: { status: "active", version: 1 } }) }),
+    ];
+
+    const report = await runMemoryLint({ store: createMockStore(entries) as MemoryStore });
+
+    expect(report.summary.coldMemories).toBe(2);
+    const finding = report.findings.find(f => f.check === "coldMemory");
+    expect(finding).toBeTruthy();
+    expect(finding!.severity).toBe("info");
+    // top ids sorted by injection desc
+    expect(finding!.memoryIds[0]).toBe("cold-a");
+    expect(finding!.memoryIds).toContain("cold-b");
+    expect(formatMemoryLintReport(report)).toContain("Cold Memories (2)");
+    } finally {
+      delete process.env.RECALLNEST_CONSTRUCTIVE_RETRIEVAL;
+    }
+  });
+
+  it("skips cold detection entirely when use signal is inactive (flag off)", async () => {
+    delete process.env.RECALLNEST_CONSTRUCTIVE_RETRIEVAL;
+    const coldishMeta = JSON.stringify({ accessCount: 12, evolution: { status: "active", version: 1 } });
+    const report = await runMemoryLint({
+      store: createMockStore([makeEntry({ id: "a", text: "alpha", metadata: coldishMeta })]) as MemoryStore,
+    });
+    expect(report.summary.coldMemories).toBe(0);
+    expect(report.findings.find(f => f.check === "coldMemory")).toBeUndefined();
+  });
+
+  it("health score dents only when cold share exceeds 10%, capped at 10", () => {
+    const base = { contradictions: 0, duplicates: 0, staleMemories: 0, orphans: 0, weakLessons: 0 };
+    // 5% cold -> no penalty
+    expect(computeHealthScore({ ...base, coldMemories: 5 }, 100)).toBe(100);
+    // 15% cold -> floor(15-10)=5 penalty
+    expect(computeHealthScore({ ...base, coldMemories: 15 }, 100)).toBe(95);
+    // 60% cold -> capped at 10
+    expect(computeHealthScore({ ...base, coldMemories: 60 }, 100)).toBe(90);
+    // backward compat: summary without coldMemories
+    expect(computeHealthScore(base, 100)).toBe(100);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 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);
+  });
+
+  // ---- Weak lessons (action-verb heuristic, inspired by Orb) ----------------
+
+  it("flags patterns without any action verb as weak lessons", async () => {
+    const entries = [
+      makeEntry({
+        id: "wl1",
+        text: "This phenomenon is very interesting and noteworthy",
+        category: "patterns",
+        scope: "project:x",
+        vector: [1, 0, 0, 0, 0],
+      }),
+    ];
+    const store = createMockStore(entries);
+    const report = await runMemoryLint({ store });
+
+    expect(report.summary.weakLessons).toBe(1);
+    const finding = report.findings.find(f => f.check === "weakLesson");
+    expect(finding).toBeDefined();
+    expect(finding!.severity).toBe("info");
+    expect(finding!.memoryIds).toContain("wl1");
+  });
+
+  it("does not flag patterns that contain action verbs (English or Chinese)", async () => {
+    const entries = [
+      makeEntry({
+        id: "wl2",
+        text: "Use Bun to run scripts; verify output before committing",
+        category: "patterns",
+        scope: "project:x",
+        vector: [1, 0, 0, 0, 0],
+      }),
+      makeEntry({
+        id: "wl3",
+        text: "使用 playwright 验证网页交互,失败时重试最多三次",
+        category: "patterns",
+        scope: "project:x",
+        vector: [0, 1, 0, 0, 0],
+      }),
+    ];
+    const store = createMockStore(entries);
+    const report = await runMemoryLint({ store });
+
+    expect(report.summary.weakLessons).toBe(0);
+  });
+
+  it("does not flag non-pattern categories for weak lessons (events/profile exempt)", async () => {
+    const entries = [
+      makeEntry({
+        id: "wl4",
+        text: "This phenomenon is interesting",  // no verb, but not a pattern
+        category: "events",
+        scope: "project:x",
+        vector: [1, 0, 0, 0, 0],
+      }),
+      makeEntry({
+        id: "wl5",
+        text: "User background info without verbs",
+        category: "profile",
+        scope: "project:x",
+        vector: [0, 1, 0, 0, 0],
+      }),
+    ];
+    const store = createMockStore(entries);
+    const report = await runMemoryLint({ store });
+
+    expect(report.summary.weakLessons).toBe(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, weakLessons: 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, weakLessons: 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, weakLessons: 0 },
+    };
+    const output = formatMemoryLintReport(report);
+    expect(output).toContain("Stale (10)");
+    expect(output).toContain("10 memories not accessed");
+  });
+
+  it("renders weak lessons section when present", () => {
+    const report: MemoryLintReport = {
+      findings: [
+        { check: "weakLesson", severity: "info", detail: 'Pattern without action verbs: "X is Y"', memoryIds: ["wl1"] },
+        { check: "weakLesson", severity: "info", detail: 'Pattern without action verbs: "abstract note"', memoryIds: ["wl2"] },
+      ],
+      healthScore: 96,
+      totalScanned: 10,
+      timestamp: "2026-04-16T12:00:00Z",
+      summary: { contradictions: 0, duplicates: 0, staleMemories: 0, orphans: 0, weakLessons: 2 },
+    };
+    const output = formatMemoryLintReport(report);
+    expect(output).toContain("Weak Lessons (2)");
+    expect(output).toContain("96/100");
+  });
+});