nlm-memory 0.5.0 → 0.5.2

package/src/core/hook/memo.ts

@@ -1,67 +0,0 @@
-/**
- * Per-conversation dedup memo for the recall hook. One JSON file per
- * conversation holds the set of session ids already surfaced, so each is
- * surfaced at most once per conversation.
- *
- * State dir defaults to ~/.nlm/hook-state/, overridable via
- * NLM_HOOK_STATE_DIR (testability — mirrors query-log.ts).
- *
- * Every function is defensive: a missing or corrupt file yields an empty
- * memo, and a write failure is swallowed. The hook must never break on memo
- * I/O.
- */
-
-import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
-import { homedir } from "node:os";
-import { join } from "node:path";
-
-function stateDir(): string {
-  return process.env["NLM_HOOK_STATE_DIR"] ?? join(homedir(), ".nlm", "hook-state");
-}
-
-function memoPath(conversationId: string): string {
-  const safe = conversationId.replace(/[^A-Za-z0-9_-]/g, "_") || "unknown";
-  return join(stateDir(), `${safe}.json`);
-}
-
-export function loadSurfaced(conversationId: string): Set<string> {
-  try {
-    const path = memoPath(conversationId);
-    if (!existsSync(path)) return new Set();
-    const parsed: unknown = JSON.parse(readFileSync(path, "utf8"));
-    if (!Array.isArray(parsed)) return new Set();
-    return new Set(parsed.filter((x): x is string => typeof x === "string"));
-  } catch {
-    return new Set();
-  }
-}
-
-export function recordSurfaced(
-  conversationId: string,
-  ids: ReadonlyArray<string>,
-): void {
-  try {
-    const merged = loadSurfaced(conversationId);
-    for (const id of ids) merged.add(id);
-    mkdirSync(stateDir(), { recursive: true });
-    writeFileSync(memoPath(conversationId), JSON.stringify([...merged]), "utf8");
-  } catch {
-    // Memo write failure must never break the hook.
-  }
-}
-
-/**
- * Delete the memo file for a closed conversation. Called by the SessionEnd
- * hook so memo files don't accumulate forever. Returns true if a file was
- * removed, false otherwise — callers may want to log the outcome.
- */
-export function clearSurfaced(conversationId: string): boolean {
-  try {
-    const path = memoPath(conversationId);
-    if (!existsSync(path)) return false;
-    rmSync(path);
-    return true;
-  } catch {
-    return false;
-  }
-}

package/src/core/hook/pointer-block.ts

@@ -1,26 +0,0 @@
-/**
- * Renders the pointer block injected by the recall hook in live mode. Pure.
- * Pointer-only by design: ids + labels, no session content. The footer
- * names all four NLM MCP tools because the pointer block is the only
- * cross-runtime distribution surface for teaching the tool inventory —
- * fresh-install users never edit a prompt or settings file, so anything
- * we want the agent to know about the tool surface ships here.
- */
-
-export interface PointerHit {
-  readonly id: string;
-  readonly label: string;
-  readonly startedAt: string;
-}
-
-export function formatPointerBlock(hits: ReadonlyArray<PointerHit>): string {
-  if (hits.length === 0) return "";
-  const lines = hits.map(
-    (h) => `- ${h.id} · ${h.label} (${h.startedAt.slice(0, 10)})`,
-  );
-  return [
-    "## Possibly-relevant prior sessions (nlm-memory)",
-    ...lines,
-    "NLM tools: recall_sessions (search), get_session (full transcript), recall_facts (prior decisions), get_fact_history (how a decision evolved).",
-  ].join("\n");
-}

package/src/core/hook/select.ts

@@ -1,32 +0,0 @@
-/**
- * Selects which recall hits the hook surfaces. Pure — no I/O.
- *
- * Order of filtering: score threshold, then dedup against ids already
- * surfaced in this conversation, then the per-fire cap bounded by the
- * remaining per-conversation budget. Hits are assumed pre-ranked best-first.
- */
-
-export interface RecallHitInput {
-  readonly id: string;
-  readonly label: string;
-  readonly startedAt: string;
-  readonly matchScore: number;
-}
-
-export interface SelectParams {
-  readonly hits: ReadonlyArray<RecallHitInput>;
-  readonly surfaced: ReadonlySet<string>;
-  readonly scoreThreshold: number;
-  readonly perFireCap: number;
-  readonly perConversationCap: number;
-}
-
-export function selectHits(params: SelectParams): ReadonlyArray<RecallHitInput> {
-  const { hits, surfaced, scoreThreshold, perFireCap, perConversationCap } = params;
-  const eligible = hits.filter(
-    (h) => h.matchScore >= scoreThreshold && !surfaced.has(h.id),
-  );
-  const budget = Math.max(0, perConversationCap - surfaced.size);
-  const limit = Math.min(perFireCap, budget);
-  return eligible.slice(0, limit);
-}

package/src/core/hook/transcript.ts

@@ -1,121 +0,0 @@
-/**
- * Read assistant messages from a Claude Code transcript JSONL.
- *
- * Claude Code passes `transcript_path` in the Stop hook payload. Each line is
- * a JSON object; assistant turns have `type:"assistant"` and a `message`
- * object whose `content` is an array of blocks (`{type:"text", text:...}` for
- * prose; `{type:"tool_use", name, input}` for tool invocations).
- *
- * Stop-hook citation detection needs the union of ALL assistant turns in the
- * transcript, not just the last one: the model typically calls a tool, reads
- * the result on the next user turn (tool_result), then writes a prose summary
- * as a separate assistant turn. Scanning only the last turn misses the
- * tool_use entirely. `readAllAssistantTurns` returns every assistant turn in
- * order so the detector can fire across the whole conversation; cross-firing
- * dedup happens upstream via the per-conversation cited memo.
- *
- * Fail-quiet: a malformed file yields nulls/empty rather than throwing —
- * the Stop hook must never break on transcript I/O.
- */
-
-import { existsSync, readFileSync } from "node:fs";
-
-interface ContentBlock {
-  readonly type: string;
-  readonly text?: string;
-  readonly name?: string;
-  readonly input?: unknown;
-}
-interface AssistantMessage {
-  readonly content?: ReadonlyArray<ContentBlock> | string;
-}
-interface TranscriptLine {
-  readonly type?: string;
-  readonly message?: AssistantMessage;
-}
-
-export interface ToolUseBlock {
-  readonly name: string;
-  readonly input: unknown;
-}
-
-export interface AssistantTurn {
-  readonly text: string;
-  readonly toolUses: ReadonlyArray<ToolUseBlock>;
-}
-
-const EMPTY_TURN: AssistantTurn = { text: "", toolUses: [] };
-
-function parseTurn(parsed: TranscriptLine): AssistantTurn | null {
-  if (parsed.type !== "assistant" || !parsed.message) return null;
-  const content = parsed.message.content;
-  if (typeof content === "string") {
-    return content ? { text: content, toolUses: [] } : null;
-  }
-  if (!Array.isArray(content)) return null;
-  const textParts: string[] = [];
-  const toolUses: ToolUseBlock[] = [];
-  for (const block of content) {
-    if (block.type === "text" && typeof block.text === "string") {
-      textParts.push(block.text);
-    } else if (block.type === "tool_use" && typeof block.name === "string") {
-      toolUses.push({ name: block.name, input: block.input });
-    }
-  }
-  if (textParts.length === 0 && toolUses.length === 0) return null;
-  return { text: textParts.join("\n"), toolUses };
-}
-
-function readLines(transcriptPath: string): string[] | null {
-  if (!transcriptPath || !existsSync(transcriptPath)) return null;
-  try {
-    return readFileSync(transcriptPath, "utf8").split("\n");
-  } catch {
-    return null;
-  }
-}
-
-export function readAllAssistantTurns(
-  transcriptPath: string,
-): ReadonlyArray<AssistantTurn> {
-  const lines = readLines(transcriptPath);
-  if (!lines) return [];
-  const turns: AssistantTurn[] = [];
-  for (const raw of lines) {
-    const line = raw.trim();
-    if (!line) continue;
-    let parsed: TranscriptLine;
-    try {
-      parsed = JSON.parse(line) as TranscriptLine;
-    } catch {
-      continue;
-    }
-    const turn = parseTurn(parsed);
-    if (turn) turns.push(turn);
-  }
-  return turns;
-}
-
-export function readLastAssistantTurn(transcriptPath: string): AssistantTurn {
-  const lines = readLines(transcriptPath);
-  if (!lines) return EMPTY_TURN;
-  for (let i = lines.length - 1; i >= 0; i--) {
-    const line = lines[i]?.trim();
-    if (!line) continue;
-    let parsed: TranscriptLine;
-    try {
-      parsed = JSON.parse(line) as TranscriptLine;
-    } catch {
-      continue;
-    }
-    const turn = parseTurn(parsed);
-    if (turn) return turn;
-  }
-  return EMPTY_TURN;
-}
-
-/** Back-compat shim for callers that only need prose. */
-export function readLastAssistantText(transcriptPath: string): string | null {
-  const turn = readLastAssistantTurn(transcriptPath);
-  return turn.text || null;
-}

package/src/core/ingest/ingest-session.ts

@@ -1,111 +0,0 @@
-/**
- * ingestSession — push a single externally-supplied session through the
- * normal classifier → embedder → store pipeline.
- *
- * Shared by the webhook endpoint (POST /api/ingest) and anything else
- * that wants to push without going through a TranscriptAdapter. Mirrors
- * the inner loop of ScanScheduler.runOnce but accepts a pre-built chunk.
- */
-
-import { createHash } from "node:crypto";
-import { extractFacts } from "@core/facts/extract-facts.js";
-import type { SqliteFactStore } from "@core/storage/sqlite-fact-store.js";
-import type { IngestRecord, SqliteSessionStore } from "@core/storage/sqlite-session-store.js";
-import type { LLMClient } from "@ports/llm-client.js";
-
-const BODY_CAP = 200_000;
-const CONFIDENCE_FLOOR = 0.3;
-
-export interface IngestInput {
-  /** Optional — if omitted, derived from a hash of (runtime + startedAt + text). */
-  readonly id?: string;
-  readonly runtime: string;
-  readonly runtimeSessionId?: string | null;
-  readonly text: string;
-  readonly startedAt?: string;
-  readonly endedAt?: string | null;
-  readonly transcriptPath?: string | null;
-  /** Webhook id when the source is webhook-pushed; null for generic. */
-  readonly sourceId?: number | null;
-}
-
-export interface IngestDeps {
-  readonly classifier: LLMClient;
-  readonly embedder: LLMClient;
-  readonly store: SqliteSessionStore;
-  readonly factStore?: SqliteFactStore;
-  /** Optional logger — defaults to console.error. */
-  readonly log?: (msg: string) => void;
-}
-
-export interface IngestResult {
-  readonly id: string;
-  readonly status: "ingested" | "low_confidence" | "classifier_failed";
-  readonly latencyMs: number;
-  readonly confidence?: number;
-  readonly error?: string;
-}
-
-export function deriveSessionId(runtime: string, startedAt: string, text: string): string {
-  const hash = createHash("sha256")
-    .update(runtime)
-    .update("|")
-    .update(startedAt)
-    .update("|")
-    .update(text.slice(0, 4_000))
-    .digest("hex")
-    .slice(0, 16);
-  return `webhook_${hash}`;
-}
-
-export async function ingestSession(input: IngestInput, deps: IngestDeps): Promise<IngestResult> {
-  const startedAt = input.startedAt ?? new Date().toISOString();
-  const id = input.id ?? deriveSessionId(input.runtime, startedAt, input.text);
-  const log = deps.log ?? ((m: string) => console.error(m));
-  const t0 = Date.now();
-
-  let classification;
-  try {
-    classification = await deps.classifier.classify(input.text);
-  } catch (e) {
-    const error = e instanceof Error ? e.message : String(e);
-    log(`[ingest] classifier failed for ${id}: ${error}`);
-    return { id, status: "classifier_failed", latencyMs: Date.now() - t0, error };
-  }
-
-  if (classification.confidence < CONFIDENCE_FLOOR) {
-    return {
-      id,
-      status: "low_confidence",
-      latencyMs: Date.now() - t0,
-      confidence: classification.confidence,
-    };
-  }
-
-  const record: IngestRecord = {
-    id,
-    runtime: input.runtime,
-    runtimeSessionId: input.runtimeSessionId ?? null,
-    startedAt,
-    endedAt: input.endedAt ?? null,
-    durationMin: null,
-    label: classification.label,
-    summary: classification.summary,
-    body: input.text.slice(0, BODY_CAP),
-    status: "closed",
-    transcriptKind: "webhook",
-    transcriptPath: input.transcriptPath ?? null,
-    transcriptOffset: null,
-    transcriptLength: null,
-    entities: classification.entities,
-    decisions: classification.decisions,
-    openQuestions: classification.open,
-  };
-
-  const factSink = deps.factStore
-    ? { factStore: deps.factStore, facts: extractFacts(classification, id, startedAt) }
-    : null;
-
-  await deps.store.insertSession(record, deps.embedder, null, factSink);
-  return { id, status: "ingested", latencyMs: Date.now() - t0, confidence: classification.confidence };
-}

package/src/core/providers/provider-models.ts

@@ -1,100 +0,0 @@
-/**
- * Provider model discovery — runtime lookup of available models.
- *
- * Per-kind strategy:
- *   - ollama:            GET {baseUrl}/api/tags
- *   - openai:            GET {baseUrl}/models with Bearer key
- *   - openrouter:        GET {baseUrl}/models with Bearer key
- *   - openai-compatible: GET {baseUrl}/models, key optional
- *   - deepseek:          hardcoded (no public list endpoint)
- *   - anthropic:         hardcoded (their /v1/models exists but
- *                         requires beta header + returns subsets;
- *                         a hardcoded list is more reliable)
- *
- * Returns a flat `string[]`. Errors throw — callers (the HTTP endpoint
- * and connection-test) catch and surface to the user.
- */
-
-import type { ProviderKind, ProviderRow } from "./provider-registry.js";
-
-export type FetchImpl = typeof fetch;
-
-const HARDCODED_MODELS: Partial<Record<ProviderKind, string[]>> = {
-  deepseek: ["deepseek-v4-flash", "deepseek-v4-pro", "deepseek-chat"],
-  anthropic: [
-    "claude-opus-4-7",
-    "claude-sonnet-4-6",
-    "claude-haiku-4-5-20251001",
-  ],
-};
-
-interface OllamaTagsResponse {
-  readonly models?: ReadonlyArray<{ readonly name?: string }>;
-}
-
-interface OpenAIModelsResponse {
-  readonly data?: ReadonlyArray<{ readonly id?: string }>;
-}
-
-export interface ListModelsOptions {
-  readonly apiKey?: string | null;
-  readonly fetchImpl?: FetchImpl;
-  readonly timeoutMs?: number;
-}
-
-export async function listModels(
-  provider: ProviderRow,
-  opts: ListModelsOptions = {},
-): Promise<string[]> {
-  const hardcoded = HARDCODED_MODELS[provider.kind];
-  if (hardcoded) return [...hardcoded];
-
-  const fetchImpl = opts.fetchImpl ?? fetch;
-  const timeoutMs = opts.timeoutMs ?? 10_000;
-  const baseUrl = (provider.baseUrl ?? "").replace(/\/+$/, "");
-  if (!baseUrl) throw new Error(`${provider.name}: baseUrl not configured`);
-
-  if (provider.kind === "ollama") {
-    return fetchOllamaModels(baseUrl, fetchImpl, timeoutMs);
-  }
-  return fetchOpenAIModels(baseUrl, opts.apiKey ?? null, fetchImpl, timeoutMs);
-}
-
-async function fetchOllamaModels(
-  baseUrl: string,
-  fetchImpl: FetchImpl,
-  timeoutMs: number,
-): Promise<string[]> {
-  const controller = new AbortController();
-  const timer = setTimeout(() => controller.abort(), timeoutMs);
-  try {
-    const res = await fetchImpl(`${baseUrl}/api/tags`, { signal: controller.signal });
-    if (!res.ok) throw new Error(`Ollama returned ${res.status}`);
-    const data = (await res.json()) as OllamaTagsResponse;
-    const names = (data.models ?? []).map((m) => m.name).filter((n): n is string => typeof n === "string");
-    return names.sort();
-  } finally {
-    clearTimeout(timer);
-  }
-}
-
-async function fetchOpenAIModels(
-  baseUrl: string,
-  apiKey: string | null,
-  fetchImpl: FetchImpl,
-  timeoutMs: number,
-): Promise<string[]> {
-  const controller = new AbortController();
-  const timer = setTimeout(() => controller.abort(), timeoutMs);
-  try {
-    const headers: Record<string, string> = {};
-    if (apiKey) headers["Authorization"] = `Bearer ${apiKey}`;
-    const res = await fetchImpl(`${baseUrl}/models`, { signal: controller.signal, headers });
-    if (!res.ok) throw new Error(`${res.status} ${res.statusText}`);
-    const data = (await res.json()) as OpenAIModelsResponse;
-    const ids = (data.data ?? []).map((m) => m.id).filter((s): s is string => typeof s === "string");
-    return ids.sort();
-  } finally {
-    clearTimeout(timer);
-  }
-}

package/src/core/providers/provider-registry.ts

@@ -1,196 +0,0 @@
-/**
- * ProviderRegistry — CRUD over the `providers` table.
- *
- * One row per LLM endpoint the user has configured. The classifier reads
- * this at boot to pick a provider/model; the UI lets users add their own.
- *
- * API keys live in the `api_key` column today. Phase 2 (Tauri shell)
- * migrates them to the OS keychain; the API shape stays identical so this
- * module's consumers don't change.
- *
- * `redact()` strips secrets on the way out — every HTTP response sends
- * redacted rows, with the key only retrievable via getSecret() inside the
- * daemon process.
- */
-
-import type Database from "better-sqlite3";
-
-export type ProviderKind =
-  | "deepseek"
-  | "ollama"
-  | "openai"
-  | "anthropic"
-  | "openrouter"
-  | "openai-compatible";
-
-export interface ProviderRow {
-  readonly id: number;
-  readonly kind: ProviderKind;
-  readonly name: string;
-  readonly baseUrl: string | null;
-  /** Always `null` on rows returned by `list()` / `get()`. Use `getSecret()`. */
-  readonly apiKey: string | null;
-  readonly hasApiKey: boolean;
-  readonly defaultModel: string | null;
-  readonly enabled: boolean;
-  readonly createdAt: string;
-  readonly updatedAt: string;
-}
-
-export interface ProviderInsert {
-  readonly kind: ProviderKind;
-  readonly name: string;
-  readonly baseUrl?: string | null;
-  readonly apiKey?: string | null;
-  readonly defaultModel?: string | null;
-  readonly enabled?: boolean;
-}
-
-export interface ProviderUpdate {
-  readonly name?: string;
-  readonly baseUrl?: string | null;
-  readonly apiKey?: string | null;
-  readonly defaultModel?: string | null;
-  readonly enabled?: boolean;
-}
-
-interface ProviderDbRow {
-  id: number;
-  kind: string;
-  name: string;
-  base_url: string | null;
-  api_key: string | null;
-  default_model: string | null;
-  enabled: number;
-  created_at: string;
-  updated_at: string;
-}
-
-function rowFromDb(r: ProviderDbRow, includeSecret: boolean): ProviderRow {
-  return {
-    id: r.id,
-    kind: r.kind as ProviderKind,
-    name: r.name,
-    baseUrl: r.base_url,
-    apiKey: includeSecret ? r.api_key : null,
-    hasApiKey: r.api_key !== null && r.api_key.length > 0,
-    defaultModel: r.default_model,
-    enabled: r.enabled === 1,
-    createdAt: r.created_at,
-    updatedAt: r.updated_at,
-  };
-}
-
-const DEFAULT_BASE_URLS: Record<ProviderKind, string | null> = {
-  deepseek: "https://api.deepseek.com",
-  ollama: "http://localhost:11434",
-  openai: "https://api.openai.com/v1",
-  anthropic: "https://api.anthropic.com",
-  openrouter: "https://openrouter.ai/api/v1",
-  "openai-compatible": null,
-};
-
-const DEFAULT_MODELS: Record<ProviderKind, string | null> = {
-  deepseek: "deepseek-v4-flash",
-  ollama: "phi4-mini:latest",
-  openai: "gpt-4o-mini",
-  anthropic: "claude-haiku-4-5-20251001",
-  openrouter: "anthropic/claude-haiku-4-5",
-  "openai-compatible": null,
-};
-
-export class ProviderRegistry {
-  constructor(private readonly db: Database.Database) {}
-
-  list(): ProviderRow[] {
-    const rows = this.db.prepare<[], ProviderDbRow>(
-      `SELECT * FROM providers ORDER BY id ASC`,
-    ).all();
-    return rows.map((r) => rowFromDb(r, false));
-  }
-
-  get(id: number): ProviderRow | null {
-    const row = this.db.prepare<[number], ProviderDbRow>(
-      `SELECT * FROM providers WHERE id = ?`,
-    ).get(id);
-    return row ? rowFromDb(row, false) : null;
-  }
-
-  getByName(name: string): ProviderRow | null {
-    const row = this.db.prepare<[string], ProviderDbRow>(
-      `SELECT * FROM providers WHERE name = ?`,
-    ).get(name);
-    return row ? rowFromDb(row, false) : null;
-  }
-
-  /** Returns the secret. Use only inside the daemon — never echo to HTTP. */
-  getSecret(id: number): string | null {
-    const row = this.db.prepare<[number], ProviderDbRow>(
-      `SELECT * FROM providers WHERE id = ?`,
-    ).get(id);
-    return row?.api_key ?? null;
-  }
-
-  insert(input: ProviderInsert): ProviderRow {
-    const baseUrl = input.baseUrl ?? DEFAULT_BASE_URLS[input.kind];
-    const defaultModel = input.defaultModel ?? DEFAULT_MODELS[input.kind];
-    const result = this.db.prepare(`
-      INSERT INTO providers (kind, name, base_url, api_key, default_model, enabled)
-      VALUES (@kind, @name, @base_url, @api_key, @default_model, @enabled)
-    `).run({
-      kind: input.kind,
-      name: input.name,
-      base_url: baseUrl ?? null,
-      api_key: input.apiKey ?? null,
-      default_model: defaultModel ?? null,
-      enabled: input.enabled === false ? 0 : 1,
-    });
-    const id = Number(result.lastInsertRowid);
-    const row = this.get(id);
-    if (!row) throw new Error(`ProviderRegistry.insert: row ${id} not found after insert`);
-    return row;
-  }
-
-  update(id: number, patch: ProviderUpdate): ProviderRow | null {
-    const fields: string[] = [];
-    const params: Record<string, unknown> = { id };
-    if (patch.name !== undefined) { fields.push("name = @name"); params["name"] = patch.name; }
-    if (patch.baseUrl !== undefined) { fields.push("base_url = @url"); params["url"] = patch.baseUrl; }
-    if (patch.apiKey !== undefined) { fields.push("api_key = @key"); params["key"] = patch.apiKey; }
-    if (patch.defaultModel !== undefined) { fields.push("default_model = @m"); params["m"] = patch.defaultModel; }
-    if (patch.enabled !== undefined) { fields.push("enabled = @en"); params["en"] = patch.enabled ? 1 : 0; }
-    if (fields.length === 0) return this.get(id);
-    fields.push("updated_at = datetime('now')");
-    this.db.prepare(`UPDATE providers SET ${fields.join(", ")} WHERE id = @id`).run(params);
-    return this.get(id);
-  }
-
-  delete(id: number): boolean {
-    const result = this.db.prepare(`DELETE FROM providers WHERE id = ?`).run(id);
-    return result.changes > 0;
-  }
-
-  /**
-   * Seed defaults on an empty registry. Bridges from the legacy env-var
-   * setup: if DEEPSEEK_API_KEY is present, the DeepSeek row carries it
-   * forward; Ollama is always seeded since it needs no key.
-   */
-  seedDefaults(): void {
-    const count = this.db.prepare<[], { c: number }>(`SELECT COUNT(*) AS c FROM providers`).get();
-    if ((count?.c ?? 0) > 0) return;
-
-    this.insert({
-      kind: "ollama",
-      name: "Ollama (local)",
-      baseUrl: process.env["NLM_OLLAMA_URL"] ?? "http://localhost:11434",
-    });
-
-    const deepseekKey = process.env["DEEPSEEK_API_KEY"];
-    this.insert({
-      kind: "deepseek",
-      name: "DeepSeek",
-      apiKey: deepseekKey ?? null,
-      enabled: Boolean(deepseekKey),
-    });
-  }
-}