nlm-memory 0.4.2 → 0.5.1

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();
-  });
-});

package/tests/unit/core/providers/provider-models.test.ts

@@ -1,101 +0,0 @@
-/**
- * provider-models — live model discovery across provider kinds.
- *
- * Mocked fetch so the suite doesn't depend on Ollama/OpenAI being up.
- * Real connectivity is covered by the connection-test endpoint in
- * integration tests, not here.
- */
-
-import { describe, expect, it, vi } from "vitest";
-import { listModels } from "../../../../src/core/providers/provider-models.js";
-import type { ProviderRow } from "../../../../src/core/providers/provider-registry.js";
-
-function row(overrides: Partial<ProviderRow>): ProviderRow {
-  return {
-    id: 1, kind: "ollama", name: "test", baseUrl: "http://localhost:11434",
-    apiKey: null, hasApiKey: false, defaultModel: null, enabled: true,
-    createdAt: "", updatedAt: "",
-    ...overrides,
-  };
-}
-
-function jsonResponse(body: unknown, status = 200): Response {
-  return new Response(JSON.stringify(body), {
-    status,
-    headers: { "content-type": "application/json" },
-  });
-}
-
-describe("listModels", () => {
-  it("returns hardcoded list for deepseek without hitting network", async () => {
-    const fetchImpl = vi.fn();
-    const models = await listModels(row({ kind: "deepseek", baseUrl: "https://api.deepseek.com" }), { fetchImpl });
-    expect(models).toContain("deepseek-v4-flash");
-    expect(fetchImpl).not.toHaveBeenCalled();
-  });
-
-  it("returns hardcoded list for anthropic without hitting network", async () => {
-    const fetchImpl = vi.fn();
-    const models = await listModels(row({ kind: "anthropic", baseUrl: "https://api.anthropic.com" }), { fetchImpl });
-    expect(models.length).toBeGreaterThan(0);
-    expect(fetchImpl).not.toHaveBeenCalled();
-  });
-
-  it("hits Ollama /api/tags and sorts results", async () => {
-    const fetchImpl = vi.fn().mockResolvedValue(jsonResponse({
-      models: [{ name: "phi4-mini:latest" }, { name: "llama3.2:3b" }, { name: "mistral:7b" }],
-    }));
-    const models = await listModels(row({ kind: "ollama" }), { fetchImpl });
-    expect(models).toEqual(["llama3.2:3b", "mistral:7b", "phi4-mini:latest"]);
-    expect(fetchImpl).toHaveBeenCalledOnce();
-    expect((fetchImpl.mock.calls[0]?.[0] as string).endsWith("/api/tags")).toBe(true);
-  });
-
-  it("hits OpenAI /models with Bearer key", async () => {
-    const fetchImpl = vi.fn().mockResolvedValue(jsonResponse({
-      data: [{ id: "gpt-4o" }, { id: "gpt-4o-mini" }],
-    }));
-    const models = await listModels(
-      row({ kind: "openai", baseUrl: "https://api.openai.com/v1" }),
-      { fetchImpl, apiKey: "sk-test" },
-    );
-    expect(models).toEqual(["gpt-4o", "gpt-4o-mini"]);
-    const init = fetchImpl.mock.calls[0]?.[1] as RequestInit;
-    expect((init.headers as Record<string, string>)["Authorization"]).toBe("Bearer sk-test");
-  });
-
-  it("hits OpenRouter the same way as OpenAI", async () => {
-    const fetchImpl = vi.fn().mockResolvedValue(jsonResponse({
-      data: [{ id: "anthropic/claude-haiku-4-5" }],
-    }));
-    const models = await listModels(
-      row({ kind: "openrouter", baseUrl: "https://openrouter.ai/api/v1" }),
-      { fetchImpl, apiKey: "or-key" },
-    );
-    expect(models).toEqual(["anthropic/claude-haiku-4-5"]);
-  });
-
-  it("openai-compatible omits Authorization when no key", async () => {
-    const fetchImpl = vi.fn().mockResolvedValue(jsonResponse({ data: [{ id: "local-model" }] }));
-    await listModels(
-      row({ kind: "openai-compatible", baseUrl: "http://192.168.1.50:8000/v1" }),
-      { fetchImpl, apiKey: null },
-    );
-    const init = fetchImpl.mock.calls[0]?.[1] as RequestInit;
-    expect((init.headers as Record<string, string>)["Authorization"]).toBeUndefined();
-  });
-
-  it("propagates HTTP errors as thrown messages", async () => {
-    const fetchImpl = vi.fn().mockResolvedValue(new Response("nope", { status: 401, statusText: "Unauthorized" }));
-    await expect(listModels(
-      row({ kind: "openai", baseUrl: "https://api.openai.com/v1" }),
-      { fetchImpl, apiKey: "bad" },
-    )).rejects.toThrow(/401/);
-  });
-
-  it("throws when baseUrl is missing for live-discovery kinds", async () => {
-    const fetchImpl = vi.fn();
-    await expect(listModels(row({ kind: "ollama", baseUrl: null }), { fetchImpl }))
-      .rejects.toThrow(/baseUrl/);
-  });
-});

package/tests/unit/core/query-shape.test.ts

@@ -1,92 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { detectQueryShape } from "../../../src/core/recall/query-shape.js";
-
-describe("detectQueryShape", () => {
-  it("returns false/false for empty query", () => {
-    expect(detectQueryShape("")).toEqual({ hasTemporal: false, hasNamedEntity: false });
-  });
-
-  describe("Real LongMemEval temporal queries that should fire the boost", () => {
-    const cases: ReadonlyArray<string> = [
-      "How many days ago did I meet Emma?",
-      "How many days ago did I watch the Super Bowl?",
-      "How many months ago did I book the Airbnb in San Francisco?",
-      "When did I book the Airbnb in Sacramento?",
-      "How many days before I bought my iPad did I attend the Holiday Market?",
-      "How many weeks ago did I attend the friends and family sale at Nordstrom?",
-      "How many months ago did I attend the Seattle International Film Festival?",
-      "How many days ago did I attend the Maundy Thursday service at the Episcopal Church?",
-    ];
-    for (const q of cases) {
-      it(`fires on: ${q.slice(0, 50)}...`, () => {
-        const shape = detectQueryShape(q);
-        expect(shape.hasTemporal).toBe(true);
-        expect(shape.hasNamedEntity).toBe(true);
-      });
-    }
-  });
-
-  describe("Temporal queries without named entities (must NOT fire)", () => {
-    const cases: ReadonlyArray<string> = [
-      "Which book did I finish a week ago?",
-      "Who did I meet at lunch last Tuesday?",
-      "sports event two weeks ago",
-      "gardening-related activity two weeks ago",
-      "art-related event two weeks ago",
-      "order of three sports events past month",
-    ];
-    for (const q of cases) {
-      it(`temporal=true, entity=false on: ${q.slice(0, 50)}...`, () => {
-        const shape = detectQueryShape(q);
-        expect(shape.hasNamedEntity).toBe(false);
-      });
-    }
-  });
-
-  describe("Non-temporal queries", () => {
-    it("plain semantic query has no temporal trigger", () => {
-      expect(detectQueryShape("what is my favorite color").hasTemporal).toBe(false);
-    });
-
-    it("named entity without temporal does not fire combined boost", () => {
-      const shape = detectQueryShape("tell me about Nordstrom");
-      expect(shape.hasTemporal).toBe(false);
-      expect(shape.hasNamedEntity).toBe(true);
-    });
-
-    it("sentence-start capitalization alone is not a named entity", () => {
-      const shape = detectQueryShape("Yesterday I went shopping");
-      expect(shape.hasTemporal).toBe(true);
-      expect(shape.hasNamedEntity).toBe(false);
-    });
-
-    it("day-of-week tokens are not named entities", () => {
-      expect(detectQueryShape("did I meet last Tuesday with someone").hasNamedEntity).toBe(false);
-    });
-
-    it("month-name tokens are not named entities", () => {
-      expect(detectQueryShape("in June I went to a thing").hasNamedEntity).toBe(false);
-    });
-  });
-
-  describe("Edge cases", () => {
-    it("ALL-CAPS acronyms count as named entities", () => {
-      const shape = detectQueryShape("how many days ago did I visit NYC");
-      expect(shape.hasNamedEntity).toBe(true);
-      expect(shape.hasTemporal).toBe(true);
-    });
-
-    it("single capital letter does not count", () => {
-      expect(detectQueryShape("yesterday I went out").hasNamedEntity).toBe(false);
-    });
-
-    it("hyphenated proper noun counts", () => {
-      expect(detectQueryShape("two weeks ago I visited Coca-Cola").hasNamedEntity).toBe(true);
-    });
-
-    it("camelCase / PascalCase product names count (iPad, FarmFresh)", () => {
-      expect(detectQueryShape("how many days ago did I buy my iPad").hasNamedEntity).toBe(true);
-      expect(detectQueryShape("did I shop at FarmFresh last week").hasNamedEntity).toBe(true);
-    });
-  });
-});

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

@@ -1,258 +0,0 @@
-/**
- * FactRecallService unit tests against an in-memory FactStore + fake LLM.
- * Mirrors the recall-service.test.ts pattern.
- */
-
-import { describe, expect, it } from "vitest";
-import { FactRecallService } from "../../../../src/core/recall-facts/fact-recall-service.js";
-import type {
-  FactListFilter,
-  FactSemanticNeighbor,
-  FactStore,
-} from "../../../../src/ports/fact-store.js";
-import type { EmbedResult, LLMClient } from "../../../../src/ports/llm-client.js";
-import { LLMUnreachableError } from "../../../../src/ports/llm-client.js";
-import type { Fact, FactHistoryChain } from "../../../../src/shared/types.js";
-import { makeFact } from "../../../fixtures/facts.js";
-
-class InMemoryFactStore implements FactStore {
-  constructor(
-    private readonly facts: Fact[],
-    private readonly neighbors: FactSemanticNeighbor[] = [],
-  ) {}
-  async insert(): Promise<void> {}
-  async insertMany(): Promise<void> {}
-  async getById(id: string): Promise<Fact | null> {
-    return this.facts.find((f) => f.id === id) ?? null;
-  }
-  async findCurrent(subject: string, predicate: string): Promise<Fact | null> {
-    return this.facts.find(
-      (f) =>
-        f.subject === subject &&
-        f.predicate === predicate &&
-        f.supersededBy === null,
-    ) ?? null;
-  }
-  async list(): Promise<ReadonlyArray<Fact>> {
-    return this.facts;
-  }
-  async listBySession(): Promise<ReadonlyArray<Fact>> {
-    return this.facts;
-  }
-  async markSuperseded(): Promise<void> {}
-  async listForRecall(filter: FactListFilter): Promise<ReadonlyArray<Fact>> {
-    return this.facts.filter((f) => {
-      if (filter.subject !== undefined && f.subject !== filter.subject) return false;
-      if (filter.predicate !== undefined && f.predicate !== filter.predicate) return false;
-      if (filter.kind !== undefined && f.kind !== filter.kind) return false;
-      if (filter.minConfidence !== undefined && f.confidence < filter.minConfidence) return false;
-      if (filter.includeSuperseded !== true && f.supersededBy !== null) return false;
-      return true;
-    });
-  }
-  async semanticSearch(): Promise<ReadonlyArray<FactSemanticNeighbor>> {
-    return this.neighbors;
-  }
-  async getHistory(): Promise<ReadonlyArray<FactHistoryChain>> {
-    return [];
-  }
-}
-
-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: Fact[] = [
-  makeFact({
-    id: "f_hono",
-    kind: "decision",
-    subject: "nlm-memory-ts",
-    predicate: "framework",
-    value: "Hono",
-    confidence: 0.9,
-  }),
-  makeFact({
-    id: "f_endpoint",
-    kind: "attribute",
-    subject: "mac-pro-llm-host",
-    predicate: "endpoint",
-    value: "http://macpro:8080/v1",
-    confidence: 0.85,
-  }),
-  makeFact({
-    id: "f_model",
-    kind: "attribute",
-    subject: "mac-pro-llm-host",
-    predicate: "model",
-    value: "qwen2.5-3b",
-    confidence: 0.8,
-  }),
-  makeFact({
-    id: "f_lowconf",
-    kind: "decision",
-    subject: "other",
-    predicate: "framework",
-    value: "Hono",
-    confidence: 0.5,
-  }),
-  makeFact({
-    id: "f_superseded",
-    kind: "decision",
-    subject: "nlm-memory-ts",
-    predicate: "framework",
-    value: "Fastify",
-    confidence: 0.9,
-    supersededBy: "f_hono",
-  }),
-];
-
-describe("FactRecallService.search (keyword)", () => {
-  it("returns empty when no query and no structured filter", async () => {
-    const svc = new FactRecallService({
-      factStore: new InMemoryFactStore(corpus),
-      llm: new StubEmbedder(),
-    });
-    const result = await svc.search({});
-    expect(result.total).toBe(0);
-    expect(result.results).toEqual([]);
-  });
-
-  it("exact subject + predicate returns current fact (no query text)", async () => {
-    const svc = new FactRecallService({
-      factStore: new InMemoryFactStore(corpus),
-      llm: new StubEmbedder(),
-    });
-    const result = await svc.search({
-      subject: "nlm-memory-ts",
-      predicate: "framework",
-    });
-    expect(result.total).toBe(1);
-    expect(result.results[0]?.id).toBe("f_hono");
-    expect(result.results[0]?.value).toBe("Hono");
-  });
-
-  it("excludes superseded facts by default", async () => {
-    const svc = new FactRecallService({
-      factStore: new InMemoryFactStore(corpus),
-      llm: new StubEmbedder(),
-    });
-    const result = await svc.search({ subject: "nlm-memory-ts" });
-    expect(result.results.map((r) => r.id)).toEqual(["f_hono"]);
-  });
-
-  it("includeSuperseded=true returns the full chain", async () => {
-    const svc = new FactRecallService({
-      factStore: new InMemoryFactStore(corpus),
-      llm: new StubEmbedder(),
-    });
-    const result = await svc.search({
-      subject: "nlm-memory-ts",
-      includeSuperseded: true,
-    });
-    expect(result.results.map((r) => r.id).sort()).toEqual(["f_hono", "f_superseded"]);
-  });
-
-  it("default minConfidence (0.6) drops low-confidence facts", async () => {
-    const svc = new FactRecallService({
-      factStore: new InMemoryFactStore(corpus),
-      llm: new StubEmbedder(),
-    });
-    const result = await svc.search({ predicate: "framework" });
-    // f_lowconf has confidence 0.5; f_hono has 0.9; f_superseded is dropped
-    expect(result.results.map((r) => r.id)).toEqual(["f_hono"]);
-  });
-
-  it("explicit minConfidence override widens the result set", async () => {
-    const svc = new FactRecallService({
-      factStore: new InMemoryFactStore(corpus),
-      llm: new StubEmbedder(),
-    });
-    const result = await svc.search({ predicate: "framework", minConfidence: 0.4 });
-    expect(result.results.map((r) => r.id).sort()).toEqual(["f_hono", "f_lowconf"]);
-  });
-
-  it("free-text query scores against value, subject, predicate", async () => {
-    const svc = new FactRecallService({
-      factStore: new InMemoryFactStore(corpus),
-      llm: new StubEmbedder(),
-    });
-    const result = await svc.search({ query: "Hono" });
-    expect(result.results[0]?.id).toBe("f_hono");
-    expect(result.results[0]?.matchedIn).toContain("value");
-  });
-
-  it("kind filter narrows to attribute / decision / open", async () => {
-    const svc = new FactRecallService({
-      factStore: new InMemoryFactStore(corpus),
-      llm: new StubEmbedder(),
-    });
-    const result = await svc.search({ kind: "attribute" });
-    expect(result.results.map((r) => r.id).sort()).toEqual(["f_endpoint", "f_model"]);
-  });
-
-  it("limit caps the result count", async () => {
-    const svc = new FactRecallService({
-      factStore: new InMemoryFactStore(corpus),
-      llm: new StubEmbedder(),
-    });
-    const result = await svc.search({ kind: "attribute", limit: 1 });
-    expect(result.results).toHaveLength(1);
-  });
-});
-
-describe("FactRecallService.search (semantic)", () => {
-  it("uses sqlite-vec neighbors to rank candidates", async () => {
-    const neighbors: FactSemanticNeighbor[] = [
-      { factId: "f_endpoint", distance: 0.2 },
-      { factId: "f_model", distance: 0.6 },
-    ];
-    const svc = new FactRecallService({
-      factStore: new InMemoryFactStore(corpus, neighbors),
-      llm: new StubEmbedder(),
-    });
-    const result = await svc.search({ query: "where does the LLM run", mode: "semantic" });
-    expect(result.results[0]?.id).toBe("f_endpoint");
-    expect(result.results[0]?.matchedIn).toEqual(["semantic"]);
-  });
-
-  it("LLM unreachable surfaces as modeUnavailable, not an exception", async () => {
-    const svc = new FactRecallService({
-      factStore: new InMemoryFactStore(corpus),
-      llm: new StubEmbedder(true),
-    });
-    const result = await svc.search({ query: "anything", mode: "semantic" });
-    expect(result.modeUnavailable).toBe("ollama_unreachable");
-    expect(result.total).toBe(0);
-  });
-});
-
-describe("FactRecallService.search (hybrid)", () => {
-  it("merges keyword + semantic scores with 0.4/0.6 weights", async () => {
-    const neighbors: FactSemanticNeighbor[] = [
-      { factId: "f_endpoint", distance: 0.1 },
-      { factId: "f_hono", distance: 1.4 },
-    ];
-    const svc = new FactRecallService({
-      factStore: new InMemoryFactStore(corpus, neighbors),
-      llm: new StubEmbedder(),
-    });
-    const result = await svc.search({ query: "Hono", mode: "hybrid" });
-    // Result should include both. Top result depends on weights — keyword
-    // scores "Hono" strongly for f_hono; semantic scores f_endpoint strongly.
-    const ids = result.results.map((r) => r.id);
-    expect(ids).toContain("f_hono");
-    expect(ids).toContain("f_endpoint");
-    // Hybrid hits expose both subscores.
-    for (const hit of result.results) {
-      expect(hit.keywordScore).toBeDefined();
-      expect(hit.semanticScore).toBeDefined();
-    }
-  });
-});