learning-agent 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,780 @@
+import { z } from 'zod';
+import { LlamaEmbeddingContext } from 'node-llama-cpp';
+
+/**
+ * Lesson type definitions using Zod schemas
+ */
+
+declare const SourceSchema: z.ZodEnum<["user_correction", "self_correction", "test_failure", "manual"]>;
+declare const ContextSchema: z.ZodObject<{
+    tool: z.ZodString;
+    intent: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    tool: string;
+    intent: string;
+}, {
+    tool: string;
+    intent: string;
+}>;
+declare const SeveritySchema: z.ZodEnum<["high", "medium", "low"]>;
+declare const LessonTypeSchema: z.ZodEnum<["quick", "full"]>;
+/**
+ * Unified Lesson schema.
+ *
+ * The `type` field is a semantic marker:
+ * - 'quick': Minimal lesson for fast capture
+ * - 'full': Important lesson (typically has evidence/severity)
+ *
+ * All fields except core identity are optional for flexibility.
+ * Semantic meaning is preserved through convention, not schema enforcement.
+ */
+declare const LessonSchema: z.ZodObject<{
+    id: z.ZodString;
+    type: z.ZodEnum<["quick", "full"]>;
+    trigger: z.ZodString;
+    insight: z.ZodString;
+    tags: z.ZodArray<z.ZodString, "many">;
+    source: z.ZodEnum<["user_correction", "self_correction", "test_failure", "manual"]>;
+    context: z.ZodObject<{
+        tool: z.ZodString;
+        intent: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        tool: string;
+        intent: string;
+    }, {
+        tool: string;
+        intent: string;
+    }>;
+    created: z.ZodString;
+    confirmed: z.ZodBoolean;
+    supersedes: z.ZodArray<z.ZodString, "many">;
+    related: z.ZodArray<z.ZodString, "many">;
+    evidence: z.ZodOptional<z.ZodString>;
+    severity: z.ZodOptional<z.ZodEnum<["high", "medium", "low"]>>;
+    pattern: z.ZodOptional<z.ZodObject<{
+        bad: z.ZodString;
+        good: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        bad: string;
+        good: string;
+    }, {
+        bad: string;
+        good: string;
+    }>>;
+    deleted: z.ZodOptional<z.ZodBoolean>;
+    retrievalCount: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    type: "quick" | "full";
+    id: string;
+    trigger: string;
+    insight: string;
+    tags: string[];
+    source: "user_correction" | "self_correction" | "test_failure" | "manual";
+    context: {
+        tool: string;
+        intent: string;
+    };
+    created: string;
+    confirmed: boolean;
+    supersedes: string[];
+    related: string[];
+    evidence?: string | undefined;
+    severity?: "high" | "medium" | "low" | undefined;
+    pattern?: {
+        bad: string;
+        good: string;
+    } | undefined;
+    deleted?: boolean | undefined;
+    retrievalCount?: number | undefined;
+}, {
+    type: "quick" | "full";
+    id: string;
+    trigger: string;
+    insight: string;
+    tags: string[];
+    source: "user_correction" | "self_correction" | "test_failure" | "manual";
+    context: {
+        tool: string;
+        intent: string;
+    };
+    created: string;
+    confirmed: boolean;
+    supersedes: string[];
+    related: string[];
+    evidence?: string | undefined;
+    severity?: "high" | "medium" | "low" | undefined;
+    pattern?: {
+        bad: string;
+        good: string;
+    } | undefined;
+    deleted?: boolean | undefined;
+    retrievalCount?: number | undefined;
+}>;
+declare const TombstoneSchema: z.ZodObject<{
+    id: z.ZodString;
+    deleted: z.ZodLiteral<true>;
+    deletedAt: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    deleted: true;
+    deletedAt: string;
+}, {
+    id: string;
+    deleted: true;
+    deletedAt: string;
+}>;
+type Lesson = z.infer<typeof LessonSchema>;
+type LessonType = z.infer<typeof LessonTypeSchema>;
+type Tombstone = z.infer<typeof TombstoneSchema>;
+type Source = z.infer<typeof SourceSchema>;
+type Severity = z.infer<typeof SeveritySchema>;
+type Context = z.infer<typeof ContextSchema>;
+/**
+ * Generate deterministic lesson ID from insight text.
+ * Format: L + 8 hex characters from SHA-256 hash
+ */
+declare function generateId(insight: string): string;
+
+/**
+ * JSONL storage layer for lessons
+ *
+ * Append-only storage with last-write-wins deduplication.
+ * Source of truth - git trackable.
+ */
+
+/** Relative path to lessons file from repo root */
+declare const LESSONS_PATH = ".claude/lessons/index.jsonl";
+/** Options for reading lessons */
+interface ReadLessonsOptions {
+    /** If true, throw on first parse error. Default: false (skip errors) */
+    strict?: boolean;
+    /** Callback for each parse error in non-strict mode */
+    onParseError?: (error: ParseError) => void;
+}
+/** Parse error details */
+interface ParseError {
+    /** 1-based line number */
+    line: number;
+    /** Error message */
+    message: string;
+    /** Original error */
+    cause: unknown;
+}
+/** Result of reading lessons */
+interface ReadLessonsResult {
+    /** Successfully parsed lessons */
+    lessons: Lesson[];
+    /** Number of lines skipped due to errors */
+    skippedCount: number;
+}
+/**
+ * Append a lesson to the JSONL file.
+ * Creates directory structure if missing.
+ */
+declare function appendLesson(repoRoot: string, lesson: Lesson): Promise<void>;
+/**
+ * Read all non-deleted lessons from the JSONL file.
+ * Applies last-write-wins deduplication by ID.
+ * Returns result object with lessons and skippedCount.
+ *
+ * @param repoRoot - Repository root directory
+ * @param options - Optional settings for error handling
+ * @returns Result with lessons array and count of skipped lines
+ */
+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).
+ */
+
+/** 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);
+ * });
+ * ```
+ */
+declare function closeDb(): void;
+/**
+ * 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.
+ */
+declare function rebuildIndex(repoRoot: string): Promise<void>;
+/**
+ * Search lessons using FTS5 keyword search.
+ * Returns matching lessons up to the specified limit.
+ * Increments retrieval count for all returned lessons.
+ */
+declare function searchKeyword(repoRoot: string, query: string, limit: number): Promise<Lesson[]>;
+
+/**
+ * Embedding model resolution using node-llama-cpp's built-in resolver.
+ *
+ * Uses resolveModelFile for automatic download and caching.
+ * Model is stored in ~/.node-llama-cpp/models/ by default.
+ */
+/**
+ * HuggingFace URI for EmbeddingGemma-300M (Q4_0 quantization).
+ *
+ * - Size: ~278MB
+ * - Dimensions: 768 (default), supports MRL truncation to 512/256/128
+ * - Context: 2048 tokens
+ */
+declare const MODEL_URI = "hf:ggml-org/embeddinggemma-300M-qat-q4_0-GGUF/embeddinggemma-300M-qat-Q4_0.gguf";
+/**
+ * Expected model filename after download.
+ * node-llama-cpp uses format: hf_{org}_{filename}
+ */
+declare const MODEL_FILENAME = "hf_ggml-org_embeddinggemma-300M-qat-Q4_0.gguf";
+/**
+ * Check if the embedding model is available locally.
+ *
+ * @returns true if model file exists
+ */
+declare function isModelAvailable(): boolean;
+/**
+ * Resolve the embedding model path, downloading if necessary.
+ *
+ * Uses node-llama-cpp's resolveModelFile for automatic download with progress.
+ *
+ * @param options - Optional configuration
+ * @param options.cli - Show download progress in console (default: true)
+ * @returns Path to the resolved model file
+ *
+ * @example
+ * ```typescript
+ * const modelPath = await resolveModel();
+ * const llama = await getLlama();
+ * const model = await llama.loadModel({ modelPath });
+ * ```
+ */
+declare function resolveModel(options?: {
+    cli?: boolean;
+}): Promise<string>;
+
+/**
+ * Text embedding via node-llama-cpp with EmbeddingGemma model
+ *
+ * **Resource lifecycle:**
+ * - Model is loaded lazily on first embedding call (~150MB in memory)
+ * - Once loaded, the model remains in memory until `unloadEmbedding()` is called
+ * - Loading is slow (~1-3s); keeping loaded improves subsequent call performance
+ *
+ * **Memory usage:**
+ * - Embedding model: ~150MB RAM when loaded
+ * - Embeddings themselves: ~3KB per embedding (768 dimensions x 4 bytes)
+ *
+ * @see {@link unloadEmbedding} for releasing memory
+ * @see {@link getEmbedding} for the lazy-loading mechanism
+ */
+
+/**
+ * Get the LlamaEmbeddingContext instance for generating embeddings.
+ *
+ * **Lazy loading behavior:**
+ * - First call loads the embedding model (~150MB) into memory
+ * - Loading takes ~1-3 seconds depending on hardware
+ * - Subsequent calls return the cached instance immediately
+ * - Downloads model automatically if not present
+ *
+ * **Resource lifecycle:**
+ * - Once loaded, model stays in memory until `unloadEmbedding()` is called
+ * - For CLI commands: typically load once, use, then unload on exit
+ * - For long-running processes: keep loaded for performance
+ *
+ * @returns The singleton embedding context
+ * @throws Error if model download fails
+ *
+ * @example
+ * ```typescript
+ * // Direct usage (prefer embedText for simple cases)
+ * const ctx = await getEmbedding();
+ * const result = await ctx.getEmbeddingFor('some text');
+ *
+ * // Ensure cleanup
+ * process.on('exit', () => unloadEmbedding());
+ * ```
+ *
+ * @see {@link embedText} for simpler text-to-vector conversion
+ * @see {@link unloadEmbedding} for releasing memory
+ */
+declare function getEmbedding(): Promise<LlamaEmbeddingContext>;
+/**
+ * Unload the embedding context to free memory (~150MB).
+ *
+ * **Resource lifecycle:**
+ * - Disposes the underlying LlamaEmbeddingContext
+ * - Releases ~150MB of RAM used by the model
+ * - After unloading, subsequent embedding calls will reload the model
+ *
+ * **When to call:**
+ * - At the end of CLI commands to ensure clean process exit
+ * - In memory-constrained environments after batch processing
+ * - Before process exit in graceful shutdown handlers
+ * - When switching to a different model (if supported in future)
+ *
+ * **Best practices:**
+ * - For single-operation scripts: call before exit
+ * - For daemon/server processes: call in shutdown handler
+ * - Not needed between embedding calls in the same process
+ *
+ * @example
+ * ```typescript
+ * // CLI command pattern
+ * try {
+ *   const embedding = await embedText('some text');
+ *   // ... use embedding
+ * } finally {
+ *   unloadEmbedding();
+ *   closeDb();
+ * }
+ *
+ * // Graceful shutdown pattern
+ * process.on('SIGTERM', () => {
+ *   unloadEmbedding();
+ *   closeDb();
+ *   process.exit(0);
+ * });
+ * ```
+ *
+ * @see {@link getEmbedding} for loading the model
+ * @see {@link closeDb} for database cleanup (often used together)
+ */
+declare function unloadEmbedding(): void;
+/**
+ * Embed a single text string into a vector.
+ *
+ * **Lazy loading:** First call loads the embedding model (~150MB, ~1-3s).
+ * Subsequent calls use the cached model and complete in milliseconds.
+ *
+ * @param text - The text to embed
+ * @returns A 768-dimensional vector (number[])
+ * @throws Error if model download fails
+ *
+ * @example
+ * ```typescript
+ * const vector = await embedText('TypeScript error handling');
+ * console.log(vector.length); // 768
+ *
+ * // Remember to clean up when done
+ * unloadEmbedding();
+ * ```
+ *
+ * @see {@link embedTexts} for batch embedding
+ * @see {@link unloadEmbedding} for releasing memory
+ */
+declare function embedText(text: string): Promise<number[]>;
+/**
+ * Embed multiple texts into vectors.
+ *
+ * **Lazy loading:** First call loads the embedding model (~150MB, ~1-3s).
+ * Subsequent calls use the cached model.
+ *
+ * **Performance:** More efficient than calling `embedText` in a loop
+ * when processing multiple texts, as model loading happens only once.
+ *
+ * @param texts - Array of texts to embed
+ * @returns Array of 768-dimensional vectors, same order as input
+ * @throws Error if model download fails
+ *
+ * @example
+ * ```typescript
+ * const texts = ['first text', 'second text'];
+ * const vectors = await embedTexts(texts);
+ * console.log(vectors.length); // 2
+ * console.log(vectors[0].length); // 768
+ *
+ * // Remember to clean up when done
+ * unloadEmbedding();
+ * ```
+ *
+ * @see {@link embedText} for single text embedding
+ * @see {@link unloadEmbedding} for releasing memory
+ */
+declare function embedTexts(texts: string[]): Promise<number[][]>;
+
+/**
+ * Vector search with cosine similarity
+ *
+ * Embeds query text and ranks lessons by semantic similarity.
+ * Uses SQLite cache to avoid recomputing embeddings.
+ */
+
+/**
+ * Calculate cosine similarity between two vectors.
+ * Returns value between -1 (opposite) and 1 (identical).
+ */
+declare function cosineSimilarity(a: number[], b: number[]): number;
+/** Lesson with similarity score */
+interface ScoredLesson {
+    lesson: Lesson;
+    score: number;
+}
+/** Options for vector search */
+interface SearchVectorOptions {
+    /** Maximum number of results to return (default: 10) */
+    limit?: number;
+}
+/**
+ * Search lessons by vector similarity to query text.
+ * Returns top N lessons sorted by similarity score (descending).
+ * Uses embedding cache to avoid recomputing embeddings.
+ */
+declare function searchVector(repoRoot: string, query: string, options?: SearchVectorOptions): Promise<ScoredLesson[]>;
+
+/**
+ * Multi-factor lesson ranking system
+ *
+ * Combines vector similarity with semantic boosts:
+ * - Severity: high=1.5, medium=1.0, low=0.8
+ * - Recency: 1.2 for lessons ≤30 days old
+ * - Confirmation: 1.3 for confirmed lessons
+ */
+
+/** Lesson with final ranked score */
+interface RankedLesson extends ScoredLesson {
+    finalScore?: number;
+}
+/**
+ * Calculate severity boost based on lesson severity.
+ * Lessons without severity get 1.0 (medium boost).
+ */
+declare function severityBoost(lesson: Lesson): number;
+/**
+ * Calculate recency boost based on lesson age.
+ * Lessons ≤30 days old get 1.2, older get 1.0.
+ */
+declare function recencyBoost(lesson: Lesson): number;
+/**
+ * Calculate confirmation boost.
+ * Confirmed lessons get 1.3, unconfirmed get 1.0.
+ */
+declare function confirmationBoost(lesson: Lesson): number;
+/**
+ * Calculate combined score for a lesson.
+ * score = vectorSimilarity * severity * recency * confirmation
+ */
+declare function calculateScore(lesson: Lesson, vectorSimilarity: number): number;
+/**
+ * Rank lessons by combined score.
+ * Returns new array sorted by finalScore descending.
+ */
+declare function rankLessons(lessons: ScoredLesson[]): RankedLesson[];
+
+/**
+ * Quality filters for lesson capture
+ *
+ * Filters to ensure lessons are:
+ * - Novel (not duplicate)
+ * - Specific (not vague)
+ * - Actionable (contains action words)
+ */
+/** Result of novelty check */
+interface NoveltyResult {
+    novel: boolean;
+    reason?: string;
+    existingId?: string;
+}
+/** Options for novelty check */
+interface NoveltyOptions {
+    threshold?: number;
+}
+/**
+ * Check if an insight is novel (not a duplicate of existing lessons).
+ * Uses keyword search to find potentially similar lessons.
+ */
+declare function isNovel(repoRoot: string, insight: string, options?: NoveltyOptions): Promise<NoveltyResult>;
+/** Result of specificity check */
+interface SpecificityResult {
+    specific: boolean;
+    reason?: string;
+}
+/**
+ * Check if an insight is specific enough to be useful.
+ * Rejects vague, generic advice that doesn't provide actionable guidance.
+ */
+declare function isSpecific(insight: string): SpecificityResult;
+/** Result of actionability check */
+interface ActionabilityResult {
+    actionable: boolean;
+    reason?: string;
+}
+/**
+ * Check if an insight contains actionable guidance.
+ * Returns false for pure observations or questions.
+ */
+declare function isActionable(insight: string): ActionabilityResult;
+/** Result of combined quality check */
+interface ProposeResult {
+    shouldPropose: boolean;
+    reason?: string;
+}
+/**
+ * Combined quality check for lesson proposals.
+ * Returns true only if insight is novel, specific, AND actionable.
+ */
+declare function shouldPropose(repoRoot: string, insight: string): Promise<ProposeResult>;
+
+/**
+ * Trigger detection for automatic lesson capture
+ *
+ * Detects patterns that indicate potential learning opportunities:
+ * - User corrections
+ * - Self-corrections
+ * - Test failures
+ */
+
+/** Signal data for correction detection */
+interface CorrectionSignal {
+    messages: string[];
+    context: Context;
+}
+/** Detected correction result */
+interface DetectedCorrection {
+    trigger: string;
+    correctionMessage: string;
+    context: Context;
+}
+/**
+ * Detect user correction signals in conversation.
+ *
+ * Looks for patterns that indicate the user is correcting Claude's
+ * understanding or actions.
+ *
+ * @param signals - Messages and context to analyze
+ * @returns Detected correction or null if none found
+ */
+declare function detectUserCorrection(signals: CorrectionSignal): DetectedCorrection | null;
+/** Edit history entry */
+interface EditEntry {
+    file: string;
+    success: boolean;
+    timestamp: number;
+}
+/** Edit history for self-correction detection */
+interface EditHistory {
+    edits: EditEntry[];
+}
+/** Detected self-correction */
+interface DetectedSelfCorrection {
+    file: string;
+    trigger: string;
+}
+/**
+ * Detect self-correction patterns in edit history.
+ *
+ * Looks for edit→fail→re-edit patterns on the same file,
+ * which indicate Claude had to correct its own work.
+ *
+ * @param history - Edit history to analyze
+ * @returns Detected self-correction or null if none found
+ */
+declare function detectSelfCorrection(history: EditHistory): DetectedSelfCorrection | null;
+/** Test result for failure detection */
+interface TestResult {
+    passed: boolean;
+    output: string;
+    testFile: string;
+}
+/** Detected test failure */
+interface DetectedTestFailure {
+    testFile: string;
+    errorOutput: string;
+    trigger: string;
+}
+/**
+ * Detect test failure patterns.
+ *
+ * When tests fail, this creates a potential learning opportunity
+ * if the failure is later fixed.
+ *
+ * @param testResult - Test result to analyze
+ * @returns Detected test failure or null if tests passed
+ */
+declare function detectTestFailure(testResult: TestResult): DetectedTestFailure | null;
+
+/**
+ * Session-start lesson retrieval
+ *
+ * Loads high-severity lessons at the start of a session.
+ * No vector search - just filter by severity and recency.
+ */
+
+/** A full lesson with severity field present */
+type FullLesson = Lesson & {
+    type: 'full';
+    severity: Severity;
+};
+/**
+ * Load high-severity lessons for session start.
+ *
+ * Returns confirmed, high-severity lessons sorted by recency.
+ * These are the most important lessons to surface at the start
+ * of a coding session.
+ *
+ * @param repoRoot - Repository root directory
+ * @param limit - Maximum number of lessons to return (default: 5)
+ * @returns Array of high-severity lessons, most recent first
+ */
+declare function loadSessionLessons(repoRoot: string, limit?: number): Promise<FullLesson[]>;
+
+/**
+ * Plan-time lesson retrieval
+ *
+ * Retrieves relevant lessons when planning an implementation.
+ * Uses vector search to find semantically similar lessons.
+ */
+
+/** Result of plan-time retrieval */
+interface PlanRetrievalResult {
+    lessons: RankedLesson[];
+    message: string;
+}
+/**
+ * Retrieve relevant lessons for a plan.
+ *
+ * Uses vector search to find semantically similar lessons,
+ * then applies ranking boosts for severity, recency, and confirmation.
+ *
+ * Hard-fails if embeddings are unavailable (propagates error from embedText).
+ *
+ * @param repoRoot - Repository root directory
+ * @param planText - The plan text to search against
+ * @param limit - Maximum number of lessons to return (default: 5)
+ * @returns Ranked lessons and formatted message
+ */
+declare function retrieveForPlan(repoRoot: string, planText: string, limit?: number): Promise<PlanRetrievalResult>;
+/**
+ * Format a "Lessons Check" message for display.
+ *
+ * This message is intended to be shown at plan-time to remind
+ * the developer of relevant lessons before implementation.
+ *
+ * @param lessons - Ranked lessons to include in the message
+ * @returns Formatted message string
+ */
+declare function formatLessonsCheck(lessons: ScoredLesson[]): string;
+
+/**
+ * Learning Agent - Repository-scoped learning system for Claude Code
+ *
+ * This package helps Claude Code learn from mistakes and avoid repeating them.
+ * It captures lessons during coding sessions and retrieves relevant lessons
+ * when planning new work.
+ *
+ * ## Quick Start
+ *
+ * ```typescript
+ * import { appendLesson, retrieveForPlan, loadSessionLessons } from 'learning-agent';
+ *
+ * // At session start, load high-severity lessons
+ * const criticalLessons = await loadSessionLessons(repoRoot);
+ *
+ * // When planning, retrieve relevant lessons
+ * const { lessons, message } = await retrieveForPlan(repoRoot, planText);
+ *
+ * // When capturing a lesson
+ * await appendLesson(repoRoot, lesson);
+ * ```
+ *
+ * ## Hook Integration
+ *
+ * Add to your `.claude/settings.json`:
+ *
+ * ```json
+ * {
+ *   "hooks": {
+ *     "session_start": "npx learning-agent load-session",
+ *     "pre_tool": "npx learning-agent check-plan"
+ *   }
+ * }
+ * ```
+ *
+ * ## Resource Management
+ *
+ * This library manages two heavyweight resources that require cleanup:
+ *
+ * ### SQLite Database
+ * - **Acquired:** Lazily on first database operation (search, rebuild, etc.)
+ * - **Memory:** Minimal (~few KB for connection, index cached by OS)
+ * - **Cleanup:** Call `closeDb()` before process exit
+ *
+ * ### Embedding Model
+ * - **Acquired:** Lazily on first embedding call (embedText, embedTexts, searchVector)
+ * - **Memory:** ~150MB RAM for the EmbeddingGemma model
+ * - **Cleanup:** Call `unloadEmbedding()` before process exit
+ *
+ * ### Recommended Cleanup Pattern
+ *
+ * ```typescript
+ * import { closeDb, unloadEmbedding } from 'learning-agent';
+ *
+ * // For CLI commands - use try/finally
+ * async function main() {
+ *   try {
+ *     // ... your code that uses learning-agent
+ *   } finally {
+ *     unloadEmbedding();
+ *     closeDb();
+ *   }
+ * }
+ *
+ * // For long-running processes - use shutdown handlers
+ * process.on('SIGTERM', () => {
+ *   unloadEmbedding();
+ *   closeDb();
+ *   process.exit(0);
+ * });
+ * process.on('SIGINT', () => {
+ *   unloadEmbedding();
+ *   closeDb();
+ *   process.exit(0);
+ * });
+ * ```
+ *
+ * **Note:** Failing to clean up will not corrupt data, but may cause:
+ * - Memory leaks in long-running processes
+ * - Unclean process exits (warnings in some environments)
+ *
+ * @see {@link closeDb} for database cleanup
+ * @see {@link unloadEmbedding} for embedding model cleanup
+ * @module learning-agent
+ */
+declare const VERSION = "0.1.0";
+
+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 };