claude-mem-lite 2.0.0

package/haiku-client.mjs

@@ -0,0 +1,165 @@
+// claude-mem-lite: Unified LLM call wrapper
+// Shared by memory (hook.mjs) and dispatch modules
+// Auto-detects API key for direct calls, falls back to claude CLI
+// Model configurable via CLAUDE_MEM_MODEL env var (default: haiku)
+
+import { execFileSync } from 'child_process';
+import { readFileSync } from 'fs';
+import { join } from 'path';
+import { debugLog, debugCatch, parseJsonFromLLM } from './utils.mjs';
+import { DB_DIR } from './schema.mjs';
+
+// ─── Model Resolution ────────────────────────────────────────────────────────
+
+// CLI name → API model ID mapping
+const MODEL_MAP = {
+  haiku: 'claude-haiku-4-5-20251001',
+  sonnet: 'claude-sonnet-4-5-20250929',
+};
+
+/**
+ * Resolve the LLM model to use for background calls.
+ * Reads CLAUDE_MEM_MODEL env var, defaults to 'haiku'.
+ * @returns {{ cli: string, api: string }} CLI name and API model ID
+ */
+export function resolveModel() {
+  const raw = (process.env.CLAUDE_MEM_MODEL || 'haiku').toLowerCase().trim();
+  const cli = MODEL_MAP[raw] ? raw : 'haiku';
+  const api = MODEL_MAP[cli];
+  return { cli, api };
+}
+
+// ─── Mode Detection ──────────────────────────────────────────────────────────
+
+let _mode = null;
+
+/**
+ * Detect whether to use direct API or CLI for LLM calls.
+ * Cached after first call.
+ * @returns {'api'|'cli'} The detected mode
+ */
+export function detectMode() {
+  if (_mode) return _mode;
+  _mode = process.env.ANTHROPIC_API_KEY ? 'api' : 'cli';
+  const { cli } = resolveModel();
+  debugLog('DEBUG', 'haiku-client', `mode: ${_mode}, model: ${cli}`);
+  return _mode;
+}
+
+/** Reset cached mode (for testing). */
+export function _resetMode() { _mode = null; }
+
+// ─── CLI Path ────────────────────────────────────────────────────────────────
+
+export function getClaudePath() {
+  try {
+    const s = JSON.parse(readFileSync(join(DB_DIR, 'settings.json'), 'utf8'));
+    if (s.CLAUDE_CODE_PATH) return s.CLAUDE_CODE_PATH;
+  } catch {}
+  return process.env.CLAUDE_CODE_PATH || 'claude';
+}
+
+// ─── Core Call ───────────────────────────────────────────────────────────────
+
+/**
+ * Call Haiku model with a prompt. Returns parsed text or null on failure.
+ * Uses direct API when ANTHROPIC_API_KEY is available, otherwise falls back to CLI.
+ * Never throws — returns null on any error.
+ *
+ * @param {string} prompt The prompt text
+ * @param {object} [opts] Options
+ * @param {number} [opts.timeout=10000] Timeout in milliseconds
+ * @param {number} [opts.maxTokens=500] Max tokens in response
+ * @returns {Promise<{text: string}|null>} Response or null on failure
+ */
+export async function callHaiku(prompt, { timeout = 10000, maxTokens = 500 } = {}) {
+  if (!prompt) return null;
+
+  const mode = detectMode();
+
+  try {
+    if (mode === 'api') {
+      return await callHaikuAPI(prompt, { timeout, maxTokens });
+    }
+    return callHaikuCLI(prompt, { timeout });
+  } catch (e) {
+    debugCatch(e, 'callHaiku');
+    return null;
+  }
+}
+
+/**
+ * Call Haiku and parse JSON response. Convenience wrapper.
+ * @param {string} prompt The prompt text
+ * @param {object} [opts] Options passed to callHaiku
+ * @returns {Promise<object|null>} Parsed JSON or null
+ */
+export async function callHaikuJSON(prompt, opts) {
+  const result = await callHaiku(prompt, opts);
+  if (!result?.text) return null;
+  return parseJsonFromLLM(result.text);
+}
+
+// ─── API Mode ────────────────────────────────────────────────────────────────
+
+async function callHaikuAPI(prompt, { timeout, maxTokens }) {
+  const apiKey = process.env.ANTHROPIC_API_KEY;
+  if (!apiKey) return null;
+
+  const { api: modelId } = resolveModel();
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeout);
+
+  try {
+    const res = await fetch('https://api.anthropic.com/v1/messages', {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'x-api-key': apiKey,
+        'anthropic-version': '2023-06-01',
+      },
+      body: JSON.stringify({
+        model: modelId,
+        max_tokens: maxTokens,
+        messages: [{ role: 'user', content: prompt }],
+      }),
+      signal: controller.signal,
+    });
+
+    if (!res.ok) {
+      debugLog('WARN', 'haiku-api', `HTTP ${res.status}`);
+      return null;
+    }
+
+    const data = await res.json();
+    const text = data.content?.[0]?.text;
+    return text ? { text } : null;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+// ─── CLI Mode ────────────────────────────────────────────────────────────────
+
+function callHaikuCLI(prompt, { timeout }) {
+  const { cli: modelName } = resolveModel();
+  try {
+    const result = execFileSync(getClaudePath(), ['-p', '--model', modelName], {
+      input: prompt,
+      timeout,
+      encoding: 'utf8',
+      env: { ...process.env, CLAUDE_MEM_HOOK_RUNNING: '1' },
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    const text = result.trim();
+    return text ? { text } : null;
+  } catch (e) {
+    // Try to extract partial output on timeout — validate JSON before returning
+    const out = e.stdout?.toString?.()?.trim() || e.output?.[1]?.toString?.()?.trim();
+    if (out && out.startsWith('{') && out.endsWith('}')) {
+      try { JSON.parse(out); return { text: out }; } catch {}
+    }
+    debugCatch(e, 'haiku-cli');
+    return null;
+  }
+}

package/hook-context.mjs

@@ -0,0 +1,176 @@
+// claude-mem-lite CLAUDE.md context injection and token budgeting
+// Handles adaptive time windows, token-budgeted selection, and CLAUDE.md persistence
+
+import { join } from 'path';
+import { readFileSync, writeFileSync, renameSync } from 'fs';
+import { estimateTokens, debugLog, debugCatch } from './utils.mjs';
+
+/**
+ * Infer the project directory from environment variables or cwd.
+ * @returns {string} Absolute path to the project directory
+ */
+function inferProjectDir() {
+  return process.env.CLAUDE_PROJECT_DIR || process.env.PWD || process.cwd();
+}
+
+/**
+ * Compute adaptive recall time windows based on project activity velocity.
+ * High activity -> shorter windows (recent data more relevant).
+ * Low activity -> longer windows (older data stays relevant).
+ * @param {object} db better-sqlite3 database handle
+ * @param {string} project Project name to check velocity for
+ * @returns {{tier1: number, tier2: number, tier3: number, sessWindow: number}} Time window durations in ms
+ */
+export function computeAdaptiveWindows(db, project) {
+  const sevenDaysAgo = Date.now() - 7 * 86400000;
+  const row = db.prepare(`
+    SELECT COUNT(*) as c FROM observations
+    WHERE project = ? AND created_at_epoch > ? AND COALESCE(compressed_into, 0) = 0
+  `).get(project, sevenDaysAgo);
+  const velocity = (row?.c || 0) / 7; // observations per day
+
+  if (velocity > 10) {
+    // High velocity: tighter windows, focus on very recent
+    return { tier1: 12 * 3600000, tier2: 3 * 86400000, tier3: 14 * 86400000, sessWindow: 3 * 86400000 };
+  } else if (velocity >= 3) {
+    // Medium velocity: default windows
+    return { tier1: 24 * 3600000, tier2: 7 * 86400000, tier3: 30 * 86400000, sessWindow: 7 * 86400000 };
+  } else {
+    // Low velocity: wider windows, older data still relevant
+    return { tier1: 48 * 3600000, tier2: 14 * 86400000, tier3: 60 * 86400000, sessWindow: 14 * 86400000 };
+  }
+}
+
+/**
+ * Select observations and sessions within a token budget using greedy knapsack.
+ * Scores candidates by recency * importance, picks highest value-density first.
+ * @param {object} db better-sqlite3 database handle
+ * @param {string} project Project name
+ * @param {number} [budget=2000] Maximum token budget
+ * @returns {{observations: object[], summaries: object[], totalTokens: number}} Selected items
+ */
+export function selectWithTokenBudget(db, project, budget = 2000) {
+  const now_ms = Date.now();
+  const windows = computeAdaptiveWindows(db, project);
+  const tier1Ago = now_ms - windows.tier1;
+  const tier2Ago = now_ms - windows.tier2;
+  const tier3Ago = now_ms - windows.tier3;
+
+  // Candidate pool: tiered time windows by importance (adaptive)
+  const obsPool = db.prepare(`
+    SELECT id, type, title, narrative, importance, created_at_epoch, files_modified
+    FROM observations
+    WHERE project = ? AND COALESCE(compressed_into, 0) = 0
+      AND (
+        (created_at_epoch > ? AND importance >= 1)
+        OR (created_at_epoch > ? AND importance >= 2)
+        OR (created_at_epoch > ? AND importance >= 3)
+      )
+    ORDER BY created_at_epoch DESC
+    LIMIT 50
+  `).all(project, tier1Ago, tier2Ago, tier3Ago);
+
+  const sessPool = db.prepare(`
+    SELECT id, request, completed, next_steps, created_at_epoch
+    FROM session_summaries
+    WHERE project = ? AND created_at_epoch > ?
+    ORDER BY created_at_epoch DESC
+    LIMIT 10
+  `).all(project, now_ms - windows.sessWindow);
+
+  const now = Date.now();
+  const selectedObs = [];
+  const selectedSess = [];
+  let totalTokens = 0;
+
+  // Score each candidate: value = recency * importance, cost = tokens
+  const scoredObs = obsPool.map(o => {
+    const ageDays = (now - o.created_at_epoch) / 86400000;
+    const recency = 1 / (1 + ageDays);
+    const impBoost = 0.5 + 0.5 * (o.importance || 1);
+    const value = recency * impBoost;
+    const cost = estimateTokens((o.title || '') + (o.narrative || ''));
+    return { ...o, value, cost, valueDensity: cost > 0 ? value / Math.sqrt(cost) : 0 };
+  });
+
+  const scoredSess = sessPool.map(s => {
+    const ageDays = (now - s.created_at_epoch) / 86400000;
+    const recency = 1 / (1 + ageDays);
+    const value = recency * 1.5; // Session summaries slightly boosted
+    const cost = estimateTokens((s.request || '') + (s.completed || '') + (s.next_steps || ''));
+    return { ...s, value, cost, valueDensity: cost > 0 ? value / Math.sqrt(cost) : 0 };
+  });
+
+  // Combine and sort by value density (greedy knapsack)
+  const allCandidates = [
+    ...scoredObs.map(o => ({ ...o, _kind: 'obs' })),
+    ...scoredSess.map(s => ({ ...s, _kind: 'sess' })),
+  ].sort((a, b) => b.valueDensity - a.valueDensity);
+
+  const selectedFiles = new Set();
+
+  for (const c of allCandidates) {
+    if (totalTokens + c.cost > budget) continue;
+
+    // Diversity penalty: reduce value for file overlap with already-selected
+    if (c._kind === 'obs' && c.files_modified) {
+      let cFiles;
+      try { cFiles = JSON.parse(c.files_modified || '[]'); } catch (e) { debugCatch(e, 'budgetSelect-parseFiles'); cFiles = []; }
+      if (cFiles.length > 0 && selectedFiles.size > 0) {
+        const overlap = cFiles.filter(f => selectedFiles.has(f)).length;
+        const overlapRatio = overlap / cFiles.length;
+        const penalizedValue = c.valueDensity * (1 - 0.3 * overlapRatio);
+        if (penalizedValue < 0.001) continue; // Skip if too redundant
+      }
+      for (const f of cFiles) selectedFiles.add(f);
+    }
+
+    totalTokens += c.cost;
+    if (c._kind === 'obs') {
+      selectedObs.push({ id: c.id, type: c.type, title: c.title, created_at: new Date(c.created_at_epoch).toISOString() });
+    } else {
+      selectedSess.push({ id: c.id, request: c.request, completed: c.completed, next_steps: c.next_steps, created_at: new Date(c.created_at_epoch).toISOString() });
+    }
+  }
+
+  return { observations: selectedObs, summaries: selectedSess, totalTokens };
+}
+
+/**
+ * Update the project's CLAUDE.md file with a context block.
+ * Replaces existing <claude-mem-context> section or appends a new one.
+ * Uses atomic tmp+rename write to prevent partial writes.
+ * @param {string} contextBlock Markdown content to inject
+ */
+export function updateClaudeMd(contextBlock) {
+  const claudeMdPath = join(inferProjectDir(), 'CLAUDE.md');
+  let content = '';
+  try { content = readFileSync(claudeMdPath, 'utf8'); } catch {}
+
+  const startTag = '<claude-mem-context>';
+  const endTag = '</claude-mem-context>';
+  const hintComment = '<!-- claude-mem-lite: auto-updated context. To avoid git noise, add CLAUDE.md to .gitignore -->';
+  const newSection = `${startTag}\n${contextBlock}\n${endTag}`;
+
+  const startIdx = content.indexOf(startTag);
+  const endIdx = content.indexOf(endTag);
+
+  if (startIdx !== -1 && endIdx !== -1) {
+    // Replace existing section in-place — preserves surrounding content (including hint if present)
+    content = content.slice(0, startIdx) + newSection + content.slice(endIdx + endTag.length);
+  } else if (content.length > 0) {
+    // Append to end — never disturb existing CLAUDE.md structure
+    const hint = content.includes(hintComment) ? '' : hintComment + '\n';
+    content = content.trimEnd() + '\n\n' + hint + newSection + '\n';
+  } else {
+    content = hintComment + '\n' + newSection + '\n';
+  }
+
+  try {
+    const tmp = claudeMdPath + '.mem-tmp';
+    writeFileSync(tmp, content);
+    renameSync(tmp, claudeMdPath);
+  } catch (e) {
+    debugLog('ERROR', 'updateClaudeMd', `CLAUDE.md write failed: ${e.message}`);
+  }
+}

package/hook-episode.mjs

@@ -0,0 +1,222 @@
+// claude-mem-lite episode buffer management
+// Handles file-based episode storage with advisory locking and pending entry recovery
+
+import { join } from 'path';
+import { readFileSync, writeFileSync, unlinkSync, readdirSync, openSync, closeSync, writeSync, renameSync, statSync, constants as fsConstants } from 'fs';
+import { inferProject } from './utils.mjs';
+import { RUNTIME_DIR } from './hook-shared.mjs';
+
+/**
+ * Read episode file without locking (for signal handlers only).
+ * @returns {object|null} Parsed episode or null on failure
+ */
+export function readEpisodeRaw() {
+  try {
+    return JSON.parse(readFileSync(join(RUNTIME_DIR, `ep-${inferProject()}.json`), 'utf8'));
+  } catch { return null; }
+}
+
+/**
+ * Get the path to the current project's episode buffer file.
+ * @returns {string} Absolute path to the episode JSON file
+ */
+export function episodeFile() {
+  return join(RUNTIME_DIR, `ep-${inferProject()}.json`);
+}
+
+/**
+ * Get the path to the advisory lock file for episode operations.
+ * @returns {string} Absolute path to the lock file
+ */
+export function lockFile() {
+  return episodeFile() + '.lock';
+}
+
+/**
+ * Acquire an advisory file lock for episode buffer operations.
+ * Uses atomic O_CREAT|O_EXCL for lock creation with stale lock detection.
+ * @param {number} [maxWaitMs=500] Maximum time to wait for the lock
+ * @returns {boolean} true if lock acquired, false on timeout
+ */
+export function acquireLock(maxWaitMs = 500) {
+  const lf = lockFile();
+  const deadline = Date.now() + maxWaitMs;
+  while (Date.now() < deadline) {
+    try {
+      let fd;
+      try {
+        fd = openSync(lf, fsConstants.O_CREAT | fsConstants.O_EXCL | fsConstants.O_WRONLY);
+        const payload = JSON.stringify({ pid: process.pid, ts: Date.now() });
+        writeSync(fd, payload);
+      } finally {
+        if (fd !== undefined) closeSync(fd);
+      }
+      return true;
+    } catch {
+      // Lock exists — check if stale or orphaned
+      try {
+        const raw = readFileSync(lf, 'utf8');
+        const info = JSON.parse(raw);
+        const age = Date.now() - (info.ts || 0);
+        let stale = age > 30000; // >30s = stale
+        if (!stale && info.pid) {
+          try { process.kill(info.pid, 0); } catch (killErr) {
+            stale = killErr.code === 'ESRCH'; // Only stale if process truly gone
+          }
+        }
+        if (stale) { try { unlinkSync(lf); } catch {} continue; }
+      } catch {
+        // Can't read lock — check mtime
+        try {
+          const st = statSync(lf);
+          if (Date.now() - st.mtimeMs > 30000) { try { unlinkSync(lf); } catch {} continue; }
+        } catch {}
+      }
+      // WARNING: Atomics.wait blocks the main thread. This is intentional and safe here
+      // because hook.mjs runs as a short-lived subprocess (not the MCP server).
+      // Do NOT use this pattern in server.mjs or any long-lived event-driven process.
+      const wait = Math.ceil(Math.random() * 20);
+      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, wait);
+    }
+  }
+  return false;
+}
+
+/**
+ * Release the advisory file lock for episode buffer operations.
+ */
+export function releaseLock() {
+  try { unlinkSync(lockFile()); } catch {}
+}
+
+/**
+ * Read the current episode buffer from disk (requires lock).
+ * @returns {object|null} Parsed episode or null if not found
+ */
+export function readEpisode() {
+  try {
+    return JSON.parse(readFileSync(episodeFile(), 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Atomically write episode buffer to disk using tmp+rename.
+ * @param {object} episode The episode object to persist
+ */
+export function writeEpisode(episode) {
+  const target = episodeFile();
+  const tmp = target + '.tmp';
+  const { _fileSet, ...serializable } = episode;
+  writeFileSync(tmp, JSON.stringify(serializable));
+  try {
+    renameSync(tmp, target);
+  } catch (err) {
+    try { unlinkSync(tmp); } catch {}
+    throw err;
+  }
+}
+
+/**
+ * Create a new empty episode buffer.
+ * @param {string} sessionId The current session ID
+ * @param {string} project The current project name
+ * @returns {object} A fresh episode object
+ */
+export function createEpisode(sessionId, project) {
+  return {
+    sessionId,
+    project,
+    startedAt: Date.now(),
+    lastAt: Date.now(),
+    files: [],
+    entries: [],
+    filesRead: [],
+    fileHistoryShown: [],
+  };
+}
+
+/**
+ * Add file paths to an episode's file tracking set (deduped).
+ * @param {object} episode The episode to update
+ * @param {string[]} files Array of file paths to add
+ */
+export function addFileToEpisode(episode, files) {
+  if (!episode._fileSet) episode._fileSet = new Set(episode.files);
+  for (const f of files) {
+    if (!episode._fileSet.has(f)) {
+      episode._fileSet.add(f);
+      episode.files.push(f);
+    }
+  }
+}
+
+/**
+ * Write a pending entry to a recovery file when the episode lock cannot be acquired.
+ * @param {object} entry The episode entry to persist
+ * @param {string} sessionId The current session ID
+ * @param {string} project The current project name
+ */
+export function writePendingEntry(entry, sessionId, project) {
+  const ts = Date.now();
+  const rand = Math.random().toString(36).slice(2, 6);
+  const pendingFile = join(RUNTIME_DIR, `pending-${ts}-${rand}.json`);
+  const tmp = pendingFile + '.tmp';
+  try {
+    writeFileSync(tmp, JSON.stringify({ entry, sessionId, project, ts }));
+    renameSync(tmp, pendingFile);
+  } catch {
+    try { unlinkSync(tmp); } catch {}
+  }
+}
+
+/**
+ * Merge pending recovery entries into the current episode buffer.
+ * Reads and removes pending-*.json files from the runtime directory.
+ * @param {object} episode The episode to merge entries into
+ */
+export function mergePendingEntries(episode) {
+  const oneHourAgo = Date.now() - 3600000;
+  const MAX_PENDING_MERGE = 50;
+  let files;
+  try {
+    files = readdirSync(RUNTIME_DIR).filter(f => f.startsWith('pending-')).sort();
+  } catch { return; }
+
+  let merged = 0;
+  for (const f of files) {
+    if (merged >= MAX_PENDING_MERGE) break;
+    const fp = join(RUNTIME_DIR, f);
+    try {
+      const raw = readFileSync(fp, 'utf8');
+      const pending = JSON.parse(raw);
+      if (pending.ts < oneHourAgo) { try { unlinkSync(fp); } catch {} continue; }
+      // Only merge entries belonging to the same project
+      if (pending.project && episode.project && pending.project !== episode.project) continue;
+      unlinkSync(fp);
+      if (pending.entry) {
+        episode.entries.push(pending.entry);
+        episode.lastAt = Math.max(episode.lastAt, pending.entry.ts || pending.ts);
+        addFileToEpisode(episode, pending.entry.files || []);
+        merged++;
+      }
+    } catch {
+      // Corrupt pending file — remove
+      try { unlinkSync(fp); } catch {}
+    }
+  }
+}
+
+/**
+ * Check if an episode has significant content worth processing with LLM.
+ * Significant = contains file edits or Bash errors.
+ * @param {object} episode The episode to check
+ * @returns {boolean} true if the episode has significant content
+ */
+export function episodeHasSignificantContent(episode) {
+  return episode.entries.some(e =>
+    ['Edit', 'Write', 'NotebookEdit'].includes(e.tool) ||
+    (e.tool === 'Bash' && e.isError)
+  );
+}