recallnest 2.3.0 → 2.5.4

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

@@ -0,0 +1,283 @@
+/**
+ * Tests for Tier 3.4: Prospective Memory (Conditional Trigger Reminders)
+ *
+ * Validates:
+ * 1. setReminder creates a properly structured memory entry
+ * 2. checkTriggers finds matching pending reminders
+ * 3. checkTriggers ignores fired/expired reminders
+ * 4. fireReminder marks the reminder as fired
+ * 5. formatReminders produces readable output
+ * 6. Trigger matching uses keyword logic
+ * 7. Expiration is handled correctly
+ */
+import { describe, expect, it } from "bun:test";
+import {
+  setReminder,
+  checkTriggers,
+  fireReminder,
+  formatReminders,
+} from "../prospective-memory.js";
+import type { MemoryEntry, MemorySearchResult } from "../store.js";
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function createMockStore() {
+  const data = new Map<string, MemoryEntry>();
+  let idCounter = 0;
+
+  return {
+    data,
+    async store(entry: Omit<MemoryEntry, "id" | "timestamp">) {
+      const id = `reminder-${++idCounter}`;
+      const full: MemoryEntry = {
+        ...entry,
+        id,
+        timestamp: Date.now(),
+      } as MemoryEntry;
+      data.set(id, full);
+      return full;
+    },
+    async vectorSearch(
+      _vector: number[],
+      _limit: number,
+      _minScore: number,
+      _scopeFilter?: string[],
+    ): Promise<MemorySearchResult[]> {
+      return [...data.values()].map(e => ({ entry: e, score: 0.8 }));
+    },
+    async getById(id: string) {
+      return data.get(id) ?? null;
+    },
+    async update(id: string, upd: { metadata?: string; text?: string }, _scope?: string[]) {
+      const entry = data.get(id);
+      if (!entry) return null;
+      if (upd.metadata) entry.metadata = upd.metadata;
+      if (upd.text) entry.text = upd.text;
+      return entry;
+    },
+  };
+}
+
+function createMockEmbedder() {
+  return {
+    async embedPassage(_text: string) {
+      return [0.1, 0.2, 0.3];
+    },
+    async embedBatchPassage(texts: string[]) {
+      return texts.map(() => [0.1, 0.2, 0.3]);
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// setReminder
+// ---------------------------------------------------------------------------
+
+describe("setReminder", () => {
+  it("creates a reminder with prospective metadata", async () => {
+    const store = createMockStore();
+    const embedder = createMockEmbedder();
+
+    const entry = await setReminder(store as any, embedder as any, {
+      trigger: "deployment",
+      action: "Check the monitoring dashboard after deploy",
+      scope: "project:test",
+    });
+
+    expect(entry.id).toBeTruthy();
+    expect(entry.category).toBe("patterns");
+    expect(entry.text).toContain("Reminder");
+    expect(entry.text).toContain("deployment");
+
+    const meta = JSON.parse(entry.metadata);
+    expect(meta.prospective.trigger).toBe("deployment");
+    expect(meta.prospective.action).toBe("Check the monitoring dashboard after deploy");
+    expect(meta.prospective.status).toBe("pending");
+  });
+
+  it("creates a reminder with expiration", async () => {
+    const store = createMockStore();
+    const embedder = createMockEmbedder();
+
+    const entry = await setReminder(store as any, embedder as any, {
+      trigger: "release",
+      action: "Update changelog",
+      scope: "project:test",
+      expiresInDays: 7,
+    });
+
+    const meta = JSON.parse(entry.metadata);
+    expect(meta.prospective.expiresAt).toBeTruthy();
+    // Should expire roughly 7 days from now
+    const expiresAt = new Date(meta.prospective.expiresAt).getTime();
+    const now = Date.now();
+    const sevenDays = 7 * 86_400_000;
+    expect(expiresAt - now).toBeGreaterThan(sevenDays - 60_000);
+    expect(expiresAt - now).toBeLessThan(sevenDays + 60_000);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// checkTriggers
+// ---------------------------------------------------------------------------
+
+describe("checkTriggers", () => {
+  it("finds matching pending reminders", async () => {
+    const store = createMockStore();
+    const embedder = createMockEmbedder();
+
+    await setReminder(store as any, embedder as any, {
+      trigger: "deployment",
+      action: "Check monitoring",
+      scope: "project:test",
+    });
+
+    const reminders = await checkTriggers(
+      store as any,
+      embedder as any,
+      "We need to do a deployment today",
+    );
+
+    expect(reminders.length).toBe(1);
+    expect(reminders[0].action).toBe("Check monitoring");
+  });
+
+  it("ignores non-matching queries", async () => {
+    const store = createMockStore();
+    const embedder = createMockEmbedder();
+
+    await setReminder(store as any, embedder as any, {
+      trigger: "deployment",
+      action: "Check monitoring",
+      scope: "project:test",
+    });
+
+    const reminders = await checkTriggers(
+      store as any,
+      embedder as any,
+      "Let me review the code changes",
+    );
+
+    expect(reminders.length).toBe(0);
+  });
+
+  it("ignores fired reminders", async () => {
+    const store = createMockStore();
+    const embedder = createMockEmbedder();
+
+    const entry = await setReminder(store as any, embedder as any, {
+      trigger: "deployment",
+      action: "Check monitoring",
+      scope: "project:test",
+    });
+
+    // Fire the reminder
+    await fireReminder(store as any, entry.id);
+
+    const reminders = await checkTriggers(
+      store as any,
+      embedder as any,
+      "deployment is happening",
+    );
+
+    expect(reminders.length).toBe(0);
+  });
+
+  it("handles expired reminders", async () => {
+    const store = createMockStore();
+    const embedder = createMockEmbedder();
+
+    // Create a reminder that's already expired
+    const entry = await setReminder(store as any, embedder as any, {
+      trigger: "something",
+      action: "do something",
+      scope: "project:test",
+    });
+
+    // Manually set expiresAt to past
+    const meta = JSON.parse(entry.metadata);
+    meta.prospective.expiresAt = "2020-01-01T00:00:00Z";
+    entry.metadata = JSON.stringify(meta);
+
+    const reminders = await checkTriggers(
+      store as any,
+      embedder as any,
+      "something came up",
+    );
+
+    expect(reminders.length).toBe(0);
+    // Should be marked as expired
+    const updated = JSON.parse(entry.metadata);
+    expect(updated.prospective.status).toBe("expired");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// fireReminder
+// ---------------------------------------------------------------------------
+
+describe("fireReminder", () => {
+  it("marks reminder as fired and returns action", async () => {
+    const store = createMockStore();
+    const embedder = createMockEmbedder();
+
+    const entry = await setReminder(store as any, embedder as any, {
+      trigger: "test",
+      action: "do the thing",
+      scope: "project:test",
+    });
+
+    const action = await fireReminder(store as any, entry.id);
+
+    expect(action).toBe("do the thing");
+    const meta = JSON.parse(store.data.get(entry.id)!.metadata);
+    expect(meta.prospective.status).toBe("fired");
+    expect(meta.prospective.firedAt).toBeTruthy();
+  });
+
+  it("returns null for non-existent entry", async () => {
+    const store = createMockStore();
+    const action = await fireReminder(store as any, "nonexistent");
+    expect(action).toBeNull();
+  });
+
+  it("returns null for already-fired reminder", async () => {
+    const store = createMockStore();
+    const embedder = createMockEmbedder();
+
+    const entry = await setReminder(store as any, embedder as any, {
+      trigger: "test",
+      action: "do it",
+      scope: "project:test",
+    });
+
+    await fireReminder(store as any, entry.id);
+    const secondFire = await fireReminder(store as any, entry.id);
+
+    expect(secondFire).toBeNull();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// formatReminders
+// ---------------------------------------------------------------------------
+
+describe("formatReminders", () => {
+  it("formats reminders for context injection", () => {
+    const formatted = formatReminders([
+      { entryId: "r1", trigger: "deploy", action: "Check monitoring after deploy" },
+      { entryId: "r2", trigger: "meeting", action: "Bring up the budget issue" },
+    ]);
+
+    expect(formatted.length).toBe(2);
+    expect(formatted[0]).toContain("deploy");
+    expect(formatted[0]).toContain("Check monitoring after deploy");
+    expect(formatted[1]).toContain("meeting");
+  });
+
+  it("handles empty array", () => {
+    expect(formatReminders([])).toEqual([]);
+  });
+});

package/src/__tests__/query-entity-detector.test.ts

@@ -0,0 +1,171 @@
+import { describe, expect, it } from "bun:test";
+import { detectEntitiesSync, detectEntities } from "../query-entity-detector.js";
+
+// ============================================================================
+// Sync detection (no KG validation)
+// ============================================================================
+
+describe("detectEntitiesSync", () => {
+  describe("English entity extraction", () => {
+    it("extracts capitalized names", () => {
+      const result = detectEntitiesSync("What does Alice use?");
+      expect(result.entities).toContain("Alice");
+    });
+
+    it("extracts multi-word capitalized names", () => {
+      const result = detectEntitiesSync("Tell me about Claude Code");
+      expect(result.entities).toContain("Claude Code");
+    });
+
+    it("extracts CamelCase identifiers (normalized to title case)", () => {
+      const result = detectEntitiesSync("How does RecallNest work?");
+      // normalizeEntity applies title case: RecallNest -> Recallnest
+      expect(result.entities).toContain("Recallnest");
+    });
+
+    it("extracts quoted strings (normalized to title case)", () => {
+      const result = detectEntitiesSync('Search for "LanceDB" docs');
+      expect(result.entities).toContain("Lancedb");
+    });
+
+    it("extracts backtick-quoted strings (normalized to title case)", () => {
+      const result = detectEntitiesSync("What is `OpenAI` embedding?");
+      expect(result.entities).toContain("Openai");
+    });
+
+    it("skips stop words even when capitalized", () => {
+      const result = detectEntitiesSync("The quick brown fox");
+      // "The" should be filtered as stop word
+      expect(result.entities).not.toContain("The");
+    });
+
+    it("deduplicates entities (case-insensitive)", () => {
+      const result = detectEntitiesSync('Alice uses "alice" tool');
+      // Should have only one Alice entry
+      const aliceCount = result.entities.filter(e => e.toLowerCase() === "alice").length;
+      expect(aliceCount).toBe(1);
+    });
+
+    it("returns empty for queries without entities", () => {
+      const result = detectEntitiesSync("what happened yesterday?");
+      expect(result.entities.length).toBe(0);
+    });
+  });
+
+  describe("multi-hop detection — English", () => {
+    it("detects possessive friend pattern", () => {
+      const result = detectEntitiesSync("Alice's friends");
+      expect(result.isMultiHop).toBe(true);
+      expect(result.hopPredicate).toBe("friend_of");
+    });
+
+    it("detects 'friend of' pattern", () => {
+      const result = detectEntitiesSync("friends of Bob");
+      expect(result.isMultiHop).toBe(true);
+      expect(result.hopPredicate).toBe("friend_of");
+    });
+
+    it("detects 'what does X use' pattern", () => {
+      const result = detectEntitiesSync("what does Alice use?");
+      expect(result.isMultiHop).toBe(true);
+      expect(result.hopPredicate).toBe("uses");
+    });
+
+    it("detects 'who created' pattern", () => {
+      const result = detectEntitiesSync("who created RecallNest?");
+      expect(result.isMultiHop).toBe(true);
+      expect(result.hopPredicate).toBe("created_by");
+    });
+
+    it("detects 'who manages' pattern", () => {
+      const result = detectEntitiesSync("who manages the team?");
+      expect(result.isMultiHop).toBe(true);
+      expect(result.hopPredicate).toBe("manages");
+    });
+
+    it("detects 'X depends on' pattern", () => {
+      const result = detectEntitiesSync("what depends on LanceDB?");
+      expect(result.isMultiHop).toBe(true);
+      expect(result.hopPredicate).toBe("depends_on");
+    });
+
+    it("returns isMultiHop=false for simple queries", () => {
+      const result = detectEntitiesSync("Tell me about Python");
+      expect(result.isMultiHop).toBe(false);
+      expect(result.hopPredicate).toBeUndefined();
+    });
+  });
+
+  describe("multi-hop detection — Chinese", () => {
+    it("detects 的朋友 pattern", () => {
+      const result = detectEntitiesSync("Alice的朋友有谁？");
+      expect(result.isMultiHop).toBe(true);
+      expect(result.hopPredicate).toBe("friend_of");
+    });
+
+    it("detects 谁和X一起 pattern", () => {
+      const result = detectEntitiesSync("谁和Bob一起工作？");
+      expect(result.isMultiHop).toBe(true);
+      expect(result.hopPredicate).toBe("works_with");
+    });
+
+    it("detects 谁创建了 pattern", () => {
+      const result = detectEntitiesSync("谁创建了RecallNest？");
+      expect(result.isMultiHop).toBe(true);
+      expect(result.hopPredicate).toBe("created_by");
+    });
+
+    it("detects 依赖什么 pattern", () => {
+      const result = detectEntitiesSync("RecallNest依赖什么？");
+      expect(result.isMultiHop).toBe(true);
+      expect(result.hopPredicate).toBe("depends_on");
+    });
+  });
+});
+
+// ============================================================================
+// Async detection with KG validation
+// ============================================================================
+
+describe("detectEntities (async with mock KG)", () => {
+  function createMockKGStore(knownEntities: string[]) {
+    return {
+      async getAllEntities() {
+        return knownEntities;
+      },
+    } as any;
+  }
+
+  it("validates entities against KG", async () => {
+    const kgStore = createMockKGStore(["Alice", "Python", "LanceDB"]);
+    const result = await detectEntities("Alice uses Python and React", kgStore);
+
+    // Alice and Python are in KG, React is not
+    expect(result.entities).toContain("Alice");
+    expect(result.entities).toContain("Python");
+    expect(result.entities).not.toContain("React");
+  });
+
+  it("falls back to heuristic when KG validates nothing", async () => {
+    const kgStore = createMockKGStore([]); // empty KG
+    const result = await detectEntities("Alice uses Python", kgStore);
+
+    // Should fall back to heuristic candidates
+    expect(result.entities).toContain("Alice");
+    expect(result.entities).toContain("Python");
+  });
+
+  it("preserves KG canonical casing", async () => {
+    const kgStore = createMockKGStore(["alice"]); // lowercase in KG
+    const result = await detectEntities("Tell me about Alice", kgStore);
+
+    // Should use KG's casing
+    expect(result.entities).toContain("alice");
+  });
+
+  it("works without KG store", async () => {
+    const result = await detectEntities("Alice uses Python");
+    expect(result.entities).toContain("Alice");
+    expect(result.entities).toContain("Python");
+  });
+});

package/src/__tests__/query-expander-alias.test.ts

@@ -0,0 +1,146 @@
+import { describe, it, expect, beforeEach, afterEach } from "bun:test";
+import { expandQuery, setAliasMapPath, resetAliasMapCache, upsertUserAlias, removeUserAlias, listUserAliases, explainUserAliases } from "../query-expander.js";
+import { expandQueryWithAliases, ALIAS_QUERY_MAX_LENGTH } from "../aliases.js";
+import { writeFileSync, unlinkSync, existsSync, mkdirSync } from "fs";
+import { join } from "path";
+
+const TEST_DIR = join(import.meta.dir, "../../.test-data");
+const TEST_ALIAS = join(TEST_DIR, "test-alias-map.json");
+
+function cleanup() {
+  try { if (existsSync(TEST_ALIAS)) unlinkSync(TEST_ALIAS); } catch {}
+}
+
+describe("expandQuery with alias-map", () => {
+  beforeEach(() => {
+    if (!existsSync(TEST_DIR)) mkdirSync(TEST_DIR, { recursive: true });
+    cleanup();
+    resetAliasMapCache();
+  });
+  afterEach(() => {
+    cleanup();
+    resetAliasMapCache();
+  });
+
+  it("expands short query using alias-map", () => {
+    writeFileSync(TEST_ALIAS, JSON.stringify([
+      { trigger: "轮巡", expansions: ["仓库", "patrol", "repo", "每日检查"] },
+    ]));
+    setAliasMapPath(TEST_ALIAS);
+
+    const expanded = expandQuery("轮巡");
+    expect(expanded).toContain("轮巡");
+    expect(expanded).toContain("仓库");
+    expect(expanded).toContain("patrol");
+  });
+
+  it("does not expand when trigger not matched", () => {
+    writeFileSync(TEST_ALIAS, JSON.stringify([
+      { trigger: "轮巡", expansions: ["仓库", "patrol"] },
+    ]));
+    setAliasMapPath(TEST_ALIAS);
+
+    const expanded = expandQuery("部署");
+    // "部署" matches built-in synonym map, but should NOT match alias "轮巡"
+    expect(expanded).not.toContain("patrol");
+  });
+
+  it("works with empty alias-map file", () => {
+    writeFileSync(TEST_ALIAS, "[]");
+    setAliasMapPath(TEST_ALIAS);
+
+    const result = expandQuery("轮巡");
+    // Should still work (only built-in synonyms)
+    expect(result).toContain("轮巡");
+  });
+
+  it("works with missing alias-map file", () => {
+    setAliasMapPath(join(TEST_DIR, "nonexistent.json"));
+
+    const result = expandQuery("轮巡");
+    expect(result).toContain("轮巡");
+  });
+
+  it("skips expansion terms already in query", () => {
+    writeFileSync(TEST_ALIAS, JSON.stringify([
+      { trigger: "轮巡", expansions: ["轮巡", "仓库", "patrol"] },
+    ]));
+    setAliasMapPath(TEST_ALIAS);
+
+    const expanded = expandQuery("轮巡仓库");
+    // "仓库" already in query, should not be duplicated
+    const occurrences = expanded.split("仓库").length - 1;
+    expect(occurrences).toBe(1);
+  });
+
+  it("respects MAX_EXPANSION_TERMS cap", () => {
+    writeFileSync(TEST_ALIAS, JSON.stringify([
+      {
+        trigger: "测试",
+        expansions: ["a", "b", "c", "d", "e", "f", "g", "h", "i", "j"],
+      },
+    ]));
+    setAliasMapPath(TEST_ALIAS);
+
+    const expanded = expandQuery("测试");
+    // Built-in synonyms + alias expansions, but capped at MAX_EXPANSION_TERMS (5)
+    const addedTerms = expanded.replace("测试", "").trim().split(/\s+/);
+    expect(addedTerms.length).toBeLessThanOrEqual(5);
+  });
+});
+
+describe("manage_alias backend (P1-B)", () => {
+  beforeEach(() => {
+    if (!existsSync(TEST_DIR)) mkdirSync(TEST_DIR, { recursive: true });
+    cleanup();
+    setAliasMapPath(TEST_ALIAS);
+    resetAliasMapCache();
+  });
+  afterEach(() => {
+    cleanup();
+    resetAliasMapCache();
+  });
+
+  it("upserts, lists, expands, and removes a user alias", () => {
+    const added = upsertUserAlias("我的桥", ["telegram-ai-bridge", "tg-bridge-channel"]);
+    expect(added.ok).toBe(true);
+    expect(listUserAliases()).toHaveLength(1);
+
+    // 写完即生效(缓存失效),BM25 通道扩展可见
+    const expanded = expandQuery("我的桥怎么挂了");
+    expect(expanded).toContain("telegram-ai-bridge");
+
+    // update 路径
+    const updated = upsertUserAlias("我的桥", ["telegram-ai-bridge"]);
+    expect(updated.ok && updated.action === "updated").toBe(true);
+    expect(listUserAliases()[0].expansions).toEqual(["telegram-ai-bridge"]);
+
+    expect(explainUserAliases("我的桥呢")).toHaveLength(1);
+    expect(removeUserAlias("我的桥")).toBe(true);
+    expect(removeUserAlias("我的桥")).toBe(false);
+    expect(listUserAliases()).toHaveLength(0);
+  });
+
+  it("rejects invalid rules with reasons", () => {
+    const tooShort = upsertUserAlias("桥", ["x-bridge"]);
+    expect(tooShort.ok).toBe(false);
+
+    const tooMany = upsertUserAlias("我的桥", ["a1", "a2", "a3", "a4", "a5", "a6", "a7", "a8", "a9"]);
+    expect(tooMany.ok).toBe(false);
+
+    const selfRef = upsertUserAlias("我的桥", ["我的桥"]);
+    expect(selfRef.ok).toBe(false);
+
+    const empty = upsertUserAlias("我的桥", ["  "]);
+    expect(empty.ok).toBe(false);
+  });
+});
+
+describe("expandQueryWithAliases length gate (P1-B)", () => {
+  it("skips expansion for queries beyond ALIAS_QUERY_MAX_LENGTH", () => {
+    const longQuery = "我的记忆项目".padEnd(ALIAS_QUERY_MAX_LENGTH + 10, "字");
+    expect(expandQueryWithAliases(longQuery)).toBe(longQuery);
+    // 短 query 照常扩展
+    expect(expandQueryWithAliases("我的记忆项目")).toContain("recallnest");
+  });
+});

package/src/__tests__/query-expander.test.ts

@@ -0,0 +1,34 @@
+import { describe, it, expect } from "bun:test";
+import { expandQuery } from "../query-expander.js";
+
+describe("expandQuery", () => {
+  it("expands colloquial Chinese to technical terms", () => {
+    const result = expandQuery("bot 突然挂了");
+    expect(result).toContain("崩溃");
+    expect(result).toContain("crash");
+    expect(result).toContain("挂了");
+  });
+
+  it("expands fuzzy feeling queries", () => {
+    const result = expandQuery("AI 到底有没有感受");
+    expect(result).toContain("意识");
+    expect(result).toContain("consciousness");
+    expect(result).toContain("感受");
+  });
+
+  it("preserves original query terms", () => {
+    const result = expandQuery("配图风格");
+    expect(result).toContain("配图");
+    expect(result).toContain("风格");
+  });
+
+  it("returns original for already-precise queries", () => {
+    const result = expandQuery("JINA_API_KEY");
+    expect(result).toBe("JINA_API_KEY");
+  });
+
+  it("handles empty/short queries", () => {
+    expect(expandQuery("")).toBe("");
+    expect(expandQuery("hi")).toBe("hi");
+  });
+});