nlm-memory 0.4.0

package/tests/unit/core/recall-service.test.ts

@@ -0,0 +1,200 @@
+import { describe, expect, it } from "vitest";
+import { RecallService } from "../../../src/core/recall/recall-service.js";
+import type { LLMClient, EmbedResult } from "../../../src/ports/llm-client.js";
+import { LLMUnreachableError } from "../../../src/ports/llm-client.js";
+import type {
+  KeywordNeighbor,
+  SessionStore,
+  SemanticNeighbor,
+} from "../../../src/ports/session-store.js";
+import type { Session } from "../../../src/shared/types.js";
+import { makeSession } from "../../fixtures/sessions.js";
+
+// Fake store: keyword and semantic hits are pre-baked. Unit tests here cover
+// RecallService orchestration (filter, merge, limit, error handling) — not
+// keyword ranking quality, which is covered by the FTS integration tests.
+class InMemoryStore implements SessionStore {
+  listCalls = 0;
+  getByIdsCalls = 0;
+  constructor(
+    private readonly sessions: Session[],
+    private readonly neighbors: SemanticNeighbor[] = [],
+    private readonly keywordHits: KeywordNeighbor[] = [],
+  ) {}
+  async list(): Promise<ReadonlyArray<Session>> {
+    this.listCalls += 1;
+    return this.sessions;
+  }
+  async getById(id: string): Promise<Session | null> {
+    return this.sessions.find((s) => s.id === id) ?? null;
+  }
+  async getByIds(ids: ReadonlyArray<string>): Promise<ReadonlyArray<Session>> {
+    this.getByIdsCalls += 1;
+    return this.sessions.filter((s) => ids.includes(s.id));
+  }
+  async semanticSearch(): Promise<ReadonlyArray<SemanticNeighbor>> {
+    return this.neighbors;
+  }
+  async keywordSearch(): Promise<ReadonlyArray<KeywordNeighbor>> {
+    return this.keywordHits;
+  }
+  async updateStatus(): Promise<void> {}
+}
+
+class StubEmbedder implements LLMClient {
+  constructor(private readonly fail: boolean = false) {}
+  async embed(): Promise<EmbedResult> {
+    if (this.fail) throw new LLMUnreachableError("ollama");
+    return { vector: new Float32Array([1, 0, 0]), model: "stub" };
+  }
+  async classify(): Promise<never> {
+    throw new Error("not used");
+  }
+}
+
+const corpus: Session[] = [
+  makeSession({
+    id: "a",
+    label: "Hono router setup",
+    entities: ["NLM"],
+    decisions: ["chose Hono over Express"],
+  }),
+  makeSession({
+    id: "b",
+    label: "pgvector migration plan",
+    entities: ["NLM", "Postgres"],
+    open: ["timing of cutover"],
+  }),
+  makeSession({
+    id: "c",
+    label: "unrelated session",
+    entities: ["Other"],
+  }),
+];
+
+describe("RecallService.search", () => {
+  it("returns empty result when query and filters are all blank", async () => {
+    const svc = new RecallService({
+      store: new InMemoryStore(corpus),
+      llm: new StubEmbedder(),
+    });
+    const result = await svc.search({ query: "" });
+    expect(result.total).toBe(0);
+    expect(result.results).toEqual([]);
+  });
+
+  it("keyword mode surfaces store keyword hits ranked by store score", async () => {
+    const store = new InMemoryStore(corpus, [], [
+      { sessionId: "b", score: 9.2 },
+      { sessionId: "a", score: 2.1 },
+    ]);
+    const svc = new RecallService({ store, llm: new StubEmbedder() });
+    const result = await svc.search({ query: "pgvector", mode: "keyword" });
+    expect(result.results.map((r) => r.id)).toEqual(["b", "a"]);
+    expect(result.results[0]?.matchScore).toBe(9.2);
+  });
+
+  it("keyword mode populates matchedIn from the resolved session", async () => {
+    const store = new InMemoryStore(corpus, [], [{ sessionId: "b", score: 5 }]);
+    const svc = new RecallService({ store, llm: new StubEmbedder() });
+    const result = await svc.search({ query: "pgvector", mode: "keyword" });
+    expect(result.results[0]?.matchedIn).toEqual(["label"]);
+  });
+
+  it("entity filter restricts the keyword corpus", async () => {
+    const store = new InMemoryStore(corpus, [], [
+      { sessionId: "b", score: 5 },
+      { sessionId: "c", score: 4 },
+    ]);
+    const svc = new RecallService({ store, llm: new StubEmbedder() });
+    const result = await svc.search({ query: "session", mode: "keyword", entity: "NLM" });
+    expect(result.results.every((r) => r.entities.includes("NLM"))).toBe(true);
+    expect(result.results.map((r) => r.id)).not.toContain("c");
+  });
+
+  it("semantic mode returns ollama_unreachable when the embedder fails", async () => {
+    const svc = new RecallService({
+      store: new InMemoryStore(corpus),
+      llm: new StubEmbedder(true),
+    });
+    const result = await svc.search({ query: "anything", mode: "semantic" });
+    expect(result.modeUnavailable).toBe("ollama_unreachable");
+    expect(result.results).toEqual([]);
+  });
+
+  it("hybrid mode degrades to keyword scores when semantic is unavailable", async () => {
+    const store = new InMemoryStore(corpus, [], [{ sessionId: "b", score: 7 }]);
+    const svc = new RecallService({ store, llm: new StubEmbedder(true) });
+    const result = await svc.search({ query: "pgvector", mode: "hybrid" });
+    expect(result.modeUnavailable).toBe("ollama_unreachable");
+    expect(result.results).toHaveLength(1);
+    expect(result.results[0]?.id).toBe("b");
+  });
+
+  it("semantic mode reports cosine similarity computed from L2 distance of unit vectors", async () => {
+    const store = new InMemoryStore(corpus, [{ sessionId: "a", distance: 0 }]);
+    const svc = new RecallService({ store, llm: new StubEmbedder() });
+    const result = await svc.search({ query: "anything", mode: "semantic" });
+    expect(result.results[0]?.matchScore).toBe(1);
+  });
+
+  it("hybrid mode uses RRF fusion — rank 1 in both legs scores 2/(60+1)", async () => {
+    const store = new InMemoryStore(
+      corpus,
+      [{ sessionId: "b", distance: 0 }],
+      [{ sessionId: "b", score: 9.2 }],
+    );
+    const svc = new RecallService({ store, llm: new StubEmbedder() });
+    const result = await svc.search({ query: "pgvector", mode: "hybrid" });
+    const top = result.results[0];
+    expect(top?.id).toBe("b");
+    // RRF with both legs at rank 1, k=60: 1/61 + 1/61 = 2/61 ≈ 0.0328
+    expect(top?.matchScore).toBeCloseTo(2 / 61, 4);
+    // Informational normalized scores preserved for UI display.
+    expect(top?.keywordScore).toBe(1);
+    expect(top?.semanticScore).toBe(1);
+  });
+
+  it("hybrid RRF: a session in only one leg scores half as much as a session in both legs at the same rank", async () => {
+    // Session "a" appears in keyword leg at rank 1.
+    // Session "b" appears in BOTH legs at rank 1.
+    const store = new InMemoryStore(
+      corpus,
+      [{ sessionId: "b", distance: 0 }],
+      [
+        { sessionId: "a", score: 100 }, // huge raw score, but only one leg
+        { sessionId: "b", score: 1 },   // tiny raw score, but in both legs
+      ],
+    );
+    const svc = new RecallService({ store, llm: new StubEmbedder() });
+    const result = await svc.search({ query: "pgvector", mode: "hybrid" });
+    expect(result.results[0]?.id).toBe("b"); // both-legs wins despite tiny kw score
+    expect(result.results[0]?.matchScore).toBeCloseTo(1 / 61 + 1 / 62, 4); // b is rank 1 sem, rank 2 kw
+    expect(result.results[1]?.id).toBe("a");
+    expect(result.results[1]?.matchScore).toBeCloseTo(1 / 61, 4); // a is rank 1 kw only
+  });
+
+  it("clamps limit to MAX_LIMIT (100) and at least 1", async () => {
+    const store = new InMemoryStore(corpus, [], [{ sessionId: "b", score: 5 }]);
+    const svc = new RecallService({ store, llm: new StubEmbedder() });
+    const big = await svc.search({ query: "session", mode: "keyword", limit: 9999 });
+    expect(big.limit).toBe(100);
+    const small = await svc.search({ query: "session", mode: "keyword", limit: 0 });
+    expect(small.limit).toBe(1);
+  });
+
+  it("resolves only the hit sessions and never loads the full corpus", async () => {
+    const big: Session[] = Array.from({ length: 100 }, (_, i) =>
+      makeSession({ id: `s${i}`, label: `session ${i}` }),
+    );
+    const store = new InMemoryStore(big, [], [
+      { sessionId: "s7", score: 9 },
+      { sessionId: "s42", score: 8 },
+    ]);
+    const svc = new RecallService({ store, llm: new StubEmbedder() });
+    const result = await svc.search({ query: "anything", mode: "keyword" });
+    expect(result.results.map((r) => r.id)).toEqual(["s7", "s42"]);
+    expect(store.listCalls).toBe(0);
+    expect(store.getByIdsCalls).toBe(1);
+  });
+});

package/tests/unit/core/storage/live-status.test.ts

@@ -0,0 +1,54 @@
+import { mkdtempSync, rmSync, writeFileSync, utimesSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { liveSessionStatus } from "../../../../src/core/storage/live-status.js";
+
+function touchAt(path: string, agoMs: number): void {
+  writeFileSync(path, "");
+  const t = (Date.now() - agoMs) / 1000;
+  utimesSync(path, t, t);
+}
+
+describe("liveSessionStatus", () => {
+  let tmp: string;
+
+  beforeEach(() => {
+    tmp = mkdtempSync(join(tmpdir(), "nlm-status-"));
+  });
+
+  afterEach(() => {
+    rmSync(tmp, { recursive: true, force: true });
+  });
+
+  it("superseded persisted status always wins", () => {
+    expect(liveSessionStatus(null, "superseded")).toBe("superseded");
+    expect(liveSessionStatus("/nonexistent", "superseded")).toBe("superseded");
+  });
+
+  it("returns 'closed' when transcript path is null", () => {
+    expect(liveSessionStatus(null, "active")).toBe("closed");
+  });
+
+  it("returns 'closed' when transcript file is missing", () => {
+    expect(liveSessionStatus(join(tmp, "missing.jsonl"), "active")).toBe("closed");
+  });
+
+  it("returns 'active' when mtime is under 15 minutes ago", () => {
+    const p = join(tmp, "fresh.jsonl");
+    touchAt(p, 5 * 60 * 1000);
+    expect(liveSessionStatus(p, "active")).toBe("active");
+  });
+
+  it("returns 'idle' when mtime is between 15 minutes and 24 hours", () => {
+    const p = join(tmp, "stale.jsonl");
+    touchAt(p, 2 * 60 * 60 * 1000);
+    expect(liveSessionStatus(p, "active")).toBe("idle");
+  });
+
+  it("returns 'closed' when mtime exceeds 24 hours", () => {
+    const p = join(tmp, "old.jsonl");
+    touchAt(p, 48 * 60 * 60 * 1000);
+    expect(liveSessionStatus(p, "active")).toBe("closed");
+  });
+});

package/tests/unit/core/tokenize.test.ts

@@ -0,0 +1,32 @@
+import { describe, expect, it } from "vitest";
+import { tokenize, tokenSet } from "../../../src/core/recall/tokenize.js";
+
+describe("tokenize", () => {
+  it("returns empty array for nullish or empty input", () => {
+    expect(tokenize("")).toEqual([]);
+    expect(tokenize(null)).toEqual([]);
+    expect(tokenize(undefined)).toEqual([]);
+  });
+
+  it("lowercases all tokens", () => {
+    expect(tokenize("Hello WORLD")).toEqual(["hello", "world"]);
+  });
+
+  it("matches the Python TOKEN_PATTERN [A-Za-z0-9][A-Za-z0-9_.-]*", () => {
+    expect(tokenize("Hermes-Pi v1.2_beta")).toEqual(["hermes-pi", "v1.2_beta"]);
+  });
+
+  it("drops leading punctuation since tokens must start with [A-Za-z0-9]", () => {
+    expect(tokenize("-leading +middle")).toEqual(["leading", "middle"]);
+  });
+
+  it("splits on whitespace and standalone punctuation", () => {
+    expect(tokenize("foo, bar; baz")).toEqual(["foo", "bar", "baz"]);
+  });
+});
+
+describe("tokenSet", () => {
+  it("deduplicates", () => {
+    expect(tokenSet("Foo foo FOO")).toEqual(new Set(["foo"]));
+  });
+});