family-ai-agent 1.0.5 → 1.0.7

package/src/database/adapters/sqlite-adapter.ts

@@ -0,0 +1,420 @@
+/**
+ * SQLite Database Adapter
+ *
+ * Adapter for SQLite using better-sqlite3 for embedded database support.
+ * Provides zero-config database that works out of the box.
+ */
+
+import Database from 'better-sqlite3';
+import { drizzle } from 'drizzle-orm/better-sqlite3';
+import type { BetterSQLite3Database } from 'drizzle-orm/better-sqlite3';
+import { existsSync, mkdirSync } from 'fs';
+import { dirname } from 'path';
+
+import { BaseAdapter } from './base-adapter.js';
+import type {
+  QueryResult,
+  TransactionClient,
+  DatabaseConfig,
+} from '../types.js';
+import { createLogger } from '../../utils/logger.js';
+import { MemoryError } from '../../utils/errors.js';
+
+import * as schema from '../drizzle/schema/index.js';
+
+const logger = createLogger('SQLiteAdapter');
+
+/**
+ * SQLite database adapter with Drizzle ORM
+ */
+export class SQLiteAdapter extends BaseAdapter {
+  readonly type = 'sqlite' as const;
+
+  private db: Database.Database | null = null;
+  private drizzleInstance: BetterSQLite3Database<typeof schema> | null = null;
+  private dbPath: string;
+  private config: DatabaseConfig;
+
+  constructor(dbPath: string, config: DatabaseConfig) {
+    super();
+    this.dbPath = dbPath;
+    this.config = config;
+  }
+
+  /**
+   * Get Drizzle ORM instance
+   */
+  get drizzle(): BetterSQLite3Database<typeof schema> {
+    this.ensureInitialized();
+    return this.drizzleInstance!;
+  }
+
+  /**
+   * Get raw database (for advanced operations)
+   */
+  get rawDb(): Database.Database {
+    this.ensureInitialized();
+    return this.db!;
+  }
+
+  /**
+   * Initialize SQLite database
+   */
+  async initialize(): Promise<void> {
+    if (this._isInitialized) return;
+
+    try {
+      // Ensure directory exists
+      const dir = dirname(this.dbPath);
+      if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+        logger.debug('Created database directory', { path: dir });
+      }
+
+      // Open database
+      this.db = new Database(this.dbPath);
+
+      // Configure for better performance
+      this.db.pragma('journal_mode = WAL');
+      this.db.pragma('synchronous = NORMAL');
+      this.db.pragma('cache_size = -64000'); // 64MB cache
+      this.db.pragma('foreign_keys = ON');
+      this.db.pragma('temp_store = MEMORY');
+
+      // Create Drizzle instance
+      this.drizzleInstance = drizzle(this.db, {
+        schema,
+        logger: process.env.NODE_ENV === 'development',
+      });
+
+      // Initialize schema
+      await this.initializeSchema();
+
+      this._isInitialized = true;
+      logger.info('SQLite adapter initialized', { path: this.dbPath });
+    } catch (error) {
+      const message = error instanceof Error ? error.message : 'Unknown error';
+      logger.error('Failed to initialize SQLite', { error: message });
+      throw new MemoryError(`SQLite initialization failed: ${message}`);
+    }
+  }
+
+  /**
+   * Initialize database schema
+   */
+  private async initializeSchema(): Promise<void> {
+    const statements = [
+      // Conversations
+      `CREATE TABLE IF NOT EXISTS conversations (
+        id TEXT PRIMARY KEY,
+        thread_id TEXT NOT NULL,
+        user_id TEXT,
+        created_at INTEGER NOT NULL,
+        updated_at INTEGER NOT NULL
+      )`,
+      `CREATE INDEX IF NOT EXISTS idx_conversations_thread ON conversations(thread_id)`,
+      `CREATE INDEX IF NOT EXISTS idx_conversations_user ON conversations(user_id)`,
+
+      // Messages
+      `CREATE TABLE IF NOT EXISTS messages (
+        id TEXT PRIMARY KEY,
+        conversation_id TEXT NOT NULL REFERENCES conversations(id) ON DELETE CASCADE,
+        role TEXT NOT NULL,
+        content TEXT NOT NULL,
+        metadata TEXT NOT NULL DEFAULT '{}',
+        created_at INTEGER NOT NULL
+      )`,
+      `CREATE INDEX IF NOT EXISTS idx_messages_conversation ON messages(conversation_id)`,
+
+      // Long-term memories
+      `CREATE TABLE IF NOT EXISTS long_term_memories (
+        id TEXT PRIMARY KEY,
+        user_id TEXT,
+        memory_type TEXT NOT NULL,
+        content TEXT NOT NULL,
+        embedding TEXT NOT NULL,
+        importance REAL NOT NULL DEFAULT 0.5,
+        access_count INTEGER NOT NULL DEFAULT 0,
+        last_accessed INTEGER,
+        metadata TEXT NOT NULL DEFAULT '{}',
+        created_at INTEGER NOT NULL,
+        updated_at INTEGER NOT NULL
+      )`,
+      `CREATE INDEX IF NOT EXISTS idx_memories_user ON long_term_memories(user_id)`,
+      `CREATE INDEX IF NOT EXISTS idx_memories_type ON long_term_memories(memory_type)`,
+
+      // Documents
+      `CREATE TABLE IF NOT EXISTS documents (
+        id TEXT PRIMARY KEY,
+        user_id TEXT,
+        filename TEXT NOT NULL,
+        file_type TEXT,
+        file_size INTEGER,
+        content TEXT,
+        metadata TEXT NOT NULL DEFAULT '{}',
+        created_at INTEGER NOT NULL
+      )`,
+      `CREATE INDEX IF NOT EXISTS idx_documents_user ON documents(user_id)`,
+
+      // Document chunks
+      `CREATE TABLE IF NOT EXISTS document_chunks (
+        id TEXT PRIMARY KEY,
+        document_id TEXT NOT NULL REFERENCES documents(id) ON DELETE CASCADE,
+        chunk_index INTEGER NOT NULL,
+        content TEXT NOT NULL,
+        embedding TEXT NOT NULL,
+        metadata TEXT NOT NULL DEFAULT '{}',
+        created_at INTEGER NOT NULL
+      )`,
+      `CREATE INDEX IF NOT EXISTS idx_chunks_document ON document_chunks(document_id)`,
+
+      // Checkpoints
+      `CREATE TABLE IF NOT EXISTS checkpoints (
+        thread_id TEXT NOT NULL,
+        checkpoint_ns TEXT NOT NULL DEFAULT '',
+        checkpoint_id TEXT NOT NULL,
+        parent_checkpoint_id TEXT,
+        type TEXT,
+        checkpoint TEXT NOT NULL,
+        metadata TEXT NOT NULL DEFAULT '{}',
+        created_at INTEGER NOT NULL,
+        PRIMARY KEY (thread_id, checkpoint_ns, checkpoint_id)
+      )`,
+
+      // Checkpoint writes
+      `CREATE TABLE IF NOT EXISTS checkpoint_writes (
+        thread_id TEXT NOT NULL,
+        checkpoint_ns TEXT NOT NULL DEFAULT '',
+        checkpoint_id TEXT NOT NULL,
+        task_id TEXT NOT NULL,
+        idx INTEGER NOT NULL,
+        channel TEXT NOT NULL,
+        type TEXT,
+        value TEXT,
+        created_at INTEGER NOT NULL,
+        PRIMARY KEY (thread_id, checkpoint_ns, checkpoint_id, task_id, idx)
+      )`,
+
+      // Audit logs
+      `CREATE TABLE IF NOT EXISTS audit_logs (
+        id TEXT PRIMARY KEY,
+        user_id TEXT,
+        agent_id TEXT,
+        action_type TEXT NOT NULL,
+        action_details TEXT NOT NULL DEFAULT '{}',
+        input_hash TEXT,
+        output_hash TEXT,
+        status TEXT NOT NULL DEFAULT 'success',
+        error_message TEXT,
+        execution_time_ms INTEGER,
+        ip_address TEXT,
+        user_agent TEXT,
+        success INTEGER NOT NULL DEFAULT 1,
+        created_at INTEGER NOT NULL
+      )`,
+      `CREATE INDEX IF NOT EXISTS idx_audit_user ON audit_logs(user_id)`,
+      `CREATE INDEX IF NOT EXISTS idx_audit_action ON audit_logs(action_type)`,
+      `CREATE INDEX IF NOT EXISTS idx_audit_created ON audit_logs(created_at)`,
+
+      // Tasks
+      `CREATE TABLE IF NOT EXISTS tasks (
+        id TEXT PRIMARY KEY,
+        user_id TEXT,
+        task_type TEXT NOT NULL,
+        priority INTEGER NOT NULL DEFAULT 0,
+        status TEXT NOT NULL DEFAULT 'pending',
+        payload TEXT NOT NULL DEFAULT '{}',
+        result TEXT,
+        error_message TEXT,
+        scheduled_at INTEGER,
+        started_at INTEGER,
+        completed_at INTEGER,
+        retry_count INTEGER NOT NULL DEFAULT 0,
+        max_retries INTEGER NOT NULL DEFAULT 3,
+        created_at INTEGER NOT NULL,
+        updated_at INTEGER NOT NULL
+      )`,
+      `CREATE INDEX IF NOT EXISTS idx_tasks_user ON tasks(user_id)`,
+      `CREATE INDEX IF NOT EXISTS idx_tasks_status ON tasks(status)`,
+
+      // Schema version tracking
+      `CREATE TABLE IF NOT EXISTS schema_versions (
+        version INTEGER PRIMARY KEY,
+        name TEXT NOT NULL,
+        applied_at INTEGER NOT NULL,
+        checksum TEXT
+      )`,
+    ];
+
+    for (const statement of statements) {
+      try {
+        this.db!.exec(statement);
+      } catch (error) {
+        // Ignore errors for existing objects
+        const message = error instanceof Error ? error.message : '';
+        if (!message.includes('already exists')) {
+          throw error;
+        }
+      }
+    }
+
+    logger.debug('SQLite schema initialized');
+  }
+
+  /**
+   * Execute a raw SQL query
+   */
+  async query<T extends Record<string, any> = Record<string, any>>(
+    sqlText: string,
+    params?: unknown[]
+  ): Promise<QueryResult<T>> {
+    this.ensureInitialized();
+    const start = Date.now();
+
+    try {
+      // Convert PostgreSQL placeholders to SQLite
+      const sqliteSql = this.convertToSqlite(sqlText);
+      const sqliteParams = params ?? [];
+
+      const isSelect = this.isSelectQuery(sqlText);
+      const hasReturning = this.hasReturning(sqlText);
+
+      let rows: T[] = [];
+      let rowCount: number | null = 0;
+
+      if (isSelect) {
+        const stmt = this.db!.prepare(sqliteSql);
+        rows = stmt.all(...sqliteParams) as T[];
+        rowCount = rows.length;
+      } else if (hasReturning) {
+        // Handle INSERT/UPDATE/DELETE with RETURNING
+        const returning = this.extractReturning(sqlText);
+        const tableName = this.extractTableName(sqlText);
+
+        // Remove RETURNING clause for SQLite
+        const sqlWithoutReturning = sqliteSql.replace(/\s+RETURNING\s+.+$/i, '');
+        const stmt = this.db!.prepare(sqlWithoutReturning);
+        const info = stmt.run(...sqliteParams);
+        rowCount = info.changes;
+
+        if (returning && tableName && info.lastInsertRowid) {
+          // Fetch the inserted/updated row
+          const selectStmt = this.db!.prepare(
+            `SELECT ${returning} FROM ${tableName} WHERE rowid = ?`
+          );
+          const row = selectStmt.get(info.lastInsertRowid);
+          if (row) {
+            rows = [row as T];
+          }
+        }
+      } else {
+        const stmt = this.db!.prepare(sqliteSql);
+        const info = stmt.run(...sqliteParams);
+        rowCount = info.changes;
+      }
+
+      const duration = Date.now() - start;
+      this.logQuery(sqlText, duration, rowCount);
+
+      return { rows, rowCount };
+    } catch (error) {
+      this.logError(sqlText, error);
+      const message = error instanceof Error ? error.message : 'Unknown error';
+      throw new MemoryError(`Query failed: ${message}`);
+    }
+  }
+
+  /**
+   * Execute a transaction
+   */
+  async transaction<T>(
+    callback: (client: TransactionClient) => Promise<T>
+  ): Promise<T> {
+    this.ensureInitialized();
+
+    const transactionClient: TransactionClient = {
+      query: async <R extends Record<string, any> = Record<string, any>>(
+        sqlText: string,
+        params?: unknown[]
+      ): Promise<QueryResult<R>> => {
+        return this.query<R>(sqlText, params);
+      },
+    };
+
+    try {
+      this.db!.exec('BEGIN');
+      const result = await callback(transactionClient);
+      this.db!.exec('COMMIT');
+      return result;
+    } catch (error) {
+      this.db!.exec('ROLLBACK');
+      throw error;
+    }
+  }
+
+  /**
+   * Check database health
+   */
+  async healthCheck(): Promise<boolean> {
+    try {
+      const result = await this.query<{ ok: number }>('SELECT 1 as ok');
+      return result.rows.length > 0 && result.rows[0]!.ok === 1;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Close database connection
+   */
+  async close(): Promise<void> {
+    if (this.db) {
+      this.db.close();
+      this.db = null;
+      this.drizzleInstance = null;
+      this._isInitialized = false;
+      logger.info('SQLite database closed');
+    }
+  }
+
+  /**
+   * Get database file path
+   */
+  getPath(): string {
+    return this.dbPath;
+  }
+
+  /**
+   * Get database file size in bytes
+   */
+  getFileSize(): number {
+    if (!this.db) return 0;
+    try {
+      const stats = this.db.pragma('page_count') as Array<{ page_count: number }>;
+      const pageSize = this.db.pragma('page_size') as Array<{ page_size: number }>;
+      return (stats[0]?.page_count ?? 0) * (pageSize[0]?.page_size ?? 4096);
+    } catch {
+      return 0;
+    }
+  }
+
+  /**
+   * Vacuum database to reclaim space
+   */
+  vacuum(): void {
+    this.ensureInitialized();
+    this.db!.exec('VACUUM');
+    logger.debug('Database vacuumed');
+  }
+
+  /**
+   * Checkpoint WAL to main database
+   */
+  checkpoint(): void {
+    this.ensureInitialized();
+    this.db!.pragma('wal_checkpoint(TRUNCATE)');
+    logger.debug('WAL checkpoint completed');
+  }
+}
+
+export default SQLiteAdapter;

package/src/database/cache/cache-keys.ts

@@ -0,0 +1,150 @@
+/**
+ * Cache Key Generation
+ *
+ * Utilities for generating consistent cache keys.
+ */
+
+/**
+ * Generate a cache key from operation, table, and parameters
+ */
+export function generateCacheKey(
+  operation: string,
+  table: string,
+  params: Record<string, unknown>
+): string {
+  const sortedParams = Object.keys(params)
+    .sort()
+    .map((key) => `${key}:${JSON.stringify(params[key])}`)
+    .join('|');
+
+  return `${operation}:${table}:${sortedParams}`;
+}
+
+/**
+ * Cache key generators for common operations
+ */
+export const cacheKeys = {
+  /**
+   * Get conversation by thread ID
+   */
+  conversation: (threadId: string): string =>
+    generateCacheKey('get', 'conversations', { threadId }),
+
+  /**
+   * Get conversation by ID
+   */
+  conversationById: (id: string): string =>
+    generateCacheKey('get', 'conversations', { id }),
+
+  /**
+   * List messages for a conversation
+   */
+  messages: (conversationId: string, limit: number, offset: number): string =>
+    generateCacheKey('list', 'messages', { conversationId, limit, offset }),
+
+  /**
+   * Get document by ID
+   */
+  document: (id: string): string =>
+    generateCacheKey('get', 'documents', { id }),
+
+  /**
+   * List documents for a user
+   */
+  userDocuments: (userId: string, limit: number, offset: number): string =>
+    generateCacheKey('list', 'documents', { userId, limit, offset }),
+
+  /**
+   * Get memory by ID
+   */
+  memory: (id: string): string =>
+    generateCacheKey('get', 'long_term_memories', { id }),
+
+  /**
+   * List recent memories for a user
+   */
+  userMemories: (userId: string, limit: number): string =>
+    generateCacheKey('list', 'long_term_memories', { userId, limit }),
+
+  /**
+   * Vector search results
+   */
+  vectorSearch: (
+    embeddingHash: string,
+    options: Record<string, unknown>
+  ): string =>
+    generateCacheKey('search', 'embeddings', { hash: embeddingHash, ...options }),
+
+  /**
+   * Task by ID
+   */
+  task: (id: string): string =>
+    generateCacheKey('get', 'tasks', { id }),
+
+  /**
+   * List tasks for a user
+   */
+  userTasks: (userId: string, status: string, limit: number): string =>
+    generateCacheKey('list', 'tasks', { userId, status, limit }),
+};
+
+/**
+ * Invalidation patterns for write operations
+ */
+export const invalidationPatterns = {
+  /**
+   * Invalidate all conversation-related cache
+   */
+  conversation: (conversationId: string): RegExp =>
+    new RegExp(`conversations.*${conversationId}`),
+
+  /**
+   * Invalidate all message-related cache for a conversation
+   */
+  messages: (conversationId: string): RegExp =>
+    new RegExp(`messages.*${conversationId}`),
+
+  /**
+   * Invalidate all document-related cache
+   */
+  document: (documentId: string): RegExp =>
+    new RegExp(`documents.*${documentId}`),
+
+  /**
+   * Invalidate user's document list
+   */
+  userDocuments: (userId: string): string => `list:documents:userId:"${userId}"`,
+
+  /**
+   * Invalidate all memory-related cache
+   */
+  memory: (memoryId: string): RegExp =>
+    new RegExp(`long_term_memories.*${memoryId}`),
+
+  /**
+   * Invalidate user's memory list
+   */
+  userMemories: (userId: string): string =>
+    `list:long_term_memories:userId:"${userId}"`,
+
+  /**
+   * Invalidate all vector search results
+   */
+  vectorSearchAll: (): string => 'search:embeddings',
+
+  /**
+   * Invalidate all task-related cache
+   */
+  task: (taskId: string): RegExp => new RegExp(`tasks.*${taskId}`),
+
+  /**
+   * Invalidate user's task list
+   */
+  userTasks: (userId: string): string => `list:tasks:userId:"${userId}"`,
+};
+
+export default {
+  generateCacheKey,
+  cacheKeys,
+  invalidationPatterns,
+};

package/src/database/cache/index.ts

@@ -0,0 +1,44 @@
+/**
+ * Cache Layer Exports
+ *
+ * Central export for query caching functionality.
+ */
+
+export { QueryCache } from './query-cache.js';
+export {
+  generateCacheKey,
+  cacheKeys,
+  invalidationPatterns,
+} from './cache-keys.js';
+
+import { QueryCache } from './query-cache.js';
+import type { QueryCacheOptions } from '../types.js';
+
+// Singleton cache instance
+let cacheInstance: QueryCache | null = null;
+
+/**
+ * Get the global query cache instance
+ */
+export function getQueryCache(options?: Partial<QueryCacheOptions>): QueryCache {
+  if (!cacheInstance) {
+    cacheInstance = new QueryCache(options);
+  }
+  return cacheInstance;
+}
+
+/**
+ * Reset the global cache instance
+ */
+export function resetQueryCache(): void {
+  if (cacheInstance) {
+    cacheInstance.clear();
+    cacheInstance = null;
+  }
+}
+
+export default {
+  QueryCache,
+  getQueryCache,
+  resetQueryCache,
+};