recallnest 1.4.1 → 2.2.1

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

@@ -1,144 +0,0 @@
-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-output.test.ts

@@ -1,215 +0,0 @@
-import { describe, expect, it } from "bun:test";
-
-import { formatExplainResults, formatSearchResults } from "../memory-output.js";
-import type { RetrievalResult } from "../retriever.js";
-
-function buildResult(id: string, metadata: Record<string, unknown>): RetrievalResult {
-  return {
-    entry: {
-      id,
-      text: "User prefers concise, direct replies.",
-      vector: [],
-      category: "preferences",
-      scope: "memory:agent",
-      importance: 0.8,
-      timestamp: Date.parse("2026-03-16T00:00:00.000Z"),
-      metadata: JSON.stringify(metadata),
-    },
-    score: 0.91,
-    sources: {
-      vector: { score: 0.9, rank: 1 },
-      bm25: { score: 0.8, rank: 2 },
-      fused: { score: 0.91 },
-    },
-  };
-}
-
-describe("memory output", () => {
-  it("includes provenance in search results", () => {
-    const output = formatSearchResults([
-      buildResult("abcd1234-0000-0000-0000-000000000001", {
-        source: "agent",
-        canonicalKey: "user-reply-style",
-        boundary: {
-          layer: "durable",
-          authority: "structured-memory",
-          conflictPolicy: "latest-wins",
-          originalCategory: "preferences",
-        },
-        promotedFrom: {
-          memoryId: "feedface-0000-0000-0000-000000000001",
-          scope: "cc:session1",
-          category: "events",
-          boundary: {
-            layer: "evidence",
-            authority: "transcript-ingest",
-            conflictPolicy: "append-only",
-            originalCategory: "preferences",
-          },
-        },
-        provenanceHistory: [
-          {
-            memoryId: "feedface-0000-0000-0000-000000000001",
-            scope: "cc:session1",
-            category: "events",
-            source: "cc",
-          },
-          {
-            memoryId: "deadbeef-0000-0000-0000-000000000002",
-            scope: "cc:session2",
-            category: "events",
-            source: "cc",
-            observedAt: "2026-03-17T04:30:00.000Z",
-            boundary: {
-              layer: "evidence",
-              authority: "transcript-ingest",
-              conflictPolicy: "append-only",
-              originalCategory: "preferences",
-            },
-          },
-        ],
-        provenanceHistoryCount: 2,
-        preferenceSlot: {
-          type: "brand-item",
-          brand: "麦当劳",
-          item: "麦辣鸡翅",
-        },
-      }),
-    ], {
-      query: "reply style",
-      profile: "default",
-    });
-
-    expect(output).toContain("prov : durable/structured-memory");
-    expect(output).toContain("key:user-reply-style");
-    expect(output).toContain("promoted:feedface<-evidence/transcript-ingest");
-    expect(output).toContain("history:2");
-    expect(output).toContain("observed:deadbeef@2026-03-17");
-    expect(output).toContain("slot:brand-item:麦当劳:麦辣鸡翅");
-  });
-
-  it("includes provenance in explain results", () => {
-    const output = formatExplainResults([
-      buildResult("abcd1234-0000-0000-0000-000000000001", {
-        source: "cc",
-        boundary: {
-          layer: "evidence",
-          authority: "transcript-ingest",
-          conflictPolicy: "append-only",
-          originalCategory: "preferences",
-          downgradedFrom: "preferences",
-        },
-      }),
-    ], {
-      query: "reply style",
-      profile: "writing",
-    });
-
-    expect(output).toContain("prov    : evidence/transcript-ingest");
-    expect(output).toContain("downgraded:preferences");
-  });
-
-  it("renders reply-style slots in provenance summaries", () => {
-    const output = formatSearchResults([
-      buildResult("abcd1234-0000-0000-0000-000000000002", {
-        source: "agent",
-        canonicalKey: "preferences:reply-style:concise:direct",
-        boundary: {
-          layer: "durable",
-          authority: "structured-memory",
-          conflictPolicy: "latest-wins",
-          originalCategory: "preferences",
-        },
-        preferenceSlot: {
-          type: "reply-style",
-          traits: ["concise", "direct"],
-        },
-      }),
-    ], {
-      query: "reply style",
-      profile: "default",
-    });
-
-    expect(output).toContain("slot:reply-style:concise:direct");
-  });
-
-  it("renders tool-choice slots in provenance summaries", () => {
-    const output = formatSearchResults([
-      buildResult("abcd1234-0000-0000-0000-000000000003", {
-        source: "agent",
-        canonicalKey: "preferences:tool-choice:bun:over:node",
-        boundary: {
-          layer: "durable",
-          authority: "structured-memory",
-          conflictPolicy: "latest-wins",
-          originalCategory: "preferences",
-        },
-        preferenceSlot: {
-          type: "tool-choice",
-          preferredTool: "bun",
-          avoidedTool: "node",
-        },
-      }),
-    ], {
-      query: "tool choice",
-      profile: "default",
-    });
-
-    expect(output).toContain("slot:tool-choice:bun:over:node");
-  });
-
-  it("does not render slot provenance for plain preferences canonical keys", () => {
-    const output = formatSearchResults([
-      buildResult("abcd1234-0000-0000-0000-000000000004", {
-        source: "agent",
-        canonicalKey: "preferences:这段文案简洁直接-先别改",
-        boundary: {
-          layer: "durable",
-          authority: "structured-memory",
-          conflictPolicy: "latest-wins",
-          originalCategory: "preferences",
-        },
-      }),
-      buildResult("abcd1234-0000-0000-0000-000000000005", {
-        source: "agent",
-        canonicalKey: "preferences:文档里写了-uses-bun-over-node-的迁移说明",
-        boundary: {
-          layer: "durable",
-          authority: "structured-memory",
-          conflictPolicy: "latest-wins",
-          originalCategory: "preferences",
-        },
-      }),
-    ], {
-      query: "preferences",
-      profile: "default",
-    });
-
-    expect(output).toContain("key:preferences:这段文案简洁直接-先别改");
-    expect(output).toContain("key:preferences:文档里写了-uses-bun-over-node-的迁移说明");
-    expect(output).not.toContain("slot:reply-style:");
-    expect(output).not.toContain("slot:tool-choice:");
-  });
-
-  it("does not render slot provenance in explain output for plain preferences canonical keys", () => {
-    const output = formatExplainResults([
-      buildResult("abcd1234-0000-0000-0000-000000000006", {
-        source: "agent",
-        canonicalKey: "preferences:这段文案简洁直接-先别改",
-        boundary: {
-          layer: "durable",
-          authority: "structured-memory",
-          conflictPolicy: "latest-wins",
-          originalCategory: "preferences",
-        },
-      }),
-    ], {
-      query: "draft note",
-      profile: "default",
-    });
-
-    expect(output).toContain("key:preferences:这段文案简洁直接-先别改");
-    expect(output).not.toContain("slot:reply-style:");
-    expect(output).not.toContain("slot:tool-choice:");
-  });
-});

package/src/__tests__/multi-vector.test.ts

@@ -1,242 +0,0 @@
-import { describe, expect, it, beforeEach, afterEach } from "bun:test";
-
-import {
-  blendMultiVectorScores,
-  cosineSimilarity,
-  DEFAULT_BLEND_CONFIG,
-  embedMultiVector,
-  extractMultiVectorText,
-  isMultiVectorEnabled,
-  tokenize,
-  textOverlapScore,
-  adaptiveBlendConfig,
-} from "../multi-vector.js";
-
-describe("isMultiVectorEnabled", () => {
-  const original = process.env.RECALLNEST_MULTI_VECTOR;
-
-  afterEach(() => {
-    if (original === undefined) {
-      delete process.env.RECALLNEST_MULTI_VECTOR;
-    } else {
-      process.env.RECALLNEST_MULTI_VECTOR = original;
-    }
-  });
-
-  it("returns false by default", () => {
-    delete process.env.RECALLNEST_MULTI_VECTOR;
-    expect(isMultiVectorEnabled()).toBe(false);
-  });
-
-  it("returns true when set to 'true'", () => {
-    process.env.RECALLNEST_MULTI_VECTOR = "true";
-    expect(isMultiVectorEnabled()).toBe(true);
-  });
-});
-
-describe("extractMultiVectorText", () => {
-  it("extracts L0 and L1 from valid metadata", () => {
-    const meta = JSON.stringify({
-      l0_abstract: "User prefers TypeScript",
-      l1_overview: "User consistently chooses TypeScript over JavaScript for type safety",
-    });
-    const result = extractMultiVectorText(meta);
-    expect(result.l0).toBe("User prefers TypeScript");
-    expect(result.l1).toContain("TypeScript");
-  });
-
-  it("returns empty for missing fields", () => {
-    const meta = JSON.stringify({ source: "manual" });
-    const result = extractMultiVectorText(meta);
-    expect(result.l0).toBeUndefined();
-    expect(result.l1).toBeUndefined();
-  });
-
-  it("returns empty for undefined metadata", () => {
-    const result = extractMultiVectorText(undefined);
-    expect(result.l0).toBeUndefined();
-  });
-
-  it("skips very short L0/L1 text (<=5 chars)", () => {
-    const meta = JSON.stringify({ l0_abstract: "abc", l1_overview: "short" });
-    const result = extractMultiVectorText(meta);
-    expect(result.l0).toBeUndefined();
-    expect(result.l1).toBeUndefined();
-  });
-});
-
-describe("embedMultiVector", () => {
-  const mockEmbedder = {
-    async embedPassage(text: string) {
-      return [text.length, 0.5, 0.1];
-    },
-  };
-
-  it("returns null vectors when disabled", async () => {
-    delete process.env.RECALLNEST_MULTI_VECTOR;
-    const result = await embedMultiVector(mockEmbedder, JSON.stringify({
-      l0_abstract: "Some abstract text here",
-    }));
-    expect(result.vector_l0).toBeNull();
-    expect(result.vector_l1).toBeNull();
-  });
-
-  it("generates vectors when enabled and text available", async () => {
-    process.env.RECALLNEST_MULTI_VECTOR = "true";
-    const result = await embedMultiVector(mockEmbedder, JSON.stringify({
-      l0_abstract: "User prefers TypeScript",
-      l1_overview: "Detailed overview of TypeScript preference with reasoning",
-    }));
-    expect(result.vector_l0).not.toBeNull();
-    expect(result.vector_l1).not.toBeNull();
-    expect(result.vector_l0![0]).toBe("User prefers TypeScript".length);
-    // Cleanup
-    delete process.env.RECALLNEST_MULTI_VECTOR;
-  });
-
-  it("returns null for missing L0/L1 text even when enabled", async () => {
-    process.env.RECALLNEST_MULTI_VECTOR = "true";
-    const result = await embedMultiVector(mockEmbedder, JSON.stringify({ source: "manual" }));
-    expect(result.vector_l0).toBeNull();
-    expect(result.vector_l1).toBeNull();
-    delete process.env.RECALLNEST_MULTI_VECTOR;
-  });
-});
-
-describe("blendMultiVectorScores", () => {
-  it("returns main score when no L0/L1 available", () => {
-    expect(blendMultiVectorScores(0.8, null, null)).toBe(0.8);
-  });
-
-  it("blends with L0 only", () => {
-    const blended = blendMultiVectorScores(0.8, 0.9, null);
-    // (0.8 * 0.65 + 0.9 * 0.20) / (0.65 + 0.20) = (0.52 + 0.18) / 0.85
-    expect(blended).toBeCloseTo(0.824, 2);
-  });
-
-  it("blends with both L0 and L1", () => {
-    const blended = blendMultiVectorScores(0.8, 0.9, 0.7);
-    // (0.8*0.65 + 0.9*0.20 + 0.7*0.15) / (0.65+0.20+0.15) = (0.52+0.18+0.105)/1.0
-    expect(blended).toBeCloseTo(0.805, 2);
-  });
-
-  it("supports custom weights", () => {
-    const config = { vectorWeight: 0.5, l0Weight: 0.3, l1Weight: 0.2 };
-    const blended = blendMultiVectorScores(0.8, 0.9, 0.7, config);
-    expect(blended).toBeCloseTo(0.81, 2);
-  });
-});
-
-describe("cosineSimilarity", () => {
-  it("returns 1 for identical vectors", () => {
-    expect(cosineSimilarity([1, 0, 0], [1, 0, 0])).toBeCloseTo(1.0, 5);
-  });
-
-  it("returns 0 for orthogonal vectors", () => {
-    expect(cosineSimilarity([1, 0, 0], [0, 1, 0])).toBeCloseTo(0.0, 5);
-  });
-
-  it("returns -1 for opposite vectors", () => {
-    expect(cosineSimilarity([1, 0, 0], [-1, 0, 0])).toBeCloseTo(-1.0, 5);
-  });
-
-  it("returns 0 for empty vectors", () => {
-    expect(cosineSimilarity([], [])).toBe(0);
-  });
-
-  it("returns 0 for mismatched dimensions", () => {
-    expect(cosineSimilarity([1, 0], [1, 0, 0])).toBe(0);
-  });
-});
-
-// ===========================================================================
-// Tier 4.3: Text-overlap multi-vector scoring
-// ===========================================================================
-
-describe("tokenize", () => {
-  it("tokenizes English text, removes stop words", () => {
-    const tokens = tokenize("The user prefers TypeScript for projects");
-    expect(tokens).toContain("user");
-    expect(tokens).toContain("prefers");
-    expect(tokens).toContain("typescript");
-    expect(tokens).toContain("projects");
-    expect(tokens).not.toContain("the");
-    expect(tokens).not.toContain("for");
-  });
-
-  it("tokenizes Chinese text into unigrams, removes stop words", () => {
-    const tokens = tokenize("用户喜欢使用TypeScript编程");
-    expect(tokens).toContain("用");
-    expect(tokens).toContain("户");
-    expect(tokens).toContain("喜");
-    expect(tokens).toContain("欢");
-    expect(tokens).toContain("typescript");
-    expect(tokens).not.toContain("的");
-  });
-
-  it("handles mixed CJK and English", () => {
-    const tokens = tokenize("RecallNest 记忆服务 is great");
-    expect(tokens).toContain("recallnest");
-    expect(tokens).toContain("记");
-    expect(tokens).toContain("忆");
-    expect(tokens).toContain("服");
-    expect(tokens).toContain("务");
-    expect(tokens).toContain("great");
-  });
-
-  it("returns empty for empty/whitespace input", () => {
-    expect(tokenize("")).toEqual([]);
-    expect(tokenize("   ")).toEqual([]);
-  });
-});
-
-describe("textOverlapScore", () => {
-  it("returns 1.0 when query fully matches a concise abstract", () => {
-    const score = textOverlapScore("TypeScript preference", "TypeScript preference");
-    expect(score).toBeGreaterThan(0.8);
-  });
-
-  it("returns higher score for L0 abstract than L2 full text on topic query", () => {
-    const query = "TypeScript projects";
-    const l0 = "User prefers TypeScript for all projects";
-    const l2 = "The user mentioned that they have been working with React and JavaScript for three years. They recently started using TypeScript for their projects because of type safety. They also mentioned Python for data science work.";
-
-    const l0Score = textOverlapScore(query, l0);
-    const l2Score = textOverlapScore(query, l2);
-    expect(l0Score).toBeGreaterThan(l2Score);
-  });
-
-  it("returns 0 for completely unrelated texts", () => {
-    const score = textOverlapScore("TypeScript projects", "天气很好适合出去玩");
-    expect(score).toBe(0);
-  });
-
-  it("returns 0 for empty query", () => {
-    expect(textOverlapScore("", "some text")).toBe(0);
-  });
-
-  it("returns 0 for empty candidate", () => {
-    expect(textOverlapScore("some query", "")).toBe(0);
-  });
-});
-
-describe("adaptiveBlendConfig", () => {
-  it("boosts L0/L1 for short queries (≤3 tokens)", () => {
-    const config = adaptiveBlendConfig(2);
-    expect(config.l0Weight).toBe(0.25);
-    expect(config.l1Weight).toBe(0.25);
-    expect(config.vectorWeight).toBe(0.50);
-  });
-
-  it("uses default for medium queries (4-10 tokens)", () => {
-    const config = adaptiveBlendConfig(7);
-    expect(config).toEqual(DEFAULT_BLEND_CONFIG);
-  });
-
-  it("favors L2 for long queries (>10 tokens)", () => {
-    const config = adaptiveBlendConfig(15);
-    expect(config.vectorWeight).toBe(0.80);
-    expect(config.l0Weight).toBe(0.10);
-    expect(config.l1Weight).toBe(0.10);
-  });
-});