@cleocode/core 2026.3.42 → 2026.3.44

package/dist/lifecycle/tessera-engine.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Tessera Instantiation Engine
+ *
+ * Provides template management and instantiation for parameterized
+ * WarpChain workflows. Wraps buildDefaultChain() with template
+ * variables and manages the template registry.
+ *
+ * @task T5409
+ */
+import type { TesseraInstantiationInput, TesseraTemplate, WarpChainInstance } from '@cleocode/contracts';
+/**
+ * Build the default RCASD Tessera template.
+ *
+ * Wraps buildDefaultChain() with template variables:
+ * - epicId (required, type 'epicId')
+ * - projectName (optional, type 'string', default 'unnamed')
+ * - skipResearch (optional, type 'boolean', default false)
+ *
+ * @task T5409
+ */
+export declare function buildDefaultTessera(): TesseraTemplate;
+/**
+ * Instantiate a Tessera template into a concrete WarpChainInstance.
+ *
+ * Steps:
+ * 1. Validate all required variables are provided
+ * 2. Apply defaults for missing optional variables
+ * 3. Construct concrete WarpChain from template
+ * 4. Validate chain via validateChain()
+ * 5. Store via createInstance() from chain-store
+ * 6. Return instance
+ *
+ * @task T5409
+ */
+export declare function instantiateTessera(template: TesseraTemplate, input: TesseraInstantiationInput, projectRoot: string): Promise<WarpChainInstance>;
+/**
+ * List all registered Tessera templates.
+ *
+ * @task T5409
+ */
+export declare function listTesseraTemplates(): TesseraTemplate[];
+/**
+ * Find a Tessera template by ID.
+ *
+ * @task T5409
+ */
+export declare function showTessera(id: string): TesseraTemplate | null;
+//# sourceMappingURL=tessera-engine.d.ts.map

package/dist/lifecycle/tessera-engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tessera-engine.d.ts","sourceRoot":"","sources":["../../src/lifecycle/tessera-engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EACV,yBAAyB,EACzB,eAAe,EAGf,iBAAiB,EAClB,MAAM,qBAAqB,CAAC;AA6J7B;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,IAAI,eAAe,CAoCrD;AAYD;;;;;;;;;;;;GAYG;AACH,wBAAsB,kBAAkB,CACtC,QAAQ,EAAE,eAAe,EACzB,KAAK,EAAE,yBAAyB,EAChC,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,iBAAiB,CAAC,CA6C5B;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,IAAI,eAAe,EAAE,CAGxD;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,eAAe,GAAG,IAAI,CAG9D"}

package/dist/logger.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Centralized pino logger factory for CLEO.
+ *
+ * Singleton pattern. Uses pino-roll for automatic file rotation and retention.
+ * Custom formatters for uppercase level labels and ISO timestamps.
+ * Context via child loggers (getLogger('subsystem')).
+ *
+ * MCP safety: all diagnostic logging goes to files — stdout is reserved
+ * for the MCP protocol. Fallback stderr logger if not yet initialized.
+ */
+import pino from 'pino';
+export interface LoggerConfig {
+    level: string;
+    filePath: string;
+    maxFileSize: number;
+    maxFiles: number;
+}
+/**
+ * Initialize the root logger. Call once at startup.
+ *
+ * Uses pino-roll for automatic size+daily rotation with built-in retention.
+ * No custom rotation code needed.
+ *
+ * @param cleoDir      - Absolute path to .cleo directory
+ * @param config       - Logging configuration from CleoConfig.logging
+ * @param projectHash  - Stable project identity token bound to every log entry.
+ *                        Optional for backward compatibility; warns if absent.
+ * @returns The root pino logger instance
+ */
+export declare function initLogger(cleoDir: string, config: LoggerConfig, projectHash?: string): pino.Logger;
+/**
+ * Get a child logger bound to a subsystem name.
+ *
+ * Safe to call before initLogger — returns a stderr fallback logger
+ * so early startup code and tests never crash.
+ *
+ * @param subsystem - Logical subsystem name (e.g. 'audit', 'mcp', 'migration')
+ */
+export declare function getLogger(subsystem: string): pino.Logger;
+/**
+ * Get the current log directory path.
+ * Useful for read APIs that need to scan log files.
+ */
+export declare function getLogDir(): string | null;
+/**
+ * Flush and close the logger. Call during graceful shutdown.
+ *
+ * Returns a Promise that resolves once the pino transport worker thread
+ * has processed all pending writes. Callers that cannot await (e.g. sync
+ * shutdown handlers) may fire-and-forget safely — the underlying flush
+ * will still occur before the process exits.
+ */
+export declare function closeLogger(): Promise<void>;
+//# sourceMappingURL=logger.d.ts.map

package/dist/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,OAAO,IAAI,MAAM,MAAM,CAAC;AAKxB,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAaD;;;;;;;;;;;GAWG;AACH,wBAAgB,UAAU,CACxB,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,YAAY,EACpB,WAAW,CAAC,EAAE,MAAM,GACnB,IAAI,CAAC,MAAM,CAgEb;AAED;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC,MAAM,CAYxD;AAED;;;GAGG;AACH,wBAAgB,SAAS,IAAI,MAAM,GAAG,IAAI,CAEzC;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC,CAY3C"}

package/dist/mcp/index.d.ts

@@ -0,0 +1,42 @@
+/**
+ * MCP environment detection - CLEO-specific runtime mode resolution.
+ *
+ * Detects dev-ts vs prod-npm mode by reading ~/.cleo/VERSION.
+ * This is the only CLEO-specific concern here — all provider detection,
+ * config writing, and MCP server installation is delegated to @cleocode/caamp.
+ *
+ * @task T4676
+ * @epic T4663
+ */
+/** Resolved environment mode for MCP server config. */
+export interface McpEnvMode {
+    mode: 'dev-ts' | 'prod-npm' | 'unknown';
+    /** Absolute path to the source directory (dev-ts mode only). */
+    source: string | null;
+    /** Resolved install channel for npm package invocation. */
+    channel: 'stable' | 'beta' | 'dev' | 'unknown';
+}
+/** Resolve MCP server name by channel. */
+export declare function getMcpServerName(env: McpEnvMode): string;
+/**
+ * Detect the current CLEO environment mode by reading ~/.cleo/VERSION.
+ *
+ * The VERSION file format:
+ *   Line 1: version number
+ *   Lines 2+: key=value pairs (mode, source, etc.)
+ *
+ * @task T4584
+ */
+export declare function detectEnvMode(): McpEnvMode;
+/**
+ * Generate the MCP server entry for the cleo server based on env mode.
+ *
+ * Returns a config object compatible with CAAMP's McpServerConfig:
+ * - dev-ts: { command: 'node', args: ['<source>/dist/mcp/index.js'] }
+ * - prod-npm stable: { command: 'npx', args: ['-y', '@cleocode/cleo@latest', 'mcp'] }
+ * - prod-npm beta: { command: 'npx', args: ['-y', '@cleocode/cleo@beta', 'mcp'] }
+ *
+ * @task T4584
+ */
+export declare function generateMcpServerEntry(env: McpEnvMode): Record<string, unknown>;
+//# sourceMappingURL=index.d.ts.map

package/dist/mcp/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/mcp/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAMH,uDAAuD;AACvD,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,QAAQ,GAAG,UAAU,GAAG,SAAS,CAAC;IACxC,gEAAgE;IAChE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,2DAA2D;IAC3D,OAAO,EAAE,QAAQ,GAAG,MAAM,GAAG,KAAK,GAAG,SAAS,CAAC;CAChD;AAED,0CAA0C;AAC1C,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,UAAU,GAAG,MAAM,CAIxD;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,IAAI,UAAU,CAuF1C;AAED;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAuB/E"}

package/dist/memory/auto-extract.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Auto-extract structured memory entries from task completions and session ends.
+ *
+ * Best-effort extraction: all functions wrap their logic in try/catch and
+ * must never throw — memory extraction must never block the calling flow.
+ *
+ * @task T-auto-extract
+ * @epic T5149
+ */
+import type { Task } from '@cleocode/contracts';
+import type { SessionBridgeData } from '../sessions/session-memory-bridge.js';
+/**
+ * Extract and store memory entries when a task is completed.
+ *
+ * - Always stores a learning for the completed task.
+ * - Stores a second learning if the task had dependencies.
+ * - Detects recurring label patterns across recent completed tasks
+ *   and stores a success pattern when any label appears 3+ times.
+ */
+export declare function extractTaskCompletionMemory(projectRoot: string, task: Task, _parentTask?: Task): Promise<void>;
+/**
+ * Extract and store memory entries when a session ends.
+ *
+ * - Stores a process decision summarising the session.
+ * - Stores a per-task learning for each completed task.
+ * - Stores a workflow pattern when 2+ completed tasks share a label.
+ */
+export declare function extractSessionEndMemory(projectRoot: string, sessionData: SessionBridgeData, taskDetails: Task[]): Promise<void>;
+/**
+ * Resolve an array of task IDs to their full Task objects.
+ * Tasks that cannot be found are silently excluded.
+ */
+export declare function resolveTaskDetails(projectRoot: string, taskIds: string[]): Promise<Task[]>;
+//# sourceMappingURL=auto-extract.d.ts.map

package/dist/memory/auto-extract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auto-extract.d.ts","sourceRoot":"","sources":["../../src/memory/auto-extract.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,qBAAqB,CAAC;AAChD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sCAAsC,CAAC;AAK9E;;;;;;;GAOG;AACH,wBAAsB,2BAA2B,CAC/C,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,IAAI,EACV,WAAW,CAAC,EAAE,IAAI,GACjB,OAAO,CAAC,IAAI,CAAC,CAwDf;AAED;;;;;;GAMG;AACH,wBAAsB,uBAAuB,CAC3C,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,iBAAiB,EAC9B,WAAW,EAAE,IAAI,EAAE,GAClB,OAAO,CAAC,IAAI,CAAC,CA6Cf;AAED;;;GAGG;AACH,wBAAsB,kBAAkB,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC,CAYhG"}

package/dist/memory/brain-embedding.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Brain Embedding System
+ *
+ * Provides text-to-vector embedding for semantic search in brain.db.
+ * Uses a pluggable provider interface — real model integration
+ * (e.g. @huggingface/transformers with all-MiniLM-L6-v2) is separate
+ * from the embedding pipeline. When no provider is set, the system
+ * falls back to FTS5-only search gracefully.
+ *
+ * @epic T5149
+ * @task T5386
+ */
+/** Contract for embedding providers (local models, API services, etc.). */
+export interface EmbeddingProvider {
+    /** Convert text into a fixed-dimension float vector. */
+    embed(text: string): Promise<Float32Array>;
+    /** Number of dimensions the provider produces. Must match vec0 table. */
+    readonly dimensions: number;
+    /** Whether the provider is ready to produce embeddings. */
+    isAvailable(): boolean;
+}
+/** Matches the brain_embeddings vec0 table: FLOAT[384]. */
+export declare const EMBEDDING_DIMENSIONS = 384;
+/**
+ * Register an embedding provider for the brain system.
+ * Validates that the provider's dimensions match the vec0 table.
+ *
+ * @throws Error if provider dimensions do not match EMBEDDING_DIMENSIONS
+ */
+export declare function setEmbeddingProvider(provider: EmbeddingProvider): void;
+/** Get the currently registered embedding provider, or null. */
+export declare function getEmbeddingProvider(): EmbeddingProvider | null;
+/** Clear the current embedding provider (useful for testing). */
+export declare function clearEmbeddingProvider(): void;
+/**
+ * Embed text into a float vector using the registered provider.
+ * Returns null when no provider is set or not available (FTS5-only fallback).
+ */
+export declare function embedText(text: string): Promise<Float32Array | null>;
+/** Check whether embedding is currently available. */
+export declare function isEmbeddingAvailable(): boolean;
+//# sourceMappingURL=brain-embedding.d.ts.map

package/dist/memory/brain-embedding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"brain-embedding.d.ts","sourceRoot":"","sources":["../../src/memory/brain-embedding.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,2EAA2E;AAC3E,MAAM,WAAW,iBAAiB;IAChC,wDAAwD;IACxD,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;IAC3C,yEAAyE;IACzE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,2DAA2D;IAC3D,WAAW,IAAI,OAAO,CAAC;CACxB;AAED,2DAA2D;AAC3D,eAAO,MAAM,oBAAoB,MAAM,CAAC;AAIxC;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,iBAAiB,GAAG,IAAI,CAOtE;AAED,gEAAgE;AAChE,wBAAgB,oBAAoB,IAAI,iBAAiB,GAAG,IAAI,CAE/D;AAED,iEAAiE;AACjE,wBAAgB,sBAAsB,IAAI,IAAI,CAE7C;AAED;;;GAGG;AACH,wBAAsB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CAG1E;AAED,sDAAsD;AACtD,wBAAgB,oBAAoB,IAAI,OAAO,CAE9C"}

package/dist/memory/brain-lifecycle.d.ts

@@ -0,0 +1,57 @@
+/**
+ * BRAIN lifecycle operations — temporal decay and memory consolidation.
+ *
+ * Reduces confidence of stale learnings based on age, following an
+ * exponential decay model: new_confidence = confidence * (decayRate ^ daysSinceUpdate).
+ *
+ * Consolidation groups old observations by keyword overlap and merges
+ * clusters into summary observations, archiving the originals.
+ *
+ * @task T5394 T5395
+ * @epic T5149
+ */
+/** Result from applying temporal decay. */
+export interface DecayResult {
+    updated: number;
+    tablesProcessed: string[];
+}
+/**
+ * Apply temporal decay to brain_learnings confidence values.
+ *
+ * Entries older than `olderThanDays` have their confidence reduced
+ * by an exponential decay factor based on the number of days since
+ * their last update (or creation if never updated).
+ *
+ * Formula: new_confidence = confidence * (decayRate ^ daysSinceUpdate)
+ *
+ * @param projectRoot - Project root directory for brain.db resolution
+ * @param options - Decay configuration
+ * @returns Count of updated rows and tables processed
+ */
+export declare function applyTemporalDecay(projectRoot: string, options?: {
+    decayRate?: number;
+    olderThanDays?: number;
+}): Promise<DecayResult>;
+/** Result from consolidating memories. */
+export interface ConsolidationResult {
+    grouped: number;
+    merged: number;
+    archived: number;
+}
+/**
+ * Consolidate old observations by keyword similarity.
+ *
+ * Groups observations older than `olderThanDays` by FTS5 keyword overlap.
+ * For groups with at least `minClusterSize` entries, creates one summary
+ * observation and marks originals as archived (updated_at set, narrative
+ * prefixed with [ARCHIVED]).
+ *
+ * @param projectRoot - Project root directory for brain.db resolution
+ * @param options - Consolidation configuration
+ * @returns Counts of grouped, merged, and archived observations
+ */
+export declare function consolidateMemories(projectRoot: string, options?: {
+    olderThanDays?: number;
+    minClusterSize?: number;
+}): Promise<ConsolidationResult>;
+//# sourceMappingURL=brain-lifecycle.d.ts.map

package/dist/memory/brain-lifecycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"brain-lifecycle.d.ts","sourceRoot":"","sources":["../../src/memory/brain-lifecycle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAOH,2CAA2C;AAC3C,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,eAAe,EAAE,MAAM,EAAE,CAAC;CAC3B;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,kBAAkB,CACtC,WAAW,EAAE,MAAM,EACnB,OAAO,CAAC,EAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,aAAa,CAAC,EAAE,MAAM,CAAA;CAAE,GACvD,OAAO,CAAC,WAAW,CAAC,CAqCtB;AAMD,0CAA0C;AAC1C,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;CAClB;AAmID;;;;;;;;;;;GAWG;AACH,wBAAsB,mBAAmB,CACvC,WAAW,EAAE,MAAM,EACnB,OAAO,CAAC,EAAE;IAAE,aAAa,CAAC,EAAE,MAAM,CAAC;IAAC,cAAc,CAAC,EAAE,MAAM,CAAA;CAAE,GAC5D,OAAO,CAAC,mBAAmB,CAAC,CA+G9B"}

package/dist/memory/brain-links.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Cross-reference management between BRAIN memory entries and tasks.
+ *
+ * Provides linking/unlinking and query functions for relationships
+ * between decisions, patterns, learnings and CLEO tasks.
+ *
+ * @task T5156
+ * @epic T5149
+ */
+import type { BRAIN_LINK_TYPES, BRAIN_MEMORY_TYPES, BrainDecisionRow, BrainLearningRow, BrainMemoryLinkRow, BrainPatternRow } from '../store/brain-schema.js';
+type MemoryType = (typeof BRAIN_MEMORY_TYPES)[number];
+type LinkType = (typeof BRAIN_LINK_TYPES)[number];
+/** A link to be created in bulk. */
+export interface BulkLinkEntry {
+    memoryType: MemoryType;
+    memoryId: string;
+    taskId: string;
+    linkType: LinkType;
+}
+/**
+ * Link a memory entry to a task.
+ *
+ * @task T5156
+ */
+export declare function linkMemoryToTask(projectRoot: string, memoryType: MemoryType, memoryId: string, taskId: string, linkType: LinkType): Promise<BrainMemoryLinkRow>;
+/**
+ * Remove a link between a memory entry and a task.
+ *
+ * @task T5156
+ */
+export declare function unlinkMemoryFromTask(projectRoot: string, memoryType: MemoryType, memoryId: string, taskId: string, linkType: LinkType): Promise<void>;
+/**
+ * Get all memory entries linked to a specific task.
+ *
+ * @task T5156
+ */
+export declare function getTaskLinks(projectRoot: string, taskId: string): Promise<BrainMemoryLinkRow[]>;
+/**
+ * Get all tasks linked to a specific memory entry.
+ *
+ * @task T5156
+ */
+export declare function getMemoryLinks(projectRoot: string, memoryType: MemoryType, memoryId: string): Promise<BrainMemoryLinkRow[]>;
+/**
+ * Batch create multiple links at once.
+ *
+ * @task T5156
+ */
+export declare function bulkLink(projectRoot: string, links: BulkLinkEntry[]): Promise<{
+    created: number;
+    skipped: number;
+}>;
+/**
+ * Get all decisions linked to a task.
+ * Convenience method that fetches full decision rows.
+ *
+ * @task T5156
+ */
+export declare function getLinkedDecisions(projectRoot: string, taskId: string): Promise<BrainDecisionRow[]>;
+/**
+ * Get all patterns linked to a task.
+ * Convenience method that fetches full pattern rows.
+ *
+ * @task T5156
+ */
+export declare function getLinkedPatterns(projectRoot: string, taskId: string): Promise<BrainPatternRow[]>;
+/**
+ * Get all learnings linked to a task.
+ * Convenience method that fetches full learning rows.
+ *
+ * @task T5156
+ */
+export declare function getLinkedLearnings(projectRoot: string, taskId: string): Promise<BrainLearningRow[]>;
+export {};
+//# sourceMappingURL=brain-links.d.ts.map

package/dist/memory/brain-links.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"brain-links.d.ts","sourceRoot":"","sources":["../../src/memory/brain-links.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,KAAK,EACV,gBAAgB,EAChB,kBAAkB,EAClB,gBAAgB,EAChB,gBAAgB,EAChB,kBAAkB,EAClB,eAAe,EAChB,MAAM,0BAA0B,CAAC;AAElC,KAAK,UAAU,GAAG,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,CAAC,CAAC;AACtD,KAAK,QAAQ,GAAG,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,CAAC,CAAC;AAElD,oCAAoC;AACpC,MAAM,WAAW,aAAa;IAC5B,UAAU,EAAE,UAAU,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,QAAQ,CAAC;CACpB;AAED;;;;GAIG;AACH,wBAAsB,gBAAgB,CACpC,WAAW,EAAE,MAAM,EACnB,UAAU,EAAE,UAAU,EACtB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,QAAQ,GACjB,OAAO,CAAC,kBAAkB,CAAC,CAyB7B;AAED;;;;GAIG;AACH,wBAAsB,oBAAoB,CACxC,WAAW,EAAE,MAAM,EACnB,UAAU,EAAE,UAAU,EACtB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,QAAQ,GACjB,OAAO,CAAC,IAAI,CAAC,CAGf;AAED;;;;GAIG;AACH,wBAAsB,YAAY,CAChC,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAG/B;AAED;;;;GAIG;AACH,wBAAsB,cAAc,CAClC,WAAW,EAAE,MAAM,EACnB,UAAU,EAAE,UAAU,EACtB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAG/B;AAED;;;;GAIG;AACH,wBAAsB,QAAQ,CAC5B,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,aAAa,EAAE,GACrB,OAAO,CAAC;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC,CA2B/C;AAED;;;;;GAKG;AACH,wBAAsB,kBAAkB,CACtC,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAa7B;AAED;;;;;GAKG;AACH,wBAAsB,iBAAiB,CACrC,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,eAAe,EAAE,CAAC,CAa5B;AAED;;;;;GAKG;AACH,wBAAsB,kBAAkB,CACtC,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAa7B"}

package/dist/memory/brain-migration.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Migrate BRAIN memory from JSONL files to brain.db SQLite tables.
+ * Reads .cleo/memory/patterns.jsonl and .cleo/memory/learnings.jsonl
+ * and inserts into brain_patterns and brain_learnings tables.
+ *
+ * Idempotent: checks for existing entries by ID to skip duplicates.
+ *
+ * @task T5129
+ * @epic T5149
+ */
+/** Result from a migration run. */
+export interface BrainMigrationResult {
+    patternsImported: number;
+    learningsImported: number;
+    duplicatesSkipped: number;
+    errors: string[];
+}
+/**
+ * Migrate BRAIN memory data from JSONL files to brain.db.
+ *
+ * Reads:
+ * - .cleo/memory/patterns.jsonl -> brain_patterns table
+ * - .cleo/memory/learnings.jsonl -> brain_learnings table
+ *
+ * Skips entries where the ID already exists in the database (idempotent).
+ *
+ * @task T5129
+ */
+export declare function migrateBrainData(projectRoot: string): Promise<BrainMigrationResult>;
+//# sourceMappingURL=brain-migration.d.ts.map

package/dist/memory/brain-migration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"brain-migration.d.ts","sourceRoot":"","sources":["../../src/memory/brain-migration.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAOH,mCAAmC;AACnC,MAAM,WAAW,oBAAoB;IACnC,gBAAgB,EAAE,MAAM,CAAC;IACzB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AA6DD;;;;;;;;;;GAUG;AACH,wBAAsB,gBAAgB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAgFzF"}

package/dist/memory/brain-reasoning.d.ts

@@ -0,0 +1,54 @@
+/**
+ * BRAIN Reasoning — causal trace through task dependency chains.
+ *
+ * `reasonWhy(taskId)` walks upstream through a task's blocker chain,
+ * enriching each node with related brain_decisions. Leaf tasks with
+ * no further unresolved blockers are identified as root causes.
+ *
+ * @task T5390
+ * @epic T5149
+ */
+import type { DataAccessor } from '../store/data-accessor.js';
+import type { BrainDecisionNode } from './brain-row-types.js';
+export interface BlockerNode {
+    taskId: string;
+    status: string;
+    reason?: string;
+    decisions: BrainDecisionNode[];
+}
+export interface CausalTrace {
+    taskId: string;
+    blockers: BlockerNode[];
+    rootCauses: string[];
+    depth: number;
+}
+/**
+ * Build a causal trace for why a task is blocked.
+ *
+ * Walks upstream through `depends` fields, collecting unresolved blockers
+ * and their associated brain decisions. Leaf blockers (no further unresolved
+ * deps) are reported as root causes.
+ */
+export declare function reasonWhy(taskId: string, projectRoot: string, taskAccessor?: DataAccessor): Promise<CausalTrace>;
+export interface SimilarEntry {
+    id: string;
+    distance: number;
+    type: string;
+    title: string;
+    text: string;
+}
+/**
+ * Find entries similar to a given brain.db entry.
+ *
+ * 1. Loads the source entry's text from brain.db.
+ * 2. Calls searchSimilar() for vector-based similarity if embeddings exist.
+ * 3. Falls back to FTS5 keyword search if no embeddings are available.
+ * 4. Filters out the source entry itself.
+ *
+ * @param entryId - ID of the brain.db entry to find similar entries for
+ * @param projectRoot - Project root directory
+ * @param limit - Maximum results to return (default 10)
+ * @returns Array of similar entries ranked by distance/relevance
+ */
+export declare function reasonSimilar(entryId: string, projectRoot: string, limit?: number): Promise<SimilarEntry[]>;
+//# sourceMappingURL=brain-reasoning.d.ts.map

package/dist/memory/brain-reasoning.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"brain-reasoning.d.ts","sourceRoot":"","sources":["../../src/memory/brain-reasoning.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAE9D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAQ9D,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,iBAAiB,EAAE,CAAC;CAChC;AAED,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,WAAW,EAAE,CAAC;IACxB,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;CACf;AAQD;;;;;;GAMG;AACH,wBAAsB,SAAS,CAC7B,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,MAAM,EACnB,YAAY,CAAC,EAAE,YAAY,GAC1B,OAAO,CAAC,WAAW,CAAC,CAyFtB;AAgBD,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,aAAa,CACjC,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,MAAM,EACnB,KAAK,CAAC,EAAE,MAAM,GACb,OAAO,CAAC,YAAY,EAAE,CAAC,CA2FzB"}

package/dist/memory/brain-retrieval.d.ts

@@ -0,0 +1,157 @@
+/**
+ * BRAIN Retrieval Operations — 3-layer pattern (search -> timeline -> fetch).
+ *
+ * Provides token-efficient memory access modeled after claude-mem's
+ * search/timeline/get_observations workflow:
+ *
+ * 1. searchBrainCompact — lightweight index (IDs + titles, ~50 tokens/hit)
+ * 2. timelineBrain      — chronological context around an anchor entry
+ * 3. fetchBrainEntries  — full details for a filtered set of IDs
+ * 4. observeBrain       — unified save (observations table)
+ *
+ * Wave 2A provides the core implementations; Wave 2B wires them through
+ * the dispatch layer (engine-compat -> domain handler -> MCP gateway).
+ *
+ * @task T5131 T5132 T5133 T5134 T5135
+ * @epic T5149
+ */
+import type { BRAIN_OBSERVATION_SOURCE_TYPES, BRAIN_OBSERVATION_TYPES } from '../store/brain-schema.js';
+import type { BrainAnchor } from './brain-row-types.js';
+/** Compact search hit — minimal fields for index-level results. */
+export interface BrainCompactHit {
+    id: string;
+    type: 'decision' | 'pattern' | 'learning' | 'observation';
+    title: string;
+    date: string;
+    relevance?: number;
+}
+/** Parameters for searchBrainCompact. */
+export interface SearchBrainCompactParams {
+    query: string;
+    limit?: number;
+    tables?: Array<'decisions' | 'patterns' | 'learnings' | 'observations'>;
+    dateStart?: string;
+    dateEnd?: string;
+}
+/** Result from searchBrainCompact. */
+export interface SearchBrainCompactResult {
+    results: BrainCompactHit[];
+    total: number;
+    tokensEstimated: number;
+}
+/** Parameters for timelineBrain. */
+export interface TimelineBrainParams {
+    anchor: string;
+    depthBefore?: number;
+    depthAfter?: number;
+}
+/** Timeline entry — compact id/type/date tuple. */
+export interface TimelineNeighbor {
+    id: string;
+    type: string;
+    date: string;
+}
+/** Result from timelineBrain. */
+export interface TimelineBrainResult {
+    anchor: BrainAnchor | null;
+    before: TimelineNeighbor[];
+    after: TimelineNeighbor[];
+}
+/** Parameters for fetchBrainEntries. */
+export interface FetchBrainEntriesParams {
+    ids: string[];
+}
+/** Fetched entry with full data. */
+export interface FetchedBrainEntry {
+    id: string;
+    type: string;
+    data: unknown;
+}
+/** Result from fetchBrainEntries. */
+export interface FetchBrainEntriesResult {
+    results: FetchedBrainEntry[];
+    notFound: string[];
+    tokensEstimated: number;
+}
+/** Observation type from schema. */
+export type BrainObservationType = (typeof BRAIN_OBSERVATION_TYPES)[number];
+/** Observation source type from schema. */
+export type BrainObservationSourceType = (typeof BRAIN_OBSERVATION_SOURCE_TYPES)[number];
+/** Parameters for observeBrain. */
+export interface ObserveBrainParams {
+    text: string;
+    title?: string;
+    type?: BrainObservationType;
+    project?: string;
+    sourceSessionId?: string;
+    sourceType?: BrainObservationSourceType;
+}
+/** Result from observeBrain. */
+export interface ObserveBrainResult {
+    id: string;
+    type: string;
+    createdAt: string;
+}
+/**
+ * Token-efficient compact search across BRAIN tables.
+ * Returns index-level hits (~50 tokens per result).
+ *
+ * Delegates to searchBrain() from brain-search.ts for FTS5/LIKE search,
+ * then projects results to a compact format with optional date filtering.
+ *
+ * @param projectRoot - Project root directory
+ * @param params - Search parameters
+ * @returns Compact search results with token estimate
+ */
+export declare function searchBrainCompact(projectRoot: string, params: SearchBrainCompactParams): Promise<SearchBrainCompactResult>;
+/**
+ * Get chronological context around an anchor entry.
+ * Fetches the anchor's full data, then queries all 4 BRAIN tables
+ * via UNION ALL to find chronological neighbors.
+ *
+ * @param projectRoot - Project root directory
+ * @param params - Timeline parameters with anchor ID and depth
+ * @returns Anchor entry data with surrounding chronological entries
+ */
+export declare function timelineBrain(projectRoot: string, params: TimelineBrainParams): Promise<TimelineBrainResult>;
+/**
+ * Batch-fetch full details by IDs.
+ * Groups IDs by prefix to query the correct tables via BrainDataAccessor.
+ *
+ * @param projectRoot - Project root directory
+ * @param params - Fetch parameters with IDs
+ * @returns Full entry data for each found ID, plus not-found list
+ */
+export declare function fetchBrainEntries(projectRoot: string, params: FetchBrainEntriesParams): Promise<FetchBrainEntriesResult>;
+/**
+ * Save an observation to the BRAIN observations table.
+ * Replaces the external claude-mem save_observation pattern.
+ *
+ * Auto-classifies type from text if not provided. Generates a
+ * unique ID with O- prefix + base36 timestamp.
+ *
+ * @param projectRoot - Project root directory
+ * @param params - Observation data
+ * @returns Created observation ID, type, and timestamp
+ */
+export declare function observeBrain(projectRoot: string, params: ObserveBrainParams): Promise<ObserveBrainResult>;
+/** Result from populateEmbeddings backfill. */
+export interface PopulateEmbeddingsResult {
+    processed: number;
+    skipped: number;
+}
+/**
+ * Backfill embeddings for existing observations that lack them.
+ *
+ * Iterates through observations not yet in brain_embeddings and
+ * generates vectors using the registered embedding provider.
+ * Processes in batches to avoid memory pressure.
+ *
+ * @param projectRoot - Project root directory
+ * @param options - Optional batch size configuration
+ * @returns Count of processed and skipped observations
+ */
+export declare function populateEmbeddings(projectRoot: string, options?: {
+    batchSize?: number;
+}): Promise<PopulateEmbeddingsResult>;
+//# sourceMappingURL=brain-retrieval.d.ts.map

package/dist/memory/brain-retrieval.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"brain-retrieval.d.ts","sourceRoot":"","sources":["../../src/memory/brain-retrieval.ts"],"names":[],"mappings":"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"}