compound-agent 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,971 @@
+import { L as Lesson, M as MemoryItem, a as MemoryItemType, C as Context, S as Severity } from './types--TsW4ZqX.js';
+export { b as LegacyLessonSchema, c as LegacyTombstoneSchema, d as LessonItemSchema, e as LessonRecord, f as LessonRecordSchema, g as LessonSchema, h as LessonType, i as LessonTypeSchema, j as MemoryItemRecord, k as MemoryItemRecordSchema, l as MemoryItemSchema, m as MemoryItemTypeSchema, P as PatternItem, n as PatternItemSchema, o as Preference, p as PreferenceItemSchema, q as Solution, r as SolutionItemSchema, s as Source, t as generateId } from './types--TsW4ZqX.js';
+import { LlamaEmbeddingContext } from 'node-llama-cpp';
+import { z } from 'zod';
+
+/**
+ * JSONL storage layer for memory items
+ *
+ * Append-only storage with last-write-wins deduplication.
+ * Source of truth - git trackable.
+ *
+ * Primary API:
+ *   appendMemoryItem() - Append any memory item type
+ *   readMemoryItems()  - Read all non-deleted memory items
+ *
+ * Backward-compatible API:
+ *   appendLesson()     - Append a lesson (delegates to appendMemoryItem)
+ *   readLessons()      - Read lesson-type items only
+ *
+ * Deletion: append the item with `deleted: true` and `deletedAt`.
+ * Read path also accepts old minimal tombstone records for backward compat.
+ * Legacy type:'quick'/'full' records are converted to type:'lesson' on read.
+ */
+
+/** Relative path to lessons file from repo root */
+declare const LESSONS_PATH = ".claude/lessons/index.jsonl";
+/** Options for reading memory items */
+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 (backward-compat) */
+interface ReadLessonsResult {
+    /** Successfully parsed lessons */
+    lessons: Lesson[];
+    /** Number of lines skipped due to errors */
+    skippedCount: number;
+}
+/** Result of reading memory items */
+interface ReadMemoryItemsResult {
+    /** Successfully parsed memory items */
+    items: MemoryItem[];
+    /** Number of lines skipped due to errors */
+    skippedCount: number;
+}
+/**
+ * Append a memory item to the JSONL file.
+ * Creates directory structure if missing.
+ * Primary write function for all memory item types.
+ *
+ * @param repoRoot - Repository root directory
+ * @param item - Memory item to append (any type: lesson, solution, pattern, preference)
+ */
+declare function appendMemoryItem(repoRoot: string, item: MemoryItem): Promise<void>;
+/**
+ * Append a lesson to the JSONL file.
+ * Backward-compatible wrapper around appendMemoryItem.
+ *
+ * @param repoRoot - Repository root directory
+ * @param lesson - Lesson to append
+ */
+declare function appendLesson(repoRoot: string, lesson: Lesson): Promise<void>;
+/**
+ * Read all non-deleted memory items from the JSONL file.
+ * Primary read function for the unified memory API.
+ *
+ * Applies last-write-wins deduplication by ID.
+ * Converts legacy type:'quick'/'full' to type:'lesson'.
+ *
+ * Handles tombstone formats:
+ * - Canonical: { id, deleted: true, deletedAt }
+ * - Legacy: Full record with deleted:true field
+ *
+ * @param repoRoot - Repository root directory
+ * @param options - Optional settings for error handling
+ * @returns Result with items array and count of skipped lines
+ */
+declare function readMemoryItems(repoRoot: string, options?: ReadLessonsOptions): Promise<ReadMemoryItemsResult>;
+/**
+ * Read all non-deleted lessons from the JSONL file.
+ * Backward-compatible wrapper that filters to lesson-type items only.
+ *
+ * @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 database connection management.
+ */
+
+/** Relative path to database file from repo root */
+declare const DB_PATH = ".claude/.cache/lessons.sqlite";
+/**
+ * Close the SQLite database connection.
+ */
+declare function closeDb(): void;
+
+/**
+ * SQLite index synchronization with JSONL source of truth.
+ */
+
+/**
+ * Rebuild the SQLite index from JSONL source of truth.
+ * Preserves cached embeddings when item 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 full-text search.
+ * @param repoRoot - Absolute path to repository root
+ * @param query - FTS5 query string
+ * @param limit - Maximum number of results
+ * @param typeFilter - Optional memory item type to filter by
+ * @returns Matching lessons
+ */
+declare function searchKeyword(repoRoot: string, query: string, limit: number, typeFilter?: MemoryItemType): Promise<MemoryItem[]>;
+
+/**
+ * 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;
+/**
+ * Result of checking if the model is usable at runtime.
+ *
+ * A discriminated union where `usable` determines which fields are present:
+ * - usable=true: Model can initialize and create embedding context
+ * - usable=false: Model cannot be used, with reason and actionable fix
+ */
+type UsabilityResult = {
+    usable: true;
+    reason?: undefined;
+    action?: undefined;
+} | {
+    usable: false;
+    reason: string;
+    action: string;
+};
+/**
+ * Check if the embedding model is usable at runtime.
+ *
+ * Goes beyond file existence to verify the model can actually initialize:
+ * 1. Checks if model file exists (fast fail)
+ * 2. Attempts to load llama runtime
+ * 3. Attempts to load model
+ * 4. Attempts to create embedding context
+ * 5. Cleans up all resources after check
+ *
+ * @returns UsabilityResult with usable status and actionable error if failed
+ */
+declare function isModelUsable(): Promise<UsabilityResult>;
+/**
+ * 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;
+/**
+ * Memory item with similarity score.
+ * The `lesson` field holds any MemoryItem type (not just Lesson).
+ * Field name kept for backward compatibility.
+ */
+interface ScoredLesson {
+    lesson: MemoryItem;
+    score: number;
+}
+/** Alias for ScoredLesson for unified memory API consumers. */
+type ScoredMemoryItem = ScoredLesson;
+/** Options for vector search */
+interface SearchVectorOptions {
+    /** Maximum number of results to return (default: 10) */
+    limit?: number;
+}
+declare function searchVector(repoRoot: string, query: string, options?: SearchVectorOptions): Promise<ScoredLesson[]>;
+
+/**
+ * Multi-factor memory item ranking system
+ *
+ * Combines vector similarity with semantic boosts:
+ * - Severity: high=1.5, medium=1.0, low=0.8
+ * - Recency: 1.2 for items ≤30 days old
+ * - Confirmation: 1.3 for confirmed items
+ */
+
+/** Lesson/memory item with final ranked score */
+interface RankedLesson extends ScoredLesson {
+    finalScore?: number;
+}
+/** Alias for RankedLesson for unified memory API consumers. */
+type RankedMemoryItem = RankedLesson;
+/**
+ * Calculate severity boost based on item severity.
+ * Items without severity get 1.0 (medium boost).
+ */
+declare function severityBoost(item: MemoryItem): number;
+/**
+ * Calculate recency boost based on item age.
+ * Items ≤30 days old get 1.2, older get 1.0.
+ */
+declare function recencyBoost(item: MemoryItem): number;
+/**
+ * Calculate confirmation boost.
+ * Confirmed items get 1.3, unconfirmed get 1.0.
+ */
+declare function confirmationBoost(item: MemoryItem): number;
+/**
+ * Calculate combined score for a memory item.
+ * score = vectorSimilarity * min(severity * recency * confirmation, MAX_COMBINED_BOOST)
+ */
+declare function calculateScore(item: MemoryItem, vectorSimilarity: number): number;
+/**
+ * Rank lessons by combined score.
+ * Returns new array sorted by finalScore descending.
+ *
+ * Works with ScoredLesson[] (backward compat, uses .lesson field).
+ * For ScoredMemoryItem[], use the .item field — same underlying data.
+ */
+declare function rankLessons(lessons: ScoredLesson[]): RankedLesson[];
+/**
+ * Rank memory items by combined score.
+ * Primary API for unified memory types. Uses .item field.
+ * Returns new array sorted by finalScore descending.
+ */
+declare const rankMemoryItems: typeof rankLessons;
+
+/**
+ * Quality filters for lesson capture
+ *
+ * Filters to ensure lessons are:
+ * - Novel (not duplicate)
+ * - Specific (not vague)
+ *
+ * Actionability check is available but not part of the capture gate.
+ * Strategy: capture aggressively, prune later.
+ */
+/** 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 AND specific.
+ * Actionability gate removed: capture aggressively, prune later.
+ */
+declare function shouldPropose(repoRoot: string, insight: string): Promise<ProposeResult>;
+
+/**
+ * Trigger detection for automatic memory capture
+ *
+ * Detects patterns that indicate potential learning opportunities:
+ * - User corrections
+ * - Self-corrections
+ * - Test failures
+ *
+ * Also infers memory item type from insight text:
+ * - pattern: "use X instead of Y", "prefer X over Y"
+ * - solution: "when X, do Y", "if X then Y", "to fix X"
+ * - preference: "always X", "never X"
+ * - lesson: default for unclassified insights
+ */
+
+/** 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 memory item with severity field present */
+type LessonWithSeverity = MemoryItem & {
+    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<LessonWithSeverity[]>;
+/**
+ * @deprecated Use loadSessionMemory. Backward-compat alias.
+ */
+declare const loadSessionMemory: typeof loadSessionLessons;
+
+/**
+ * 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;
+/**
+ * @deprecated Use formatMemoryCheck. Backward-compat alias.
+ */
+declare const formatMemoryCheck: typeof formatLessonsCheck;
+
+/**
+ * Prime command - Context recovery for Claude Code with Beads-style trust language.
+ *
+ * Generates trust language guidelines combined with high-severity lessons
+ * for context recovery after compaction or session restart.
+ */
+
+/**
+ * Generate prime context output for Claude Code.
+ *
+ * Combines Beads-style trust language guidelines with high-severity lessons
+ * for context recovery after compaction or session restart.
+ *
+ * @param repoRoot - Repository root directory (defaults to getRepoRoot())
+ * @returns Formatted markdown string (< 2K tokens)
+ */
+declare function getPrimeContext(repoRoot?: string): Promise<string>;
+
+/**
+ * Audit module types and Zod schemas.
+ */
+
+/** Schema for a single audit finding. */
+declare const AuditFindingSchema: z.ZodObject<{
+    file: z.ZodString;
+    issue: z.ZodString;
+    severity: z.ZodEnum<["error", "warning", "info"]>;
+    relatedLessonId: z.ZodOptional<z.ZodString>;
+    suggestedFix: z.ZodOptional<z.ZodString>;
+    source: z.ZodEnum<["rule", "pattern", "lesson"]>;
+}, "strip", z.ZodTypeAny, {
+    file: string;
+    source: "lesson" | "pattern" | "rule";
+    severity: "error" | "warning" | "info";
+    issue: string;
+    relatedLessonId?: string | undefined;
+    suggestedFix?: string | undefined;
+}, {
+    file: string;
+    source: "lesson" | "pattern" | "rule";
+    severity: "error" | "warning" | "info";
+    issue: string;
+    relatedLessonId?: string | undefined;
+    suggestedFix?: string | undefined;
+}>;
+/** Schema for a complete audit report. */
+declare const AuditReportSchema: z.ZodObject<{
+    findings: z.ZodArray<z.ZodObject<{
+        file: z.ZodString;
+        issue: z.ZodString;
+        severity: z.ZodEnum<["error", "warning", "info"]>;
+        relatedLessonId: z.ZodOptional<z.ZodString>;
+        suggestedFix: z.ZodOptional<z.ZodString>;
+        source: z.ZodEnum<["rule", "pattern", "lesson"]>;
+    }, "strip", z.ZodTypeAny, {
+        file: string;
+        source: "lesson" | "pattern" | "rule";
+        severity: "error" | "warning" | "info";
+        issue: string;
+        relatedLessonId?: string | undefined;
+        suggestedFix?: string | undefined;
+    }, {
+        file: string;
+        source: "lesson" | "pattern" | "rule";
+        severity: "error" | "warning" | "info";
+        issue: string;
+        relatedLessonId?: string | undefined;
+        suggestedFix?: string | undefined;
+    }>, "many">;
+    summary: z.ZodObject<{
+        errors: z.ZodNumber;
+        warnings: z.ZodNumber;
+        infos: z.ZodNumber;
+        filesChecked: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        errors: number;
+        warnings: number;
+        infos: number;
+        filesChecked: number;
+    }, {
+        errors: number;
+        warnings: number;
+        infos: number;
+        filesChecked: number;
+    }>;
+    timestamp: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    timestamp: string;
+    findings: {
+        file: string;
+        source: "lesson" | "pattern" | "rule";
+        severity: "error" | "warning" | "info";
+        issue: string;
+        relatedLessonId?: string | undefined;
+        suggestedFix?: string | undefined;
+    }[];
+    summary: {
+        errors: number;
+        warnings: number;
+        infos: number;
+        filesChecked: number;
+    };
+}, {
+    timestamp: string;
+    findings: {
+        file: string;
+        source: "lesson" | "pattern" | "rule";
+        severity: "error" | "warning" | "info";
+        issue: string;
+        relatedLessonId?: string | undefined;
+        suggestedFix?: string | undefined;
+    }[];
+    summary: {
+        errors: number;
+        warnings: number;
+        infos: number;
+        filesChecked: number;
+    };
+}>;
+type AuditFinding = z.infer<typeof AuditFindingSchema>;
+type AuditReport = z.infer<typeof AuditReportSchema>;
+/** Options to toggle individual audit checks. */
+interface AuditOptions {
+    includeRules?: boolean;
+    includePatterns?: boolean;
+    includeLessons?: boolean;
+}
+
+/**
+ * Audit engine: orchestrates checks and builds report.
+ */
+
+/**
+ * Run audit checks and build a report.
+ *
+ * @param repoRoot - Repository root directory
+ * @param options - Toggle individual checks (all enabled by default)
+ * @returns Complete audit report with findings and summary
+ */
+declare function runAudit(repoRoot: string, options?: AuditOptions): Promise<AuditReport>;
+
+/**
+ * Types for the compounding module.
+ *
+ * CctPattern represents a cross-cutting pattern synthesized
+ * from multiple similar lessons.
+ */
+
+/** Relative path to CCT patterns file from repo root */
+declare const CCT_PATTERNS_PATH = ".claude/lessons/cct-patterns.jsonl";
+/** Schema for a cross-cutting pattern */
+declare const CctPatternSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    description: z.ZodString;
+    frequency: z.ZodNumber;
+    testable: z.ZodBoolean;
+    testApproach: z.ZodOptional<z.ZodString>;
+    sourceIds: z.ZodArray<z.ZodString, "many">;
+    created: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    created: string;
+    name: string;
+    description: string;
+    frequency: number;
+    testable: boolean;
+    sourceIds: string[];
+    testApproach?: string | undefined;
+}, {
+    id: string;
+    created: string;
+    name: string;
+    description: string;
+    frequency: number;
+    testable: boolean;
+    sourceIds: string[];
+    testApproach?: string | undefined;
+}>;
+/** Inferred type from CctPatternSchema */
+type CctPattern = z.infer<typeof CctPatternSchema>;
+/** Result from clustering operation */
+interface ClusterResult {
+    /** Groups of similar items */
+    clusters: MemoryItem[][];
+    /** Items that didn't fit any cluster */
+    noise: MemoryItem[];
+}
+
+/**
+ * Clustering module for grouping similar memory items.
+ *
+ * Uses single-linkage agglomerative clustering with cosine similarity.
+ */
+
+/**
+ * Build a pairwise cosine similarity matrix from embedding vectors.
+ *
+ * @param embeddings - Array of embedding vectors
+ * @returns NxN similarity matrix
+ */
+declare function buildSimilarityMatrix(embeddings: number[][]): number[][];
+/**
+ * Cluster memory items by embedding similarity using single-linkage
+ * agglomerative clustering.
+ *
+ * @param items - Memory items to cluster
+ * @param embeddings - Embedding vectors (same order as items)
+ * @param threshold - Minimum similarity to merge clusters (default: 0.75)
+ * @returns Clusters of similar items and noise (unclustered items)
+ */
+declare function clusterBySimilarity(items: MemoryItem[], embeddings: number[][], threshold?: number): ClusterResult;
+
+/**
+ * I/O module for CctPattern persistence.
+ *
+ * Append-only JSONL storage, following the same pattern as
+ * src/memory/storage/jsonl.ts.
+ */
+
+/**
+ * Read all CCT patterns from the JSONL file.
+ *
+ * @param repoRoot - Repository root directory
+ * @returns Array of CctPattern objects
+ */
+declare function readCctPatterns(repoRoot: string): Promise<CctPattern[]>;
+/**
+ * Append CCT patterns to the JSONL file (append-only).
+ *
+ * @param repoRoot - Repository root directory
+ * @param patterns - Patterns to append
+ */
+declare function writeCctPatterns(repoRoot: string, patterns: CctPattern[]): Promise<void>;
+
+/**
+ * Synthesis module for extracting cross-cutting patterns from clusters.
+ *
+ * Takes a cluster of similar memory items and produces a CctPattern
+ * summarizing the common theme.
+ */
+
+/**
+ * Synthesize a CctPattern from a cluster of similar memory items.
+ *
+ * @param cluster - Group of similar memory items
+ * @param clusterId - Identifier for this cluster (used for ID generation)
+ * @returns A CctPattern summarizing the cluster
+ */
+declare function synthesizePattern(cluster: MemoryItem[], clusterId: string): CctPattern;
+
+/**
+ * Compound 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 'compound-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);
+ * ```
+ *
+ * ## Setup
+ *
+ * Run `npx ca init` in your project root to configure hooks and AGENTS.md.
+ *
+ * ## 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 'compound-agent';
+ *
+ * // For CLI commands - use try/finally
+ * async function main() {
+ *   try {
+ *     // ... your code that uses compound-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 compound-agent
+ */
+/** Package version, read from package.json. */
+declare const VERSION: string;
+
+export { type ActionabilityResult, type AuditFinding, AuditFindingSchema, type AuditOptions, type AuditReport, AuditReportSchema, CCT_PATTERNS_PATH, type CctPattern, CctPatternSchema, type ClusterResult, Context, type CorrectionSignal, DB_PATH, type DetectedCorrection, type DetectedSelfCorrection, type DetectedTestFailure, type EditEntry, type EditHistory, LESSONS_PATH, Lesson, MODEL_FILENAME, MODEL_URI, MemoryItem, MemoryItemType, type NoveltyOptions, type NoveltyResult, type ParseError, type PlanRetrievalResult, type ProposeResult, type RankedLesson, type RankedMemoryItem, type ReadLessonsOptions, type ReadLessonsResult, type ReadMemoryItemsResult, type ScoredLesson, type ScoredMemoryItem, type SearchVectorOptions, Severity, type SpecificityResult, type TestResult, type UsabilityResult, VERSION, appendLesson, appendMemoryItem, buildSimilarityMatrix, calculateScore, closeDb, clusterBySimilarity, confirmationBoost, cosineSimilarity, detectSelfCorrection, detectTestFailure, detectUserCorrection, embedText, embedTexts, formatLessonsCheck, formatMemoryCheck, getEmbedding, getPrimeContext, isActionable, isModelAvailable, isModelUsable, isNovel, isSpecific, loadSessionLessons, loadSessionMemory, rankLessons, rankMemoryItems, readCctPatterns, readLessons, readMemoryItems, rebuildIndex, recencyBoost, resolveModel, retrieveForPlan, runAudit, searchKeyword, searchVector, severityBoost, shouldPropose, synthesizePattern, unloadEmbedding, writeCctPatterns };