nlm-memory 0.5.0 → 0.5.2

package/tests/unit/core/facts/extract-facts.test.ts

@@ -1,117 +0,0 @@
-/**
- * extractFacts — pure transform from ClassifyResult to Fact[]. No DB, no
- * randomness (idGenerator is injected).
- */
-
-import { describe, expect, it } from "vitest";
-import { extractFacts } from "../../../../src/core/facts/extract-facts.js";
-import type { ClassifyResult } from "../../../../src/ports/llm-client.js";
-
-function classifyResult(overrides: Partial<ClassifyResult> = {}): ClassifyResult {
-  return {
-    label: "L",
-    summary: "S",
-    entities: [],
-    decisions: [],
-    open: [],
-    confidence: 0.9,
-    facts: [],
-    ...overrides,
-  };
-}
-
-describe("extractFacts", () => {
-  it("returns an empty array when classify result has no facts", () => {
-    const out = extractFacts(classifyResult(), "sess_1", "2026-05-19T10:00:00Z");
-    expect(out).toEqual([]);
-  });
-
-  it("maps classifier facts to full Fact records with injected id + timestamp", () => {
-    let n = 0;
-    const result = classifyResult({
-      confidence: 0.85,
-      facts: [
-        { kind: "decision", subject: "nlm-memory-ts", predicate: "framework", value: "Hono" },
-        {
-          kind: "attribute",
-          subject: "mac-pro",
-          predicate: "endpoint",
-          value: "http://macpro:8080/v1",
-          sourceQuote: "endpoint at :8080",
-        },
-      ],
-    });
-    const out = extractFacts(result, "sess_1", "2026-05-19T10:00:00Z", {
-      idGenerator: () => `fact_${++n}`,
-    });
-    expect(out).toEqual([
-      {
-        id: "fact_1",
-        kind: "decision",
-        subject: "nlm-memory-ts",
-        predicate: "framework",
-        value: "Hono",
-        sourceSessionId: "sess_1",
-        sourceQuote: null,
-        createdAt: "2026-05-19T10:00:00Z",
-        supersededBy: null,
-        confidence: 0.85,
-      },
-      {
-        id: "fact_2",
-        kind: "attribute",
-        subject: "mac-pro",
-        predicate: "endpoint",
-        value: "http://macpro:8080/v1",
-        sourceSessionId: "sess_1",
-        sourceQuote: "endpoint at :8080",
-        createdAt: "2026-05-19T10:00:00Z",
-        supersededBy: null,
-        confidence: 0.85,
-      },
-    ]);
-  });
-
-  it("drops all facts when classifier confidence is below 0.4", () => {
-    const result = classifyResult({
-      confidence: 0.35,
-      facts: [
-        { kind: "decision", subject: "x", predicate: "framework", value: "y" },
-      ],
-    });
-    expect(extractFacts(result, "sess_1", "2026-05-19T10:00:00Z")).toEqual([]);
-  });
-
-  it("keeps facts when confidence is exactly the floor (0.4)", () => {
-    const result = classifyResult({
-      confidence: 0.4,
-      facts: [
-        { kind: "decision", subject: "x", predicate: "framework", value: "y" },
-      ],
-    });
-    expect(extractFacts(result, "sess_1", "2026-05-19T10:00:00Z")).toHaveLength(1);
-  });
-
-  it("uses default id generator (fact_<uuid>) when none provided", () => {
-    const result = classifyResult({
-      facts: [{ kind: "decision", subject: "x", predicate: "framework", value: "y" }],
-    });
-    const out = extractFacts(result, "sess_1", "2026-05-19T10:00:00Z");
-    expect(out[0]?.id).toMatch(/^fact_[0-9a-f-]{36}$/);
-  });
-
-  it("each fact gets its own id from the generator (no reuse)", () => {
-    let n = 0;
-    const result = classifyResult({
-      facts: [
-        { kind: "decision", subject: "a", predicate: "framework", value: "x" },
-        { kind: "decision", subject: "b", predicate: "framework", value: "y" },
-        { kind: "decision", subject: "c", predicate: "framework", value: "z" },
-      ],
-    });
-    const out = extractFacts(result, "sess_1", "2026-05-19T10:00:00Z", {
-      idGenerator: () => `fact_${++n}`,
-    });
-    expect(out.map((f) => f.id)).toEqual(["fact_1", "fact_2", "fact_3"]);
-  });
-});

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

@@ -1,40 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { applyFilter } from "../../../src/core/recall/filter.js";
-import { makeSession } from "../../fixtures/sessions.js";
-
-describe("applyFilter", () => {
-  const noDecisionsNoOpen = makeSession({ id: "a", entities: ["Whtnxt"] });
-  const onlyDecisions = makeSession({ id: "b", entities: ["NLM"], decisions: ["picked Hono"] });
-  const onlyOpen = makeSession({ id: "c", entities: ["NLM"], open: ["pgvector later"] });
-  const both = makeSession({
-    id: "d",
-    entities: ["NLM", "Whtnxt"],
-    decisions: ["use SQLite + sqlite-vec"],
-    open: ["Tauri or Electron"],
-  });
-  const corpus = [noDecisionsNoOpen, onlyDecisions, onlyOpen, both];
-
-  it("returns input unchanged when filter is empty", () => {
-    expect(applyFilter(corpus, {})).toEqual(corpus);
-  });
-
-  it("filters by entity tag", () => {
-    const result = applyFilter(corpus, { entity: "NLM" });
-    expect(result.map((s) => s.id)).toEqual(["b", "c", "d"]);
-  });
-
-  it("filters by kind=decision (drops sessions with no decisions)", () => {
-    const result = applyFilter(corpus, { kind: "decision" });
-    expect(result.map((s) => s.id)).toEqual(["b", "d"]);
-  });
-
-  it("filters by kind=open (drops sessions with no open questions)", () => {
-    const result = applyFilter(corpus, { kind: "open" });
-    expect(result.map((s) => s.id)).toEqual(["c", "d"]);
-  });
-
-  it("combines entity and kind constraints (AND semantics)", () => {
-    const result = applyFilter(corpus, { entity: "Whtnxt", kind: "decision" });
-    expect(result.map((s) => s.id)).toEqual(["d"]);
-  });
-});

package/tests/unit/core/hook/citation-detect-cite-session.test.ts

@@ -1,96 +0,0 @@
-/**
- * cite_session tool_use handling in the Stop hook detector.
- *
- * The MCP server's citeSessionHandler already calls appendCitation() directly
- * when the model invokes cite_session. The Stop hook must NOT detect the same
- * cite_session tool_use and write a second log entry (double-count). The A1
- * sub-case in detectCitations now skips cite_session calls entirely.
- *
- * Implicit citations via other NLM tools (get_session, recall_sessions, etc.)
- * still fire through the A2 path as before.
- */
-
-import { describe, expect, it } from "vitest";
-import { detectCitations } from "../../../../src/core/hook/citation-detect.js";
-
-describe("detectCitations — cite_session skipped to prevent double-count", () => {
-  it("does not detect cite_session as a citation (MCP handler already logged it)", () => {
-    const result = detectCitations({
-      responseText: "Based on that session, here is my answer.",
-      toolUses: [
-        {
-          name: "mcp__nlm-memory__cite_session",
-          input: { id: "cc_sub_a139f4ab7ca5aa909" },
-        },
-      ],
-      surfacedIds: ["cc_sub_a139f4ab7ca5aa909"],
-    });
-    expect(result).toEqual([]);
-  });
-
-  it("does not detect cite_session even for a surfaced ID", () => {
-    const result = detectCitations({
-      responseText: "",
-      toolUses: [
-        {
-          name: "mcp__nlm-memory__cite_session",
-          input: { id: "cc_sub_a139f4ab7ca5aa909" },
-        },
-      ],
-      surfacedIds: ["cc_sub_a139f4ab7ca5aa909"],
-    });
-    expect(result).toEqual([]);
-  });
-
-  it("falls back to prose detection when cite_session is skipped and ID appears in text", () => {
-    const result = detectCitations({
-      responseText: "Per cc_sub_a139f4ab7ca5aa909, the decision was FTS5.",
-      toolUses: [
-        {
-          name: "mcp__nlm-memory__cite_session",
-          input: { id: "cc_sub_a139f4ab7ca5aa909" },
-        },
-      ],
-      surfacedIds: ["cc_sub_a139f4ab7ca5aa909"],
-    });
-    expect(result).toHaveLength(1);
-    expect(result[0]).toEqual({ id: "cc_sub_a139f4ab7ca5aa909", kind: "prose" });
-  });
-
-  it("returns empty when multiple cite_session calls are skipped and no prose match", () => {
-    const result = detectCitations({
-      responseText: "",
-      toolUses: [
-        {
-          name: "mcp__nlm-memory__cite_session",
-          input: { id: "cc_sub_a139f4ab7ca5aa909" },
-        },
-        {
-          name: "mcp__nlm-memory__cite_session",
-          input: { id: "hm_20260427_6ff562" },
-        },
-      ],
-      surfacedIds: ["cc_sub_a139f4ab7ca5aa909", "hm_20260427_6ff562"],
-    });
-    expect(result).toEqual([]);
-  });
-
-  it("A2 path (get_session) still fires while cite_session is skipped for the same turn", () => {
-    const result = detectCitations({
-      responseText: "",
-      toolUses: [
-        {
-          name: "mcp__nlm-memory__cite_session",
-          input: { id: "cc_sub_a139f4ab7ca5aa909" },
-        },
-        {
-          name: "mcp__nlm-memory__get_session",
-          input: { id: "hm_20260427_6ff562" },
-        },
-      ],
-      surfacedIds: ["cc_sub_a139f4ab7ca5aa909", "hm_20260427_6ff562"],
-    });
-    expect(result).toHaveLength(1);
-    expect(result[0]).toMatchObject({ id: "hm_20260427_6ff562", kind: "tool_use" });
-  });
-});

package/tests/unit/core/hook/citation-detect.test.ts

@@ -1,124 +0,0 @@
-import { describe, expect, it } from "vitest";
-import {
-  detectCitations,
-  detectCitedIds,
-} from "../../../../src/core/hook/citation-detect.js";
-
-describe("detectCitedIds (back-compat prose-only)", () => {
-  it("returns IDs that appear as substrings in the response", () => {
-    const surfaced = new Set([
-      "cc_sub_a139f4ab7ca5aa909",
-      "hm_20260427_6ff562",
-    ]);
-    const text = "Per cc_sub_a139f4ab7ca5aa909 and hm_20260427_6ff562 we chose FTS5.";
-    expect(detectCitedIds(text, surfaced).sort()).toEqual(
-      ["cc_sub_a139f4ab7ca5aa909", "hm_20260427_6ff562"].sort(),
-    );
-  });
-
-  it("returns empty when no surfaced IDs appear", () => {
-    expect(detectCitedIds("unrelated", new Set(["cc_sub_abc123def456"]))).toEqual([]);
-  });
-
-  it("ignores IDs shorter than the minimum length", () => {
-    expect(detectCitedIds("a ab abc abcdef", new Set(["a", "ab", "abc"]))).toEqual([]);
-  });
-});
-
-describe("detectCitations (combined tool_use + prose)", () => {
-  it("emits a tool_use citation when an NLM MCP tool input references a surfaced ID", () => {
-    const result = detectCitations({
-      responseText: "Let me look at that.",
-      toolUses: [
-        {
-          name: "mcp__nlm-memory__get_session",
-          input: { id: "cc_sub_a139f4ab7ca5aa909" },
-        },
-      ],
-      surfacedIds: ["cc_sub_a139f4ab7ca5aa909", "hm_20260427_6ff562"],
-    });
-    expect(result).toEqual([
-      { id: "cc_sub_a139f4ab7ca5aa909", kind: "tool_use" },
-    ]);
-  });
-
-  it("emits a prose citation when only the response text mentions the ID", () => {
-    const result = detectCitations({
-      responseText: "We decided on FTS5 per cc_sub_a139f4ab7ca5aa909.",
-      toolUses: [],
-      surfacedIds: ["cc_sub_a139f4ab7ca5aa909"],
-    });
-    expect(result).toEqual([
-      { id: "cc_sub_a139f4ab7ca5aa909", kind: "prose" },
-    ]);
-  });
-
-  it("prefers tool_use over prose when both fire on the same ID", () => {
-    const result = detectCitations({
-      responseText: "Per cc_sub_a139f4ab7ca5aa909, here is the answer.",
-      toolUses: [
-        {
-          name: "mcp__nlm-memory__get_session",
-          input: { id: "cc_sub_a139f4ab7ca5aa909" },
-        },
-      ],
-      surfacedIds: ["cc_sub_a139f4ab7ca5aa909"],
-    });
-    expect(result).toEqual([
-      { id: "cc_sub_a139f4ab7ca5aa909", kind: "tool_use" },
-    ]);
-  });
-
-  it("ignores non-NLM tool_use blocks even when they happen to contain the ID", () => {
-    const result = detectCitations({
-      responseText: "",
-      toolUses: [
-        {
-          name: "Bash",
-          input: { command: "grep cc_sub_a139f4ab7ca5aa909 /tmp/log" },
-        },
-      ],
-      surfacedIds: ["cc_sub_a139f4ab7ca5aa909"],
-    });
-    expect(result).toEqual([]);
-  });
-
-  it("handles multiple NLM tool calls in one turn", () => {
-    const result = detectCitations({
-      responseText: "",
-      toolUses: [
-        {
-          name: "mcp__nlm-memory__get_session",
-          input: { id: "cc_sub_a139f4ab7ca5aa909" },
-        },
-        {
-          name: "mcp__nlm-memory__get_session",
-          input: { id: "hm_20260427_6ff562" },
-        },
-      ],
-      surfacedIds: [
-        "cc_sub_a139f4ab7ca5aa909",
-        "hm_20260427_6ff562",
-        "cc_unused_id_xyz",
-      ],
-    });
-    expect(result.map((c) => c.id).sort()).toEqual(
-      ["cc_sub_a139f4ab7ca5aa909", "hm_20260427_6ff562"].sort(),
-    );
-    expect(result.every((c) => c.kind === "tool_use")).toBe(true);
-  });
-
-  it("recognizes recall_sessions tool calls with query+limit (no direct id) — does not emit when no ID present in input", () => {
-    const result = detectCitations({
-      responseText: "",
-      toolUses: [
-        {
-          name: "mcp__nlm-memory__recall_sessions",
-          input: { query: "FTS5 vs pgvector", limit: 5 },
-        },
-      ],
-      surfacedIds: ["cc_sub_a139f4ab7ca5aa909"],
-    });
-    expect(result).toEqual([]);
-  });
-});

package/tests/unit/core/hook/gate.test.ts

@@ -1,29 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { classifyPrompt } from "../../../../src/core/hook/gate.js";
-
-describe("classifyPrompt", () => {
-  it("classifies obvious generative openers as generative", () => {
-    expect(classifyPrompt("draft a LinkedIn post about FTS5")).toBe("generative");
-    expect(classifyPrompt("write the migration")).toBe("generative");
-    expect(classifyPrompt("brainstorm names for the feature")).toBe("generative");
-    expect(classifyPrompt("Create a test file")).toBe("generative");
-  });
-
-  it("classifies retrospective prompts as evaluate", () => {
-    expect(classifyPrompt("what did we decide about pgvector")).toBe("evaluate");
-    expect(classifyPrompt("have I worked with this client before")).toBe("evaluate");
-    expect(classifyPrompt("why is the recall backend returning zero results")).toBe("evaluate");
-  });
-
-  it("strips leading filler before checking the opener", () => {
-    expect(classifyPrompt("can you write a script")).toBe("generative");
-    expect(classifyPrompt("please draft the email")).toBe("generative");
-    expect(classifyPrompt("could you tell me what we decided")).toBe("evaluate");
-  });
-
-  it("defaults to evaluate for empty or ambiguous prompts", () => {
-    expect(classifyPrompt("")).toBe("evaluate");
-    expect(classifyPrompt("the FTS5 work")).toBe("evaluate");
-    expect(classifyPrompt("fix the failing test")).toBe("evaluate");
-  });
-});

package/tests/unit/core/hook/pointer-block.test.ts

@@ -1,22 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { formatPointerBlock } from "../../../../src/core/hook/pointer-block.js";
-
-describe("formatPointerBlock", () => {
-  it("returns an empty string for no hits", () => {
-    expect(formatPointerBlock([])).toBe("");
-  });
-
-  it("renders a header, one line per hit, and the tool footer", () => {
-    const block = formatPointerBlock([
-      { id: "sess_a", label: "FTS5 vs pgvector decision", startedAt: "2026-05-15T10:00:00.000Z" },
-      { id: "sess_b", label: "Semantic recall via sqlite-vec", startedAt: "2026-05-17T09:30:00.000Z" },
-    ]);
-    expect(block).toContain("## Possibly-relevant prior sessions (nlm-memory)");
-    expect(block).toContain("- sess_a · FTS5 vs pgvector decision (2026-05-15)");
-    expect(block).toContain("- sess_b · Semantic recall via sqlite-vec (2026-05-17)");
-    expect(block).toContain("recall_sessions");
-    expect(block).toContain("get_session");
-    expect(block).toContain("recall_facts");
-    expect(block).toContain("get_fact_history");
-  });
-});

package/tests/unit/core/hook/select.test.ts

@@ -1,66 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { selectHits, type RecallHitInput } from "../../../../src/core/hook/select.js";
-
-const hit = (id: string, matchScore: number): RecallHitInput => ({
-  id,
-  label: `label ${id}`,
-  startedAt: "2026-05-15T10:00:00.000Z",
-  matchScore,
-});
-
-describe("selectHits", () => {
-  it("drops hits below the score threshold", () => {
-    const out = selectHits({
-      hits: [hit("a", 0.9), hit("b", 0.3)],
-      surfaced: new Set(),
-      scoreThreshold: 0.5,
-      perFireCap: 3,
-      perConversationCap: 10,
-    });
-    expect(out.map((h) => h.id)).toEqual(["a"]);
-  });
-
-  it("drops hits already surfaced in this conversation", () => {
-    const out = selectHits({
-      hits: [hit("a", 0.9), hit("b", 0.8)],
-      surfaced: new Set(["a"]),
-      scoreThreshold: 0.5,
-      perFireCap: 3,
-      perConversationCap: 10,
-    });
-    expect(out.map((h) => h.id)).toEqual(["b"]);
-  });
-
-  it("caps the number surfaced per fire", () => {
-    const out = selectHits({
-      hits: [hit("a", 0.9), hit("b", 0.8), hit("c", 0.7), hit("d", 0.6)],
-      surfaced: new Set(),
-      scoreThreshold: 0.5,
-      perFireCap: 3,
-      perConversationCap: 10,
-    });
-    expect(out.map((h) => h.id)).toEqual(["a", "b", "c"]);
-  });
-
-  it("respects the remaining per-conversation budget", () => {
-    const out = selectHits({
-      hits: [hit("a", 0.9), hit("b", 0.8), hit("c", 0.7)],
-      surfaced: new Set(["x", "y", "z", "p", "q", "r", "s", "t", "u"]), // 9 surfaced
-      scoreThreshold: 0.5,
-      perFireCap: 3,
-      perConversationCap: 10,
-    });
-    expect(out.map((h) => h.id)).toEqual(["a"]); // only 1 slot left
-  });
-
-  it("returns nothing when the per-conversation cap is already met", () => {
-    const out = selectHits({
-      hits: [hit("a", 0.9)],
-      surfaced: new Set(Array.from({ length: 10 }, (_, i) => `s${i}`)),
-      scoreThreshold: 0.5,
-      perFireCap: 3,
-      perConversationCap: 10,
-    });
-    expect(out).toEqual([]);
-  });
-});

package/tests/unit/core/match-fields.test.ts

@@ -1,39 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { keywordMatchFields } from "../../../src/core/recall/match-fields.js";
-import { tokenSet } from "../../../src/core/recall/tokenize.js";
-import { makeSession } from "../../fixtures/sessions.js";
-
-describe("keywordMatchFields", () => {
-  it("returns no fields for empty query tokens", () => {
-    expect(keywordMatchFields(makeSession({ label: "anything" }), new Set())).toEqual([]);
-  });
-
-  it("reports the label field on a label match", () => {
-    const session = makeSession({ label: "pgvector migration plan" });
-    expect(keywordMatchFields(session, tokenSet("pgvector"))).toEqual(["label"]);
-  });
-
-  it("reports decisions and open from marker text", () => {
-    const session = makeSession({
-      decisions: ["picked Hono for HTTP"],
-      open: ["whether to use Tauri later"],
-    });
-    expect(keywordMatchFields(session, tokenSet("Hono"))).toEqual(["decisions"]);
-    expect(keywordMatchFields(session, tokenSet("Tauri"))).toEqual(["open"]);
-  });
-
-  it("reports every matching field in label, decisions, open, summary order", () => {
-    const session = makeSession({
-      label: "recall port",
-      summary: "ported recall to TypeScript",
-      decisions: ["use sqlite-vec for semantic recall"],
-      open: ["recall stats endpoint"],
-    });
-    expect(keywordMatchFields(session, tokenSet("recall"))).toEqual([
-      "label",
-      "decisions",
-      "open",
-      "summary",
-    ]);
-  });
-});

package/tests/unit/core/mcp-cite-session.test.ts

@@ -1,51 +0,0 @@
-/**
- * citeSessionHandler unit tests. Exercises the MCP tool handler directly
- * without a transport or store dependency — appendCitation writes to a tmp
- * file so we can verify the entry was written.
- */
-
-import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import { afterEach, beforeEach, describe, expect, it } from "vitest";
-import { citeSessionHandler } from "../../../src/mcp/server.js";
-
-describe("citeSessionHandler", () => {
-  let tmp: string;
-
-  beforeEach(() => {
-    tmp = mkdtempSync(join(tmpdir(), "nlm-cite-session-"));
-  });
-
-  afterEach(() => {
-    rmSync(tmp, { recursive: true, force: true });
-  });
-
-  it("returns logged:true for a valid id", async () => {
-    const result = await citeSessionHandler({ id: "cc_sub_abc123def456" });
-    expect(result.isError).toBeFalsy();
-    const parsed = JSON.parse(result.content[0]!.text) as Record<string, unknown>;
-    expect(parsed["logged"]).toBe(true);
-    expect(parsed["id"]).toBe("cc_sub_abc123def456");
-  });
-
-  it("returns an error for an id that is too short", async () => {
-    const result = await citeSessionHandler({ id: "short" });
-    expect(result.isError).toBe(true);
-    expect(result.content[0]!.text).toContain("Error");
-  });
-
-  it("returns an error for an empty id", async () => {
-    const result = await citeSessionHandler({ id: "" });
-    expect(result.isError).toBe(true);
-  });
-
-  it("accepts optional conversation_id and reason without error", async () => {
-    const result = await citeSessionHandler({
-      id: "cc_sub_abc123def456",
-      conversation_id: "conv_test_001",
-      reason: "Used to confirm FTS5 choice.",
-    });
-    expect(result.isError).toBeFalsy();
-  });
-});