learning-agent 0.2.2 → 0.2.3

package/dist/index.d.ts

@@ -222,61 +222,40 @@ declare function appendLesson(repoRoot: string, lesson: Lesson): Promise<void>;
 declare function readLessons(repoRoot: string, options?: ReadLessonsOptions): Promise<ReadLessonsResult>;
 
 /**
- * SQLite storage layer with FTS5 for full-text search
- *
- * Rebuildable index - not the source of truth.
- * Stored in .claude/.cache (gitignored).
+ * SQLite database connection management.
  */
 
 /** Relative path to database file from repo root */
 declare const DB_PATH = ".claude/.cache/lessons.sqlite";
 /**
- * Close the database connection and release resources.
- *
- * **Resource lifecycle:**
- * - The database is opened lazily on first call to `openDb()` or any function that uses it
- *   (e.g., `searchKeyword`, `rebuildIndex`, `syncIfNeeded`, `getCachedEmbedding`)
- * - Once opened, the connection remains active until `closeDb()` is called
- * - After closing, subsequent database operations will reopen the connection
- *
- * **When to call:**
- * - At the end of CLI commands to ensure clean process exit
- * - When transitioning between repositories in long-running processes
- * - Before process exit in graceful shutdown handlers
- *
- * **Best practices for long-running processes:**
- * - In single-operation scripts: call before exit
- * - In daemon/server processes: call in shutdown handler
- * - Not necessary to call between operations in the same repository
- *
- * @example
- * ```typescript
- * // CLI command pattern
- * try {
- *   await searchKeyword(repoRoot, 'typescript', 10);
- *   // ... process results
- * } finally {
- *   closeDb();
- * }
- *
- * // Graceful shutdown pattern
- * process.on('SIGTERM', () => {
- *   closeDb();
- *   process.exit(0);
- * });
- * ```
+ * Close the SQLite database connection.
  */
 declare function closeDb(): void;
+
+/**
+ * SQLite index synchronization with JSONL source of truth.
+ */
+
 /**
- * Rebuild the SQLite index from the JSONL source of truth.
- * Preserves embeddings where content hash is unchanged.
- * Updates the last sync mtime after successful rebuild.
+ * Rebuild the SQLite index from JSONL source of truth.
+ * Gracefully degrades: no-op with warning if SQLite unavailable.
+ * Preserves cached embeddings when lesson content hasn't changed.
+ * @param repoRoot - Absolute path to repository root
  */
 declare function rebuildIndex(repoRoot: string): Promise<void>;
+
+/**
+ * SQLite search operations using FTS5 full-text search.
+ */
+
 /**
- * Search lessons using FTS5 keyword search.
- * Returns matching lessons up to the specified limit.
- * Increments retrieval count for all returned lessons.
+ * Search lessons using FTS5 full-text search.
+ * Does NOT degrade gracefully: throws error if SQLite unavailable.
+ * @param repoRoot - Absolute path to repository root
+ * @param query - FTS5 query string
+ * @param limit - Maximum number of results
+ * @returns Matching lessons
+ * @throws Error if SQLite unavailable (FTS5 required)
  */
 declare function searchKeyword(repoRoot: string, query: string, limit: number): Promise<Lesson[]>;
 
@@ -813,6 +792,10 @@ declare function formatLessonsCheck(lessons: ScoredLesson[]): string;
  * @see {@link unloadEmbedding} for embedding model cleanup
  * @module learning-agent
  */
-declare const VERSION = "0.1.0";
+/**
+ * Package version - must match package.json.
+ * Update this when releasing a new version.
+ */
+declare const VERSION = "0.2.3";
 
 export { type ActionabilityResult, type Context, type CorrectionSignal, DB_PATH, type DetectedCorrection, type DetectedSelfCorrection, type DetectedTestFailure, type EditEntry, type EditHistory, LESSONS_PATH, type Lesson, LessonSchema, type LessonType, LessonTypeSchema, MODEL_FILENAME, MODEL_URI, type NoveltyOptions, type NoveltyResult, type ParseError, type PlanRetrievalResult, type ProposeResult, type RankedLesson, type ReadLessonsOptions, type ReadLessonsResult, type ScoredLesson, type SearchVectorOptions, type Severity, type Source, type SpecificityResult, type TestResult, type Tombstone, TombstoneSchema, VERSION, appendLesson, calculateScore, closeDb, confirmationBoost, cosineSimilarity, detectSelfCorrection, detectTestFailure, detectUserCorrection, embedText, embedTexts, formatLessonsCheck, generateId, getEmbedding, isActionable, isModelAvailable, isNovel, isSpecific, loadSessionLessons, rankLessons, readLessons, rebuildIndex, recencyBoost, resolveModel, retrieveForPlan, searchKeyword, searchVector, severityBoost, shouldPropose, unloadEmbedding };

package/dist/index.js

@@ -2,8 +2,8 @@ import { mkdir, appendFile, readFile } from 'fs/promises';
 import { join, dirname } from 'path';
 import { createHash } from 'crypto';
 import { z } from 'zod';
+import { createRequire } from 'module';
 import { existsSync, mkdirSync, statSync } from 'fs';
-import Database from 'better-sqlite3';
 import { resolveModelFile, getLlama } from 'node-llama-cpp';
 import { homedir } from 'os';
 
@@ -158,9 +158,45 @@ async function readLessons(repoRoot, options = {}) {
   }
   return { lessons: Array.from(lessons.values()), skippedCount };
 }
-var DB_PATH = ".claude/.cache/lessons.sqlite";
+var require2 = createRequire(import.meta.url);
+var sqliteAvailable = null;
+var sqliteWarningLogged = false;
+var DatabaseConstructor = null;
+function isSqliteAvailable() {
+  if (sqliteAvailable !== null) {
+    return sqliteAvailable;
+  }
+  try {
+    const module = require2("better-sqlite3");
+    const Constructor = module.default || module;
+    const testDb = new Constructor(":memory:");
+    testDb.close();
+    DatabaseConstructor = Constructor;
+    sqliteAvailable = true;
+  } catch {
+    sqliteAvailable = false;
+    if (!sqliteWarningLogged) {
+      console.warn("SQLite unavailable, running in JSONL-only mode");
+      sqliteWarningLogged = true;
+    }
+  }
+  return sqliteAvailable;
+}
+function logDegradationWarning() {
+  if (!sqliteAvailable && !sqliteWarningLogged) {
+    console.warn("SQLite unavailable, running in JSONL-only mode");
+    sqliteWarningLogged = true;
+  }
+}
+function getDatabaseConstructor() {
+  if (!isSqliteAvailable()) {
+    return null;
+  }
+  return DatabaseConstructor;
+}
+
+// src/storage/sqlite/schema.ts
 var SCHEMA_SQL = `
-  -- Main lessons table
   CREATE TABLE IF NOT EXISTS lessons (
     id TEXT PRIMARY KEY,
     type TEXT NOT NULL,
@@ -180,7 +216,6 @@ var SCHEMA_SQL = `
     last_retrieved TEXT,
     embedding BLOB,
     content_hash TEXT,
-    -- v0.2.2 fields
     invalidated_at TEXT,
     invalidation_reason TEXT,
     citation_file TEXT,
@@ -190,29 +225,21 @@ var SCHEMA_SQL = `
     compacted_at TEXT
   );
 
-  -- FTS5 virtual table for full-text search
   CREATE VIRTUAL TABLE IF NOT EXISTS lessons_fts USING fts5(
-    id,
-    trigger,
-    insight,
-    tags,
-    content='lessons',
-    content_rowid='rowid'
+    id, trigger, insight, tags,
+    content='lessons', content_rowid='rowid'
   );
 
-  -- Trigger to sync FTS on INSERT
   CREATE TRIGGER IF NOT EXISTS lessons_ai AFTER INSERT ON lessons BEGIN
     INSERT INTO lessons_fts(rowid, id, trigger, insight, tags)
     VALUES (new.rowid, new.id, new.trigger, new.insight, new.tags);
   END;
 
-  -- Trigger to sync FTS on DELETE
   CREATE TRIGGER IF NOT EXISTS lessons_ad AFTER DELETE ON lessons BEGIN
     INSERT INTO lessons_fts(lessons_fts, rowid, id, trigger, insight, tags)
     VALUES ('delete', old.rowid, old.id, old.trigger, old.insight, old.tags);
   END;
 
-  -- Trigger to sync FTS on UPDATE
   CREATE TRIGGER IF NOT EXISTS lessons_au AFTER UPDATE ON lessons BEGIN
     INSERT INTO lessons_fts(lessons_fts, rowid, id, trigger, insight, tags)
     VALUES ('delete', old.rowid, old.id, old.trigger, old.insight, old.tags);
@@ -220,12 +247,10 @@ var SCHEMA_SQL = `
     VALUES (new.rowid, new.id, new.trigger, new.insight, new.tags);
   END;
 
-  -- Index for common queries
   CREATE INDEX IF NOT EXISTS idx_lessons_created ON lessons(created);
   CREATE INDEX IF NOT EXISTS idx_lessons_confirmed ON lessons(confirmed);
   CREATE INDEX IF NOT EXISTS idx_lessons_severity ON lessons(severity);
 
-  -- Metadata table for sync tracking
   CREATE TABLE IF NOT EXISTS metadata (
     key TEXT PRIMARY KEY,
     value TEXT NOT NULL
@@ -234,17 +259,35 @@ var SCHEMA_SQL = `
 function createSchema(database) {
   database.exec(SCHEMA_SQL);
 }
+
+// src/storage/sqlite/connection.ts
+var DB_PATH = ".claude/.cache/lessons.sqlite";
 var db = null;
-function contentHash(trigger, insight) {
-  return createHash("sha256").update(`${trigger} ${insight}`).digest("hex");
-}
-function openDb(repoRoot) {
-  if (db) return db;
-  const dbPath = join(repoRoot, DB_PATH);
-  const dir = dirname(dbPath);
-  mkdirSync(dir, { recursive: true });
-  db = new Database(dbPath);
-  db.pragma("journal_mode = WAL");
+var dbIsInMemory = false;
+function openDb(repoRoot, options = {}) {
+  if (!isSqliteAvailable()) {
+    return null;
+  }
+  const { inMemory = false } = options;
+  if (db) {
+    if (inMemory !== dbIsInMemory) {
+      closeDb();
+    } else {
+      return db;
+    }
+  }
+  const Database = getDatabaseConstructor();
+  if (inMemory) {
+    db = new Database(":memory:");
+    dbIsInMemory = true;
+  } else {
+    const dbPath = join(repoRoot, DB_PATH);
+    const dir = dirname(dbPath);
+    mkdirSync(dir, { recursive: true });
+    db = new Database(dbPath);
+    dbIsInMemory = false;
+    db.pragma("journal_mode = WAL");
+  }
   createSchema(db);
   return db;
 }
@@ -252,10 +295,18 @@ function closeDb() {
   if (db) {
     db.close();
     db = null;
+    dbIsInMemory = false;
   }
 }
+function contentHash(trigger, insight) {
+  return createHash("sha256").update(`${trigger} ${insight}`).digest("hex");
+}
 function getCachedEmbedding(repoRoot, lessonId, expectedHash) {
   const database = openDb(repoRoot);
+  if (!database) {
+    logDegradationWarning();
+    return null;
+  }
   const row = database.prepare("SELECT embedding, content_hash FROM lessons WHERE id = ?").get(lessonId);
   if (!row || !row.embedding || !row.content_hash) {
     return null;
@@ -272,60 +323,14 @@ function getCachedEmbedding(repoRoot, lessonId, expectedHash) {
 }
 function setCachedEmbedding(repoRoot, lessonId, embedding, hash) {
   const database = openDb(repoRoot);
+  if (!database) {
+    logDegradationWarning();
+    return;
+  }
   const float32 = embedding instanceof Float32Array ? embedding : new Float32Array(embedding);
   const buffer = Buffer.from(float32.buffer, float32.byteOffset, float32.byteLength);
   database.prepare("UPDATE lessons SET embedding = ?, content_hash = ? WHERE id = ?").run(buffer, hash, lessonId);
 }
-function rowToLesson(row) {
-  const lesson = {
-    id: row.id,
-    type: row.type,
-    trigger: row.trigger,
-    insight: row.insight,
-    tags: row.tags ? row.tags.split(",").filter(Boolean) : [],
-    source: row.source,
-    context: JSON.parse(row.context),
-    supersedes: JSON.parse(row.supersedes),
-    related: JSON.parse(row.related),
-    created: row.created,
-    confirmed: row.confirmed === 1
-  };
-  if (row.evidence !== null) {
-    lesson.evidence = row.evidence;
-  }
-  if (row.severity !== null) {
-    lesson.severity = row.severity;
-  }
-  if (row.deleted === 1) {
-    lesson.deleted = true;
-  }
-  if (row.retrieval_count > 0) {
-    lesson.retrievalCount = row.retrieval_count;
-  }
-  if (row.invalidated_at !== null) {
-    lesson.invalidatedAt = row.invalidated_at;
-  }
-  if (row.invalidation_reason !== null) {
-    lesson.invalidationReason = row.invalidation_reason;
-  }
-  if (row.citation_file !== null) {
-    lesson.citation = {
-      file: row.citation_file,
-      ...row.citation_line !== null && { line: row.citation_line },
-      ...row.citation_commit !== null && { commit: row.citation_commit }
-    };
-  }
-  if (row.compaction_level !== null && row.compaction_level !== 0) {
-    lesson.compactionLevel = row.compaction_level;
-  }
-  if (row.compacted_at !== null) {
-    lesson.compactedAt = row.compacted_at;
-  }
-  if (row.last_retrieved !== null) {
-    lesson.lastRetrieved = row.last_retrieved;
-  }
-  return lesson;
-}
 function collectCachedEmbeddings(database) {
   const cache = /* @__PURE__ */ new Map();
   const rows = database.prepare("SELECT id, embedding, content_hash FROM lessons WHERE embedding IS NOT NULL").all();
@@ -358,6 +363,10 @@ function setLastSyncMtime(database, mtime) {
 }
 async function rebuildIndex(repoRoot) {
   const database = openDb(repoRoot);
+  if (!database) {
+    logDegradationWarning();
+    return;
+  }
   const { lessons } = await readLessons(repoRoot);
   const cachedEmbeddings = collectCachedEmbeddings(database);
   database.exec("DELETE FROM lessons");
@@ -393,7 +402,6 @@ async function rebuildIndex(repoRoot) {
         last_retrieved: lesson.lastRetrieved ?? null,
         embedding: hasValidCache ? cached.embedding : null,
         content_hash: hasValidCache ? cached.contentHash : null,
-        // v0.2.2 fields
         invalidated_at: lesson.invalidatedAt ?? null,
         invalidation_reason: lesson.invalidationReason ?? null,
         citation_file: lesson.citation?.file ?? null,
@@ -411,12 +419,17 @@ async function rebuildIndex(repoRoot) {
   }
 }
 async function syncIfNeeded(repoRoot, options = {}) {
+  if (!isSqliteAvailable()) {
+    logDegradationWarning();
+    return false;
+  }
   const { force = false } = options;
   const jsonlMtime = getJsonlMtime(repoRoot);
   if (jsonlMtime === null && !force) {
     return false;
   }
   const database = openDb(repoRoot);
+  if (!database) return false;
   const lastSyncMtime = getLastSyncMtime(database);
   const needsRebuild = force || lastSyncMtime === null || jsonlMtime !== null && jsonlMtime > lastSyncMtime;
   if (needsRebuild) {
@@ -425,8 +438,70 @@ async function syncIfNeeded(repoRoot, options = {}) {
   }
   return false;
 }
+
+// src/storage/sqlite/search.ts
+function rowToLesson(row) {
+  const lesson = {
+    id: row.id,
+    type: row.type,
+    trigger: row.trigger,
+    insight: row.insight,
+    tags: row.tags ? row.tags.split(",").filter(Boolean) : [],
+    source: row.source,
+    context: JSON.parse(row.context),
+    supersedes: JSON.parse(row.supersedes),
+    related: JSON.parse(row.related),
+    created: row.created,
+    confirmed: row.confirmed === 1
+  };
+  if (row.evidence !== null) lesson.evidence = row.evidence;
+  if (row.severity !== null) lesson.severity = row.severity;
+  if (row.deleted === 1) lesson.deleted = true;
+  if (row.retrieval_count > 0) lesson.retrievalCount = row.retrieval_count;
+  if (row.invalidated_at !== null) lesson.invalidatedAt = row.invalidated_at;
+  if (row.invalidation_reason !== null) lesson.invalidationReason = row.invalidation_reason;
+  if (row.citation_file !== null) {
+    lesson.citation = {
+      file: row.citation_file,
+      ...row.citation_line !== null && { line: row.citation_line },
+      ...row.citation_commit !== null && { commit: row.citation_commit }
+    };
+  }
+  if (row.compaction_level !== null && row.compaction_level !== 0) {
+    lesson.compactionLevel = row.compaction_level;
+  }
+  if (row.compacted_at !== null) lesson.compactedAt = row.compacted_at;
+  if (row.last_retrieved !== null) lesson.lastRetrieved = row.last_retrieved;
+  return lesson;
+}
+function incrementRetrievalCount(repoRoot, lessonIds) {
+  if (lessonIds.length === 0) return;
+  const database = openDb(repoRoot);
+  if (!database) {
+    logDegradationWarning();
+    return;
+  }
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  const update = database.prepare(`
+    UPDATE lessons
+    SET retrieval_count = retrieval_count + 1,
+        last_retrieved = ?
+    WHERE id = ?
+  `);
+  const updateMany = database.transaction((ids) => {
+    for (const id of ids) {
+      update.run(now, id);
+    }
+  });
+  updateMany(lessonIds);
+}
 async function searchKeyword(repoRoot, query, limit) {
   const database = openDb(repoRoot);
+  if (!database) {
+    throw new Error(
+      "Keyword search requires SQLite (FTS5 required). Install native build tools or use vector search instead."
+    );
+  }
   const countResult = database.prepare("SELECT COUNT(*) as cnt FROM lessons").get();
   if (countResult.cnt === 0) return [];
   const rows = database.prepare(
@@ -444,22 +519,13 @@ async function searchKeyword(repoRoot, query, limit) {
   }
   return rows.map(rowToLesson);
 }
-function incrementRetrievalCount(repoRoot, lessonIds) {
-  if (lessonIds.length === 0) return;
-  const database = openDb(repoRoot);
-  const now = (/* @__PURE__ */ new Date()).toISOString();
-  const update = database.prepare(`
-    UPDATE lessons
-    SET retrieval_count = retrieval_count + 1,
-        last_retrieved = ?
-    WHERE id = ?
-  `);
-  const updateMany = database.transaction((ids) => {
-    for (const id of ids) {
-      update.run(now, id);
-    }
-  });
-  updateMany(lessonIds);
+
+// src/utils.ts
+var MS_PER_DAY = 24 * 60 * 60 * 1e3;
+function getLessonAgeDays(lesson) {
+  const created = new Date(lesson.created).getTime();
+  const now = Date.now();
+  return Math.floor((now - created) / MS_PER_DAY);
 }
 var MODEL_URI = "hf:ggml-org/embeddinggemma-300M-qat-q4_0-GGUF/embeddinggemma-300M-qat-Q4_0.gguf";
 var MODEL_FILENAME = "hf_ggml-org_embeddinggemma-300M-qat-Q4_0.gguf";
@@ -544,14 +610,6 @@ async function searchVector(repoRoot, query, options) {
   return scored.slice(0, limit);
 }
 
-// src/utils.ts
-var MS_PER_DAY = 24 * 60 * 60 * 1e3;
-function getLessonAgeDays(lesson) {
-  const created = new Date(lesson.created).getTime();
-  const now = Date.now();
-  return Math.floor((now - created) / MS_PER_DAY);
-}
-
 // src/search/ranking.ts
 var RECENCY_THRESHOLD_DAYS = 30;
 var HIGH_SEVERITY_BOOST = 1.5;
@@ -783,7 +841,7 @@ async function retrieveForPlan(repoRoot, planText, limit = DEFAULT_LIMIT3) {
   return { lessons: topLessons, message };
 }
 function formatLessonsCheck(lessons) {
-  const header = "\u{1F4DA} Lessons Check\n" + "\u2500".repeat(40);
+  const header = "Lessons Check\n" + "\u2500".repeat(40);
   if (lessons.length === 0) {
     return `${header}
 No relevant lessons found for this plan.`;
@@ -798,7 +856,7 @@ ${lessonLines.join("\n")}`;
 }
 
 // src/index.ts
-var VERSION = "0.1.0";
+var VERSION = "0.2.3";
 
 export { DB_PATH, LESSONS_PATH, LessonSchema, LessonTypeSchema, MODEL_FILENAME, MODEL_URI, TombstoneSchema, VERSION, appendLesson, calculateScore, closeDb, confirmationBoost, cosineSimilarity, detectSelfCorrection, detectTestFailure, detectUserCorrection, embedText, embedTexts, formatLessonsCheck, generateId, getEmbedding, isActionable, isModelAvailable, isNovel, isSpecific, loadSessionLessons, rankLessons, readLessons, rebuildIndex, recencyBoost, resolveModel, retrieveForPlan, searchKeyword, searchVector, severityBoost, shouldPropose, unloadEmbedding };
 //# sourceMappingURL=index.js.map