@chude/memory 4.0.0

package/dist/infrastructure/database/schema.d.ts

@@ -0,0 +1,203 @@
+/**
+ * Database Schema Definitions
+ *
+ * SQLite schema with FTS5 full-text search support.
+ * Uses external content pattern for efficient FTS5 indexing.
+ */
+import type { Database } from "bun:sqlite";
+/**
+ * Sessions table - stores session metadata
+ */
+export declare const SESSIONS_TABLE = "\nCREATE TABLE IF NOT EXISTS sessions (\n    id TEXT PRIMARY KEY,\n    project_path_encoded TEXT NOT NULL,\n    project_path_decoded TEXT NOT NULL,\n    project_name TEXT NOT NULL,\n    start_time TEXT NOT NULL,\n    end_time TEXT,\n    message_count INTEGER DEFAULT 0,\n    summary TEXT,\n    created_at TEXT DEFAULT (datetime('now')),\n    updated_at TEXT DEFAULT (datetime('now'))\n);\nCREATE INDEX IF NOT EXISTS idx_sessions_project ON sessions(project_path_encoded);\nCREATE INDEX IF NOT EXISTS idx_sessions_start_time ON sessions(start_time);\n";
+/**
+ * Messages metadata table - content table for FTS5
+ * Uses explicit rowid for FTS5 external content linkage
+ */
+export declare const MESSAGES_META_TABLE = "\nCREATE TABLE IF NOT EXISTS messages_meta (\n    rowid INTEGER PRIMARY KEY AUTOINCREMENT,\n    id TEXT UNIQUE NOT NULL,\n    session_id TEXT NOT NULL,\n    role TEXT NOT NULL CHECK (role IN ('user', 'assistant')),\n    content TEXT NOT NULL,\n    timestamp TEXT NOT NULL,\n    tool_use_ids TEXT,\n    FOREIGN KEY (session_id) REFERENCES sessions(id) ON DELETE CASCADE\n);\nCREATE INDEX IF NOT EXISTS idx_messages_session ON messages_meta(session_id);\nCREATE INDEX IF NOT EXISTS idx_messages_timestamp ON messages_meta(timestamp);\n";
+/**
+ * Messages FTS5 virtual table - external content pattern
+ * References messages_meta for content storage
+ */
+export declare const MESSAGES_FTS_TABLE = "\nCREATE VIRTUAL TABLE IF NOT EXISTS messages_fts USING fts5(\n    content,\n    content=messages_meta,\n    content_rowid=rowid,\n    tokenize='porter unicode61'\n);\n";
+/**
+ * FTS5 synchronization triggers
+ * Keep FTS5 index in sync with messages_meta content
+ */
+export declare const FTS_TRIGGERS = "\nCREATE TRIGGER IF NOT EXISTS messages_fts_insert AFTER INSERT ON messages_meta BEGIN\n    INSERT INTO messages_fts(rowid, content) VALUES (new.rowid, new.content);\nEND;\n\nCREATE TRIGGER IF NOT EXISTS messages_fts_delete AFTER DELETE ON messages_meta BEGIN\n    INSERT INTO messages_fts(messages_fts, rowid, content) VALUES('delete', old.rowid, old.content);\nEND;\n\nCREATE TRIGGER IF NOT EXISTS messages_fts_update AFTER UPDATE ON messages_meta BEGIN\n    INSERT INTO messages_fts(messages_fts, rowid, content) VALUES('delete', old.rowid, old.content);\n    INSERT INTO messages_fts(rowid, content) VALUES (new.rowid, new.content);\nEND;\n";
+/**
+ * Tool uses table - stores tool invocation records
+ */
+export declare const TOOL_USES_TABLE = "\nCREATE TABLE IF NOT EXISTS tool_uses (\n    id TEXT PRIMARY KEY,\n    session_id TEXT NOT NULL,\n    name TEXT NOT NULL,\n    input TEXT NOT NULL,\n    timestamp TEXT NOT NULL,\n    status TEXT NOT NULL CHECK (status IN ('pending', 'success', 'error')),\n    result TEXT,\n    FOREIGN KEY (session_id) REFERENCES sessions(id) ON DELETE CASCADE\n);\nCREATE INDEX IF NOT EXISTS idx_tool_uses_session ON tool_uses(session_id);\nCREATE INDEX IF NOT EXISTS idx_tool_uses_name ON tool_uses(name);\n";
+/**
+ * Links table - graph-like relationships between entities
+ */
+export declare const LINKS_TABLE = "\nCREATE TABLE IF NOT EXISTS links (\n    id INTEGER PRIMARY KEY AUTOINCREMENT,\n    source_type TEXT NOT NULL CHECK (source_type IN ('session', 'message', 'topic')),\n    source_id TEXT NOT NULL,\n    target_type TEXT NOT NULL CHECK (target_type IN ('session', 'message', 'topic')),\n    target_id TEXT NOT NULL,\n    relationship TEXT NOT NULL CHECK (relationship IN ('mentions', 'related_to', 'continues')),\n    weight REAL DEFAULT 1.0 CHECK (weight >= 0 AND weight <= 1),\n    UNIQUE(source_type, source_id, target_type, target_id, relationship)\n);\nCREATE INDEX IF NOT EXISTS idx_links_source ON links(source_type, source_id);\nCREATE INDEX IF NOT EXISTS idx_links_target ON links(target_type, target_id);\n";
+/**
+ * Topics table - stores extracted topics
+ */
+export declare const TOPICS_TABLE = "\nCREATE TABLE IF NOT EXISTS topics (\n    id INTEGER PRIMARY KEY AUTOINCREMENT,\n    name TEXT UNIQUE NOT NULL,\n    created_at TEXT DEFAULT (datetime('now'))\n);\nCREATE INDEX IF NOT EXISTS idx_topics_name ON topics(name);\n";
+/**
+ * Extraction state table - tracks sync progress
+ */
+export declare const EXTRACTION_STATE_TABLE = "\nCREATE TABLE IF NOT EXISTS extraction_state (\n    id TEXT PRIMARY KEY,\n    session_path TEXT UNIQUE NOT NULL,\n    started_at TEXT NOT NULL,\n    status TEXT NOT NULL CHECK (status IN ('pending', 'in_progress', 'complete', 'error')),\n    completed_at TEXT,\n    messages_extracted INTEGER DEFAULT 0,\n    error_message TEXT,\n    file_mtime TEXT,\n    file_size INTEGER\n);\nCREATE INDEX IF NOT EXISTS idx_extraction_session_path ON extraction_state(session_path);\nCREATE INDEX IF NOT EXISTS idx_extraction_status ON extraction_state(status);\n";
+/**
+ * Entities table - stores extracted metadata (concepts, files, decisions, terms)
+ */
+export declare const ENTITIES_TABLE = "\nCREATE TABLE IF NOT EXISTS entities (\n    id INTEGER PRIMARY KEY AUTOINCREMENT,\n    type TEXT NOT NULL CHECK (type IN ('concept', 'file', 'decision', 'term')),\n    name TEXT NOT NULL,\n    metadata TEXT,\n    confidence REAL DEFAULT 1.0 CHECK (confidence >= 0 AND confidence <= 1),\n    created_at TEXT DEFAULT (datetime('now')),\n    UNIQUE(type, name)\n);\nCREATE INDEX IF NOT EXISTS idx_entities_type ON entities(type);\nCREATE INDEX IF NOT EXISTS idx_entities_name ON entities(name);\n";
+/**
+ * Session-Entity links - many-to-many relationship with frequency tracking
+ */
+export declare const SESSION_ENTITIES_TABLE = "\nCREATE TABLE IF NOT EXISTS session_entities (\n    session_id TEXT NOT NULL,\n    entity_id INTEGER NOT NULL,\n    frequency INTEGER DEFAULT 1,\n    FOREIGN KEY (session_id) REFERENCES sessions(id) ON DELETE CASCADE,\n    FOREIGN KEY (entity_id) REFERENCES entities(id) ON DELETE CASCADE,\n    PRIMARY KEY (session_id, entity_id)\n);\n";
+/**
+ * Entity-Entity links - cross-project relationships between entities
+ */
+export declare const ENTITY_LINKS_TABLE = "\nCREATE TABLE IF NOT EXISTS entity_links (\n    source_id INTEGER NOT NULL,\n    target_id INTEGER NOT NULL,\n    relationship TEXT NOT NULL CHECK (relationship IN ('related', 'implies', 'contradicts')),\n    weight REAL DEFAULT 1.0 CHECK (weight >= 0 AND weight <= 1),\n    FOREIGN KEY (source_id) REFERENCES entities(id) ON DELETE CASCADE,\n    FOREIGN KEY (target_id) REFERENCES entities(id) ON DELETE CASCADE,\n    PRIMARY KEY (source_id, target_id, relationship)\n);\n";
+/**
+ * Embedding state table - tracks which messages have been embedded
+ * and with which model, for incremental embedding and re-embedding detection.
+ *
+ * Always created regardless of sqlite-vec availability (regular SQL table).
+ */
+export declare const EMBEDDING_STATE_TABLE = "\nCREATE TABLE IF NOT EXISTS embedding_state (\n    message_id INTEGER PRIMARY KEY,\n    embedded_at TEXT NOT NULL,\n    model_hash TEXT NOT NULL,\n    FOREIGN KEY (message_id) REFERENCES messages_meta(rowid) ON DELETE CASCADE\n);\nCREATE INDEX IF NOT EXISTS idx_embedding_state_model ON embedding_state(model_hash);\n";
+/**
+ * Message embeddings vec0 virtual table - stores vector embeddings for messages.
+ *
+ * Only created when sqlite-vec extension is loaded (sqliteVecAvailable: true).
+ * Uses 384-dimensional float vectors matching all-MiniLM-L6-v2 default model.
+ */
+export declare const MESSAGE_EMBEDDINGS_TABLE = "\nCREATE VIRTUAL TABLE IF NOT EXISTS message_embeddings USING vec0(\n    embedding float[384]\n);\n";
+/**
+ * Migration: Add model_name column to embedding_state.
+ *
+ * The model_name stores the human-readable model identifier (e.g., "Xenova/all-MiniLM-L6-v2")
+ * alongside the model_hash. Required for user-facing prompts like "Model changed from X to Y"
+ * where X and Y must be readable model names, not opaque hex hashes.
+ *
+ * Uses ALTER TABLE with DEFAULT '' so existing rows (if any) get an empty string,
+ * and new rows always store the model name explicitly.
+ */
+export declare const EMBEDDING_STATE_ADD_MODEL_NAME = "\nALTER TABLE embedding_state ADD COLUMN model_name TEXT NOT NULL DEFAULT '';\n";
+/**
+ * Memory files table - stores indexed legacy markdown sidecar files
+ */
+export declare const MEMORY_FILES_TABLE = "\nCREATE TABLE IF NOT EXISTS memory_files (\n    id INTEGER PRIMARY KEY AUTOINCREMENT,\n    file_path TEXT UNIQUE NOT NULL,\n    file_type TEXT NOT NULL CHECK (file_type IN ('daily_log', 'decisions', 'learnings', 'user_prefs')),\n    project_encoded TEXT,\n    content TEXT NOT NULL,\n    content_hash TEXT NOT NULL,\n    last_indexed_at TEXT NOT NULL,\n    created_at TEXT DEFAULT (datetime('now'))\n);\nCREATE INDEX IF NOT EXISTS idx_memory_files_type ON memory_files(file_type);\nCREATE INDEX IF NOT EXISTS idx_memory_files_project ON memory_files(project_encoded);\n";
+/**
+ * Memory files FTS5 virtual table - external content pattern
+ * References memory_files for content storage
+ */
+export declare const MEMORY_FILES_FTS_TABLE = "\nCREATE VIRTUAL TABLE IF NOT EXISTS memory_files_fts USING fts5(\n    content,\n    content=memory_files,\n    content_rowid=id,\n    tokenize='porter unicode61'\n);\n";
+/**
+ * Memory files FTS5 synchronization triggers
+ * Keep memory_files_fts index in sync with memory_files content.
+ * Follows the same pattern as FTS_TRIGGERS for messages_fts.
+ */
+export declare const MEMORY_FILES_FTS_TRIGGERS = "\nCREATE TRIGGER IF NOT EXISTS memory_files_fts_insert AFTER INSERT ON memory_files BEGIN\n    INSERT INTO memory_files_fts(rowid, content) VALUES (new.id, new.content);\nEND;\n\nCREATE TRIGGER IF NOT EXISTS memory_files_fts_delete AFTER DELETE ON memory_files BEGIN\n    INSERT INTO memory_files_fts(memory_files_fts, rowid, content) VALUES('delete', old.id, old.content);\nEND;\n\nCREATE TRIGGER IF NOT EXISTS memory_files_fts_update AFTER UPDATE ON memory_files BEGIN\n    INSERT INTO memory_files_fts(memory_files_fts, rowid, content) VALUES('delete', old.id, old.content);\n    INSERT INTO memory_files_fts(rowid, content) VALUES (new.id, new.content);\nEND;\n";
+/**
+ * Friction log table - stores friction entries for tool self-improvement
+ */
+export declare const FRICTION_LOG_TABLE = "\nCREATE TABLE IF NOT EXISTS friction_log (\n    id INTEGER PRIMARY KEY AUTOINCREMENT,\n    description TEXT NOT NULL,\n    severity TEXT NOT NULL DEFAULT 'medium' CHECK (severity IN ('low', 'medium', 'high', 'critical')),\n    category TEXT NOT NULL DEFAULT 'cli',\n    tool TEXT NOT NULL DEFAULT 'memory',\n    tags TEXT,\n    status TEXT NOT NULL DEFAULT 'open' CHECK (status IN ('open', 'resolved', 'wont-fix')),\n    context TEXT,\n    source_project TEXT,\n    logged_at TEXT NOT NULL,\n    resolved_at TEXT,\n    resolution TEXT,\n    last_reviewed_at TEXT\n);\nCREATE INDEX IF NOT EXISTS idx_friction_status ON friction_log(status);\nCREATE INDEX IF NOT EXISTS idx_friction_severity ON friction_log(severity);\nCREATE INDEX IF NOT EXISTS idx_friction_category ON friction_log(category);\nCREATE INDEX IF NOT EXISTS idx_friction_tool ON friction_log(tool);\n";
+/**
+ * Migration: Universalize friction_log table.
+ *
+ * Recreates friction_log with new columns (tool, tags, last_reviewed_at)
+ * and removes the category CHECK constraint. Preserves existing data
+ * with tool defaulting to 'memory'.
+ */
+export declare const FRICTION_LOG_UNIVERSALIZE_MIGRATION = "\nCREATE TABLE friction_log_new (\n    id INTEGER PRIMARY KEY AUTOINCREMENT,\n    description TEXT NOT NULL,\n    severity TEXT NOT NULL DEFAULT 'medium' CHECK (severity IN ('low', 'medium', 'high', 'critical')),\n    category TEXT NOT NULL DEFAULT 'cli',\n    tool TEXT NOT NULL DEFAULT 'memory',\n    tags TEXT,\n    status TEXT NOT NULL DEFAULT 'open' CHECK (status IN ('open', 'resolved', 'wont-fix')),\n    context TEXT,\n    source_project TEXT,\n    logged_at TEXT NOT NULL,\n    resolved_at TEXT,\n    resolution TEXT,\n    last_reviewed_at TEXT\n);\nINSERT INTO friction_log_new (id, description, severity, category, tool, tags, status, context, source_project, logged_at, resolved_at, resolution, last_reviewed_at)\nSELECT id, description, severity, category, 'memory', NULL, status, context, source_project, logged_at, resolved_at, resolution, NULL\nFROM friction_log;\nDROP TABLE friction_log;\nALTER TABLE friction_log_new RENAME TO friction_log;\nCREATE INDEX IF NOT EXISTS idx_friction_status ON friction_log(status);\nCREATE INDEX IF NOT EXISTS idx_friction_severity ON friction_log(severity);\nCREATE INDEX IF NOT EXISTS idx_friction_category ON friction_log(category);\nCREATE INDEX IF NOT EXISTS idx_friction_tool ON friction_log(tool);\n";
+/**
+ * Backfill state table - tracks which sessions have been backfilled
+ *
+ * Enables idempotent backfill: processed sessions are skipped on re-run.
+ * No foreign keys to sessions table (session_id is text reference only).
+ */
+export declare const BACKFILL_STATE_TABLE = "\nCREATE TABLE IF NOT EXISTS backfill_state (\n    session_id TEXT PRIMARY KEY,\n    backfilled_at TEXT NOT NULL,\n    daily_log_path TEXT NOT NULL,\n    success INTEGER DEFAULT 1,\n    error_message TEXT\n);\n";
+/**
+ * Facts table - derived projection of the plain-text event log.
+ */
+export declare const FACTS_TABLE = "\nCREATE TABLE IF NOT EXISTS facts (\n    id INTEGER PRIMARY KEY AUTOINCREMENT,\n    uuid TEXT UNIQUE NOT NULL,\n    type TEXT NOT NULL CHECK (type IN ('decision', 'learning', 'preference', 'friction', 'observation', 'supersedence')),\n    project TEXT NOT NULL,\n    content TEXT NOT NULL,\n    metadata TEXT,\n    observed_at TEXT NOT NULL,\n    superseded_at TEXT,\n    superseded_by TEXT,\n    created_at TEXT DEFAULT (datetime('now')),\n    updated_at TEXT DEFAULT (datetime('now'))\n);\nCREATE INDEX IF NOT EXISTS idx_facts_uuid ON facts(uuid);\nCREATE INDEX IF NOT EXISTS idx_facts_project ON facts(project);\nCREATE INDEX IF NOT EXISTS idx_facts_type ON facts(type);\n";
+/**
+ * Facts FTS5 virtual table - external content pattern.
+ * References facts table for content storage.
+ */
+export declare const FACTS_FTS_TABLE = "\nCREATE VIRTUAL TABLE IF NOT EXISTS facts_fts USING fts5(\n    content,\n    content=facts,\n    content_rowid=id,\n    tokenize='porter unicode61'\n);\n";
+/**
+ * Facts FTS5 synchronization triggers.
+ */
+export declare const FACTS_FTS_TRIGGERS = "\nCREATE TRIGGER IF NOT EXISTS facts_fts_insert AFTER INSERT ON facts BEGIN\n    INSERT INTO facts_fts(rowid, content) VALUES (new.id, new.content);\nEND;\n\nCREATE TRIGGER IF NOT EXISTS facts_fts_delete AFTER DELETE ON facts BEGIN\n    INSERT INTO facts_fts(facts_fts, rowid, content) VALUES('delete', old.id, old.content);\nEND;\n\nCREATE TRIGGER IF NOT EXISTS facts_fts_update AFTER UPDATE ON facts BEGIN\n    INSERT INTO facts_fts(facts_fts, rowid, content) VALUES('delete', old.id, old.content);\n    INSERT INTO facts_fts(rowid, content) VALUES (new.id, new.content);\nEND;\n";
+/**
+ * Extraction log table - tracks run logs of LLM fact extraction.
+ */
+export declare const EXTRACTION_LOG_TABLE = "\nCREATE TABLE IF NOT EXISTS extraction_log (\n    session_id TEXT PRIMARY KEY,\n    mode TEXT NOT NULL,\n    facts_added INTEGER DEFAULT 0,\n    facts_updated INTEGER DEFAULT 0,\n    facts_superseded INTEGER DEFAULT 0,\n    facts_skipped INTEGER DEFAULT 0,\n    provider TEXT NOT NULL,\n    model TEXT NOT NULL,\n    tokens_consumed INTEGER DEFAULT 0,\n    extracted_at TEXT NOT NULL\n);\n";
+/**
+ * Schema options for conditional table creation
+ */
+export interface SchemaOptions {
+    /** Whether sqlite-vec extension is loaded and vec0 tables can be created. Default: false */
+    sqliteVecAvailable?: boolean;
+}
+/**
+ * Sessions FTS5 virtual table - for summary full-text search
+ *
+ * Uses standalone FTS5 table (not external content) because summaries
+ * are only added/updated after session ends, and we want FTS5 to manage
+ * its own content for simplicity.
+ */
+export declare const SESSIONS_FTS_TABLE = "\nCREATE VIRTUAL TABLE IF NOT EXISTS sessions_fts USING fts5(\n    session_id,\n    summary,\n    tokenize='porter unicode61'\n);\n";
+/**
+ * Sessions FTS5 synchronization triggers
+ * Keep sessions_fts index in sync with sessions summary updates
+ *
+ * Note: INSERT trigger does not index since summary is NULL on insert.
+ * Only UPDATE trigger handles FTS indexing when summary is set.
+ */
+export declare const SESSIONS_FTS_TRIGGERS = "\nCREATE TRIGGER IF NOT EXISTS sessions_fts_update AFTER UPDATE OF summary ON sessions\nWHEN new.summary IS NOT NULL AND new.summary != ''\nBEGIN\n    DELETE FROM sessions_fts WHERE session_id = old.id;\n    INSERT INTO sessions_fts(session_id, summary) VALUES (new.id, new.summary);\nEND;\n\nCREATE TRIGGER IF NOT EXISTS sessions_fts_delete AFTER DELETE ON sessions BEGIN\n    DELETE FROM sessions_fts WHERE session_id = old.id;\nEND;\n";
+/**
+ * Complete schema SQL statements in dependency order
+ *
+ * Order matters:
+ * 1. sessions (no dependencies)
+ * 2. messages_meta (depends on sessions)
+ * 3. messages_fts (depends on messages_meta)
+ * 4. FTS triggers (depend on both messages tables)
+ * 5. tool_uses (depends on sessions)
+ * 6. links (no foreign keys)
+ * 7. topics (no dependencies)
+ * 8. extraction_state (no dependencies)
+ * 9. entities (no dependencies)
+ * 10. session_entities (depends on sessions, entities)
+ * 11. entity_links (depends on entities)
+ * 12. sessions_fts (depends on sessions)
+ * 13. sessions_fts triggers (depends on sessions, sessions_fts)
+ * 14. embedding_state (depends on messages_meta) -- always created
+ * 15. memory_files (no dependencies)
+ * 16. memory_files_fts (depends on memory_files)
+ * 17. memory_files FTS triggers (depend on both memory_files tables)
+ * 18. friction_log (no dependencies)
+ * 19. backfill_state (no dependencies)
+ *
+ * Note: message_embeddings (vec0) is NOT in this array.
+ * It is conditionally created in createSchema() when sqliteVecAvailable is true.
+ */
+export declare const SCHEMA_SQL: readonly string[];
+/**
+ * Check if FTS5 extension is available in the database
+ *
+ * @param db - SQLite database instance
+ * @returns true if FTS5 is supported, false otherwise
+ */
+export declare function checkFts5Support(db: Database): boolean;
+/**
+ * Create all schema tables in the database
+ *
+ * Executes all DDL statements in dependency order.
+ * Safe to call multiple times (uses IF NOT EXISTS).
+ *
+ * When sqliteVecAvailable is true, also creates the message_embeddings
+ * vec0 virtual table for vector similarity search. The embedding_state
+ * tracking table is always created regardless of sqlite-vec availability.
+ *
+ * @param db - SQLite database instance
+ * @param options - Schema creation options (defaults to sqliteVecAvailable: false)
+ * @throws Error if FTS5 is not supported or SQL execution fails
+ */
+export declare function createSchema(db: Database, options?: SchemaOptions): void;

package/dist/infrastructure/database/services/context-service.d.ts

@@ -0,0 +1,93 @@
+/**
+ * SQLite Context Service Implementation
+ *
+ * Implements project context aggregation using SQLite queries.
+ * Provides session counts, message breakdown, tool usage, and topics
+ * for a specific project.
+ */
+import type { Database } from "bun:sqlite";
+import type { IProjectResolver } from "../../../application/services/smart-context-service.js";
+/**
+ * Tool usage summary with name and count.
+ */
+export interface ToolUsage {
+    name: string;
+    count: number;
+}
+/**
+ * Aggregated context for a project.
+ */
+export interface ProjectContext {
+    projectName: string;
+    projectPathDecoded: string;
+    sessionCount: number;
+    totalMessages: number;
+    userMessages: number;
+    assistantMessages: number;
+    recentTopics: string[];
+    recentToolUses: ToolUsage[];
+    lastActivity: Date | null;
+}
+/**
+ * Options for context retrieval.
+ */
+export interface ContextOptions {
+    /** Filter to last N days (includes today) */
+    days?: number | undefined;
+    /** Maximum topics to return (default 10) */
+    topicsLimit?: number | undefined;
+    /** Maximum tools to return (default 10) */
+    toolsLimit?: number | undefined;
+}
+/**
+ * SQLite implementation of context service.
+ *
+ * Features:
+ * - LIKE match for project name substring search
+ * - Aggregation queries for counts
+ * - Time-based filtering with --days option
+ * - Tool usage breakdown sorted by count
+ * - Topics from links table (graceful empty handling)
+ */
+export declare class SqliteContextService {
+    private readonly db;
+    /**
+     * Create a new SqliteContextService.
+     *
+     * @param db - Initialized SQLite database with schema applied
+     */
+    constructor(db: Database);
+    /**
+     * Get aggregated context for a project.
+     *
+     * @param projectFilter Project name or substring to filter by
+     * @param options Context retrieval options
+     * @returns Project context or null if not found
+     */
+    getProjectContext(projectFilter: string, options?: ContextOptions): Promise<ProjectContext | null>;
+}
+/**
+ * SQLite implementation of IProjectResolver.
+ *
+ * Resolves project names to encoded paths and display names
+ * using the sessions table. Supports exact (case-insensitive)
+ * and substring matching, ranked by session count.
+ */
+export declare class SqliteProjectResolver implements IProjectResolver {
+    private readonly db;
+    constructor(db: Database);
+    /**
+     * Resolve a project name or filter to its encoded path.
+     *
+     * @param projectFilter Project name or substring
+     * @returns Encoded path or null if not found
+     */
+    resolveProjectEncoded(projectFilter: string): string | null;
+    /**
+     * Resolve a project name or filter to its display name.
+     *
+     * @param projectFilter Project name or substring
+     * @returns Display name or null if not found
+     */
+    resolveProjectName(projectFilter: string): string | null;
+}

package/dist/infrastructure/database/services/hybrid-search-service.d.ts

@@ -0,0 +1,156 @@
+/**
+ * HybridSearchService
+ *
+ * Composes Fts5SearchService, EmbeddingRepository, and EmbeddingProviderFactory
+ * into a unified search interface supporting four modes: auto, fts, vector, hybrid.
+ *
+ * Implements ISearchService from the domain ports layer so it can be a drop-in
+ * replacement for the FTS-only search service.
+ *
+ * Mode resolution: explicit CLI mode > config search.defaultMode > 'auto'
+ *
+ * Degradation:
+ * - auto mode: silently uses FTS when vector unavailable
+ * - hybrid mode: degrades to FTS when vector fails
+ * - vector mode: throws VECTOR_UNAVAILABLE (explicit user intent)
+ * - fts mode: never touches vector infrastructure
+ */
+import type { Database } from "bun:sqlite";
+import type { ISearchService, SearchMode, HybridSearchOptions } from "../../../domain/ports/services.js";
+import type { SearchQuery } from "../../../domain/value-objects/search-query.js";
+import { SearchResult } from "../../../domain/value-objects/search-result.js";
+import type { Fts5SearchService } from "./search-service.js";
+import type { EmbeddingRepository } from "../repositories/embedding-repository.js";
+import type { EmbeddingProviderFactory } from "../../embedding/embedding-provider-factory.js";
+import type { MemoryConfig } from "../../hooks/config-manager.js";
+/**
+ * Dependencies injected via constructor.
+ */
+export interface HybridSearchDeps {
+    db: Database;
+    fts5Service: Fts5SearchService;
+    embeddingRepo: EmbeddingRepository;
+    providerFactory: EmbeddingProviderFactory;
+    config: MemoryConfig;
+    sqliteVecAvailable: boolean;
+}
+/**
+ * Metadata about the last search operation.
+ */
+export interface SearchMeta {
+    /** The effective search mode used */
+    mode: SearchMode;
+    /** Reason for the mode selection */
+    modeReason: string;
+    /** Whether the search degraded from requested mode */
+    degraded: boolean;
+    /** Reason for degradation, if any */
+    degradationReason?: string | undefined;
+    /** Fraction of messages with embeddings (0-1) */
+    embeddingCoverage: number;
+    /** System capabilities for this search */
+    capabilities: {
+        fts: boolean;
+        vector: boolean;
+        hybrid: boolean;
+    };
+    /** Total search time in milliseconds */
+    timingMs: number;
+}
+/**
+ * HybridSearchService composes FTS5 and vector search with RRF fusion.
+ *
+ * Implements ISearchService for drop-in compatibility.
+ */
+export declare class HybridSearchService implements ISearchService {
+    private readonly db;
+    private readonly fts5Service;
+    private readonly embeddingRepo;
+    private readonly providerFactory;
+    private readonly config;
+    private readonly sqliteVecAvailable;
+    private lastSearchMeta;
+    constructor(deps: HybridSearchDeps);
+    /**
+     * Get metadata from the last search operation.
+     */
+    getLastSearchMeta(): SearchMeta | null;
+    /**
+     * Search for content using the configured mode.
+     *
+     * Supports FTS, vector, hybrid, and auto modes.
+     * Degrades gracefully when vector components are unavailable.
+     */
+    search(query: SearchQuery, options?: HybridSearchOptions): Promise<SearchResult[]>;
+    /**
+     * Resolve the effective search mode from requested mode, config, and capabilities.
+     */
+    private resolveMode;
+    /**
+     * Apply temporal decay to search results using their embedded timestamps.
+     *
+     * Builds decay by computing age from each result's timestamp,
+     * applying the standard half-life formula, and re-sorting by
+     * decayed score. This is the single point where temporal decay
+     * is applied, regardless of search mode (FTS, vector, hybrid).
+     */
+    private applyDecayToResults;
+    /**
+     * FTS-only search path. Delegates directly to Fts5SearchService.
+     */
+    private ftsSearch;
+    /**
+     * Get or initialize the embedding provider.
+     *
+     * For auto/hybrid mode: returns null on failure (allows degradation).
+     * For vector mode: throws on failure (user explicitly requested).
+     */
+    private getProvider;
+    /**
+     * Embed the query text using the configured provider.
+     */
+    private embedQuery;
+    /**
+     * Check for dimension mismatch between stored embeddings and current provider.
+     *
+     * The vec0 table was created with a specific dimension. If the provider
+     * produces embeddings of a different dimension, KNN queries will fail.
+     * We detect this by comparing the provider's dimensions against the
+     * schema's stored dimension (derived from the embedding table definition).
+     *
+     * Returns the mismatch reason string if mismatch found, null otherwise.
+     */
+    private checkDimensionMismatch;
+    /**
+     * Get the dimension count of stored embeddings.
+     * Queries the first embedding to determine its dimension.
+     */
+    private getStoredEmbeddingDimensions;
+    /**
+     * Vector-only search path.
+     * Embeds query, runs KNN, hydrates results.
+     */
+    private vectorSearch;
+    /**
+     * Hybrid search path.
+     * Runs FTS and vector searches, combines with RRF, applies temporal decay.
+     * Returns results plus degradation status.
+     */
+    private hybridSearch;
+    /**
+     * Build a map from message ID to rowid for FTS results.
+     */
+    private buildFtsRowidMap;
+    /**
+     * Hydrate message metadata by rowids.
+     */
+    private hydrateByRowids;
+    /**
+     * Generate a snippet for vector-only results (first 200 chars).
+     */
+    private vectorSnippet;
+    /**
+     * Check if a message passes the search filters.
+     */
+    private passesFilters;
+}

package/dist/infrastructure/database/services/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Database Services
+ *
+ * Service implementations for search and other database operations.
+ */
+export { Fts5SearchService } from "./search-service.js";
+export { HybridSearchService } from "./hybrid-search-service.js";
+export type { HybridSearchDeps, SearchMeta } from "./hybrid-search-service.js";
+export { SqliteStatsService } from "./stats-service.js";
+export { SqliteContextService, SqliteProjectResolver, type ProjectContext, type ContextOptions, type ToolUsage, } from "./context-service.js";

package/dist/infrastructure/database/services/search-service.d.ts

@@ -0,0 +1,57 @@
+/**
+ * FTS5 Search Service Implementation
+ *
+ * Implements ISearchService using SQLite FTS5 full-text search.
+ * Uses BM25 ranking algorithm for relevance scoring and snippet extraction.
+ */
+import type { Database } from "bun:sqlite";
+import type { ISearchService, SearchOptions } from "../../../domain/ports/services.js";
+import type { SearchQuery } from "../../../domain/value-objects/search-query.js";
+import { SearchResult } from "../../../domain/value-objects/search-result.js";
+/**
+ * FTS5-based implementation of ISearchService
+ *
+ * Features:
+ * - Full-text search using FTS5 MATCH operator
+ * - BM25 relevance ranking normalized to 0-1 range
+ * - Snippet extraction with match highlighting
+ * - Filtering by project, role, and date range
+ *
+ * CRITICAL: Always uses MATCH operator for FTS5 queries (never =).
+ * Using = would cause a full table scan defeating the purpose of FTS5.
+ */
+export declare class Fts5SearchService implements ISearchService {
+    private readonly db;
+    /**
+     * Create a new Fts5SearchService
+     *
+     * @param db - Initialized SQLite database with FTS5 schema applied
+     */
+    constructor(db: Database);
+    /**
+     * Search for content matching the query.
+     *
+     * Uses FTS5 MATCH operator with BM25 ranking. Results are normalized
+     * to 0-1 score range (higher = more relevant) and mapped to SearchResult
+     * value objects.
+     *
+     * @param query - Validated search query
+     * @param options - Optional filters and limits
+     * @returns Array of search results, ranked by relevance
+     */
+    search(query: SearchQuery, options?: SearchOptions): Promise<SearchResult[]>;
+    /**
+     * Build the search SQL query with optional filters
+     */
+    private buildSearchQuery;
+    /**
+     * Normalize BM25 scores to 0-1 range
+     *
+     * BM25 returns negative values where more negative = better match.
+     * We normalize so that:
+     * - Best match (most negative) gets score 1.0
+     * - Worst match (least negative) gets score based on relative ranking
+     * - Single result gets score 1.0
+     */
+    private normalizeBm25Scores;
+}

package/dist/infrastructure/database/services/stats-service.d.ts

@@ -0,0 +1,36 @@
+/**
+ * SQLite Stats Service Implementation
+ *
+ * Implements IStatsService using SQLite queries for database statistics.
+ * Provides total counts, database size, and per-project breakdown.
+ */
+import type { Database } from "bun:sqlite";
+import type { IStatsService, StatsResult } from "../../../domain/ports/services.js";
+/**
+ * SQLite implementation of IStatsService.
+ *
+ * Features:
+ * - Single query with subqueries for totals (efficient)
+ * - Table-valued PRAGMA for database size
+ * - GROUP BY with proper COUNT for project breakdown
+ */
+export declare class SqliteStatsService implements IStatsService {
+    private readonly db;
+    /**
+     * Create a new SqliteStatsService.
+     *
+     * @param db - Initialized SQLite database with schema applied
+     */
+    constructor(db: Database);
+    /**
+     * Get database-wide statistics with per-project breakdown.
+     *
+     * When projectLimit is applied, totals (sessions and messages) are computed
+     * from the filtered project breakdown, so they match what's displayed.
+     * Database size and tool uses remain as database-wide totals.
+     *
+     * @param projectLimit Maximum projects to include in breakdown (default 10)
+     * @returns Statistics including totals and per-project breakdown
+     */
+    getStats(projectLimit?: number): Promise<StatsResult>;
+}