@jungjaehoon/mama-core 1.1.2 → 1.1.3

package/dist/db-adapter/sqlite-adapter.js

@@ -0,0 +1,330 @@
+"use strict";
+/**
+ * SQLite Database Adapter
+ *
+ * Implements DatabaseAdapter interface using better-sqlite3 + sqlite-vec
+ * This is the current production implementation extracted from memory-store.js
+ *
+ * @module sqlite-adapter
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SQLiteAdapter = void 0;
+const path_1 = __importDefault(require("path"));
+const os_1 = __importDefault(require("os"));
+const fs_1 = __importDefault(require("fs"));
+const better_sqlite3_1 = __importDefault(require("better-sqlite3"));
+const base_adapter_js_1 = require("./base-adapter.js");
+const statement_js_1 = require("./statement.js");
+const debug_logger_js_1 = require("../debug-logger.js");
+const embeddings_js_1 = require("../embeddings.js");
+// Try to load sqlite-vec
+let sqliteVec = null;
+try {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    sqliteVec = require('sqlite-vec');
+}
+catch {
+    // Defer logging until connect() so we have logger context initialized
+    sqliteVec = null;
+}
+// Database paths
+const LEGACY_DB_PATH = path_1.default.join(os_1.default.homedir(), '.spinelift', 'memories.db');
+// Default to ~/.claude/mama-memory.db for Claude Code/Desktop compatibility
+const DEFAULT_DB_PATH = path_1.default.join(os_1.default.homedir(), '.claude', 'mama-memory.db');
+class SQLiteAdapter extends base_adapter_js_1.DatabaseAdapter {
+    config;
+    db = null;
+    _vectorSearchEnabled = false;
+    constructor(config = {}) {
+        super();
+        this.config = config;
+    }
+    /**
+     * Check if vector search is enabled
+     */
+    get vectorSearchEnabled() {
+        return this._vectorSearchEnabled;
+    }
+    /**
+     * Get database path with backward compatibility
+     */
+    getDbPath() {
+        // Support both MAMA_DB_PATH and MAMA_DATABASE_PATH for backward compatibility
+        const envPath = process.env.MAMA_DB_PATH || process.env.MAMA_DATABASE_PATH;
+        const configPath = this.config.dbPath;
+        // Expand ${HOME} or ~ in environment variable
+        let expandedEnvPath = envPath;
+        if (envPath) {
+            expandedEnvPath = envPath.replace(/\$\{HOME\}/g, os_1.default.homedir()).replace(/^~/, os_1.default.homedir());
+        }
+        // Priority: config > env > default
+        const targetPath = configPath || expandedEnvPath || DEFAULT_DB_PATH;
+        // Backward compatibility: Check legacy path if not explicitly set
+        if (!configPath && !envPath && fs_1.default.existsSync(LEGACY_DB_PATH)) {
+            (0, debug_logger_js_1.info)('[sqlite-adapter] Found legacy database at ~/.spinelift/memories.db, using it for backward compatibility');
+            return LEGACY_DB_PATH;
+        }
+        return targetPath;
+    }
+    /**
+     * Connect to SQLite database
+     */
+    connect() {
+        if (this.db) {
+            return this.db;
+        }
+        const dbPath = this.getDbPath();
+        const dbDir = path_1.default.dirname(dbPath);
+        // Ensure directory exists
+        if (!fs_1.default.existsSync(dbDir)) {
+            fs_1.default.mkdirSync(dbDir, { recursive: true });
+            (0, debug_logger_js_1.info)(`[sqlite-adapter] Created database directory: ${dbDir}`);
+        }
+        // Open database
+        this.db = new better_sqlite3_1.default(dbPath, { verbose: undefined });
+        (0, debug_logger_js_1.info)(`[sqlite-adapter] Opened database at: ${dbPath}`);
+        // Production configuration
+        this.db.pragma('journal_mode = WAL');
+        this.db.pragma('busy_timeout = 5000');
+        this.db.pragma('synchronous = NORMAL');
+        this.db.pragma('cache_size = -64000'); // 64MB cache
+        this.db.pragma('temp_store = MEMORY');
+        this.db.pragma('foreign_keys = ON');
+        // Load sqlite-vec extension (graceful degradation if unavailable)
+        if (sqliteVec) {
+            try {
+                sqliteVec.load(this.db);
+                this._vectorSearchEnabled = true;
+                (0, debug_logger_js_1.info)('[sqlite-adapter] Loaded sqlite-vec extension');
+            }
+            catch (err) {
+                this._vectorSearchEnabled = false;
+                const message = err instanceof Error ? err.message : String(err);
+                (0, debug_logger_js_1.warn)(`[sqlite-adapter] sqlite-vec unavailable (Tier 2 fallback): ${message}`);
+            }
+        }
+        else {
+            this._vectorSearchEnabled = false;
+            (0, debug_logger_js_1.warn)('[sqlite-adapter] sqlite-vec package not installed; vector search disabled');
+        }
+        return this.db;
+    }
+    /**
+     * Disconnect from database
+     */
+    disconnect() {
+        if (this.db) {
+            this.db.close();
+            this.db = null;
+            (0, debug_logger_js_1.info)('[sqlite-adapter] Disconnected from database');
+        }
+    }
+    /**
+     * Check if connected
+     */
+    isConnected() {
+        return this.db !== null && this.db.open;
+    }
+    /**
+     * Prepare a SQL statement
+     */
+    prepare(sql) {
+        if (!this.isConnected() || !this.db) {
+            throw new Error('Database not connected');
+        }
+        const stmt = this.db.prepare(sql);
+        return new statement_js_1.SQLiteStatement(stmt);
+    }
+    /**
+     * Execute raw SQL
+     */
+    exec(sql) {
+        if (!this.isConnected() || !this.db) {
+            throw new Error('Database not connected');
+        }
+        this.db.exec(sql);
+    }
+    /**
+     * Execute function in transaction
+     */
+    transaction(fn) {
+        if (!this.isConnected() || !this.db) {
+            throw new Error('Database not connected');
+        }
+        const txn = this.db.transaction(fn);
+        return txn();
+    }
+    /**
+     * Vector similarity search using sqlite-vec (vec0 virtual table)
+     */
+    vectorSearch(embedding, limit = 5) {
+        if (!this.isConnected()) {
+            throw new Error('Database not connected');
+        }
+        if (!this._vectorSearchEnabled) {
+            return null;
+        }
+        const embeddingJson = JSON.stringify(Array.from(embedding));
+        const stmt = this.prepare(`
+      SELECT
+        rowid,
+        embedding,
+        distance
+      FROM vss_memories
+      WHERE embedding MATCH vec_f32(?)
+      LIMIT ?
+    `);
+        const queryVector = embedding instanceof Float32Array ? embedding : Float32Array.from(embedding);
+        const results = stmt.all(embeddingJson, Math.max(limit, 1));
+        return results
+            .map((row) => {
+            const candidate = bufferToVector(row.embedding);
+            if (!candidate) {
+                return null;
+            }
+            const similarity = (0, embeddings_js_1.cosineSimilarity)(candidate, queryVector);
+            return {
+                rowid: row.rowid,
+                similarity,
+                distance: 1 - similarity,
+            };
+        })
+            .filter((r) => r !== null);
+    }
+    /**
+     * Insert vector embedding
+     */
+    insertEmbedding(rowid, embedding) {
+        if (!this.isConnected()) {
+            throw new Error('Database not connected');
+        }
+        if (!this._vectorSearchEnabled) {
+            return null;
+        }
+        const embeddingJson = JSON.stringify(Array.from(embedding));
+        // CRITICAL FIX: sqlite-vec virtual tables accept rowid as literal but not via ? placeholder
+        // Using template literal with Number() cast for safety (prevents SQL injection)
+        const safeRowid = Number(rowid);
+        if (!Number.isInteger(safeRowid) || safeRowid < 1) {
+            throw new Error(`Invalid rowid: ${rowid}`);
+        }
+        const stmt = this.prepare(`
+      INSERT OR REPLACE INTO vss_memories(rowid, embedding)
+      VALUES (${safeRowid}, ?)
+    `);
+        return stmt.run(embeddingJson);
+    }
+    /**
+     * Get last inserted row ID
+     */
+    getLastInsertRowid() {
+        if (!this.isConnected() || !this.db) {
+            throw new Error('Database not connected');
+        }
+        // better-sqlite3 provides this via Database instance
+        const result = this.db.prepare('SELECT last_insert_rowid() as rowid').get();
+        return result.rowid;
+    }
+    /**
+     * Run migrations
+     */
+    runMigrations(migrationsDir) {
+        if (!this.isConnected()) {
+            throw new Error('Database not connected');
+        }
+        // Check if schema_version table exists
+        const tables = this.prepare(`
+      SELECT name FROM sqlite_master
+      WHERE type='table' AND name='schema_version'
+    `).all();
+        let currentVersion = 0;
+        if (tables.length > 0) {
+            const version = this.prepare('SELECT MAX(version) as version FROM schema_version').get();
+            currentVersion = version?.version || 0;
+        }
+        (0, debug_logger_js_1.info)(`[sqlite-adapter] Current schema version: ${currentVersion}`);
+        // Get all migration files
+        const migrationFiles = fs_1.default
+            .readdirSync(migrationsDir)
+            .filter((file) => file.endsWith('.sql'))
+            .sort();
+        // Apply migrations
+        for (const file of migrationFiles) {
+            const versionMatch = file.match(/^(\d+)-/);
+            if (!versionMatch) {
+                continue;
+            }
+            const version = parseInt(versionMatch[1], 10);
+            if (version <= currentVersion) {
+                continue;
+            }
+            const migrationPath = path_1.default.join(migrationsDir, file);
+            const migrationSQL = fs_1.default.readFileSync(migrationPath, 'utf8');
+            (0, debug_logger_js_1.info)(`[sqlite-adapter] Applying migration: ${file}`);
+            try {
+                this.exec('BEGIN TRANSACTION');
+                this.exec(migrationSQL);
+                this.exec('COMMIT');
+                // Record migration in schema_version table (outside transaction for idempotency)
+                this.prepare('INSERT OR IGNORE INTO schema_version (version) VALUES (?)').run(version);
+                (0, debug_logger_js_1.info)(`[sqlite-adapter] Migration ${file} applied successfully`);
+            }
+            catch (err) {
+                this.exec('ROLLBACK');
+                const message = err instanceof Error ? err.message : String(err);
+                // Handle duplicate column errors as idempotent (migration 003)
+                if (message.includes('duplicate column')) {
+                    (0, debug_logger_js_1.warn)(`[sqlite-adapter] Migration ${file} skipped (duplicate column - already applied)`);
+                    // Record migration as applied
+                    this.prepare('INSERT OR IGNORE INTO schema_version (version) VALUES (?)').run(version);
+                    continue;
+                }
+                if (message.includes('no such table')) {
+                    // Only skip if this migration contains an ALTER TABLE (adding column to optional table)
+                    // Note: migrationSQL may contain comments, so check if ALTER TABLE exists anywhere
+                    const hasAlterTable = migrationSQL.toUpperCase().includes('ALTER TABLE');
+                    if (!hasAlterTable) {
+                        (0, debug_logger_js_1.error)(`[sqlite-adapter] Migration ${file} failed (missing required table):`, err);
+                        throw new Error(`Migration ${file} failed: ${message}`);
+                    }
+                    (0, debug_logger_js_1.warn)(`[sqlite-adapter] Migration ${file} skipped: ALTER TABLE on non-existent table (${message})`);
+                    this.prepare('INSERT OR IGNORE INTO schema_version (version) VALUES (?)').run(version);
+                    continue;
+                }
+                (0, debug_logger_js_1.error)(`[sqlite-adapter] Migration ${file} failed:`, err);
+                throw new Error(`Migration ${file} failed: ${message}`);
+            }
+        }
+        // Create vss_memories table if not exists
+        if (this._vectorSearchEnabled) {
+            const vssTables = this.prepare(`
+        SELECT name FROM sqlite_master
+        WHERE type='table' AND name='vss_memories'
+      `).all();
+            if (vssTables.length === 0) {
+                (0, debug_logger_js_1.info)('[sqlite-adapter] Creating vss_memories virtual table via sqlite-vec');
+                this.exec(`
+          CREATE VIRTUAL TABLE vss_memories USING vec0(
+            embedding float[384]
+          )
+        `);
+            }
+        }
+        else {
+            (0, debug_logger_js_1.warn)('[sqlite-adapter] Skipping vss_memories creation (sqlite-vec unavailable)');
+        }
+    }
+}
+exports.SQLiteAdapter = SQLiteAdapter;
+exports.default = SQLiteAdapter;
+function bufferToVector(buffer) {
+    if (!buffer) {
+        return null;
+    }
+    const arrayBuffer = buffer.buffer.slice(buffer.byteOffset, buffer.byteOffset + buffer.byteLength);
+    return new Float32Array(arrayBuffer);
+}
+//# sourceMappingURL=sqlite-adapter.js.map

package/dist/db-adapter/statement.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Unified Statement Interface
+ *
+ * Wraps database-specific prepared statements to provide consistent API
+ * Compatible with better-sqlite3 and pg
+ *
+ * @module statement
+ */
+/**
+ * Run result from statement execution
+ */
+export interface RunResult {
+    changes: number;
+    lastInsertRowid: number | bigint;
+}
+/**
+ * Prepared statement interface
+ * Common interface used across all database modules
+ */
+export interface PreparedStatement {
+    run: (...args: unknown[]) => RunResult;
+    get: (...args: unknown[]) => unknown;
+    all: (...args: unknown[]) => unknown[];
+}
+/**
+ * better-sqlite3 native statement type
+ */
+interface BetterSQLiteStatement {
+    all: (...params: unknown[]) => unknown[];
+    get: (...params: unknown[]) => unknown;
+    run: (...params: unknown[]) => {
+        changes: number;
+        lastInsertRowid: number | bigint;
+    };
+}
+/**
+ * pg client type
+ */
+interface PgClient {
+    query: (sql: string, params: unknown[]) => Promise<{
+        rows: unknown[];
+        rowCount: number | null;
+    }>;
+}
+/**
+ * Base statement interface
+ * All statement wrappers must implement these methods
+ */
+export declare abstract class Statement {
+    /**
+     * Execute statement and return all rows
+     * @param params - Query parameters
+     * @returns All matching rows
+     */
+    abstract all(...params: unknown[]): object[];
+    /**
+     * Execute statement and return first row
+     * @param params - Query parameters
+     * @returns First matching row or undefined
+     */
+    abstract get(...params: unknown[]): object | undefined;
+    /**
+     * Execute statement without returning rows
+     * @param params - Query parameters
+     * @returns Execution info (changes, lastInsertRowid)
+     */
+    abstract run(...params: unknown[]): RunResult;
+    /**
+     * Release statement resources
+     */
+    finalize(): void;
+}
+/**
+ * SQLite statement wrapper (better-sqlite3)
+ */
+export declare class SQLiteStatement extends Statement {
+    private stmt;
+    constructor(stmt: BetterSQLiteStatement);
+    all(...params: unknown[]): object[];
+    get(...params: unknown[]): object | undefined;
+    run(...params: unknown[]): RunResult;
+    finalize(): void;
+}
+/**
+ * PostgreSQL statement wrapper (pg)
+ *
+ * Maps pg's async query interface to synchronous-like API
+ * Note: This requires careful handling in the adapter
+ */
+export declare class PostgreSQLStatement extends Statement {
+    private client;
+    private sql;
+    constructor(client: PgClient, sql: string);
+    /**
+     * Convert SQLite ? placeholders to PostgreSQL $1, $2, ...
+     * @param sql - SQL with ? placeholders
+     * @returns SQL with $N placeholders
+     *
+     * Note: This naive implementation replaces all '?' characters.
+     * It does not handle '?' inside SQL string literals or comments.
+     * For production use with complex SQL, consider a proper SQL parser.
+     */
+    static convertPlaceholders(sql: string): string;
+    all(..._params: unknown[]): object[];
+    get(..._params: unknown[]): object | undefined;
+    run(..._params: unknown[]): RunResult;
+    allAsync(...params: unknown[]): Promise<unknown[]>;
+    getAsync(...params: unknown[]): Promise<unknown>;
+    /**
+     * Execute statement asynchronously without returning rows
+     *
+     * Note: lastInsertRowid requires the SQL to include 'RETURNING id'.
+     * PostgreSQL does not have SQLite's last_insert_rowid() equivalent.
+     */
+    runAsync(...params: unknown[]): Promise<RunResult>;
+    finalize(): void;
+}
+export {};
+//# sourceMappingURL=statement.d.ts.map

package/dist/db-adapter/statement.js

@@ -0,0 +1,113 @@
+"use strict";
+/**
+ * Unified Statement Interface
+ *
+ * Wraps database-specific prepared statements to provide consistent API
+ * Compatible with better-sqlite3 and pg
+ *
+ * @module statement
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PostgreSQLStatement = exports.SQLiteStatement = exports.Statement = void 0;
+/**
+ * Base statement interface
+ * All statement wrappers must implement these methods
+ */
+class Statement {
+    /**
+     * Release statement resources
+     */
+    finalize() {
+        // Optional: Some drivers don't require cleanup
+    }
+}
+exports.Statement = Statement;
+/**
+ * SQLite statement wrapper (better-sqlite3)
+ */
+class SQLiteStatement extends Statement {
+    stmt;
+    constructor(stmt) {
+        super();
+        this.stmt = stmt;
+    }
+    all(...params) {
+        return this.stmt.all(...params);
+    }
+    get(...params) {
+        return this.stmt.get(...params);
+    }
+    run(...params) {
+        return this.stmt.run(...params);
+    }
+    finalize() {
+        // better-sqlite3 statements don't need explicit cleanup
+    }
+}
+exports.SQLiteStatement = SQLiteStatement;
+/**
+ * PostgreSQL statement wrapper (pg)
+ *
+ * Maps pg's async query interface to synchronous-like API
+ * Note: This requires careful handling in the adapter
+ */
+class PostgreSQLStatement extends Statement {
+    client;
+    sql;
+    constructor(client, sql) {
+        super();
+        this.client = client;
+        this.sql = sql;
+    }
+    /**
+     * Convert SQLite ? placeholders to PostgreSQL $1, $2, ...
+     * @param sql - SQL with ? placeholders
+     * @returns SQL with $N placeholders
+     *
+     * Note: This naive implementation replaces all '?' characters.
+     * It does not handle '?' inside SQL string literals or comments.
+     * For production use with complex SQL, consider a proper SQL parser.
+     */
+    static convertPlaceholders(sql) {
+        let index = 0;
+        return sql.replace(/\?/g, () => `$${++index}`);
+    }
+    // Note: PostgreSQL methods are async but the interface expects sync
+    // In practice, these would need to be wrapped or the adapter would handle async
+    all(..._params) {
+        // This is a simplified sync interface - actual pg usage would be async
+        throw new Error('PostgreSQLStatement requires async usage - use allAsync() instead');
+    }
+    get(..._params) {
+        throw new Error('PostgreSQLStatement requires async usage - use getAsync() instead');
+    }
+    run(..._params) {
+        throw new Error('PostgreSQLStatement requires async usage - use runAsync() instead');
+    }
+    async allAsync(...params) {
+        const result = await this.client.query(this.sql, params);
+        return result.rows;
+    }
+    async getAsync(...params) {
+        const result = await this.client.query(this.sql, params);
+        return result.rows[0];
+    }
+    /**
+     * Execute statement asynchronously without returning rows
+     *
+     * Note: lastInsertRowid requires the SQL to include 'RETURNING id'.
+     * PostgreSQL does not have SQLite's last_insert_rowid() equivalent.
+     */
+    async runAsync(...params) {
+        const result = await this.client.query(this.sql, params);
+        return {
+            changes: result.rowCount ?? 0,
+            lastInsertRowid: result.rows[0]?.id ?? 0,
+        };
+    }
+    finalize() {
+        // pg statements don't need explicit cleanup
+    }
+}
+exports.PostgreSQLStatement = PostgreSQLStatement;
+//# sourceMappingURL=statement.js.map