@jungjaehoon/mama-core 1.1.2 → 1.1.3

package/dist/db-manager.d.ts

@@ -0,0 +1,252 @@
+/**
+ * MAMA Database Manager (SQLite-only)
+ *
+ * SQLite-exclusive database interface for MAMA Plugin.
+ * Uses better-sqlite3 + sqlite-vec for local storage.
+ *
+ * PostgreSQL support is only available in the legacy mcp-server repository.
+ *
+ * Features:
+ * - WAL mode for better concurrency
+ * - synchronous=NORMAL for performance
+ * - Automatic migration management
+ * - Vector similarity search (when sqlite-vec available)
+ *
+ * @module db-manager
+ * @version 2.1 (Plugin - SQLite-only)
+ * @date 2026-02-01
+ * @source-of-truth packages/mama-core/src/db-manager.js (mama-core)
+ */
+import type { PreparedStatement } from './db-adapter/statement.js';
+export type { PreparedStatement };
+export interface DatabaseAdapter {
+    connect: () => unknown;
+    disconnect: () => void;
+    runMigrations: (dir: string) => void;
+    prepare: (sql: string) => PreparedStatement;
+    transaction: <T>(fn: () => T) => T;
+    insertEmbedding: (rowid: number, embedding: Float32Array | number[]) => void;
+    vectorSearch: (embedding: Float32Array | number[], limit: number) => Promise<VectorSearchResult[] | null>;
+    vectorSearchEnabled: boolean;
+    getDbPath?: () => string;
+    dbPath?: string;
+    constructor: {
+        name: string;
+    };
+}
+export interface VectorSearchResult {
+    rowid: number;
+    similarity?: number;
+    distance?: number;
+}
+export interface DecisionRecord {
+    id: string;
+    topic: string;
+    decision: string;
+    reasoning?: string | null;
+    outcome?: string | null;
+    failure_reason?: string | null;
+    limitation?: string | null;
+    confidence?: number;
+    supersedes?: string | null;
+    superseded_by?: string | null;
+    refined_from?: string | string[] | null;
+    created_at: number;
+    updated_at?: number;
+    edges?: unknown[];
+}
+export interface OutcomeData {
+    outcome?: string | null;
+    failure_reason?: string | null;
+    limitation?: string | null;
+    duration_days?: number | null;
+    confidence?: number | null;
+}
+export interface VectorSearchParams {
+    query: string;
+    limit?: number;
+    threshold?: number;
+    timeWindow?: number;
+}
+export interface SemanticEdges {
+    refines: unknown[];
+    refined_by: unknown[];
+    contradicts: unknown[];
+    contradicted_by: unknown[];
+    builds_on: unknown[];
+    built_on_by: unknown[];
+    debates: unknown[];
+    debated_by: unknown[];
+    synthesizes: unknown[];
+    synthesized_by: unknown[];
+}
+/**
+ * Initialize SQLite database adapter and connect
+ *
+ * Lazy initialization: Only connects when first accessed
+ * Creates database file at ~/.claude/mama-memory.db by default
+ *
+ * Single-flight guard: Concurrent callers await the same promise
+ * to prevent multiple adapters/migrations running simultaneously.
+ *
+ * @returns SQLite database connection
+ */
+export declare function initDB(): Promise<unknown>;
+/**
+ * Get database connection (singleton pattern)
+ *
+ * Returns better-sqlite3 Database instance
+ *
+ * Note: Synchronous for backward compatibility with memory-store.js
+ * Will throw if database not initialized
+ *
+ * @returns SQLite database connection
+ */
+export declare function getDB(): unknown;
+/**
+ * Get database adapter instance
+ *
+ * Used for advanced operations (vectorSearch, insertEmbedding, etc.)
+ *
+ * @returns Adapter instance
+ */
+export declare function getAdapter(): DatabaseAdapter;
+/**
+ * Close database connection
+ *
+ * Call this on process exit
+ */
+export declare function closeDB(): Promise<void>;
+/**
+ * Insert embedding into vector search table
+ *
+ * Uses sqlite-vec for vector similarity search
+ * Gracefully degrades if sqlite-vec is not available
+ *
+ * @param decisionRowid - SQLite rowid
+ * @param embedding - 384-dim embedding vector
+ */
+export declare function insertEmbedding(decisionRowid: number, embedding: Float32Array | number[]): Promise<void>;
+/**
+ * Perform vector similarity search
+ *
+ * Returns empty array if vector search not available (no keyword fallback)
+ *
+ * @param queryEmbedding - Query embedding (384-dim)
+ * @param limit - Max results to return (default: 5)
+ * @param threshold - Minimum similarity threshold (default: 0.7)
+ * @returns Array of decisions with similarity scores, or empty array
+ */
+export declare function vectorSearch(queryEmbedding: Float32Array | number[], limit?: number, threshold?: number): Promise<DecisionRecord[]>;
+/**
+ * Decision input for storage
+ */
+export interface DecisionInput {
+    id: string;
+    topic: string;
+    decision: string;
+    reasoning?: string | null;
+    outcome?: string | null;
+    failure_reason?: string | null;
+    limitation?: string | null;
+    user_involvement?: string | null;
+    session_id?: string | null;
+    supersedes?: string | null;
+    superseded_by?: string | null;
+    refined_from?: string[] | null;
+    confidence?: number;
+    created_at?: number;
+    updated_at?: number;
+    needs_validation?: number;
+    validation_attempts?: number;
+    last_validated_at?: number | null;
+    usage_count?: number;
+    trust_context?: string | null;
+    usage_success?: number;
+    usage_failure?: number;
+    time_saved?: number;
+    evidence?: string | null;
+    alternatives?: string | null;
+    risks?: string | null;
+}
+/**
+ * Insert decision with embedding
+ *
+ * Combined operation: Insert decision + Generate embedding + Insert embedding
+ * SQLite-only implementation
+ *
+ * @param decision - Decision object
+ * @returns Decision ID
+ */
+export declare function insertDecisionWithEmbedding(decision: DecisionInput): Promise<string>;
+/**
+ * Query decision graph for topic
+ *
+ * Recursive CTE to traverse supersedes chain
+ * SQLite implementation using WITH RECURSIVE
+ *
+ * @param topic - Decision topic to query
+ * @returns Array of decisions (ordered by recency)
+ */
+export declare function queryDecisionGraph(topic: string): Promise<DecisionRecord[]>;
+/**
+ * Query semantic edges for a list of decisions
+ *
+ * Returns both outgoing (from_id) and incoming (to_id) edges
+ * for refines and contradicts relationships
+ *
+ * @param decisionIds - Decision IDs to query edges for
+ * @returns Categorized edges
+ */
+export declare function querySemanticEdges(decisionIds: string[]): Promise<SemanticEdges>;
+/**
+ * Query vector search with time window and threshold
+ *
+ * Story 014.14: AC #1 - Vector Search for Related Decisions
+ *
+ * @param params - Search parameters
+ * @returns Results with similarity scores and decision data
+ */
+export declare function queryVectorSearch(params: VectorSearchParams): Promise<DecisionRecord[]>;
+/**
+ * Update decision outcome
+ *
+ * @param decisionId - Decision ID
+ * @param outcomeData - Outcome data
+ */
+export declare function updateDecisionOutcome(decisionId: string, outcomeData: OutcomeData): Promise<void>;
+/**
+ * Get prepared statement
+ *
+ * For backward compatibility with memory-store.js
+ * Returns a compatibility shim that proxies to adapter.prepare()
+ *
+ * @param sql - SQL statement
+ * @returns Statement-like object with run/get/all methods
+ */
+export declare function getPreparedStmt(sql: string): PreparedStatement;
+/**
+ * Get database file path
+ *
+ * @returns Actual database path or 'Not initialized'
+ */
+export declare function getDbPath(): string;
+/**
+ * Reset database state for testing
+ *
+ * Resets internal state without closing connection.
+ * Use this in test teardown to allow re-initialization with different DB path.
+ *
+ * @param options - Reset options
+ * @param options.disconnect - If true, also disconnect adapter (default: true)
+ */
+export declare function resetDBState(options?: {
+    disconnect?: boolean;
+}): void;
+/**
+ * Check if running in test mode
+ *
+ * Returns true if MAMA_TEST_MODE or VITEST env vars are set
+ */
+export declare function isTestMode(): boolean;
+//# sourceMappingURL=db-manager.d.ts.map