nlm-memory 0.4.2 → 0.5.1

package/src/core/adapters/claude-code.ts

@@ -1,293 +0,0 @@
-/**
- * Claude Code adapter.
- *
- * Reads ~/.claude/projects/<encoded-path>/<uuid>.jsonl files. Each .jsonl is
- * one session containing structured events (user/assistant messages, tool
- * uses, snapshots). The adapter discovers files and parses one into a
- * normalized SessionChunk. The scan_once incremental path lives in the
- * Scheduler (Phase D); this slice is pure parsing.
- *
- * Format reference: verified on Edward's machine 2026-05-07. Each line is
- * a JSON object with a `type` field. Relevant types: user, assistant.
- * Tool envelopes are summarized inline so the classifier sees the
- * conversational flow but not raw JSON payloads.
- */
-
-import { promises as fs } from "node:fs";
-import { existsSync, statSync } from "node:fs";
-import { basename, dirname, extname, join } from "node:path";
-import { homedir } from "node:os";
-import type {
-  DetectionResult,
-  DiscoverOptions,
-  SessionChunk,
-  TranscriptAdapter,
-} from "@ports/transcript-adapter.js";
-import { durationMinutes, safeSessionId } from "./common.js";
-
-const TOOL_RESULT_PREVIEW_CHARS = 240;
-
-export interface ClaudeCodeAdapterOptions {
-  readonly projectsPath?: string;
-  readonly idleMinutes?: number;
-}
-
-interface Turn {
-  readonly role: "user" | "assistant";
-  readonly text: string;
-  readonly timestamp: string;
-}
-
-export class ClaudeCodeAdapter implements TranscriptAdapter {
-  readonly name = "claude-code";
-  readonly runtimeVersion = "claude-code/1.0";
-  readonly transcriptKind = "claude-code-jsonl";
-
-  private readonly projectsPath: string;
-  readonly idleMinutes: number;
-
-  constructor(opts: ClaudeCodeAdapterOptions = {}) {
-    this.projectsPath =
-      opts.projectsPath ?? join(homedir(), ".claude", "projects");
-    this.idleMinutes = opts.idleMinutes ?? 15;
-  }
-
-  detect(): DetectionResult {
-    const p = join(homedir(), ".claude", "projects");
-    if (existsSync(p) && statSync(p).isDirectory()) {
-      return { adapterName: this.name, enabled: true, path: p, hint: null };
-    }
-    return {
-      adapterName: this.name,
-      enabled: false,
-      path: null,
-      hint: "Claude Code not detected — ~/.claude/projects/ missing.",
-    };
-  }
-
-  async discover(options: DiscoverOptions = {}): Promise<ReadonlyArray<string>> {
-    if (!existsSync(this.projectsPath)) return [];
-
-    const found: { mtime: number; path: string }[] = [];
-    const seen = new Set<string>();
-
-    // Top-level sessions: <projects>/<project>/<uuid>.jsonl
-    const projects = await fs.readdir(this.projectsPath, { withFileTypes: true });
-    for (const proj of projects) {
-      if (!proj.isDirectory()) continue;
-      const projDir = join(this.projectsPath, proj.name);
-      const entries = await fs.readdir(projDir, { withFileTypes: true });
-      for (const ent of entries) {
-        if (ent.isFile() && extname(ent.name) === ".jsonl") {
-          await this.maybeAdd(join(projDir, ent.name), seen, found, options.since);
-        } else if (ent.isDirectory()) {
-          // Subagent transcripts: <project>/<uuid>/subagents/agent-<id>.jsonl
-          const subDir = join(projDir, ent.name, "subagents");
-          if (!existsSync(subDir)) continue;
-          const subEntries = await fs.readdir(subDir, { withFileTypes: true });
-          for (const sub of subEntries) {
-            if (sub.isFile() && extname(sub.name) === ".jsonl") {
-              await this.maybeAdd(join(subDir, sub.name), seen, found, options.since);
-            }
-          }
-        }
-      }
-    }
-
-    found.sort((a, b) => a.mtime - b.mtime);
-    return found.map((f) => f.path);
-  }
-
-  async parseSession(path: string): Promise<SessionChunk | null> {
-    const isSubagent = this.isSubagentPath(path);
-    const turns: Turn[] = [];
-    let startedAt = "";
-    let endedAt = "";
-    let projectDir = "";
-    let gitBranch = "";
-    let runtimeSessionId = "";
-    let agentId = "";
-    let agentSlug = "";
-    let parentSessionId = "";
-    let totalBytes = 0;
-
-    let raw: string;
-    try {
-      raw = await fs.readFile(path, "utf8");
-    } catch {
-      return null;
-    }
-
-    for (const line of raw.split("\n")) {
-      totalBytes += Buffer.byteLength(line, "utf8") + 1; // +1 for newline
-      const trimmed = line.trim();
-      if (!trimmed) continue;
-
-      let evt: Record<string, unknown>;
-      try {
-        evt = JSON.parse(trimmed) as Record<string, unknown>;
-      } catch {
-        continue;
-      }
-
-      if (!runtimeSessionId && typeof evt["sessionId"] === "string") {
-        runtimeSessionId = evt["sessionId"];
-      }
-      if (isSubagent) {
-        if (!agentId && typeof evt["agentId"] === "string") agentId = evt["agentId"];
-        if (!agentSlug && typeof evt["slug"] === "string") agentSlug = evt["slug"];
-        if (!parentSessionId && typeof evt["sessionId"] === "string") {
-          parentSessionId = evt["sessionId"];
-        }
-      }
-      if (!projectDir && typeof evt["cwd"] === "string") projectDir = evt["cwd"];
-      if (!gitBranch && typeof evt["gitBranch"] === "string") gitBranch = evt["gitBranch"];
-
-      const evtType = evt["type"];
-      if (evtType !== "user" && evtType !== "assistant") continue;
-
-      const msg = (evt["message"] as Record<string, unknown> | undefined) ?? {};
-      const text = extractText(msg["content"]);
-      if (!text.trim()) continue;
-
-      const cleaned = evtType === "user" ? stripEnvelopes(text) : text;
-      if (!cleaned.trim()) continue;
-
-      const timestamp =
-        typeof evt["timestamp"] === "string" ? evt["timestamp"] : "";
-      if (timestamp && !startedAt) startedAt = timestamp;
-      if (timestamp) endedAt = timestamp;
-
-      turns.push({ role: evtType, text: cleaned, timestamp });
-    }
-
-    if (turns.length === 0) return null;
-
-    const transcript = turns.map((t) => `[${t.role}] ${t.text}`).join("\n\n");
-    const duration = durationMinutes(startedAt, endedAt);
-    let label = provisionalLabel(turns);
-
-    if (isSubagent && agentId) {
-      const slugTag = agentSlug || "anon";
-      label = `[subagent ${slugTag}] ${label}`;
-      return {
-        id: safeSessionId("cc_sub", agentId),
-        runtime: this.runtimeVersion,
-        runtimeSessionId: `${parentSessionId || "unknown"}/agent-${agentId}`,
-        sourcePath: path,
-        startedAt,
-        endedAt,
-        durationMin: duration,
-        turnCount: turns.length,
-        byteRange: [0, totalBytes],
-        projectDir,
-        gitBranch,
-        text: transcript,
-        label,
-      };
-    }
-
-    const stem = basename(path, ".jsonl");
-    const rawId = runtimeSessionId || stem;
-    return {
-      id: safeSessionId("cc", rawId),
-      runtime: this.runtimeVersion,
-      runtimeSessionId: runtimeSessionId || stem,
-      sourcePath: path,
-      startedAt,
-      endedAt,
-      durationMin: duration,
-      turnCount: turns.length,
-      byteRange: [0, totalBytes],
-      projectDir,
-      gitBranch,
-      text: transcript,
-      label,
-    };
-  }
-
-  private isSubagentPath(path: string): boolean {
-    return basename(dirname(path)) === "subagents";
-  }
-
-  private async maybeAdd(
-    path: string,
-    seen: Set<string>,
-    out: { mtime: number; path: string }[],
-    since?: Date,
-  ): Promise<void> {
-    if (seen.has(path)) return;
-    seen.add(path);
-    let st;
-    try {
-      st = await fs.stat(path);
-    } catch {
-      return;
-    }
-    if (st.size === 0) return;
-    if (since && st.mtime < since) return;
-    out.push({ mtime: st.mtimeMs, path });
-  }
-}
-
-// ── content extraction ───────────────────────────────────────────────────
-
-function extractText(content: unknown): string {
-  if (typeof content === "string") return content;
-  if (!Array.isArray(content)) return "";
-
-  const parts: string[] = [];
-  for (const block of content) {
-    if (!block || typeof block !== "object") continue;
-    const b = block as Record<string, unknown>;
-    const btype = b["type"];
-    if (btype === "text") {
-      const t = b["text"];
-      if (typeof t === "string" && t) parts.push(t);
-    } else if (btype === "tool_use") {
-      const name = typeof b["name"] === "string" ? b["name"] : "tool";
-      parts.push(`[tool_use: ${name}]`);
-    } else if (btype === "tool_result") {
-      let res = b["content"];
-      if (Array.isArray(res)) {
-        res = res
-          .filter((x): x is Record<string, unknown> => !!x && typeof x === "object")
-          .map((x) => (typeof x["text"] === "string" ? (x["text"] as string) : ""))
-          .join("\n");
-      }
-      if (typeof res === "string" && res) {
-        const preview = res.slice(0, TOOL_RESULT_PREVIEW_CHARS);
-        const ellipsis = res.length > TOOL_RESULT_PREVIEW_CHARS ? "…" : "";
-        parts.push(`[tool_result: ${preview}${ellipsis}]`);
-      }
-    } else if (btype === "image") {
-      parts.push("[image]");
-    }
-  }
-  return parts.filter((p) => p).join("\n");
-}
-
-const IDE_TAG_RE = /<ide_[^>]*>[\s\S]*?<\/ide_[^>]*>/g;
-const IDE_SELF_RE = /<ide_[^/]*?\/>/g;
-const REMINDER_RE = /<system-reminder>[\s\S]*?<\/system-reminder>/g;
-const COMMAND_RE = /<command-(?:name|message|args)>[^<]*<\/command-(?:name|message|args)>/g;
-
-function stripEnvelopes(text: string): string {
-  return text
-    .replace(IDE_TAG_RE, "")
-    .replace(IDE_SELF_RE, "")
-    .replace(REMINDER_RE, "")
-    .replace(COMMAND_RE, "")
-    .trim();
-}
-
-function provisionalLabel(turns: ReadonlyArray<Turn>): string {
-  for (const t of turns) {
-    if (t.role !== "user") continue;
-    const cleaned = stripEnvelopes(t.text);
-    if (!cleaned) continue;
-    const firstLine = cleaned.split("\n", 1)[0]?.trim();
-    if (firstLine) return firstLine.slice(0, 80);
-  }
-  return "Untitled session";
-}

package/src/core/adapters/common.ts

@@ -1,54 +0,0 @@
-/**
- * Shared utilities for TranscriptAdapter implementations.
- *
- * Only functions that genuinely serve multiple adapters live here. Adapter-
- * specific logic (content extraction, file-shape detection, dedup) stays
- * with the adapter.
- */
-
-export function normalizeTimestamp(ts: unknown): string {
-  if (ts === null || ts === undefined || ts === "" || ts === 0) return "";
-  if (typeof ts === "string") return ts;
-  if (typeof ts === "number" && Number.isFinite(ts)) {
-    let secs = ts;
-    // Detect millisecond magnitude (Unix-millis are > 1e10 through ~2286)
-    if (secs > 1e10) secs = secs / 1000;
-    try {
-      return new Date(secs * 1000).toISOString();
-    } catch {
-      return "";
-    }
-  }
-  return String(ts);
-}
-
-/**
- * Build a collision-resistant session ID for an adapter prefix.
- *
- * Strategy (matches Python _common.safe_session_id):
- *   1. If raw_id has 3+ underscore-delimited parts (e.g. Hermes
- *      `YYYYMMDD_HHMMSS_HHHHHH`), use `${prefix}_${parts[0]}_${parts.at(-1)}`
- *      — date + unique suffix.
- *   2. Otherwise (UUID-style or opaque), return `${prefix}_${rawId}` verbatim;
- *      the caller is responsible for global uniqueness.
- */
-export function safeSessionId(prefix: string, rawId: string): string {
-  if (!rawId) return prefix;
-  const parts = rawId.split("_");
-  if (parts.length >= 3) {
-    return `${prefix}_${parts[0]}_${parts[parts.length - 1]}`;
-  }
-  return `${prefix}_${rawId}`;
-}
-
-export function durationMinutes(startedAt: string, endedAt: string): number {
-  if (!startedAt || !endedAt) return 0;
-  try {
-    const s = Date.parse(startedAt);
-    const e = Date.parse(endedAt);
-    if (!Number.isFinite(s) || !Number.isFinite(e)) return 0;
-    return Math.max(0, Math.trunc((e - s) / 60_000));
-  } catch {
-    return 0;
-  }
-}

package/src/core/adapters/from-source.ts

@@ -1,57 +0,0 @@
-/**
- * Adapter factory — instantiates a TranscriptAdapter for a SourceRow.
- *
- * The three legacy preset kinds (claude-code, hermes, pi) stay as their
- * own classes; this factory just injects the path from the registry row.
- * The `jsonl-generic` kind delegates to JsonlGenericAdapter with the row's
- * parseConfig. `webhook` returns null — push-based ingest doesn't poll.
- */
-
-import type { TranscriptAdapter } from "@ports/transcript-adapter.js";
-import type { SourceRow } from "../sources/source-registry.js";
-import { AiderAdapter } from "./aider.js";
-import { ClaudeCodeAdapter } from "./claude-code.js";
-import { HermesAdapter } from "./hermes.js";
-import { HermesAgentAdapter } from "./hermes-agent.js";
-import { JsonlGenericAdapter, type JsonlGenericConfig } from "./jsonl-generic.js";
-import { OpenCodeAdapter } from "./opencode.js";
-import { PiAdapter } from "./pi.js";
-
-export function adapterFromSource(source: SourceRow): TranscriptAdapter | null {
-  switch (source.kind) {
-    case "aider":
-      return source.pathOrUrl
-        ? new AiderAdapter({ historyFile: source.pathOrUrl })
-        : new AiderAdapter();
-    case "claude-code":
-      return source.pathOrUrl
-        ? new ClaudeCodeAdapter({ projectsPath: source.pathOrUrl })
-        : new ClaudeCodeAdapter();
-    case "hermes":
-      return source.pathOrUrl
-        ? new HermesAdapter({ sessionsPath: source.pathOrUrl })
-        : new HermesAdapter();
-    case "hermes-agent":
-      return source.pathOrUrl
-        ? new HermesAgentAdapter({ dbPath: source.pathOrUrl })
-        : new HermesAgentAdapter();
-    case "opencode":
-      return source.pathOrUrl
-        ? new OpenCodeAdapter({ dbPath: source.pathOrUrl })
-        : new OpenCodeAdapter();
-    case "pi":
-      return source.pathOrUrl
-        ? new PiAdapter({ sessionsPath: source.pathOrUrl })
-        : new PiAdapter();
-    case "jsonl-generic":
-      if (!source.pathOrUrl) return null;
-      return new JsonlGenericAdapter({
-        name: `jsonl:${source.name}`,
-        path: source.pathOrUrl,
-        runtime: source.runtimeLabel,
-        config: source.parseConfig as JsonlGenericConfig,
-      });
-    case "webhook":
-      return null;
-  }
-}

package/src/core/adapters/hermes-agent.ts

@@ -1,240 +0,0 @@
-/**
- * NousResearch Hermes Agent adapter.
- *
- * Reads the Hermes Agent SQLite state database at:
- *   ~/.hermes/state.db  (customizable via HERMES_HOME)
- *
- * Schema (schema version 11):
- *   sessions — id, title, source, started_at (Unix float), ended_at (Unix float)
- *   messages — id, session_id, role, content, tool_calls (JSON), tool_name, timestamp (Unix float)
- *
- * Roles extracted: user, assistant (with optional tool_calls), tool (result).
- * Roles skipped: system.
- *
- * Tool calls in assistant messages are summarized as [tool_use: <name>].
- * Tool result messages are summarized as [tool_result: <name>: <preview>].
- *
- * This adapter is distinct from HermesAdapter (src/core/adapters/hermes.ts),
- * which reads Whtnxt Hermes WebUI session JSON files from ~/.hermes/sessions/.
- */
-
-import { existsSync, readFileSync } from "node:fs";
-import { homedir } from "node:os";
-import { join } from "node:path";
-import Database from "better-sqlite3";
-import type {
-  DetectionResult,
-  DiscoverOptions,
-  SessionChunk,
-  TranscriptAdapter,
-} from "@ports/transcript-adapter.js";
-import { durationMinutes, normalizeTimestamp, safeSessionId } from "./common.js";
-
-const TOOL_RESULT_PREVIEW_CHARS = 240;
-
-export interface HermesAgentAdapterOptions {
-  readonly dbPath?: string;
-}
-
-interface Turn {
-  readonly role: "user" | "assistant" | "tool";
-  readonly text: string;
-  readonly timestamp: number;
-}
-
-interface SessionRow {
-  readonly id: string;
-  readonly title: string | null;
-  readonly started_at: number;
-  readonly ended_at: number | null;
-}
-
-interface MessageRow {
-  readonly id: number;
-  readonly role: string;
-  readonly content: string | null;
-  readonly tool_calls: string | null;
-  readonly tool_name: string | null;
-  readonly timestamp: number;
-}
-
-interface ToolCall {
-  readonly function?: {
-    readonly name?: string;
-  };
-}
-
-export function defaultDbPath(): string {
-  if (process.env["NLM_HERMES_AGENT_DB_PATH"]) return process.env["NLM_HERMES_AGENT_DB_PATH"];
-  const hermesHome = process.env["HERMES_HOME"] ?? join(homedir(), ".hermes");
-  return join(hermesHome, "state.db");
-}
-
-function readGitBranch(directory: string): string {
-  try {
-    const head = readFileSync(join(directory, ".git", "HEAD"), "utf8").trim();
-    const match = /^ref: refs\/heads\/(.+)$/.exec(head);
-    return match ? (match[1] ?? "") : "";
-  } catch {
-    return "";
-  }
-}
-
-function extractTurns(messages: MessageRow[]): Turn[] {
-  const turns: Turn[] = [];
-  for (const msg of messages) {
-    if (msg.role === "system") continue;
-    if (msg.role !== "user" && msg.role !== "assistant" && msg.role !== "tool") continue;
-
-    const segments: string[] = [];
-
-    if (msg.role === "tool") {
-      const name = msg.tool_name ?? "tool";
-      const raw = msg.content ?? "";
-      const preview = raw.slice(0, TOOL_RESULT_PREVIEW_CHARS);
-      const ellipsis = raw.length > TOOL_RESULT_PREVIEW_CHARS ? "…" : "";
-      if (raw) segments.push(`[tool_result: ${name}: ${preview}${ellipsis}]`);
-      else segments.push(`[tool_result: ${name}]`);
-    } else {
-      if (msg.content) segments.push(msg.content);
-
-      if (msg.tool_calls) {
-        let calls: ToolCall[];
-        try {
-          calls = JSON.parse(msg.tool_calls) as ToolCall[];
-        } catch {
-          calls = [];
-        }
-        for (const tc of calls) {
-          const name = tc.function?.name ?? "tool";
-          segments.push(`[tool_use: ${name}]`);
-        }
-      }
-    }
-
-    const text = segments.join("\n").trim();
-    if (!text) continue;
-
-    turns.push({
-      role: msg.role as Turn["role"],
-      text,
-      timestamp: msg.timestamp,
-    });
-  }
-  return turns;
-}
-
-function provisionalLabel(turns: ReadonlyArray<Turn>): string {
-  for (const t of turns) {
-    if (t.role !== "user") continue;
-    const first = t.text.split("\n", 1)[0]?.trim();
-    if (first) return first.slice(0, 80);
-  }
-  return "Untitled session";
-}
-
-export class HermesAgentAdapter implements TranscriptAdapter {
-  readonly name = "hermes-agent";
-  readonly runtimeVersion = "hermes-agent/1.0";
-  readonly transcriptKind = "hermes-agent-sqlite";
-
-  private readonly dbPath: string;
-
-  constructor(opts: HermesAgentAdapterOptions = {}) {
-    this.dbPath = opts.dbPath ?? defaultDbPath();
-  }
-
-  detect(): DetectionResult {
-    if (existsSync(this.dbPath)) {
-      return { adapterName: this.name, enabled: true, path: this.dbPath, hint: null };
-    }
-    return {
-      adapterName: this.name,
-      enabled: false,
-      path: null,
-      hint: "Hermes Agent state.db not found — install NousResearch Hermes Agent or set HERMES_HOME.",
-    };
-  }
-
-  async discover(options?: DiscoverOptions): Promise<ReadonlyArray<string>> {
-    if (!existsSync(this.dbPath)) return [];
-    let db: Database.Database | undefined;
-    try {
-      db = new Database(this.dbPath, { readonly: true });
-      let rows: { id: string }[];
-      if (options?.since) {
-        const sinceTs = options.since.getTime() / 1000;
-        rows = db
-          .prepare<[number], { id: string }>(
-            `SELECT id FROM sessions WHERE started_at >= ? ORDER BY started_at ASC`,
-          )
-          .all(sinceTs);
-      } else {
-        rows = db
-          .prepare<[], { id: string }>(
-            `SELECT id FROM sessions ORDER BY started_at ASC`,
-          )
-          .all();
-      }
-      return rows.map((r) => r.id);
-    } catch {
-      return [];
-    } finally {
-      db?.close();
-    }
-  }
-
-  async parseSession(sessionId: string): Promise<SessionChunk | null> {
-    if (!existsSync(this.dbPath)) return null;
-    let db: Database.Database | undefined;
-    try {
-      db = new Database(this.dbPath, { readonly: true });
-
-      const session = db
-        .prepare<[string], SessionRow>(
-          `SELECT id, title, started_at, ended_at FROM sessions WHERE id = ?`,
-        )
-        .get(sessionId);
-      if (!session) return null;
-
-      const messages = db
-        .prepare<[string], MessageRow>(
-          `SELECT id, role, content, tool_calls, tool_name, timestamp
-           FROM messages WHERE session_id = ? ORDER BY timestamp ASC`,
-        )
-        .all(sessionId);
-
-      const turns = extractTurns(messages);
-      if (turns.length === 0) return null;
-
-      const startedAt = normalizeTimestamp(session.started_at);
-      const endedAt = normalizeTimestamp(session.ended_at ?? session.started_at);
-      const transcript = turns.map((t) => `${t.role}: ${t.text}`).join("\n\n");
-
-      const label =
-        session.title && session.title.trim()
-          ? session.title.slice(0, 80)
-          : provisionalLabel(turns);
-
-      return {
-        id: safeSessionId("ha", sessionId),
-        runtime: this.runtimeVersion,
-        runtimeSessionId: sessionId,
-        sourcePath: `${this.dbPath}::${sessionId}`,
-        startedAt,
-        endedAt,
-        durationMin: durationMinutes(startedAt, endedAt),
-        turnCount: turns.length,
-        byteRange: [0, Buffer.byteLength(transcript, "utf8")],
-        projectDir: "",
-        gitBranch: "",
-        text: transcript,
-        label,
-      };
-    } catch {
-      return null;
-    } finally {
-      db?.close();
-    }
-  }
-}