recallnest 2.3.0 → 2.5.4

package/src/__tests__/drill-down.test.ts

@@ -0,0 +1,108 @@
+import { describe, it, expect } from "bun:test";
+
+describe("Tiered storage: L0/L1/L2 metadata parsing", () => {
+  it("parses L0/L1/L2 from metadata JSON", () => {
+    const metadata = JSON.stringify({
+      l0_abstract: "User prefers TypeScript",
+      l1_overview: "User consistently chooses TypeScript over JavaScript for new projects, citing type safety.",
+      l2_content: "Full detailed content here...",
+    });
+    const parsed = JSON.parse(metadata);
+    expect(parsed.l0_abstract).toBe("User prefers TypeScript");
+    expect(parsed.l1_overview.length).toBeGreaterThan(parsed.l0_abstract.length);
+  });
+
+  it("handles missing L0/L1 fields gracefully", () => {
+    const metadata = JSON.stringify({ accessCount: 5 });
+    const parsed = JSON.parse(metadata);
+    expect(parsed.l0_abstract).toBeUndefined();
+    expect(parsed.l1_overview).toBeUndefined();
+  });
+
+  it("handles malformed metadata JSON", () => {
+    const metadata = "not-json";
+    let parsed = null;
+    try {
+      parsed = JSON.parse(metadata);
+    } catch {
+      // Expected
+    }
+    expect(parsed).toBeNull();
+  });
+});
+
+describe("Tiered storage: drill-down level selection", () => {
+  it("overview level returns L1 when available", () => {
+    const meta = {
+      l0_abstract: "Short summary",
+      l1_overview: "Detailed overview with context and reasoning",
+    };
+    const fullText = "Very long full text content...";
+    const level = "overview";
+
+    const result = level === "overview" && meta.l1_overview
+      ? meta.l1_overview
+      : fullText;
+
+    expect(result).toBe(meta.l1_overview);
+  });
+
+  it("overview level falls back to full text when L1 missing", () => {
+    const meta: Record<string, string> = { l0_abstract: "Short summary" };
+    const fullText = "Very long full text content...";
+    const level = "overview";
+
+    const result = level === "overview" && meta.l1_overview
+      ? meta.l1_overview
+      : fullText;
+
+    expect(result).toBe(fullText);
+  });
+
+  it("full level always returns full text", () => {
+    const meta = {
+      l0_abstract: "Short summary",
+      l1_overview: "Detailed overview",
+    };
+    const fullText = "Very long full text content...";
+    const level = "full";
+
+    const result = level === "full" ? fullText : meta.l1_overview || fullText;
+    expect(result).toBe(fullText);
+  });
+});
+
+describe("Tiered storage: recallDepthDefault config", () => {
+  it("accepts valid depth values", () => {
+    for (const depth of ["l0", "l1", "full"]) {
+      expect(["l0", "l1", "full"].includes(depth)).toBe(true);
+    }
+  });
+
+  it("rejects invalid depth values", () => {
+    for (const depth of ["l3", "summary", "compact"]) {
+      expect(["l0", "l1", "full"].includes(depth)).toBe(false);
+    }
+  });
+
+  it("defaults to full when not set (backward compat)", () => {
+    const configValue = undefined;
+    const resolved = configValue || "full";
+    expect(resolved).toBe("full");
+  });
+});
+
+describe("Tiered storage: L0 injection format", () => {
+  it("L0 abstract is compact enough for context injection", () => {
+    const l0 = "User prefers TypeScript for all new projects";
+    // L0 should be under 100 tokens (~400 chars)
+    expect(l0.length).toBeLessThan(400);
+  });
+
+  it("L1 overview provides medium detail", () => {
+    const l1 = "## Preference\nUser consistently chooses TypeScript over JavaScript. Cited reasons: type safety, better IDE support, easier refactoring.";
+    // L1 should be under 500 tokens (~2000 chars)
+    expect(l1.length).toBeLessThan(2000);
+    expect(l1.length).toBeGreaterThan(50);
+  });
+});

package/src/__tests__/embedder.test.ts

@@ -0,0 +1,122 @@
+import { describe, expect, it } from "bun:test";
+
+import { Embedder } from "../embedder.js";
+
+describe("Embedder transient retry", () => {
+  it("retries a transient single-embedding connection error", async () => {
+    const embedder = new Embedder({
+      provider: "openai-compatible",
+      apiKey: "test-key",
+      model: "text-embedding-3-small",
+      dimensions: 3,
+    });
+
+    let calls = 0;
+    (embedder as any).client = {
+      embeddings: {
+        create: async () => {
+          calls += 1;
+          if (calls === 1) {
+            throw new Error("Connection error. ECONNRESET");
+          }
+          return {
+            data: [{ embedding: [1, 2, 3] }],
+          };
+        },
+      },
+    };
+
+    await expect(embedder.embedPassage("hello")).resolves.toEqual([1, 2, 3]);
+    expect(calls).toBe(2);
+  });
+
+  it("retries a transient batch embedding connection error", async () => {
+    const embedder = new Embedder({
+      provider: "openai-compatible",
+      apiKey: "test-key",
+      model: "text-embedding-3-small",
+      dimensions: 3,
+    });
+
+    let calls = 0;
+    (embedder as any).client = {
+      embeddings: {
+        create: async () => {
+          calls += 1;
+          if (calls === 1) {
+            throw new Error("The socket connection was closed unexpectedly. ECONNRESET");
+          }
+          return {
+            data: [
+              { embedding: [1, 2, 3] },
+              { embedding: [4, 5, 6] },
+            ],
+          };
+        },
+      },
+    };
+
+    await expect(embedder.embedBatchPassage(["a", "b"])).resolves.toEqual([
+      [1, 2, 3],
+      [4, 5, 6],
+    ]);
+    expect(calls).toBe(2);
+  });
+
+  it("does not retry non-transient embedding errors", async () => {
+    const embedder = new Embedder({
+      provider: "openai-compatible",
+      apiKey: "test-key",
+      model: "text-embedding-3-small",
+      dimensions: 3,
+    });
+
+    let calls = 0;
+    (embedder as any).client = {
+      embeddings: {
+        create: async () => {
+          calls += 1;
+          throw new Error("Authentication failed");
+        },
+      },
+    };
+
+    await expect(embedder.embedPassage("hello")).rejects.toThrow("Failed to generate embedding: Authentication failed");
+    expect(calls).toBe(1);
+  });
+
+  it("limits concurrent embedding requests", async () => {
+    const embedder = new Embedder({
+      provider: "openai-compatible",
+      apiKey: "test-key",
+      model: "text-embedding-3-small",
+      dimensions: 3,
+    });
+
+    (embedder as any)._maxConcurrentRequests = 1;
+
+    let inFlight = 0;
+    let maxInFlight = 0;
+    (embedder as any).client = {
+      embeddings: {
+        create: async () => {
+          inFlight += 1;
+          maxInFlight = Math.max(maxInFlight, inFlight);
+          await new Promise((resolve) => setTimeout(resolve, 20));
+          inFlight -= 1;
+          return {
+            data: [{ embedding: [1, 2, 3] }],
+          };
+        },
+      },
+    };
+
+    await Promise.all([
+      embedder.embedPassage("first"),
+      embedder.embedPassage("second"),
+      embedder.embedPassage("third"),
+    ]);
+
+    expect(maxInFlight).toBe(1);
+  });
+});

package/src/__tests__/emotion-decay.test.ts

@@ -0,0 +1,46 @@
+import { describe, test, expect } from "bun:test";
+import { weibullDecay, adjustHalfLifeForEmotion, computeArousalBoost } from "../decay-engine.js";
+
+describe("emotion-adjusted decay", () => {
+  test("returns base half-life when no emotion", () => {
+    expect(adjustHalfLifeForEmotion(60, undefined)).toBe(60);
+    expect(adjustHalfLifeForEmotion(60, null)).toBe(60);
+  });
+
+  test("strong negative emotion extends half-life ~27%", () => {
+    const adjusted = adjustHalfLifeForEmotion(60, { valence: -0.9, arousal: 0.5, label: "frustration" });
+    expect(adjusted).toBeCloseTo(60 * 1.27, 0);
+  });
+
+  test("strong positive emotion extends half-life ~24%", () => {
+    const adjusted = adjustHalfLifeForEmotion(60, { valence: 0.8, arousal: 0.3, label: "excitement" });
+    expect(adjusted).toBeCloseTo(60 * 1.24, 0);
+  });
+
+  test("neutral emotion has negligible effect", () => {
+    const adjusted = adjustHalfLifeForEmotion(60, { valence: 0.05, arousal: 0.1, label: "neutral" });
+    expect(adjusted).toBeCloseTo(60, 0);
+  });
+
+  test("emotional memory decays slower at 30 days", () => {
+    const baseHL = 60;
+    const emotionalHL = adjustHalfLifeForEmotion(baseHL, { valence: -0.8, arousal: 0.7, label: "frustration" });
+    const neutralDecay = weibullDecay(30, baseHL, "working");
+    const emotionalDecay = weibullDecay(30, emotionalHL, "working");
+    expect(emotionalDecay).toBeGreaterThan(neutralDecay);
+  });
+
+  test("arousal boost is 1.0 for zero arousal", () => {
+    expect(computeArousalBoost({ valence: 0.5, arousal: 0, label: "positive" })).toBe(1.0);
+  });
+
+  test("arousal boost max ~1.1 for high arousal", () => {
+    const boost = computeArousalBoost({ valence: 0.5, arousal: 0.9, label: "excitement" });
+    expect(boost).toBeCloseTo(1.09, 1);
+  });
+
+  test("arousal boost is 1.0 for null emotion", () => {
+    expect(computeArousalBoost(undefined)).toBe(1.0);
+    expect(computeArousalBoost(null)).toBe(1.0);
+  });
+});

package/src/__tests__/emotion-detector.test.ts

@@ -0,0 +1,56 @@
+import { describe, test, expect } from "bun:test";
+import { detectEmotion } from "../emotion-detector.js";
+
+describe("emotion-detector: heuristic", () => {
+  test("detects strong negative text", () => {
+    const result = detectEmotion("This bug is driving me crazy, everything is broken and wrong");
+    expect(result.valence).toBeLessThan(-0.3);
+    expect(result.label).toBe("negative");
+  });
+
+  test("detects strong positive text", () => {
+    const result = detectEmotion("Finally solved it! Works perfectly, great progress today");
+    expect(result.valence).toBeGreaterThan(0.3);
+    expect(result.label).toBe("positive");
+  });
+
+  test("detects neutral text", () => {
+    const result = detectEmotion("The user prefers dark mode and uses VS Code");
+    expect(Math.abs(result.valence)).toBeLessThan(0.3);
+    expect(result.label).toBe("neutral");
+  });
+
+  test("detects high arousal", () => {
+    const result = detectEmotion("URGENT! Critical production issue, fix immediately!");
+    expect(result.arousal).toBeGreaterThan(0.3);
+  });
+
+  test("detects low arousal for calm text", () => {
+    const result = detectEmotion("The default configuration uses port 3000");
+    expect(result.arousal).toBeLessThan(0.3);
+  });
+
+  test("handles mixed signals with net positive", () => {
+    const result = detectEmotion("Had a frustrating bug but finally solved it perfectly");
+    expect(result.valence).toBeGreaterThan(0);
+  });
+
+  test("handles empty text gracefully", () => {
+    const result = detectEmotion("");
+    expect(result.valence).toBe(0);
+    expect(result.arousal).toBe(0);
+    expect(result.label).toBe("neutral");
+  });
+
+  test("clamps valence to [-1, 1]", () => {
+    const result = detectEmotion("broken error wrong bug failure hate broken error wrong");
+    expect(result.valence).toBeGreaterThanOrEqual(-1);
+    expect(result.valence).toBeLessThanOrEqual(1);
+  });
+
+  test("clamps arousal to [0, 1]", () => {
+    const result = detectEmotion("URGENT! CRITICAL! IMMEDIATELY! ASAP!");
+    expect(result.arousal).toBeGreaterThanOrEqual(0);
+    expect(result.arousal).toBeLessThanOrEqual(1);
+  });
+});

package/src/__tests__/emotion-phase1-integration.test.ts

@@ -0,0 +1,153 @@
+/**
+ * Phase 1 integration tests: Emotional Valence in Decay pipeline.
+ *
+ * Validates the full wiring:
+ * 1. detectEmotion → salience + source fields
+ * 2. computeDecayScore → emotion-aware weights (0.15/0.25/0.45/0.15)
+ * 3. Backward compatibility when emotion flag is off or metadata absent
+ */
+import { describe, test, expect } from "bun:test";
+import { detectEmotion } from "../emotion-detector.js";
+import { computeDecayScore, type EvolutionMetadata } from "../memory-evolution.js";
+
+// ---------------------------------------------------------------------------
+// 1. detectEmotion: salience + source fields
+// ---------------------------------------------------------------------------
+
+describe("detectEmotion salience & source", () => {
+  test("returns salience field as (|valence| + arousal) / 2", () => {
+    const result = detectEmotion("Finally fixed that horrible production bug after 3 days!");
+    expect(result.salience).toBeDefined();
+    expect(typeof result.salience).toBe("number");
+    // salience = (|valence| + arousal) / 2
+    const expected = (Math.abs(result.valence) + result.arousal) / 2;
+    expect(result.salience).toBeCloseTo(expected, 5);
+  });
+
+  test("returns source: keyword", () => {
+    const result = detectEmotion("This is a great success!");
+    expect(result.source).toBe("keyword");
+  });
+
+  test("neutral text returns salience 0", () => {
+    const result = detectEmotion("The meeting is at 3pm tomorrow.");
+    expect(result.salience).toBe(0);
+  });
+
+  test("empty text returns salience 0 and source keyword", () => {
+    const result = detectEmotion("");
+    expect(result.salience).toBe(0);
+    expect(result.source).toBe("keyword");
+  });
+
+  test("high emotion + high arousal gives high salience", () => {
+    const result = detectEmotion("CRITICAL BUG! Everything is broken! Urgent fix needed!");
+    expect(result.salience).toBeGreaterThan(0.2);
+  });
+
+  test("salience is clamped to [0, 1]", () => {
+    const result = detectEmotion("fail fail fail broken broken crash crash urgent urgent critical critical !!!");
+    expect(result.salience).toBeGreaterThanOrEqual(0);
+    expect(result.salience).toBeLessThanOrEqual(1);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 2. computeDecayScore: emotion-aware weights
+// ---------------------------------------------------------------------------
+
+describe("computeDecayScore with emotion", () => {
+  const now = Date.now();
+  const baseEvo: EvolutionMetadata = {
+    status: "active",
+    version: 1,
+    accessCount: 3,
+    lastAccessedAt: now - 7 * 86_400_000, // 7 days ago
+    supersededBy: null,
+    supersedes: null,
+    evolutionNote: null,
+    consolidatedInto: null,
+    contributedToPattern: null,
+    sourceMemories: [],
+    validFrom: now - 30 * 86_400_000, // 30 days old
+    validUntil: null,
+  };
+
+  // Save and restore env
+  const origFlag = process.env.RECALLNEST_EMOTION_SCORING;
+
+  test("with emotion flag ON and metadata, emotional memory scores higher", () => {
+    process.env.RECALLNEST_EMOTION_SCORING = "true";
+    try {
+      const emotionalMeta = JSON.stringify({
+        emotion: { valence: -0.9, arousal: 0.8, label: "frustration", salience: 0.85, source: "keyword" },
+      });
+      const neutralMeta = JSON.stringify({
+        emotion: { valence: 0, arousal: 0, label: "neutral", salience: 0, source: "keyword" },
+      });
+
+      const emotionalScore = computeDecayScore(baseEvo, 0.5, now, emotionalMeta);
+      const neutralScore = computeDecayScore(baseEvo, 0.5, now, neutralMeta);
+
+      expect(emotionalScore).toBeGreaterThan(neutralScore);
+    } finally {
+      process.env.RECALLNEST_EMOTION_SCORING = origFlag;
+    }
+  });
+
+  test("with emotion flag ON, weights sum close to 1.0", () => {
+    process.env.RECALLNEST_EMOTION_SCORING = "true";
+    try {
+      // At max values: time=1, freq=1, importance=1, salience=1
+      // Score should be 0.15 + 0.25 + 0.45 + 0.15 = 1.0
+      const freshEvo: EvolutionMetadata = {
+        ...baseEvo,
+        accessCount: 100,
+        lastAccessedAt: now,
+        validFrom: now, // just created
+      };
+      const maxMeta = JSON.stringify({
+        emotion: { valence: 1, arousal: 1, label: "positive", salience: 1, source: "keyword" },
+      });
+
+      const score = computeDecayScore(freshEvo, 1.0, now, maxMeta);
+      expect(score).toBeCloseTo(1.0, 1);
+    } finally {
+      process.env.RECALLNEST_EMOTION_SCORING = origFlag;
+    }
+  });
+
+  test("backward compat: no metadata param still works", () => {
+    const score = computeDecayScore(baseEvo, 0.5, now);
+    expect(score).toBeGreaterThan(0);
+    expect(score).toBeLessThanOrEqual(1);
+  });
+
+  test("backward compat: metadata without emotion still works", () => {
+    process.env.RECALLNEST_EMOTION_SCORING = "true";
+    try {
+      const noEmotionMeta = JSON.stringify({ tier: "working" });
+      const score = computeDecayScore(baseEvo, 0.5, now, noEmotionMeta);
+      expect(score).toBeGreaterThan(0);
+      expect(score).toBeLessThanOrEqual(1);
+    } finally {
+      process.env.RECALLNEST_EMOTION_SCORING = origFlag;
+    }
+  });
+
+  test("with emotion flag OFF, metadata is ignored (base weights)", () => {
+    process.env.RECALLNEST_EMOTION_SCORING = "";
+    try {
+      const emotionalMeta = JSON.stringify({
+        emotion: { valence: -0.9, arousal: 0.8, label: "frustration", salience: 0.85, source: "keyword" },
+      });
+
+      const withMeta = computeDecayScore(baseEvo, 0.5, now, emotionalMeta);
+      const withoutMeta = computeDecayScore(baseEvo, 0.5, now);
+
+      expect(withMeta).toBeCloseTo(withoutMeta, 5);
+    } finally {
+      process.env.RECALLNEST_EMOTION_SCORING = origFlag;
+    }
+  });
+});

package/src/__tests__/emotion-retrieval.test.ts

@@ -0,0 +1,56 @@
+import { describe, test, expect } from "bun:test";
+import { applyEmotionWeight } from "../retriever.js";
+
+describe("applyEmotionWeight", () => {
+  const makeResult = (id: string, score: number, emotionJson?: object) => ({
+    id,
+    text: "test",
+    vector: [],
+    category: "events" as const,
+    scope: "test",
+    importance: 0.5,
+    timestamp: Date.now(),
+    metadata: emotionJson ? JSON.stringify({ emotion: emotionJson }) : "{}",
+    score,
+    sources: {},
+  });
+
+  test("null query emotion returns unchanged", () => {
+    const results = [makeResult("a", 0.8, { valence: 0.9, arousal: 0.5 })];
+    const output = applyEmotionWeight(results, null);
+    expect(output[0].score).toBe(0.8);
+  });
+
+  test("low-valence query returns unchanged", () => {
+    const queryEmotion = { valence: 0.1, arousal: 0, label: "neutral" };
+    const results = [makeResult("a", 0.8, { valence: 0.9, arousal: 0.5 })];
+    const output = applyEmotionWeight(results, queryEmotion);
+    expect(output[0].score).toBe(0.8);
+  });
+
+  test("negative query boosts negative memories", () => {
+    const queryEmotion = { valence: -0.8, arousal: 0.5, label: "frustration" };
+    const results = [
+      makeResult("neg", 0.7, { valence: -0.7, arousal: 0.5 }),
+      makeResult("pos", 0.7, { valence: 0.8, arousal: 0.3 }),
+    ];
+    const output = applyEmotionWeight(results, queryEmotion);
+    expect(output.find(r => r.id === "neg")!.score).toBeGreaterThan(
+      output.find(r => r.id === "pos")!.score
+    );
+  });
+
+  test("no emotion data leaves score unchanged", () => {
+    const queryEmotion = { valence: -0.8, arousal: 0.5, label: "negative" };
+    const results = [makeResult("no-emo", 0.7)];
+    const output = applyEmotionWeight(results, queryEmotion);
+    expect(output[0].score).toBe(0.7);
+  });
+
+  test("max boost is 15%", () => {
+    const queryEmotion = { valence: 1.0, arousal: 1.0, label: "positive" };
+    const results = [makeResult("a", 1.0, { valence: 1.0, arousal: 1.0 })];
+    const output = applyEmotionWeight(results, queryEmotion);
+    expect(output[0].score).toBeCloseTo(1.15, 2);
+  });
+});

package/src/__tests__/entity-resolver.test.ts

@@ -0,0 +1,58 @@
+import { describe, expect, it } from "bun:test";
+
+import { EntityResolver, BUILTIN_ALIASES, defaultResolver, resolveQueryEntities } from "../entity-resolver.js";
+
+describe("EntityResolver", () => {
+  it("resolves known aliases", () => {
+    expect(defaultResolver.resolve("ts")).toBe("typescript");
+    expect(defaultResolver.resolve("TS")).toBe("typescript");
+    expect(defaultResolver.resolve("k8s")).toBe("kubernetes");
+    expect(defaultResolver.resolve("pg")).toBe("postgresql");
+  });
+
+  it("returns term as-is for unknown aliases", () => {
+    expect(defaultResolver.resolve("unknownThing")).toBe("unknownThing");
+    expect(defaultResolver.resolve("")).toBe("");
+  });
+
+  it("supports user aliases that override builtins", () => {
+    const resolver = new EntityResolver(BUILTIN_ALIASES, { "ts": "my-custom-ts" });
+    expect(resolver.resolve("ts")).toBe("my-custom-ts");
+  });
+
+  it("resolveText replaces aliases in context", () => {
+    const text = "I'm using TS with k8s and pg for the backend";
+    const resolved = defaultResolver.resolveText(text);
+    expect(resolved).toContain("typescript");
+    expect(resolved).toContain("kubernetes");
+    expect(resolved).toContain("postgresql");
+  });
+
+  it("resolveText handles longer aliases first", () => {
+    const text = "Using docker-compose for local dev";
+    const resolved = defaultResolver.resolveText(text);
+    expect(resolved).toContain("docker compose");
+  });
+
+  it("hasAlias returns true for known aliases", () => {
+    expect(defaultResolver.hasAlias("ts")).toBe(true);
+    expect(defaultResolver.hasAlias("unknown")).toBe(false);
+  });
+
+  it("size returns the number of aliases", () => {
+    expect(defaultResolver.size).toBeGreaterThan(40);
+  });
+});
+
+describe("resolveQueryEntities", () => {
+  it("normalizes entities in a search query", () => {
+    const result = resolveQueryEntities("search for ts config in k8s");
+    expect(result).toContain("typescript");
+    expect(result).toContain("kubernetes");
+  });
+
+  it("passes through queries with no aliases", () => {
+    const result = resolveQueryEntities("how to deploy a web app");
+    expect(result).toBe("how to deploy a web app");
+  });
+});