@vinaes/succ 1.3.19

package/dist/lib/storage/backends/postgresql.js

@@ -0,0 +1,2528 @@
+/**
+ * PostgreSQL storage backend implementation.
+ *
+ * Uses pg (node-postgres) for connections and pgvector extension for vector similarity search.
+ *
+ * Schema mirrors SQLite structure with PostgreSQL-specific adaptations:
+ * - SERIAL instead of AUTOINCREMENT
+ * - BYTEA instead of BLOB
+ * - vector(N) type from pgvector extension
+ * - ON CONFLICT instead of INSERT OR REPLACE
+ */
+import { StorageError, ConfigError } from '../../errors.js';
+// Lazy-load pg to make it optional
+let pg = null;
+async function loadPg() {
+    if (pg)
+        return pg;
+    try {
+        pg = await import('pg');
+        return pg;
+    }
+    catch {
+        throw new ConfigError('PostgreSQL support requires the "pg" package. ' + 'Install it with: npm install pg');
+    }
+}
+/**
+ * Convert number[] embedding to pgvector format string: '[1.0, 2.0, 3.0]'
+ */
+function toPgVector(embedding) {
+    return '[' + embedding.join(',') + ']';
+}
+/**
+ * Parse pgvector string back to number[]
+ */
+function fromPgVector(str) {
+    // pgvector returns string like '[1.0, 2.0, 3.0]'
+    const inner = str.slice(1, -1);
+    if (!inner)
+        return [];
+    return inner.split(',').map((s) => parseFloat(s.trim()));
+}
+export class PostgresBackend {
+    pool = null;
+    config;
+    initialized = false;
+    projectId = null;
+    constructor(config, projectId) {
+        this.config = config;
+        this.projectId = projectId?.toLowerCase() ?? null;
+    }
+    /**
+     * Set the current project ID for scoping memories.
+     * NULL = global memories (shared across all projects)
+     * Always normalized to lowercase for case-insensitive path matching (Windows).
+     */
+    setProjectId(projectId) {
+        this.projectId = projectId?.toLowerCase() ?? null;
+    }
+    getProjectId() {
+        return this.projectId;
+    }
+    /**
+     * Get or create the connection pool.
+     */
+    async getPool() {
+        if (this.pool)
+            return this.pool;
+        const { Pool } = await loadPg();
+        const poolConfig = {
+            max: this.config.poolSize ?? 10,
+        };
+        if (this.config.connectionString) {
+            poolConfig.connectionString = this.config.connectionString;
+        }
+        else {
+            poolConfig.host = this.config.host ?? 'localhost';
+            poolConfig.port = this.config.port ?? 5432;
+            poolConfig.database = this.config.database ?? 'succ';
+            poolConfig.user = this.config.user;
+            poolConfig.password = this.config.password;
+        }
+        if (this.config.ssl) {
+            if (typeof this.config.ssl === 'object') {
+                poolConfig.ssl = {
+                    rejectUnauthorized: this.config.ssl.rejectUnauthorized ?? true,
+                    ca: this.config.ssl.ca,
+                };
+            }
+            else {
+                poolConfig.ssl = { rejectUnauthorized: true };
+            }
+        }
+        this.pool = new Pool(poolConfig);
+        if (!this.initialized) {
+            await this.initSchema();
+            this.initialized = true;
+        }
+        return this.pool;
+    }
+    /**
+     * Get the current embedding dimensions from config.
+     */
+    async getVectorDims() {
+        try {
+            const { getEmbeddingInfo } = await import('../../embeddings.js');
+            return getEmbeddingInfo().dimensions ?? 384;
+        }
+        catch {
+            return 384;
+        }
+    }
+    /**
+     * Initialize database schema.
+     */
+    async initSchema() {
+        const pool = await this.getPool();
+        const dims = await this.getVectorDims();
+        // Enable pgvector extension
+        await pool.query('CREATE EXTENSION IF NOT EXISTS vector');
+        // Migrate embedding column dimensions if they changed
+        for (const table of ['documents', 'memories', 'skills']) {
+            await pool.query(`
+        DO $$
+        DECLARE
+          current_dims INTEGER;
+        BEGIN
+          SELECT atttypmod INTO current_dims
+          FROM pg_attribute
+          WHERE attrelid = '${table}'::regclass
+            AND attname = 'embedding';
+          IF current_dims IS NOT NULL AND current_dims != ${dims} THEN
+            -- Drop IVFFlat index (incompatible across dimensions)
+            EXECUTE format('DROP INDEX IF EXISTS idx_%s_embedding', '${table}');
+            -- Clear old embeddings (incompatible dimensions)
+            EXECUTE format('UPDATE %I SET embedding = NULL', '${table}');
+            -- Alter column to new dimension
+            EXECUTE format('ALTER TABLE %I ALTER COLUMN embedding TYPE vector(%s)', '${table}', ${dims});
+          END IF;
+        EXCEPTION WHEN undefined_table THEN
+          NULL; -- Table doesn't exist yet, will be created below
+        END $$;
+      `);
+        }
+        // Documents table
+        // project_id: scopes documents to a specific project
+        await pool.query(`
+      CREATE TABLE IF NOT EXISTS documents (
+        id SERIAL PRIMARY KEY,
+        project_id TEXT NOT NULL,
+        file_path TEXT NOT NULL,
+        chunk_index INTEGER NOT NULL,
+        content TEXT NOT NULL,
+        start_line INTEGER NOT NULL,
+        end_line INTEGER NOT NULL,
+        embedding vector(${dims}),
+        symbol_name TEXT,
+        symbol_type TEXT,
+        signature TEXT,
+        created_at TIMESTAMPTZ DEFAULT NOW(),
+        updated_at TIMESTAMPTZ DEFAULT NOW(),
+        UNIQUE(project_id, file_path, chunk_index)
+      )
+    `);
+        // Migration: add project_id column if missing
+        await pool.query(`
+      DO $$
+      BEGIN
+        IF NOT EXISTS (
+          SELECT 1 FROM information_schema.columns
+          WHERE table_name = 'documents' AND column_name = 'project_id'
+        ) THEN
+          ALTER TABLE documents ADD COLUMN project_id TEXT;
+          -- Drop old unique constraint and add new one
+          ALTER TABLE documents DROP CONSTRAINT IF EXISTS documents_file_path_chunk_index_key;
+          ALTER TABLE documents ADD CONSTRAINT documents_project_file_chunk_key UNIQUE(project_id, file_path, chunk_index);
+        END IF;
+      END $$;
+    `);
+        // Migration: add symbol columns if missing
+        await pool.query(`
+      DO $$
+      BEGIN
+        IF NOT EXISTS (
+          SELECT 1 FROM information_schema.columns
+          WHERE table_name = 'documents' AND column_name = 'symbol_name'
+        ) THEN
+          ALTER TABLE documents ADD COLUMN symbol_name TEXT;
+          ALTER TABLE documents ADD COLUMN symbol_type TEXT;
+          ALTER TABLE documents ADD COLUMN signature TEXT;
+        END IF;
+      END $$;
+    `);
+        await pool.query('CREATE INDEX IF NOT EXISTS idx_documents_project_id ON documents(project_id)');
+        await pool.query('CREATE INDEX IF NOT EXISTS idx_documents_file_path ON documents(file_path)');
+        await pool.query('CREATE INDEX IF NOT EXISTS idx_documents_embedding ON documents USING ivfflat (embedding vector_cosine_ops) WITH (lists = 100)');
+        // Metadata table
+        await pool.query(`
+      CREATE TABLE IF NOT EXISTS metadata (
+        key TEXT PRIMARY KEY,
+        value TEXT NOT NULL
+      )
+    `);
+        // File hashes table
+        // project_id: scopes file hashes to a specific project
+        await pool.query(`
+      CREATE TABLE IF NOT EXISTS file_hashes (
+        project_id TEXT NOT NULL,
+        file_path TEXT NOT NULL,
+        content_hash TEXT NOT NULL,
+        indexed_at TIMESTAMPTZ DEFAULT NOW(),
+        PRIMARY KEY (project_id, file_path)
+      )
+    `);
+        // Migration: add project_id column if missing
+        await pool.query(`
+      DO $$
+      BEGIN
+        IF NOT EXISTS (
+          SELECT 1 FROM information_schema.columns
+          WHERE table_name = 'file_hashes' AND column_name = 'project_id'
+        ) THEN
+          -- Need to recreate table with new primary key
+          ALTER TABLE file_hashes ADD COLUMN project_id TEXT;
+          ALTER TABLE file_hashes DROP CONSTRAINT IF EXISTS file_hashes_pkey;
+          ALTER TABLE file_hashes ADD PRIMARY KEY (project_id, file_path);
+        END IF;
+      END $$;
+    `);
+        // Memories table
+        // project_id: NULL = global memory (shared across all projects)
+        //             non-NULL = project-specific memory
+        await pool.query(`
+      CREATE TABLE IF NOT EXISTS memories (
+        id SERIAL PRIMARY KEY,
+        project_id TEXT,
+        content TEXT NOT NULL,
+        tags JSONB,
+        source TEXT,
+        type TEXT DEFAULT 'observation',
+        quality_score REAL,
+        quality_factors JSONB,
+        embedding vector(${dims}),
+        access_count REAL DEFAULT 0,
+        last_accessed TIMESTAMPTZ,
+        valid_from TIMESTAMPTZ,
+        valid_until TIMESTAMPTZ,
+        created_at TIMESTAMPTZ DEFAULT NOW()
+      )
+    `);
+        // Add project_id column if it doesn't exist (migration for existing databases)
+        await pool.query(`
+      DO $$
+      BEGIN
+        IF NOT EXISTS (
+          SELECT 1 FROM information_schema.columns
+          WHERE table_name = 'memories' AND column_name = 'project_id'
+        ) THEN
+          ALTER TABLE memories ADD COLUMN project_id TEXT;
+        END IF;
+      END $$;
+    `);
+        await pool.query('CREATE INDEX IF NOT EXISTS idx_memories_created_at ON memories(created_at)');
+        await pool.query('CREATE INDEX IF NOT EXISTS idx_memories_quality ON memories(quality_score)');
+        await pool.query('CREATE INDEX IF NOT EXISTS idx_memories_type ON memories(type)');
+        await pool.query('CREATE INDEX IF NOT EXISTS idx_memories_project_id ON memories(project_id)');
+        await pool.query('CREATE INDEX IF NOT EXISTS idx_memories_embedding ON memories USING ivfflat (embedding vector_cosine_ops) WITH (lists = 100)');
+        // Memory links table
+        await pool.query(`
+      CREATE TABLE IF NOT EXISTS memory_links (
+        id SERIAL PRIMARY KEY,
+        source_id INTEGER NOT NULL REFERENCES memories(id) ON DELETE CASCADE,
+        target_id INTEGER NOT NULL REFERENCES memories(id) ON DELETE CASCADE,
+        relation TEXT NOT NULL DEFAULT 'related',
+        weight REAL DEFAULT 1.0,
+        valid_from TIMESTAMPTZ,
+        valid_until TIMESTAMPTZ,
+        created_at TIMESTAMPTZ DEFAULT NOW(),
+        UNIQUE(source_id, target_id, relation)
+      )
+    `);
+        await pool.query('CREATE INDEX IF NOT EXISTS idx_memory_links_source ON memory_links(source_id)');
+        await pool.query('CREATE INDEX IF NOT EXISTS idx_memory_links_target ON memory_links(target_id)');
+        // Migration: add llm_enriched column to memory_links
+        await pool.query('ALTER TABLE memory_links ADD COLUMN IF NOT EXISTS llm_enriched INTEGER DEFAULT 0');
+        // Migration: add project_id column to memory_links (for multi-project PG)
+        await pool.query(`
+      DO $$
+      BEGIN
+        IF NOT EXISTS (
+          SELECT 1 FROM information_schema.columns
+          WHERE table_name = 'memory_links' AND column_name = 'project_id'
+        ) THEN
+          ALTER TABLE memory_links ADD COLUMN project_id TEXT;
+        END IF;
+      END $$;
+    `);
+        await pool.query('CREATE INDEX IF NOT EXISTS idx_memory_links_project_id ON memory_links(project_id)');
+        // Memory centrality cache table
+        await pool.query(`
+      CREATE TABLE IF NOT EXISTS memory_centrality (
+        memory_id INTEGER PRIMARY KEY REFERENCES memories(id) ON DELETE CASCADE,
+        degree REAL DEFAULT 0,
+        normalized_degree REAL DEFAULT 0,
+        updated_at TIMESTAMPTZ DEFAULT NOW()
+      )
+    `);
+        // Token frequencies table
+        await pool.query(`
+      CREATE TABLE IF NOT EXISTS token_frequencies (
+        token TEXT PRIMARY KEY,
+        frequency INTEGER NOT NULL DEFAULT 1,
+        updated_at TIMESTAMPTZ DEFAULT NOW()
+      )
+    `);
+        await pool.query('CREATE INDEX IF NOT EXISTS idx_token_freq ON token_frequencies(frequency DESC)');
+        // Token stats table
+        // project_id: scopes stats to a specific project
+        await pool.query(`
+      CREATE TABLE IF NOT EXISTS token_stats (
+        id SERIAL PRIMARY KEY,
+        project_id TEXT,
+        event_type TEXT NOT NULL,
+        query TEXT,
+        returned_tokens INTEGER NOT NULL DEFAULT 0,
+        full_source_tokens INTEGER NOT NULL DEFAULT 0,
+        savings_tokens INTEGER NOT NULL DEFAULT 0,
+        files_count INTEGER,
+        chunks_count INTEGER,
+        model TEXT,
+        estimated_cost REAL DEFAULT 0,
+        created_at TIMESTAMPTZ DEFAULT NOW()
+      )
+    `);
+        // Migration: add project_id column if missing
+        await pool.query(`
+      DO $$
+      BEGIN
+        IF NOT EXISTS (
+          SELECT 1 FROM information_schema.columns
+          WHERE table_name = 'token_stats' AND column_name = 'project_id'
+        ) THEN
+          ALTER TABLE token_stats ADD COLUMN project_id TEXT;
+        END IF;
+      END $$;
+    `);
+        await pool.query('CREATE INDEX IF NOT EXISTS idx_token_stats_project_id ON token_stats(project_id)');
+        await pool.query('CREATE INDEX IF NOT EXISTS idx_token_stats_type ON token_stats(event_type)');
+        await pool.query('CREATE INDEX IF NOT EXISTS idx_token_stats_created ON token_stats(created_at)');
+        // Skills table
+        // project_id: scopes skills to a specific project (NULL for Skyll cached skills which are global)
+        await pool.query(`
+      CREATE TABLE IF NOT EXISTS skills (
+        id SERIAL PRIMARY KEY,
+        project_id TEXT,
+        name TEXT NOT NULL,
+        description TEXT NOT NULL,
+        source TEXT NOT NULL,
+        path TEXT,
+        content TEXT,
+        embedding vector(${dims}),
+        skyll_id TEXT,
+        usage_count INTEGER DEFAULT 0,
+        last_used TIMESTAMPTZ,
+        cached_at TIMESTAMPTZ,
+        cache_expires TIMESTAMPTZ,
+        created_at TIMESTAMPTZ DEFAULT NOW(),
+        updated_at TIMESTAMPTZ DEFAULT NOW(),
+        UNIQUE(project_id, name)
+      )
+    `);
+        // Migration: add project_id column if missing (for existing databases)
+        await pool.query(`
+      DO $$
+      BEGIN
+        IF NOT EXISTS (
+          SELECT 1 FROM information_schema.columns
+          WHERE table_name = 'skills' AND column_name = 'project_id'
+        ) THEN
+          -- Add project_id column
+          ALTER TABLE skills ADD COLUMN project_id TEXT;
+
+          -- Drop old unique constraint on name only
+          ALTER TABLE skills DROP CONSTRAINT IF EXISTS skills_name_key;
+
+          -- Add new unique constraint on (project_id, name)
+          ALTER TABLE skills ADD CONSTRAINT skills_project_name_unique UNIQUE(project_id, name);
+        END IF;
+      END $$;
+    `);
+        await pool.query('CREATE INDEX IF NOT EXISTS idx_skills_project_id ON skills(project_id)');
+        await pool.query('CREATE INDEX IF NOT EXISTS idx_skills_name ON skills(name)');
+        await pool.query('CREATE INDEX IF NOT EXISTS idx_skills_source ON skills(source)');
+        // Migration: add invalidated_by column for soft-delete during consolidation
+        await pool.query(`
+      DO $$
+      BEGIN
+        IF NOT EXISTS (
+          SELECT 1 FROM information_schema.columns
+          WHERE table_name = 'memories' AND column_name = 'invalidated_by'
+        ) THEN
+          ALTER TABLE memories ADD COLUMN invalidated_by INTEGER;
+        END IF;
+      END $$;
+    `);
+        await pool.query('CREATE INDEX IF NOT EXISTS idx_memories_invalidated_by ON memories(invalidated_by)');
+        // Migration: add correction_count and is_invariant for working memory pins
+        await pool.query(`
+      DO $$ BEGIN
+        IF NOT EXISTS (
+          SELECT 1 FROM information_schema.columns
+          WHERE table_name = 'memories' AND column_name = 'correction_count'
+        ) THEN
+          ALTER TABLE memories ADD COLUMN correction_count INTEGER DEFAULT 0;
+        END IF;
+        IF NOT EXISTS (
+          SELECT 1 FROM information_schema.columns
+          WHERE table_name = 'memories' AND column_name = 'is_invariant'
+        ) THEN
+          ALTER TABLE memories ADD COLUMN is_invariant INTEGER DEFAULT 0;
+        END IF;
+      END $$;
+    `);
+        await pool.query('CREATE INDEX IF NOT EXISTS idx_memories_pinned ON memories(correction_count, is_invariant)');
+        // Migration: add priority_score column for working memory ranking
+        await pool.query(`
+      DO $$ BEGIN
+        IF NOT EXISTS (
+          SELECT 1 FROM information_schema.columns
+          WHERE table_name = 'memories' AND column_name = 'priority_score'
+        ) THEN
+          ALTER TABLE memories ADD COLUMN priority_score REAL DEFAULT NULL;
+        END IF;
+      END $$;
+    `);
+        await pool.query('CREATE INDEX IF NOT EXISTS idx_memories_priority ON memories(priority_score DESC)');
+        // Learning deltas table for session progress tracking
+        await pool.query(`
+      CREATE TABLE IF NOT EXISTS learning_deltas (
+        id SERIAL PRIMARY KEY,
+        project_id TEXT,
+        timestamp TIMESTAMPTZ NOT NULL,
+        source TEXT NOT NULL,
+        memories_before INTEGER NOT NULL DEFAULT 0,
+        memories_after INTEGER NOT NULL DEFAULT 0,
+        new_memories INTEGER NOT NULL DEFAULT 0,
+        types_added JSONB,
+        avg_quality REAL,
+        created_at TIMESTAMPTZ DEFAULT NOW()
+      )
+    `);
+        await pool.query('CREATE INDEX IF NOT EXISTS idx_learning_deltas_timestamp ON learning_deltas(timestamp)');
+        await pool.query('CREATE INDEX IF NOT EXISTS idx_learning_deltas_source ON learning_deltas(source)');
+        await pool.query('CREATE INDEX IF NOT EXISTS idx_learning_deltas_project_id ON learning_deltas(project_id)');
+        // Web search history table
+        await pool.query(`
+      CREATE TABLE IF NOT EXISTS web_search_history (
+        id SERIAL PRIMARY KEY,
+        project_id TEXT,
+        tool_name TEXT NOT NULL,
+        model TEXT NOT NULL,
+        query TEXT NOT NULL,
+        prompt_tokens INTEGER NOT NULL DEFAULT 0,
+        completion_tokens INTEGER NOT NULL DEFAULT 0,
+        estimated_cost_usd REAL NOT NULL DEFAULT 0,
+        citations_count INTEGER NOT NULL DEFAULT 0,
+        has_reasoning BOOLEAN NOT NULL DEFAULT FALSE,
+        response_length_chars INTEGER NOT NULL DEFAULT 0,
+        created_at TIMESTAMPTZ DEFAULT NOW()
+      )
+    `);
+        await pool.query('CREATE INDEX IF NOT EXISTS idx_wsh_project_id ON web_search_history(project_id)');
+        await pool.query('CREATE INDEX IF NOT EXISTS idx_wsh_created ON web_search_history(created_at)');
+        await pool.query('CREATE INDEX IF NOT EXISTS idx_wsh_tool ON web_search_history(tool_name)');
+    }
+    /**
+     * Close all connections.
+     */
+    async close() {
+        if (this.pool) {
+            await this.pool.end();
+            this.pool = null;
+            this.initialized = false;
+        }
+    }
+    // ============================================================================
+    // Document Operations
+    // ============================================================================
+    async upsertDocument(filePath, chunkIndex, content, startLine, endLine, embedding, symbolName, symbolType, signature) {
+        if (!this.projectId) {
+            throw new StorageError('Project ID must be set before upserting documents');
+        }
+        const pool = await this.getPool();
+        const result = await pool.query(`INSERT INTO documents (project_id, file_path, chunk_index, content, start_line, end_line, embedding, symbol_name, symbol_type, signature, updated_at)
+       VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, NOW())
+       ON CONFLICT(project_id, file_path, chunk_index) DO UPDATE SET
+         content = EXCLUDED.content,
+         start_line = EXCLUDED.start_line,
+         end_line = EXCLUDED.end_line,
+         embedding = EXCLUDED.embedding,
+         symbol_name = EXCLUDED.symbol_name,
+         symbol_type = EXCLUDED.symbol_type,
+         signature = EXCLUDED.signature,
+         updated_at = NOW()
+       RETURNING id`, [
+            this.projectId,
+            filePath,
+            chunkIndex,
+            content,
+            startLine,
+            endLine,
+            toPgVector(embedding),
+            symbolName ?? null,
+            symbolType ?? null,
+            signature ?? null,
+        ]);
+        return result.rows[0].id;
+    }
+    async upsertDocumentsBatch(documents) {
+        if (documents.length === 0)
+            return [];
+        if (!this.projectId) {
+            throw new StorageError('Project ID must be set before upserting documents');
+        }
+        const pool = await this.getPool();
+        const client = await pool.connect();
+        const ids = [];
+        try {
+            await client.query('BEGIN');
+            for (const doc of documents) {
+                const result = await client.query(`INSERT INTO documents (project_id, file_path, chunk_index, content, start_line, end_line, embedding, symbol_name, symbol_type, signature, updated_at)
+           VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, NOW())
+           ON CONFLICT(project_id, file_path, chunk_index) DO UPDATE SET
+             content = EXCLUDED.content,
+             start_line = EXCLUDED.start_line,
+             end_line = EXCLUDED.end_line,
+             embedding = EXCLUDED.embedding,
+             symbol_name = EXCLUDED.symbol_name,
+             symbol_type = EXCLUDED.symbol_type,
+             signature = EXCLUDED.signature,
+             updated_at = NOW()
+           RETURNING id`, [
+                    this.projectId,
+                    doc.filePath,
+                    doc.chunkIndex,
+                    doc.content,
+                    doc.startLine,
+                    doc.endLine,
+                    toPgVector(doc.embedding),
+                    doc.symbolName ?? null,
+                    doc.symbolType ?? null,
+                    doc.signature ?? null,
+                ]);
+                ids.push(result.rows[0].id);
+            }
+            await client.query('COMMIT');
+        }
+        catch (e) {
+            await client.query('ROLLBACK');
+            throw e;
+        }
+        finally {
+            client.release();
+        }
+        return ids;
+    }
+    async upsertDocumentsBatchWithHashes(documents) {
+        if (documents.length === 0)
+            return [];
+        if (!this.projectId) {
+            throw new StorageError('Project ID must be set before upserting documents');
+        }
+        const pool = await this.getPool();
+        const client = await pool.connect();
+        const ids = [];
+        try {
+            await client.query('BEGIN');
+            const processedFiles = new Set();
+            for (const doc of documents) {
+                const result = await client.query(`INSERT INTO documents (project_id, file_path, chunk_index, content, start_line, end_line, embedding, symbol_name, symbol_type, signature, updated_at)
+           VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, NOW())
+           ON CONFLICT(project_id, file_path, chunk_index) DO UPDATE SET
+             content = EXCLUDED.content,
+             start_line = EXCLUDED.start_line,
+             end_line = EXCLUDED.end_line,
+             embedding = EXCLUDED.embedding,
+             symbol_name = EXCLUDED.symbol_name,
+             symbol_type = EXCLUDED.symbol_type,
+             signature = EXCLUDED.signature,
+             updated_at = NOW()
+           RETURNING id`, [
+                    this.projectId,
+                    doc.filePath,
+                    doc.chunkIndex,
+                    doc.content,
+                    doc.startLine,
+                    doc.endLine,
+                    toPgVector(doc.embedding),
+                    doc.symbolName ?? null,
+                    doc.symbolType ?? null,
+                    doc.signature ?? null,
+                ]);
+                ids.push(result.rows[0].id);
+                if (!processedFiles.has(doc.filePath)) {
+                    await client.query(`INSERT INTO file_hashes (project_id, file_path, content_hash, indexed_at)
+             VALUES ($1, $2, $3, NOW())
+             ON CONFLICT(project_id, file_path) DO UPDATE SET
+               content_hash = EXCLUDED.content_hash,
+               indexed_at = NOW()`, [this.projectId, doc.filePath, doc.hash]);
+                    processedFiles.add(doc.filePath);
+                }
+            }
+            await client.query('COMMIT');
+        }
+        catch (e) {
+            await client.query('ROLLBACK');
+            throw e;
+        }
+        finally {
+            client.release();
+        }
+        return ids;
+    }
+    async deleteDocumentsByPath(filePath) {
+        if (!this.projectId) {
+            throw new StorageError('Project ID must be set before deleting documents');
+        }
+        const pool = await this.getPool();
+        const result = await pool.query('DELETE FROM documents WHERE LOWER(project_id) = $1 AND file_path = $2 RETURNING id', [this.projectId, filePath]);
+        return result.rows.map((r) => r.id);
+    }
+    async searchDocuments(queryEmbedding, limit = 5, threshold = 0.5, options) {
+        if (!this.projectId) {
+            throw new StorageError('Project ID must be set before searching documents');
+        }
+        const pool = await this.getPool();
+        // pgvector cosine distance: <=> returns distance (0 = identical, 2 = opposite)
+        // similarity = 1 - distance/2 for normalized vectors
+        // For our use: similarity = 1 - distance (since cosine distance from pgvector is 1-cosine_similarity)
+        let whereExtra = '';
+        const params = [toPgVector(queryEmbedding), this.projectId, threshold, limit];
+        if (options?.codeOnly)
+            whereExtra = " AND file_path LIKE 'code:%'";
+        else if (options?.docsOnly)
+            whereExtra = " AND file_path NOT LIKE 'code:%'";
+        if (options?.symbolType) {
+            params.push(options.symbolType);
+            whereExtra += ` AND symbol_type = $${params.length}`;
+        }
+        const result = await pool.query(`SELECT file_path, content, start_line, end_line, symbol_name, symbol_type, signature,
+              1 - (embedding <=> $1) as similarity
+       FROM documents
+       WHERE LOWER(project_id) = $2 AND 1 - (embedding <=> $1) >= $3${whereExtra}
+       ORDER BY embedding <=> $1
+       LIMIT $4`, params);
+        return result.rows;
+    }
+    /**
+     * Batch fetch documents by IDs (for Qdrant search → PG metadata pattern).
+     * Optionally filter by code/doc type via file_path prefix.
+     */
+    async getDocumentsByIds(ids, options) {
+        if (ids.length === 0)
+            return [];
+        const pool = await this.getPool();
+        let query = `SELECT id, file_path, content, start_line, end_line FROM documents WHERE id = ANY($1)`;
+        const params = [ids];
+        if (options?.codeOnly) {
+            query += ` AND file_path LIKE 'code:%'`;
+        }
+        else if (options?.docsOnly) {
+            query += ` AND file_path NOT LIKE 'code:%'`;
+        }
+        const result = await pool.query(query, params);
+        return result.rows;
+    }
+    /**
+     * Batch fetch memories by IDs with optional SQL-level filters
+     * (for Qdrant search → PG metadata pattern).
+     */
+    async getMemoriesByIds(ids, filters) {
+        if (ids.length === 0)
+            return [];
+        const pool = await this.getPool();
+        let query = `
+      SELECT id, content, tags, source, type, quality_score, quality_factors,
+             access_count, last_accessed, valid_from, valid_until, created_at
+      FROM memories WHERE id = ANY($1)`;
+        const params = [ids];
+        let idx = 2;
+        // Soft-delete filter (default: exclude invalidated)
+        if (filters?.excludeInvalidated !== false) {
+            query += ` AND invalidated_by IS NULL`;
+        }
+        // Temporal validity
+        if (!filters?.includeExpired && filters?.temporalAsOf) {
+            const asOf = filters.temporalAsOf.toISOString();
+            query += ` AND (valid_from IS NULL OR valid_from <= $${idx})`;
+            params.push(asOf);
+            idx++;
+            query += ` AND (valid_until IS NULL OR valid_until > $${idx})`;
+            params.push(asOf);
+            idx++;
+        }
+        // Since filter
+        if (filters?.since) {
+            query += ` AND created_at >= $${idx}`;
+            params.push(filters.since.toISOString());
+            idx++;
+        }
+        // Created-before filter (for point-in-time queries)
+        if (filters?.createdBefore) {
+            query += ` AND created_at <= $${idx}`;
+            params.push(filters.createdBefore.toISOString());
+            idx++;
+        }
+        const result = await pool.query(query, params);
+        return result.rows.map((row) => ({
+            id: row.id,
+            content: row.content,
+            tags: row.tags ? (typeof row.tags === 'string' ? JSON.parse(row.tags) : row.tags) : [],
+            source: row.source,
+            type: row.type,
+            quality_score: row.quality_score,
+            quality_factors: row.quality_factors
+                ? typeof row.quality_factors === 'string'
+                    ? JSON.parse(row.quality_factors)
+                    : row.quality_factors
+                : null,
+            access_count: row.access_count ?? 0,
+            last_accessed: row.last_accessed,
+            correction_count: row.correction_count ?? 0,
+            is_invariant: !!row.is_invariant,
+            priority_score: row.priority_score ?? null,
+            valid_from: row.valid_from,
+            valid_until: row.valid_until,
+            created_at: row.created_at,
+        }));
+    }
+    async getDocumentStats() {
+        const pool = await this.getPool();
+        // If project_id is set, get stats for that project; otherwise get global stats
+        if (this.projectId) {
+            const totalDocs = await pool.query('SELECT COUNT(*) as count FROM documents WHERE LOWER(project_id) = $1', [this.projectId]);
+            const totalFiles = await pool.query('SELECT COUNT(DISTINCT file_path) as count FROM documents WHERE LOWER(project_id) = $1', [this.projectId]);
+            const lastIndexed = await pool.query('SELECT MAX(updated_at) as last FROM documents WHERE LOWER(project_id) = $1', [this.projectId]);
+            return {
+                total_documents: parseInt(totalDocs.rows[0].count),
+                total_files: parseInt(totalFiles.rows[0].count),
+                last_indexed: lastIndexed.rows[0].last,
+            };
+        }
+        // No project set = aggregate stats across all projects
+        const totalDocs = await pool.query('SELECT COUNT(*) as count FROM documents');
+        const totalFiles = await pool.query('SELECT COUNT(DISTINCT file_path) as count FROM documents');
+        const lastIndexed = await pool.query('SELECT MAX(updated_at) as last FROM documents');
+        return {
+            total_documents: parseInt(totalDocs.rows[0].count),
+            total_files: parseInt(totalFiles.rows[0].count),
+            last_indexed: lastIndexed.rows[0].last,
+        };
+    }
+    async clearDocuments() {
+        const pool = await this.getPool();
+        if (this.projectId) {
+            // Clear only current project's documents
+            await pool.query('DELETE FROM documents WHERE LOWER(project_id) = $1', [this.projectId]);
+            await pool.query('DELETE FROM file_hashes WHERE LOWER(project_id) = $1', [this.projectId]);
+        }
+        else {
+            // No project set = clear ALL documents (dangerous!)
+            await pool.query('DELETE FROM documents');
+            await pool.query('DELETE FROM file_hashes');
+        }
+        await pool.query("DELETE FROM metadata WHERE key = 'embedding_model'");
+    }
+    // ============================================================================
+    // File Hashes
+    // ============================================================================
+    async getFileHash(filePath) {
+        if (!this.projectId) {
+            throw new StorageError('Project ID must be set before getting file hash');
+        }
+        const pool = await this.getPool();
+        const result = await pool.query('SELECT content_hash FROM file_hashes WHERE LOWER(project_id) = $1 AND file_path = $2', [this.projectId, filePath]);
+        return result.rows[0]?.content_hash ?? null;
+    }
+    async setFileHash(filePath, hash) {
+        if (!this.projectId) {
+            throw new StorageError('Project ID must be set before setting file hash');
+        }
+        const pool = await this.getPool();
+        await pool.query(`INSERT INTO file_hashes (project_id, file_path, content_hash, indexed_at)
+       VALUES ($1, $2, $3, NOW())
+       ON CONFLICT(project_id, file_path) DO UPDATE SET
+         content_hash = EXCLUDED.content_hash,
+         indexed_at = NOW()`, [this.projectId, filePath, hash]);
+    }
+    async deleteFileHash(filePath) {
+        if (!this.projectId) {
+            throw new StorageError('Project ID must be set before deleting file hash');
+        }
+        const pool = await this.getPool();
+        await pool.query('DELETE FROM file_hashes WHERE LOWER(project_id) = $1 AND file_path = $2', [
+            this.projectId,
+            filePath,
+        ]);
+    }
+    async getAllFileHashes() {
+        if (!this.projectId) {
+            throw new StorageError('Project ID must be set before getting all file hashes');
+        }
+        const pool = await this.getPool();
+        const result = await pool.query('SELECT file_path, content_hash FROM file_hashes WHERE LOWER(project_id) = $1', [this.projectId]);
+        return new Map(result.rows.map((r) => [r.file_path, r.content_hash]));
+    }
+    async getAllFileHashesWithTimestamps() {
+        if (!this.projectId) {
+            throw new StorageError('Project ID must be set before getting file hashes');
+        }
+        const pool = await this.getPool();
+        const result = await pool.query('SELECT file_path, content_hash, indexed_at::text FROM file_hashes WHERE LOWER(project_id) = $1', [this.projectId]);
+        return result.rows;
+    }
+    // ============================================================================
+    // Memory Operations
+    // ============================================================================
+    async saveMemory(content, embedding, tags = [], source, type = 'observation', qualityScore, qualityFactors, validFrom, validUntil, isGlobal = false) {
+        const pool = await this.getPool();
+        const projectId = isGlobal ? null : this.projectId;
+        const result = await pool.query(`INSERT INTO memories (project_id, content, tags, source, type, quality_score, quality_factors, embedding, valid_from, valid_until)
+       VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10)
+       RETURNING id`, [
+            projectId,
+            content,
+            tags.length > 0 ? JSON.stringify(tags) : null,
+            source ?? null,
+            type,
+            qualityScore ?? null,
+            qualityFactors ? JSON.stringify(qualityFactors) : null,
+            toPgVector(embedding),
+            validFrom ?? null,
+            validUntil ?? null,
+        ]);
+        return result.rows[0].id;
+    }
+    async searchMemories(queryEmbedding, limit = 5, threshold = 0.3, tags, since, options) {
+        const pool = await this.getPool();
+        const now = options?.asOfDate ?? new Date();
+        const includeExpired = options?.includeExpired ?? false;
+        const includeGlobal = options?.includeGlobal ?? true;
+        let query = `
+      SELECT id, project_id, content, tags, source, type, quality_score, quality_factors,
+             access_count, last_accessed, valid_from, valid_until, created_at,
+             1 - (embedding <=> $1) as similarity
+      FROM memories
+      WHERE 1 - (embedding <=> $1) >= $2
+        AND invalidated_by IS NULL
+    `;
+        const params = [toPgVector(queryEmbedding), threshold];
+        let paramIndex = 3;
+        // Filter by project_id: include current project AND optionally global (NULL)
+        if (this.projectId) {
+            if (includeGlobal) {
+                query += ` AND (LOWER(project_id) = $${paramIndex} OR project_id IS NULL)`;
+            }
+            else {
+                query += ` AND LOWER(project_id) = $${paramIndex}`;
+            }
+            params.push(this.projectId);
+            paramIndex++;
+        }
+        else {
+            // No project set = only return global memories
+            query += ` AND project_id IS NULL`;
+        }
+        if (since) {
+            query += ` AND created_at >= $${paramIndex}`;
+            params.push(since.toISOString());
+            paramIndex++;
+        }
+        if (!includeExpired) {
+            query += ` AND (valid_from IS NULL OR valid_from <= $${paramIndex})`;
+            params.push(now.toISOString());
+            paramIndex++;
+            query += ` AND (valid_until IS NULL OR valid_until > $${paramIndex})`;
+            params.push(now.toISOString());
+            paramIndex++;
+        }
+        query += ` ORDER BY embedding <=> $1 LIMIT $${paramIndex}`;
+        params.push(limit);
+        const result = await pool.query(query, params);
+        let memories = result.rows.map((row) => ({
+            id: row.id,
+            content: row.content,
+            tags: row.tags ? (typeof row.tags === 'string' ? JSON.parse(row.tags) : row.tags) : [],
+            source: row.source,
+            type: row.type,
+            quality_score: row.quality_score,
+            quality_factors: row.quality_factors
+                ? typeof row.quality_factors === 'string'
+                    ? JSON.parse(row.quality_factors)
+                    : row.quality_factors
+                : null,
+            access_count: row.access_count ?? 0,
+            last_accessed: row.last_accessed,
+            correction_count: row.correction_count ?? 0,
+            is_invariant: !!row.is_invariant,
+            priority_score: row.priority_score ?? null,
+            valid_from: row.valid_from,
+            valid_until: row.valid_until,
+            created_at: row.created_at,
+            similarity: parseFloat(row.similarity),
+        }));
+        // Filter by tags if specified
+        if (tags && tags.length > 0) {
+            memories = memories.filter((m) => tags.some((t) => m.tags.some((rt) => rt.toLowerCase().includes(t.toLowerCase()))));
+        }
+        return memories;
+    }
+    async getMemoryById(id) {
+        const pool = await this.getPool();
+        const result = await pool.query(`SELECT id, content, tags, source, type, quality_score, quality_factors,
+              access_count, last_accessed, valid_from, valid_until,
+              correction_count, is_invariant, priority_score, created_at
+       FROM memories WHERE id = $1`, [id]);
+        if (result.rows.length === 0)
+            return null;
+        const row = result.rows[0];
+        return {
+            id: row.id,
+            content: row.content,
+            tags: row.tags ? (typeof row.tags === 'string' ? JSON.parse(row.tags) : row.tags) : [],
+            source: row.source,
+            type: row.type,
+            quality_score: row.quality_score,
+            quality_factors: row.quality_factors
+                ? typeof row.quality_factors === 'string'
+                    ? JSON.parse(row.quality_factors)
+                    : row.quality_factors
+                : null,
+            access_count: row.access_count ?? 0,
+            last_accessed: row.last_accessed,
+            correction_count: row.correction_count ?? 0,
+            is_invariant: !!row.is_invariant,
+            priority_score: row.priority_score ?? null,
+            valid_from: row.valid_from,
+            valid_until: row.valid_until,
+            created_at: row.created_at,
+        };
+    }
+    async deleteMemory(id) {
+        const pool = await this.getPool();
+        // Only delete memories belonging to current project or global memories
+        const result = await pool.query('DELETE FROM memories WHERE id = $1 AND (LOWER(project_id) = $2 OR project_id IS NULL)', [id, this.projectId]);
+        return (result.rowCount ?? 0) > 0;
+    }
+    /**
+     * Soft-invalidate a memory (mark as superseded by another memory).
+     */
+    async invalidateMemory(memoryId, supersededById) {
+        const pool = await this.getPool();
+        const result = await pool.query(`UPDATE memories
+       SET valid_until = NOW(), invalidated_by = $1
+       WHERE id = $2 AND invalidated_by IS NULL`, [supersededById, memoryId]);
+        return (result.rowCount ?? 0) > 0;
+    }
+    /**
+     * Restore a soft-invalidated memory.
+     */
+    async restoreInvalidatedMemory(memoryId) {
+        const pool = await this.getPool();
+        const result = await pool.query(`UPDATE memories
+       SET valid_until = NULL, invalidated_by = NULL
+       WHERE id = $1 AND invalidated_by IS NOT NULL`, [memoryId]);
+        return (result.rowCount ?? 0) > 0;
+    }
+    async getRecentMemories(limit = 10, includeGlobal = true) {
+        const pool = await this.getPool();
+        let query = `
+      SELECT id, project_id, content, tags, source, type, quality_score, quality_factors,
+             access_count, last_accessed, valid_from, valid_until,
+             correction_count, is_invariant, priority_score, created_at
+      FROM memories
+    `;
+        const params = [];
+        let paramIndex = 1;
+        // Filter by project_id and exclude soft-deleted
+        if (this.projectId) {
+            if (includeGlobal) {
+                query += ` WHERE (LOWER(project_id) = $${paramIndex} OR project_id IS NULL) AND invalidated_by IS NULL`;
+            }
+            else {
+                query += ` WHERE LOWER(project_id) = $${paramIndex} AND invalidated_by IS NULL`;
+            }
+            params.push(this.projectId);
+            paramIndex++;
+        }
+        else {
+            query += ` WHERE project_id IS NULL AND invalidated_by IS NULL`;
+        }
+        query += ` ORDER BY created_at DESC LIMIT $${paramIndex}`;
+        params.push(limit);
+        const result = await pool.query(query, params);
+        return result.rows.map((row) => ({
+            id: row.id,
+            content: row.content,
+            tags: row.tags ? (typeof row.tags === 'string' ? JSON.parse(row.tags) : row.tags) : [],
+            source: row.source,
+            type: row.type,
+            quality_score: row.quality_score,
+            quality_factors: row.quality_factors
+                ? typeof row.quality_factors === 'string'
+                    ? JSON.parse(row.quality_factors)
+                    : row.quality_factors
+                : null,
+            access_count: row.access_count ?? 0,
+            last_accessed: row.last_accessed,
+            valid_from: row.valid_from,
+            valid_until: row.valid_until,
+            correction_count: row.correction_count ?? 0,
+            is_invariant: !!row.is_invariant,
+            priority_score: row.priority_score ?? null,
+            created_at: row.created_at,
+        }));
+    }
+    async incrementCorrectionCount(memoryId) {
+        const pool = await this.getPool();
+        await pool.query(`UPDATE memories
+       SET correction_count = COALESCE(correction_count, 0) + 1
+       WHERE id = $1`, [memoryId]);
+    }
+    async setMemoryInvariant(memoryId, isInvariant) {
+        const pool = await this.getPool();
+        await pool.query(`UPDATE memories SET is_invariant = $1 WHERE id = $2`, [
+            isInvariant ? 1 : 0,
+            memoryId,
+        ]);
+    }
+    async updatePriorityScore(memoryId, score) {
+        const pool = await this.getPool();
+        await pool.query(`UPDATE memories SET priority_score = $1 WHERE id = $2`, [score, memoryId]);
+    }
+    async getPinnedMemories(threshold = 2) {
+        const pool = await this.getPool();
+        let query = `
+      SELECT id, content, tags, source, type, quality_score, quality_factors,
+             access_count, last_accessed, valid_from, valid_until,
+             correction_count, is_invariant, priority_score, created_at
+      FROM memories
+    `;
+        const params = [];
+        let paramIndex = 1;
+        if (this.projectId) {
+            query += ` WHERE (LOWER(project_id) = $${paramIndex} OR project_id IS NULL) AND invalidated_by IS NULL`;
+            params.push(this.projectId);
+            paramIndex++;
+        }
+        else {
+            query += ` WHERE project_id IS NULL AND invalidated_by IS NULL`;
+        }
+        query += ` AND (correction_count >= $${paramIndex} OR is_invariant = 1)`;
+        params.push(threshold);
+        paramIndex++;
+        query += ` ORDER BY is_invariant DESC, correction_count DESC, quality_score DESC`;
+        const result = await pool.query(query, params);
+        return result.rows.map((row) => ({
+            id: row.id,
+            content: row.content,
+            tags: row.tags ? (typeof row.tags === 'string' ? JSON.parse(row.tags) : row.tags) : [],
+            source: row.source,
+            type: row.type,
+            quality_score: row.quality_score,
+            quality_factors: row.quality_factors
+                ? typeof row.quality_factors === 'string'
+                    ? JSON.parse(row.quality_factors)
+                    : row.quality_factors
+                : null,
+            access_count: row.access_count ?? 0,
+            last_accessed: row.last_accessed,
+            valid_from: row.valid_from,
+            valid_until: row.valid_until,
+            correction_count: row.correction_count ?? 0,
+            is_invariant: !!row.is_invariant,
+            priority_score: row.priority_score ?? null,
+            created_at: row.created_at,
+        }));
+    }
+    async incrementMemoryAccess(memoryId, weight = 1.0) {
+        const pool = await this.getPool();
+        await pool.query(`UPDATE memories
+       SET access_count = COALESCE(access_count, 0) + $1,
+           last_accessed = NOW()
+       WHERE id = $2`, [weight, memoryId]);
+    }
+    // ============================================================================
+    // Memory Links
+    // ============================================================================
+    async createMemoryLink(sourceId, targetId, relation = 'related', weight = 1.0, validFrom, validUntil) {
+        const pool = await this.getPool();
+        // Validate that both memories belong to current project (case-insensitive for Windows paths)
+        const validation = await pool.query(`SELECT COUNT(*) as count FROM memories
+       WHERE id IN ($1, $2) AND (LOWER(project_id) = $3 OR project_id IS NULL)`, [sourceId, targetId, this.projectId]);
+        if (parseInt(validation.rows[0].count) !== 2) {
+            throw new StorageError('Cannot link memories from different projects');
+        }
+        const result = await pool.query(`INSERT INTO memory_links (source_id, target_id, relation, weight, valid_from, valid_until)
+       VALUES ($1, $2, $3, $4, $5, $6)
+       ON CONFLICT (source_id, target_id, relation) DO NOTHING
+       RETURNING id`, [sourceId, targetId, relation, weight, validFrom ?? null, validUntil ?? null]);
+        if (result.rows.length > 0) {
+            return { id: result.rows[0].id, created: true };
+        }
+        // Link already existed — fetch its id
+        const existing = await pool.query('SELECT id FROM memory_links WHERE source_id = $1 AND target_id = $2 AND relation = $3', [sourceId, targetId, relation]);
+        return { id: existing.rows[0].id, created: false };
+    }
+    async deleteMemoryLink(sourceId, targetId, relation) {
+        const pool = await this.getPool();
+        // Only delete links where both memories belong to current project
+        if (relation) {
+            const result = await pool.query(`DELETE FROM memory_links ml
+         USING memories m1, memories m2
+         WHERE ml.source_id = m1.id AND ml.target_id = m2.id
+           AND ml.source_id = $1 AND ml.target_id = $2 AND ml.relation = $3
+           AND (LOWER(m1.project_id) = $4 OR m1.project_id IS NULL)
+           AND (LOWER(m2.project_id) = $4 OR m2.project_id IS NULL)`, [sourceId, targetId, relation, this.projectId]);
+            return (result.rowCount ?? 0) > 0;
+        }
+        else {
+            const result = await pool.query(`DELETE FROM memory_links ml
+         USING memories m1, memories m2
+         WHERE ml.source_id = m1.id AND ml.target_id = m2.id
+           AND ml.source_id = $1 AND ml.target_id = $2
+           AND (LOWER(m1.project_id) = $3 OR m1.project_id IS NULL)
+           AND (LOWER(m2.project_id) = $3 OR m2.project_id IS NULL)`, [sourceId, targetId, this.projectId]);
+            return (result.rowCount ?? 0) > 0;
+        }
+    }
+    async getMemoryLinks(memoryId) {
+        const pool = await this.getPool();
+        // Only return links where both source and target memories belong to current project
+        const outgoing = await pool.query(`SELECT ml.* FROM memory_links ml
+       JOIN memories m ON ml.target_id = m.id
+       WHERE ml.source_id = $1 AND (LOWER(m.project_id) = $2 OR m.project_id IS NULL)`, [memoryId, this.projectId]);
+        const incoming = await pool.query(`SELECT ml.* FROM memory_links ml
+       JOIN memories m ON ml.source_id = m.id
+       WHERE ml.target_id = $1 AND (LOWER(m.project_id) = $2 OR m.project_id IS NULL)`, [memoryId, this.projectId]);
+        return {
+            outgoing: outgoing.rows,
+            incoming: incoming.rows,
+        };
+    }
+    async getGraphStats() {
+        const pool = await this.getPool();
+        // Only count memories and links for current project
+        const totalMemories = await pool.query('SELECT COUNT(*) as count FROM memories WHERE LOWER(project_id) = $1 OR project_id IS NULL', [this.projectId]);
+        // Count links only between memories of current project
+        const totalLinks = await pool.query(`SELECT COUNT(*) as count FROM memory_links ml
+       JOIN memories m1 ON ml.source_id = m1.id
+       JOIN memories m2 ON ml.target_id = m2.id
+       WHERE (LOWER(m1.project_id) = $1 OR m1.project_id IS NULL)
+         AND (LOWER(m2.project_id) = $1 OR m2.project_id IS NULL)`, [this.projectId]);
+        const isolated = await pool.query(`SELECT COUNT(*) as count FROM memories m
+       WHERE (LOWER(m.project_id) = $1 OR m.project_id IS NULL)
+         AND NOT EXISTS (
+           SELECT 1 FROM memory_links ml
+           JOIN memories m2 ON (ml.source_id = m2.id OR ml.target_id = m2.id)
+           WHERE (ml.source_id = m.id OR ml.target_id = m.id)
+             AND (LOWER(m2.project_id) = $1 OR m2.project_id IS NULL)
+         )`, [this.projectId]);
+        const relations = await pool.query(`SELECT ml.relation, COUNT(*) as count FROM memory_links ml
+       JOIN memories m1 ON ml.source_id = m1.id
+       JOIN memories m2 ON ml.target_id = m2.id
+       WHERE (LOWER(m1.project_id) = $1 OR m1.project_id IS NULL)
+         AND (LOWER(m2.project_id) = $1 OR m2.project_id IS NULL)
+       GROUP BY ml.relation`, [this.projectId]);
+        const relationsMap = {};
+        for (const row of relations.rows) {
+            relationsMap[row.relation] = parseInt(row.count);
+        }
+        const total = parseInt(totalMemories.rows[0].count);
+        const links = parseInt(totalLinks.rows[0].count);
+        return {
+            total_memories: total,
+            total_links: links,
+            avg_links_per_memory: total > 0 ? links / total : 0,
+            isolated_memories: parseInt(isolated.rows[0].count),
+            relations: relationsMap,
+        };
+    }
+    // ============================================================================
+    // Token Stats
+    // ============================================================================
+    async recordTokenStat(record) {
+        const pool = await this.getPool();
+        await pool.query(`INSERT INTO token_stats (project_id, event_type, query, returned_tokens, full_source_tokens, savings_tokens, files_count, chunks_count, model, estimated_cost)
+       VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10)`, [
+            this.projectId, // Can be NULL for global stats
+            record.event_type,
+            record.query ?? null,
+            record.returned_tokens,
+            record.full_source_tokens,
+            record.savings_tokens,
+            record.files_count ?? null,
+            record.chunks_count ?? null,
+            record.model ?? null,
+            record.estimated_cost ?? 0,
+        ]);
+    }
+    async getTokenStatsSummary() {
+        const pool = await this.getPool();
+        // If project_id is set, get stats for that project; otherwise get all stats
+        const whereClause = this.projectId ? 'WHERE LOWER(project_id) = $1' : '';
+        const params = this.projectId ? [this.projectId] : [];
+        const result = await pool.query(`
+      SELECT
+        COUNT(*) as total_queries,
+        COALESCE(SUM(returned_tokens), 0) as total_returned_tokens,
+        COALESCE(SUM(full_source_tokens), 0) as total_full_source_tokens,
+        COALESCE(SUM(savings_tokens), 0) as total_savings_tokens,
+        COALESCE(SUM(estimated_cost), 0) as total_estimated_cost
+      FROM token_stats
+      ${whereClause}
+    `, params);
+        const row = result.rows[0];
+        return {
+            total_queries: parseInt(row.total_queries),
+            total_returned_tokens: parseInt(row.total_returned_tokens),
+            total_full_source_tokens: parseInt(row.total_full_source_tokens),
+            total_savings_tokens: parseInt(row.total_savings_tokens),
+            total_estimated_cost: parseFloat(row.total_estimated_cost),
+        };
+    }
+    // ============================================================================
+    // Metadata
+    // ============================================================================
+    async getMetadata(key) {
+        const pool = await this.getPool();
+        const result = await pool.query('SELECT value FROM metadata WHERE key = $1', [key]);
+        return result.rows[0]?.value ?? null;
+    }
+    async setMetadata(key, value) {
+        const pool = await this.getPool();
+        await pool.query(`INSERT INTO metadata (key, value) VALUES ($1, $2)
+       ON CONFLICT(key) DO UPDATE SET value = EXCLUDED.value`, [key, value]);
+    }
+    // ============================================================================
+    // Global Memory Operations (project_id = NULL)
+    // ============================================================================
+    /**
+     * Save a global memory (shared across all projects).
+     */
+    async saveGlobalMemory(content, embedding, tags = [], source, type = 'observation', qualityScore, qualityFactors) {
+        return this.saveMemory(content, embedding, tags, source, type, qualityScore, qualityFactors, undefined, // validFrom
+        undefined, // validUntil
+        true // isGlobal
+        );
+    }
+    /**
+     * Search global memories only.
+     */
+    async searchGlobalMemories(queryEmbedding, limit = 5, threshold = 0.3, tags) {
+        const pool = await this.getPool();
+        const query = `
+      SELECT id, project_id, content, tags, source, type, quality_score, quality_factors,
+             access_count, last_accessed, valid_from, valid_until, created_at,
+             1 - (embedding <=> $1) as similarity
+      FROM memories
+      WHERE 1 - (embedding <=> $1) >= $2
+        AND project_id IS NULL
+        AND invalidated_by IS NULL
+      ORDER BY embedding <=> $1
+      LIMIT $3
+    `;
+        const params = [toPgVector(queryEmbedding), threshold, limit];
+        const result = await pool.query(query, params);
+        let memories = result.rows.map((row) => ({
+            id: row.id,
+            content: row.content,
+            tags: row.tags ? (typeof row.tags === 'string' ? JSON.parse(row.tags) : row.tags) : [],
+            source: row.source,
+            type: row.type,
+            quality_score: row.quality_score,
+            quality_factors: row.quality_factors
+                ? typeof row.quality_factors === 'string'
+                    ? JSON.parse(row.quality_factors)
+                    : row.quality_factors
+                : null,
+            access_count: row.access_count ?? 0,
+            last_accessed: row.last_accessed,
+            correction_count: row.correction_count ?? 0,
+            is_invariant: !!row.is_invariant,
+            priority_score: row.priority_score ?? null,
+            valid_from: row.valid_from,
+            valid_until: row.valid_until,
+            created_at: row.created_at,
+            similarity: parseFloat(row.similarity),
+        }));
+        // Filter by tags if specified
+        if (tags && tags.length > 0) {
+            memories = memories.filter((m) => tags.some((t) => m.tags.some((rt) => rt.toLowerCase().includes(t.toLowerCase()))));
+        }
+        return memories;
+    }
+    /**
+     * Get recent global memories.
+     */
+    async getRecentGlobalMemories(limit = 10) {
+        const pool = await this.getPool();
+        const result = await pool.query(`SELECT id, project_id, content, tags, source, type, quality_score, quality_factors,
+              access_count, last_accessed, valid_from, valid_until, created_at
+       FROM memories
+       WHERE project_id IS NULL
+         AND invalidated_by IS NULL
+       ORDER BY created_at DESC
+       LIMIT $1`, [limit]);
+        return result.rows.map((row) => ({
+            id: row.id,
+            content: row.content,
+            tags: row.tags ? (typeof row.tags === 'string' ? JSON.parse(row.tags) : row.tags) : [],
+            source: row.source,
+            type: row.type,
+            quality_score: row.quality_score,
+            quality_factors: row.quality_factors
+                ? typeof row.quality_factors === 'string'
+                    ? JSON.parse(row.quality_factors)
+                    : row.quality_factors
+                : null,
+            access_count: row.access_count ?? 0,
+            last_accessed: row.last_accessed,
+            correction_count: row.correction_count ?? 0,
+            is_invariant: !!row.is_invariant,
+            priority_score: row.priority_score ?? null,
+            valid_from: row.valid_from,
+            valid_until: row.valid_until,
+            created_at: row.created_at,
+        }));
+    }
+    /**
+     * Delete a global memory.
+     */
+    async deleteGlobalMemory(id) {
+        const pool = await this.getPool();
+        const result = await pool.query('DELETE FROM memories WHERE id = $1 AND project_id IS NULL', [
+            id,
+        ]);
+        return (result.rowCount ?? 0) > 0;
+    }
+    /**
+     * Get global memory statistics.
+     */
+    async getGlobalMemoryStats() {
+        const pool = await this.getPool();
+        const total = await pool.query('SELECT COUNT(*) as count FROM memories WHERE project_id IS NULL');
+        const byType = await pool.query('SELECT type, COUNT(*) as count FROM memories WHERE project_id IS NULL GROUP BY type');
+        const byQuality = await pool.query(`
+      SELECT
+        CASE
+          WHEN quality_score >= 0.7 THEN 'high'
+          WHEN quality_score >= 0.4 THEN 'medium'
+          WHEN quality_score IS NOT NULL THEN 'low'
+          ELSE 'unscored'
+        END as bucket,
+        COUNT(*) as count
+      FROM memories
+      WHERE project_id IS NULL
+      GROUP BY bucket
+    `);
+        const typeMap = {};
+        for (const row of byType.rows) {
+            typeMap[row.type || 'observation'] = parseInt(row.count);
+        }
+        const qualityMap = { high: 0, medium: 0, low: 0, unscored: 0 };
+        for (const row of byQuality.rows) {
+            qualityMap[row.bucket] = parseInt(row.count);
+        }
+        return {
+            total: parseInt(total.rows[0].count),
+            by_type: typeMap,
+            by_quality: qualityMap,
+        };
+    }
+    // ============================================================================
+    // Skills Operations
+    // ============================================================================
+    /**
+     * Upsert a skill (local or Skyll-cached).
+     * Local skills use project_id, Skyll skills use project_id = NULL (global cache).
+     */
+    async upsertSkill(skill) {
+        const pool = await this.getPool();
+        // Local skills are project-scoped, Skyll skills are global (project_id = NULL)
+        const projectId = skill.source === 'local' ? this.projectId : null;
+        const result = await pool.query(`INSERT INTO skills (project_id, name, description, source, path, content, embedding, skyll_id, cached_at, cache_expires, created_at, updated_at)
+       VALUES ($1, $2, $3, $4, $5, $6, $7, $8, NOW(), $9, NOW(), NOW())
+       ON CONFLICT(project_id, name) DO UPDATE SET
+         description = EXCLUDED.description,
+         path = EXCLUDED.path,
+         content = EXCLUDED.content,
+         embedding = EXCLUDED.embedding,
+         skyll_id = EXCLUDED.skyll_id,
+         cached_at = CASE WHEN EXCLUDED.source = 'skyll' THEN NOW() ELSE skills.cached_at END,
+         cache_expires = EXCLUDED.cache_expires,
+         updated_at = NOW()
+       RETURNING id`, [
+            projectId,
+            skill.name,
+            skill.description,
+            skill.source,
+            skill.path ?? null,
+            skill.content ?? null,
+            skill.embedding ? toPgVector(skill.embedding) : null,
+            skill.skyllId ?? null,
+            skill.cacheExpires ?? null,
+        ]);
+        return result.rows[0].id;
+    }
+    /**
+     * Get all skills for the current project (includes local + global Skyll cache).
+     */
+    async getAllSkills() {
+        const pool = await this.getPool();
+        // Include both project-specific local skills AND global Skyll cached skills
+        const result = await pool.query(`SELECT id, name, description, source, path, content, skyll_id, usage_count, last_used
+       FROM skills
+       WHERE LOWER(project_id) = $1 OR project_id IS NULL
+       ORDER BY usage_count DESC, updated_at DESC`, [this.projectId]);
+        return result.rows.map((row) => ({
+            id: row.id,
+            name: row.name,
+            description: row.description,
+            source: row.source,
+            path: row.path,
+            content: row.content,
+            skyllId: row.skyll_id,
+            usageCount: row.usage_count ?? 0,
+            lastUsed: row.last_used,
+        }));
+    }
+    /**
+     * Search skills by name or description.
+     */
+    async searchSkills(query, limit = 10) {
+        const pool = await this.getPool();
+        const result = await pool.query(`SELECT id, name, description, source, path, usage_count
+       FROM skills
+       WHERE (LOWER(project_id) = $1 OR project_id IS NULL)
+         AND (name ILIKE $2 OR description ILIKE $2)
+       ORDER BY usage_count DESC, updated_at DESC
+       LIMIT $3`, [this.projectId, `%${query}%`, limit]);
+        return result.rows.map((row) => ({
+            id: row.id,
+            name: row.name,
+            description: row.description,
+            source: row.source,
+            path: row.path,
+            usageCount: row.usage_count ?? 0,
+        }));
+    }
+    /**
+     * Get a skill by name.
+     */
+    async getSkillByName(name) {
+        const pool = await this.getPool();
+        const result = await pool.query(`SELECT id, name, description, source, path, content, skyll_id
+       FROM skills
+       WHERE name = $1 AND (LOWER(project_id) = $2 OR project_id IS NULL)
+       LIMIT 1`, [name, this.projectId]);
+        if (result.rows.length === 0)
+            return null;
+        const row = result.rows[0];
+        return {
+            id: row.id,
+            name: row.name,
+            description: row.description,
+            source: row.source,
+            path: row.path,
+            content: row.content,
+            skyllId: row.skyll_id,
+        };
+    }
+    /**
+     * Track skill usage (increment usage count).
+     */
+    async trackSkillUsage(name) {
+        const pool = await this.getPool();
+        await pool.query(`UPDATE skills SET usage_count = usage_count + 1, last_used = NOW()
+       WHERE name = $1 AND (LOWER(project_id) = $2 OR project_id IS NULL)`, [name, this.projectId]);
+    }
+    /**
+     * Delete a skill by name.
+     */
+    async deleteSkill(name) {
+        const pool = await this.getPool();
+        const result = await pool.query('DELETE FROM skills WHERE name = $1 AND LOWER(project_id) = $2', [name, this.projectId]);
+        return (result.rowCount ?? 0) > 0;
+    }
+    /**
+     * Clear expired Skyll cache entries.
+     */
+    async clearExpiredSkyllCache() {
+        const pool = await this.getPool();
+        const result = await pool.query(`DELETE FROM skills WHERE source = 'skyll' AND cache_expires < NOW()`);
+        return result.rowCount ?? 0;
+    }
+    /**
+     * Get cached Skyll skill by ID.
+     */
+    async getCachedSkyllSkill(skyllId) {
+        const pool = await this.getPool();
+        const result = await pool.query(`SELECT id, name, description, content
+       FROM skills
+       WHERE skyll_id = $1 AND cache_expires > NOW()`, [skyllId]);
+        if (result.rows.length === 0)
+            return null;
+        const row = result.rows[0];
+        return {
+            id: row.id,
+            name: row.name,
+            description: row.description,
+            content: row.content,
+        };
+    }
+    /**
+     * Get Skyll cache status.
+     *
+     * Note: Skyll cached skills are INTENTIONALLY global (not project-scoped).
+     * This is because Skyll marketplace skills are shared across all projects.
+     * Only local skills use project_id scoping.
+     */
+    async getSkyllCacheStats() {
+        const pool = await this.getPool();
+        // Global count - Skyll skills are shared across projects (project_id IS NULL)
+        const result = await pool.query(`SELECT COUNT(*) as count FROM skills WHERE source = 'skyll' AND project_id IS NULL`);
+        return { cachedSkills: parseInt(result.rows[0].count) };
+    }
+    // ============================================================================
+    // Graph Enrichment Operations
+    // ============================================================================
+    async updateMemoryEmbedding(memoryId, embedding) {
+        const pool = await this.getPool();
+        await pool.query('UPDATE memories SET embedding = $1 WHERE id = $2', [
+            toPgVector(embedding),
+            memoryId,
+        ]);
+    }
+    async updateMemoryEmbeddingsBatch(updates) {
+        const pool = await this.getPool();
+        const client = await pool.connect();
+        try {
+            await client.query('BEGIN');
+            for (const { id, embedding } of updates) {
+                await client.query('UPDATE memories SET embedding = $1 WHERE id = $2', [
+                    toPgVector(embedding),
+                    id,
+                ]);
+            }
+            await client.query('COMMIT');
+        }
+        catch (err) {
+            await client.query('ROLLBACK');
+            throw err;
+        }
+        finally {
+            client.release();
+        }
+    }
+    async getMemoriesWithoutEmbeddings(limit = 100) {
+        const pool = await this.getPool();
+        const result = await pool.query('SELECT id, content FROM memories WHERE embedding IS NULL ORDER BY id LIMIT $1', [limit]);
+        return result.rows;
+    }
+    async getMemoriesNeedingReembedding(limit = 100, afterId = 0) {
+        const pool = await this.getPool();
+        const result = await pool.query('SELECT id, content FROM memories WHERE id > $1 ORDER BY id LIMIT $2', [afterId, limit]);
+        return result.rows;
+    }
+    async getMemoryCount() {
+        const pool = await this.getPool();
+        const result = await pool.query('SELECT count(*) FROM memories');
+        return parseInt(result.rows[0].count, 10);
+    }
+    async getMemoryEmbeddingCount() {
+        const pool = await this.getPool();
+        const result = await pool.query('SELECT count(*) FROM memories WHERE embedding IS NOT NULL');
+        return parseInt(result.rows[0].count, 10);
+    }
+    async updateMemoryTags(memoryId, tags) {
+        const pool = await this.getPool();
+        await pool.query('UPDATE memories SET tags = $1 WHERE id = $2 AND LOWER(project_id) = $3', [
+            JSON.stringify(tags),
+            memoryId,
+            this.projectId,
+        ]);
+    }
+    async updateMemoryLink(linkId, updates) {
+        const pool = await this.getPool();
+        const sets = [];
+        const params = [];
+        let idx = 1;
+        if (updates.relation !== undefined) {
+            sets.push(`relation = $${idx++}`);
+            params.push(updates.relation);
+        }
+        if (updates.weight !== undefined) {
+            sets.push(`weight = $${idx++}`);
+            params.push(updates.weight);
+        }
+        if (updates.llmEnriched !== undefined) {
+            sets.push(`llm_enriched = $${idx++}`);
+            params.push(updates.llmEnriched ? 1 : 0);
+        }
+        if (sets.length > 0) {
+            params.push(linkId);
+            try {
+                await pool.query(`UPDATE memory_links SET ${sets.join(', ')} WHERE id = $${idx}`, params);
+            }
+            catch (err) {
+                // Duplicate key: a link with the target (source_id, target_id, relation) already exists.
+                // Delete this link and mark the existing one as enriched instead.
+                if (err.code === '23505' && updates.relation) {
+                    const row = await pool.query('SELECT source_id, target_id FROM memory_links WHERE id = $1', [linkId]);
+                    if (row.rows.length > 0) {
+                        const { source_id, target_id } = row.rows[0];
+                        const client = await pool.connect();
+                        try {
+                            await client.query('BEGIN');
+                            await client.query('DELETE FROM memory_links WHERE id = $1', [linkId]);
+                            await client.query('UPDATE memory_links SET llm_enriched = 1, weight = GREATEST(weight, $1) WHERE source_id = $2 AND target_id = $3 AND relation = $4', [updates.weight ?? 0.5, source_id, target_id, updates.relation]);
+                            await client.query('COMMIT');
+                        }
+                        catch (txErr) {
+                            await client.query('ROLLBACK');
+                            throw txErr;
+                        }
+                        finally {
+                            client.release();
+                        }
+                    }
+                }
+                else {
+                    throw err;
+                }
+            }
+        }
+    }
+    async upsertCentralityScore(memoryId, degree, normalizedDegree) {
+        const pool = await this.getPool();
+        await pool.query(`INSERT INTO memory_centrality (memory_id, degree, normalized_degree, updated_at)
+       VALUES ($1, $2, $3, NOW())
+       ON CONFLICT (memory_id) DO UPDATE SET degree = EXCLUDED.degree, normalized_degree = EXCLUDED.normalized_degree, updated_at = NOW()`, [memoryId, degree, normalizedDegree]);
+    }
+    async getCentralityScores(memoryIds) {
+        const map = new Map();
+        if (memoryIds.length === 0)
+            return map;
+        const pool = await this.getPool();
+        const placeholders = memoryIds.map((_, i) => `$${i + 1}`).join(',');
+        const { rows } = await pool.query(`SELECT memory_id, normalized_degree FROM memory_centrality WHERE memory_id IN (${placeholders})`, memoryIds);
+        for (const row of rows)
+            map.set(row.memory_id, row.normalized_degree);
+        return map;
+    }
+    // ============================================================================
+    // Token Frequency Operations
+    // ============================================================================
+    async updateTokenFrequencies(tokens) {
+        if (tokens.length === 0)
+            return;
+        const pool = await this.getPool();
+        const client = await pool.connect();
+        try {
+            await client.query('BEGIN');
+            for (const token of tokens) {
+                if (token.length >= 2) {
+                    await client.query(`INSERT INTO token_frequencies (token, frequency, updated_at)
+             VALUES ($1, 1, NOW())
+             ON CONFLICT(token) DO UPDATE SET
+               frequency = token_frequencies.frequency + 1,
+               updated_at = NOW()`, [token]);
+                }
+            }
+            await client.query('COMMIT');
+        }
+        catch (e) {
+            await client.query('ROLLBACK');
+            throw e;
+        }
+        finally {
+            client.release();
+        }
+    }
+    async getTokenFrequency(token) {
+        const pool = await this.getPool();
+        const result = await pool.query('SELECT frequency FROM token_frequencies WHERE token = $1', [token]);
+        return result.rows[0]?.frequency ?? 0;
+    }
+    async getTokenFrequencies(tokens) {
+        const result = new Map();
+        if (tokens.length === 0)
+            return result;
+        const pool = await this.getPool();
+        const placeholders = tokens.map((_, i) => `$${i + 1}`).join(',');
+        const rows = await pool.query(`SELECT token, frequency FROM token_frequencies WHERE token IN (${placeholders})`, tokens);
+        for (const row of rows.rows) {
+            result.set(row.token, row.frequency);
+        }
+        return result;
+    }
+    async getTotalTokenCount() {
+        const pool = await this.getPool();
+        const result = await pool.query('SELECT COALESCE(SUM(frequency), 0) as total FROM token_frequencies');
+        return parseInt(result.rows[0].total);
+    }
+    async getTopTokens(limit = 100) {
+        const pool = await this.getPool();
+        const result = await pool.query('SELECT token, frequency FROM token_frequencies ORDER BY frequency DESC LIMIT $1', [limit]);
+        return result.rows;
+    }
+    async clearTokenFrequencies() {
+        const pool = await this.getPool();
+        await pool.query('DELETE FROM token_frequencies');
+    }
+    async getTokenFrequencyStats() {
+        const pool = await this.getPool();
+        const result = await pool.query(`
+      SELECT
+        COUNT(*) as unique_tokens,
+        COALESCE(SUM(frequency), 0) as total_occurrences
+      FROM token_frequencies
+    `);
+        const row = result.rows[0];
+        const unique = parseInt(row.unique_tokens);
+        const total = parseInt(row.total_occurrences);
+        return {
+            unique_tokens: unique,
+            total_occurrences: total,
+            avg_frequency: unique > 0 ? total / unique : 0,
+        };
+    }
+    // ============================================================================
+    // Token Stats - Additional Operations
+    // ============================================================================
+    async getTokenStatsAggregated() {
+        const pool = await this.getPool();
+        const whereClause = this.projectId ? 'WHERE LOWER(project_id) = $1' : '';
+        const params = this.projectId ? [this.projectId] : [];
+        const result = await pool.query(`
+      SELECT
+        event_type,
+        COUNT(*) as query_count,
+        SUM(returned_tokens) as total_returned_tokens,
+        SUM(full_source_tokens) as total_full_source_tokens,
+        SUM(savings_tokens) as total_savings_tokens,
+        COALESCE(SUM(estimated_cost), 0) as total_estimated_cost
+      FROM token_stats
+      ${whereClause}
+      GROUP BY event_type
+      ORDER BY event_type
+    `, params);
+        return result.rows.map((row) => ({
+            event_type: row.event_type,
+            query_count: parseInt(row.query_count),
+            total_returned_tokens: parseInt(row.total_returned_tokens),
+            total_full_source_tokens: parseInt(row.total_full_source_tokens),
+            total_savings_tokens: parseInt(row.total_savings_tokens),
+            total_estimated_cost: parseFloat(row.total_estimated_cost),
+        }));
+    }
+    async clearTokenStats() {
+        const pool = await this.getPool();
+        if (this.projectId) {
+            await pool.query('DELETE FROM token_stats WHERE LOWER(project_id) = $1', [this.projectId]);
+        }
+        else {
+            await pool.query('DELETE FROM token_stats');
+        }
+    }
+    // ============================================================================
+    // Web Search History
+    // ============================================================================
+    async recordWebSearch(record) {
+        const pool = await this.getPool();
+        const result = await pool.query(`INSERT INTO web_search_history (project_id, tool_name, model, query, prompt_tokens, completion_tokens, estimated_cost_usd, citations_count, has_reasoning, response_length_chars)
+       VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10) RETURNING id`, [
+            this.projectId,
+            record.tool_name,
+            record.model,
+            record.query,
+            record.prompt_tokens,
+            record.completion_tokens,
+            record.estimated_cost_usd,
+            record.citations_count,
+            record.has_reasoning,
+            record.response_length_chars,
+        ]);
+        return result.rows[0].id;
+    }
+    async getWebSearchHistory(filter) {
+        const pool = await this.getPool();
+        const conditions = [];
+        const params = [];
+        let paramIdx = 1;
+        if (this.projectId) {
+            conditions.push(`LOWER(project_id) = $${paramIdx++}`);
+            params.push(this.projectId);
+        }
+        if (filter.tool_name) {
+            conditions.push(`tool_name = $${paramIdx++}`);
+            params.push(filter.tool_name);
+        }
+        if (filter.model) {
+            conditions.push(`model = $${paramIdx++}`);
+            params.push(filter.model);
+        }
+        if (filter.query_text) {
+            conditions.push(`query ILIKE $${paramIdx++}`);
+            params.push(`%${filter.query_text}%`);
+        }
+        if (filter.date_from) {
+            conditions.push(`created_at >= $${paramIdx++}`);
+            params.push(filter.date_from);
+        }
+        if (filter.date_to) {
+            conditions.push(`created_at <= $${paramIdx++}::date + interval '1 day'`);
+            params.push(filter.date_to);
+        }
+        const where = conditions.length > 0 ? `WHERE ${conditions.join(' AND ')}` : '';
+        const limit = filter.limit ?? 20;
+        params.push(limit);
+        const result = await pool.query(`SELECT id, tool_name, model, query, prompt_tokens, completion_tokens, estimated_cost_usd, citations_count, has_reasoning, response_length_chars, created_at
+       FROM web_search_history ${where} ORDER BY created_at DESC LIMIT $${paramIdx}`, params);
+        return result.rows.map((row) => ({
+            id: parseInt(row.id),
+            tool_name: row.tool_name,
+            model: row.model,
+            query: row.query,
+            prompt_tokens: parseInt(row.prompt_tokens),
+            completion_tokens: parseInt(row.completion_tokens),
+            estimated_cost_usd: parseFloat(row.estimated_cost_usd),
+            citations_count: parseInt(row.citations_count),
+            has_reasoning: !!row.has_reasoning,
+            response_length_chars: parseInt(row.response_length_chars),
+            created_at: row.created_at instanceof Date ? row.created_at.toISOString() : row.created_at,
+        }));
+    }
+    async getWebSearchSummary() {
+        const pool = await this.getPool();
+        const whereClause = this.projectId ? 'WHERE LOWER(project_id) = $1' : '';
+        const params = this.projectId ? [this.projectId] : [];
+        const totals = await pool.query(`SELECT COUNT(*) as total_searches, COALESCE(SUM(estimated_cost_usd), 0) as total_cost_usd
+       FROM web_search_history ${whereClause}`, params);
+        const byTool = await pool.query(`SELECT tool_name, COUNT(*) as count, COALESCE(SUM(estimated_cost_usd), 0) as cost
+       FROM web_search_history ${whereClause} GROUP BY tool_name`, params);
+        const todayWhere = this.projectId
+            ? "WHERE LOWER(project_id) = $1 AND DATE_TRUNC('day', created_at) = DATE_TRUNC('day', NOW())"
+            : "WHERE DATE_TRUNC('day', created_at) = DATE_TRUNC('day', NOW())";
+        const today = await pool.query(`SELECT COUNT(*) as today_searches, COALESCE(SUM(estimated_cost_usd), 0) as today_cost_usd
+       FROM web_search_history ${todayWhere}`, params);
+        const by_tool = {};
+        for (const row of byTool.rows) {
+            by_tool[row.tool_name] = { count: parseInt(row.count), cost: parseFloat(row.cost) };
+        }
+        return {
+            total_searches: parseInt(totals.rows[0].total_searches),
+            total_cost_usd: parseFloat(totals.rows[0].total_cost_usd),
+            by_tool,
+            today_searches: parseInt(today.rows[0].today_searches),
+            today_cost_usd: parseFloat(today.rows[0].today_cost_usd),
+        };
+    }
+    async getTodayWebSearchSpend() {
+        const pool = await this.getPool();
+        const whereClause = this.projectId
+            ? "WHERE LOWER(project_id) = $1 AND DATE_TRUNC('day', created_at) = DATE_TRUNC('day', NOW())"
+            : "WHERE DATE_TRUNC('day', created_at) = DATE_TRUNC('day', NOW())";
+        const params = this.projectId ? [this.projectId] : [];
+        const result = await pool.query(`SELECT COALESCE(SUM(estimated_cost_usd), 0) as total FROM web_search_history ${whereClause}`, params);
+        return parseFloat(result.rows[0].total);
+    }
+    async clearWebSearchHistory() {
+        const pool = await this.getPool();
+        if (this.projectId) {
+            await pool.query('DELETE FROM web_search_history WHERE LOWER(project_id) = $1', [
+                this.projectId,
+            ]);
+        }
+        else {
+            await pool.query('DELETE FROM web_search_history');
+        }
+    }
+    // ============================================================================
+    // Document Operations - Additional
+    // ============================================================================
+    async getRecentDocuments(limit = 10) {
+        if (!this.projectId) {
+            throw new StorageError('Project ID must be set before getting recent documents');
+        }
+        const pool = await this.getPool();
+        const result = await pool.query(`SELECT file_path, content, start_line, end_line
+       FROM documents
+       WHERE LOWER(project_id) = $1 AND file_path NOT LIKE 'code:%'
+       ORDER BY id DESC
+       LIMIT $2`, [this.projectId, limit]);
+        return result.rows;
+    }
+    async clearCodeDocuments() {
+        const pool = await this.getPool();
+        if (this.projectId) {
+            await pool.query("DELETE FROM documents WHERE LOWER(project_id) = $1 AND file_path LIKE 'code:%'", [this.projectId]);
+            await pool.query("DELETE FROM file_hashes WHERE LOWER(project_id) = $1 AND file_path LIKE 'code:%'", [this.projectId]);
+        }
+        else {
+            await pool.query("DELETE FROM documents WHERE file_path LIKE 'code:%'");
+            await pool.query("DELETE FROM file_hashes WHERE file_path LIKE 'code:%'");
+        }
+    }
+    async getStoredEmbeddingDimension() {
+        const pool = await this.getPool();
+        const result = await pool.query('SELECT embedding FROM documents LIMIT 1');
+        if (result.rows.length === 0)
+            return null;
+        const embedding = fromPgVector(result.rows[0].embedding);
+        return embedding.length;
+    }
+    // ============================================================================
+    // Memory Operations - Additional
+    // ============================================================================
+    async findSimilarMemory(embedding, threshold = 0.92) {
+        const pool = await this.getPool();
+        let query;
+        let params;
+        if (this.projectId) {
+            query = `SELECT id, content, 1 - (embedding <=> $1) as similarity
+               FROM memories
+               WHERE (LOWER(project_id) = $2 OR project_id IS NULL)
+                 AND 1 - (embedding <=> $1) >= $3
+               ORDER BY embedding <=> $1
+               LIMIT 1`;
+            params = [toPgVector(embedding), this.projectId, threshold];
+        }
+        else {
+            query = `SELECT id, content, 1 - (embedding <=> $1) as similarity
+               FROM memories
+               WHERE project_id IS NULL
+                 AND 1 - (embedding <=> $1) >= $2
+               ORDER BY embedding <=> $1
+               LIMIT 1`;
+            params = [toPgVector(embedding), threshold];
+        }
+        const result = await pool.query(query, params);
+        if (result.rows.length === 0)
+            return null;
+        return {
+            id: result.rows[0].id,
+            content: result.rows[0].content,
+            similarity: parseFloat(String(result.rows[0].similarity)),
+        };
+    }
+    async findSimilarGlobalMemory(embedding, threshold = 0.92) {
+        const pool = await this.getPool();
+        const result = await pool.query(`SELECT id, content, 1 - (embedding <=> $1) as similarity
+       FROM memories
+       WHERE project_id IS NULL
+         AND 1 - (embedding <=> $1) >= $2
+       ORDER BY embedding <=> $1
+       LIMIT 1`, [toPgVector(embedding), threshold]);
+        if (result.rows.length === 0)
+            return null;
+        return {
+            id: result.rows[0].id,
+            content: result.rows[0].content,
+            similarity: parseFloat(String(result.rows[0].similarity)),
+        };
+    }
+    async saveMemoriesBatch(memories, deduplicateThreshold = 0.92, options) {
+        if (memories.length === 0) {
+            return { saved: 0, skipped: 0, results: [] };
+        }
+        const pool = await this.getPool();
+        const client = await pool.connect();
+        const results = [];
+        let saved = 0;
+        let skipped = 0;
+        const shouldDedup = options?.deduplicate !== false;
+        try {
+            await client.query('BEGIN');
+            for (let i = 0; i < memories.length; i++) {
+                const memory = memories[i];
+                // Check for duplicates via pgvector
+                if (shouldDedup) {
+                    let dupQuery;
+                    let dupParams;
+                    if (this.projectId) {
+                        dupQuery = `SELECT id, 1 - (embedding <=> $1) as similarity
+                       FROM memories
+                       WHERE (LOWER(project_id) = $2 OR project_id IS NULL)
+                         AND 1 - (embedding <=> $1) >= $3
+                       ORDER BY embedding <=> $1
+                       LIMIT 1`;
+                        dupParams = [toPgVector(memory.embedding), this.projectId, deduplicateThreshold];
+                    }
+                    else {
+                        dupQuery = `SELECT id, 1 - (embedding <=> $1) as similarity
+                       FROM memories
+                       WHERE project_id IS NULL
+                         AND 1 - (embedding <=> $1) >= $2
+                       ORDER BY embedding <=> $1
+                       LIMIT 1`;
+                        dupParams = [toPgVector(memory.embedding), deduplicateThreshold];
+                    }
+                    const dupResult = await client.query(dupQuery, dupParams);
+                    if (dupResult.rows.length > 0) {
+                        results.push({
+                            index: i,
+                            isDuplicate: true,
+                            id: dupResult.rows[0].id,
+                            reason: 'duplicate',
+                            similarity: parseFloat(String(dupResult.rows[0].similarity)),
+                        });
+                        skipped++;
+                        continue;
+                    }
+                }
+                // Insert memory
+                const validFromStr = memory.validFrom
+                    ? memory.validFrom instanceof Date
+                        ? memory.validFrom.toISOString()
+                        : memory.validFrom
+                    : null;
+                const validUntilStr = memory.validUntil
+                    ? memory.validUntil instanceof Date
+                        ? memory.validUntil.toISOString()
+                        : memory.validUntil
+                    : null;
+                const insertResult = await client.query(`INSERT INTO memories (project_id, content, tags, source, type, quality_score, quality_factors, embedding, valid_from, valid_until)
+           VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10)
+           RETURNING id`, [
+                    this.projectId,
+                    memory.content,
+                    memory.tags.length > 0 ? JSON.stringify(memory.tags) : null,
+                    memory.source ?? null,
+                    memory.type,
+                    memory.qualityScore?.score ?? null,
+                    memory.qualityScore?.factors ? JSON.stringify(memory.qualityScore.factors) : null,
+                    toPgVector(memory.embedding),
+                    validFromStr,
+                    validUntilStr,
+                ]);
+                results.push({
+                    index: i,
+                    isDuplicate: false,
+                    id: insertResult.rows[0].id,
+                    reason: 'saved',
+                });
+                saved++;
+            }
+            await client.query('COMMIT');
+        }
+        catch (e) {
+            await client.query('ROLLBACK');
+            throw e;
+        }
+        finally {
+            client.release();
+        }
+        results.sort((a, b) => a.index - b.index);
+        return { saved, skipped, results };
+    }
+    async getMemoryStats() {
+        const pool = await this.getPool();
+        const scopeCond = this.projectId
+            ? '(LOWER(project_id) = $1 OR project_id IS NULL)'
+            : 'project_id IS NULL';
+        const scopeParams = this.projectId ? [this.projectId] : [];
+        const total = await pool.query(`SELECT COUNT(*) as count FROM memories WHERE ${scopeCond}`, scopeParams);
+        const active = await pool.query(`SELECT COUNT(*) as count FROM memories WHERE ${scopeCond} AND invalidated_by IS NULL`, scopeParams);
+        const oldest = await pool.query(`SELECT MIN(created_at)::text as oldest FROM memories WHERE ${scopeCond} AND invalidated_by IS NULL`, scopeParams);
+        const newest = await pool.query(`SELECT MAX(created_at)::text as newest FROM memories WHERE ${scopeCond} AND invalidated_by IS NULL`, scopeParams);
+        const typeCounts = await pool.query(`SELECT COALESCE(type, 'observation') as type, COUNT(*) as count
+       FROM memories WHERE ${scopeCond} AND invalidated_by IS NULL
+       GROUP BY type`, scopeParams);
+        const by_type = {};
+        for (const row of typeCounts.rows) {
+            by_type[row.type] = parseInt(row.count);
+        }
+        // Stale memories: older than 30 days, active only
+        const thirtyDaysAgo = new Date(Date.now() - 30 * 24 * 60 * 60 * 1000).toISOString();
+        const staleParamIdx = scopeParams.length + 1;
+        const stale = await pool.query(`SELECT COUNT(*) as count FROM memories
+       WHERE ${scopeCond} AND created_at < $${staleParamIdx} AND invalidated_by IS NULL`, [...scopeParams, thirtyDaysAgo]);
+        const totalCount = parseInt(total.rows[0].count);
+        const activeCount = parseInt(active.rows[0].count);
+        return {
+            total_memories: totalCount,
+            active_memories: activeCount,
+            invalidated_memories: totalCount - activeCount,
+            oldest_memory: oldest.rows[0].oldest,
+            newest_memory: newest.rows[0].newest,
+            by_type,
+            stale_count: parseInt(stale.rows[0].count),
+        };
+    }
+    async deleteMemoriesOlderThan(date) {
+        const pool = await this.getPool();
+        const result = await pool.query('DELETE FROM memories WHERE created_at < $1', [
+            date.toISOString(),
+        ]);
+        return result.rowCount ?? 0;
+    }
+    async deleteMemoriesByTag(tag) {
+        const pool = await this.getPool();
+        // JSONB array containment: tags is a JSONB array, check if any element matches (case-insensitive)
+        const result = await pool.query(`DELETE FROM memories
+       WHERE tags IS NOT NULL
+         AND EXISTS (
+           SELECT 1 FROM jsonb_array_elements_text(tags) elem
+           WHERE LOWER(elem) = LOWER($1)
+         )`, [tag]);
+        return result.rowCount ?? 0;
+    }
+    async deleteMemoriesByIds(ids) {
+        if (ids.length === 0)
+            return 0;
+        const pool = await this.getPool();
+        const placeholders = ids.map((_, i) => `$${i + 1}`).join(',');
+        const result = await pool.query(`DELETE FROM memories WHERE id IN (${placeholders})`, ids);
+        return result.rowCount ?? 0;
+    }
+    async searchMemoriesAsOf(queryEmbedding, asOfDate, limit = 5, threshold = 0.3) {
+        const pool = await this.getPool();
+        const asOfStr = asOfDate.toISOString();
+        // Get memories that existed at that time, with temporal validity check
+        const scopeCond = this.projectId
+            ? '(LOWER(project_id) = $4 OR project_id IS NULL)'
+            : 'project_id IS NULL';
+        const scopeParams = this.projectId ? [this.projectId] : [];
+        const result = await pool.query(`SELECT id, project_id, content, tags, source, type, quality_score, quality_factors,
+              access_count, last_accessed, valid_from, valid_until, created_at,
+              1 - (embedding <=> $1) as similarity
+       FROM memories
+       WHERE created_at <= $2
+         AND 1 - (embedding <=> $1) >= $3
+         AND ${scopeCond}
+         AND (valid_from IS NULL OR valid_from <= $2)
+         AND (valid_until IS NULL OR valid_until > $2)
+       ORDER BY embedding <=> $1
+       LIMIT $${scopeParams.length + 4}`, [toPgVector(queryEmbedding), asOfStr, threshold, ...scopeParams, limit]);
+        return result.rows.map((row) => ({
+            id: row.id,
+            content: row.content,
+            tags: row.tags ? (typeof row.tags === 'string' ? JSON.parse(row.tags) : row.tags) : [],
+            source: row.source,
+            type: row.type,
+            quality_score: row.quality_score,
+            quality_factors: row.quality_factors
+                ? typeof row.quality_factors === 'string'
+                    ? JSON.parse(row.quality_factors)
+                    : row.quality_factors
+                : null,
+            access_count: row.access_count ?? 0,
+            last_accessed: row.last_accessed,
+            correction_count: row.correction_count ?? 0,
+            is_invariant: !!row.is_invariant,
+            priority_score: row.priority_score ?? null,
+            valid_from: row.valid_from,
+            valid_until: row.valid_until,
+            created_at: row.created_at,
+            similarity: parseFloat(row.similarity),
+        }));
+    }
+    async getConsolidationHistory(limit = 20) {
+        const pool = await this.getPool();
+        // Find memories that have 'supersedes' links (merge results)
+        const rows = await pool.query(`SELECT DISTINCT ml.source_id as merged_id, ml.created_at::text as merged_at
+       FROM memory_links ml
+       WHERE ml.relation = 'supersedes'
+       ORDER BY ml.created_at DESC
+       LIMIT $1`, [limit]);
+        const results = [];
+        for (const row of rows.rows) {
+            const memory = await this.getMemoryById(row.merged_id);
+            const originals = await pool.query(`SELECT target_id FROM memory_links
+         WHERE source_id = $1 AND relation = 'supersedes'`, [row.merged_id]);
+            results.push({
+                mergedMemoryId: row.merged_id,
+                mergedContent: memory?.content ?? '(deleted)',
+                originalIds: originals.rows.map((o) => o.target_id),
+                mergedAt: row.merged_at,
+            });
+        }
+        return results;
+    }
+    // ============================================================================
+    // Retention Operations
+    // ============================================================================
+    async incrementMemoryAccessBatch(accesses) {
+        if (accesses.length === 0)
+            return;
+        const pool = await this.getPool();
+        const client = await pool.connect();
+        try {
+            await client.query('BEGIN');
+            for (const { memoryId, weight } of accesses) {
+                await client.query(`UPDATE memories
+           SET access_count = COALESCE(access_count, 0) + $1,
+               last_accessed = NOW()
+           WHERE id = $2`, [weight, memoryId]);
+            }
+            await client.query('COMMIT');
+        }
+        catch (e) {
+            await client.query('ROLLBACK');
+            throw e;
+        }
+        finally {
+            client.release();
+        }
+    }
+    async getAllMemoriesForRetention() {
+        const pool = await this.getPool();
+        const scopeCond = this.projectId
+            ? 'WHERE (LOWER(project_id) = $1 OR project_id IS NULL)'
+            : 'WHERE project_id IS NULL';
+        const params = this.projectId ? [this.projectId] : [];
+        const result = await pool.query(`SELECT id, content, quality_score, access_count, created_at::text as created_at, last_accessed::text as last_accessed
+       FROM memories
+       ${scopeCond}
+       ORDER BY created_at ASC`, params);
+        return result.rows.map((row) => ({
+            id: row.id,
+            content: row.content,
+            quality_score: row.quality_score,
+            access_count: row.access_count ?? 0,
+            created_at: row.created_at,
+            last_accessed: row.last_accessed,
+        }));
+    }
+    // ============================================================================
+    // Backfill — fetch all records with embeddings for Qdrant sync
+    // ============================================================================
+    async getAllMemoriesWithEmbeddings() {
+        const pool = await this.getPool();
+        const scopeCond = this.projectId
+            ? 'WHERE LOWER(project_id) = $1 AND invalidated_by IS NULL'
+            : 'WHERE project_id IS NULL AND invalidated_by IS NULL';
+        const params = this.projectId ? [this.projectId] : [];
+        const result = await pool.query(`SELECT id, content, tags, source, type, project_id,
+              created_at::text as created_at, valid_from::text as valid_from,
+              valid_until::text as valid_until, invalidated_by, access_count,
+              last_accessed::text as last_accessed, quality_score,
+              embedding::text as embedding
+       FROM memories ${scopeCond}
+       ORDER BY id ASC`, params);
+        return result.rows.map((row) => ({
+            id: row.id,
+            content: row.content,
+            tags: row.tags ?? [],
+            source: row.source,
+            type: row.type,
+            projectId: row.project_id,
+            createdAt: row.created_at,
+            validFrom: row.valid_from,
+            validUntil: row.valid_until,
+            invalidatedBy: row.invalidated_by,
+            accessCount: row.access_count ?? 0,
+            lastAccessed: row.last_accessed,
+            qualityScore: row.quality_score,
+            embedding: fromPgVector(row.embedding),
+        }));
+    }
+    async getAllDocumentsWithEmbeddings() {
+        const pool = await this.getPool();
+        const scopeCond = this.projectId ? 'WHERE LOWER(project_id) = $1' : '';
+        const params = this.projectId ? [this.projectId] : [];
+        const result = await pool.query(`SELECT id, file_path, content, start_line, end_line, project_id,
+              embedding::text as embedding
+       FROM documents ${scopeCond}
+       ORDER BY id ASC`, params);
+        return result.rows.map((row) => ({
+            id: row.id,
+            filePath: row.file_path,
+            content: row.content,
+            startLine: row.start_line,
+            endLine: row.end_line,
+            projectId: row.project_id,
+            embedding: fromPgVector(row.embedding),
+        }));
+    }
+    // ============================================================================
+    // Graph Operations - Additional
+    // ============================================================================
+    async getMemoryWithLinks(memoryId, options) {
+        const memory = await this.getMemoryById(memoryId);
+        if (!memory)
+            return null;
+        const links = await this.getMemoryLinks(memoryId);
+        const now = options?.asOfDate?.getTime() ?? Date.now();
+        const includeExpired = options?.includeExpired ?? false;
+        const filterLink = (link) => {
+            if (includeExpired)
+                return true;
+            if (link.valid_from) {
+                const validFrom = new Date(link.valid_from).getTime();
+                if (now < validFrom)
+                    return false;
+            }
+            if (link.valid_until) {
+                const validUntil = new Date(link.valid_until).getTime();
+                if (now > validUntil)
+                    return false;
+            }
+            return true;
+        };
+        // Fetch content for linked memories
+        const pool = await this.getPool();
+        const outgoing = [];
+        for (const l of links.outgoing.filter(filterLink)) {
+            const targetMem = await pool.query('SELECT content FROM memories WHERE id = $1', [l.target_id]);
+            outgoing.push({
+                target_id: l.target_id,
+                relation: l.relation,
+                weight: l.weight,
+                target_content: targetMem.rows[0]?.content ?? '',
+            });
+        }
+        const incoming = [];
+        for (const l of links.incoming.filter(filterLink)) {
+            const sourceMem = await pool.query('SELECT content FROM memories WHERE id = $1', [l.source_id]);
+            incoming.push({
+                source_id: l.source_id,
+                relation: l.relation,
+                weight: l.weight,
+                source_content: sourceMem.rows[0]?.content ?? '',
+            });
+        }
+        return {
+            ...memory,
+            outgoing_links: outgoing,
+            incoming_links: incoming,
+        };
+    }
+    async findConnectedMemories(memoryId, maxDepth = 2) {
+        const pool = await this.getPool();
+        const visited = new Set([memoryId]);
+        const results = [];
+        // BFS traversal
+        let currentLevel = [{ id: memoryId, path: [memoryId] }];
+        for (let depth = 1; depth <= maxDepth; depth++) {
+            const nextLevel = [];
+            for (const { id, path } of currentLevel) {
+                const outgoing = await pool.query('SELECT target_id FROM memory_links WHERE source_id = $1', [id]);
+                const incoming = await pool.query('SELECT source_id FROM memory_links WHERE target_id = $1', [id]);
+                const neighbors = [
+                    ...outgoing.rows.map((r) => r.target_id),
+                    ...incoming.rows.map((r) => r.source_id),
+                ];
+                for (const neighborId of neighbors) {
+                    if (!visited.has(neighborId)) {
+                        visited.add(neighborId);
+                        const memory = await this.getMemoryById(neighborId);
+                        if (memory) {
+                            const newPath = [...path, neighborId];
+                            results.push({ memory, depth, path: newPath });
+                            nextLevel.push({ id: neighborId, path: newPath });
+                        }
+                    }
+                }
+            }
+            currentLevel = nextLevel;
+        }
+        return results;
+    }
+    async findRelatedMemoriesForLinking(memoryId, threshold = 0.75, maxLinks = 3) {
+        const pool = await this.getPool();
+        // Use pgvector to find similar memories efficiently (scoped to current project)
+        const source = await pool.query('SELECT embedding FROM memories WHERE id = $1', [memoryId]);
+        if (source.rows.length === 0)
+            return [];
+        const result = await pool.query(`SELECT id, 1 - (embedding <=> (SELECT embedding FROM memories WHERE id = $1)) as similarity
+       FROM memories
+       WHERE id != $1
+         AND (LOWER(project_id) = $4 OR project_id IS NULL)
+         AND 1 - (embedding <=> (SELECT embedding FROM memories WHERE id = $1)) >= $2
+       ORDER BY embedding <=> (SELECT embedding FROM memories WHERE id = $1)
+       LIMIT $3`, [memoryId, threshold, maxLinks, this.projectId]);
+        return result.rows.map((r) => ({
+            id: r.id,
+            similarity: parseFloat(String(r.similarity)),
+        }));
+    }
+    async createAutoLinks(memoryId, threshold = 0.75, maxLinks = 3) {
+        const candidates = await this.findRelatedMemoriesForLinking(memoryId, threshold, maxLinks);
+        let linksCreated = 0;
+        for (const { id: targetId, similarity } of candidates) {
+            const result = await this.createMemoryLink(memoryId, targetId, 'similar_to', similarity);
+            if (result.created) {
+                linksCreated++;
+            }
+        }
+        return linksCreated;
+    }
+    async autoLinkSimilarMemories(threshold = 0.75, maxLinks = 3) {
+        const pool = await this.getPool();
+        const scopeCond = this.projectId
+            ? 'WHERE (LOWER(project_id) = $1 OR project_id IS NULL)'
+            : 'WHERE project_id IS NULL';
+        const params = this.projectId ? [this.projectId] : [];
+        // Get all memory IDs
+        const memories = await pool.query(`SELECT id FROM memories ${scopeCond}`, params);
+        let linksCreated = 0;
+        for (const { id } of memories.rows) {
+            const created = await this.createAutoLinks(id, threshold, maxLinks);
+            linksCreated += created;
+        }
+        return linksCreated;
+    }
+    async invalidateMemoryLink(sourceId, targetId, relation) {
+        const pool = await this.getPool();
+        if (relation) {
+            const result = await pool.query(`UPDATE memory_links SET valid_until = NOW()
+         WHERE source_id = $1 AND target_id = $2 AND relation = $3 AND valid_until IS NULL`, [sourceId, targetId, relation]);
+            return (result.rowCount ?? 0) > 0;
+        }
+        else {
+            const result = await pool.query(`UPDATE memory_links SET valid_until = NOW()
+         WHERE source_id = $1 AND target_id = $2 AND valid_until IS NULL`, [sourceId, targetId]);
+            return (result.rowCount ?? 0) > 0;
+        }
+    }
+    async getMemoryLinksAsOf(memoryId, asOfDate) {
+        const pool = await this.getPool();
+        const asOfStr = asOfDate.toISOString();
+        const outgoing = await pool.query(`SELECT * FROM memory_links
+       WHERE source_id = $1
+         AND created_at <= $2
+         AND (valid_from IS NULL OR valid_from <= $2)
+         AND (valid_until IS NULL OR valid_until > $2)`, [memoryId, asOfStr]);
+        const incoming = await pool.query(`SELECT * FROM memory_links
+       WHERE target_id = $1
+         AND created_at <= $2
+         AND (valid_from IS NULL OR valid_from <= $2)
+         AND (valid_until IS NULL OR valid_until > $2)`, [memoryId, asOfStr]);
+        return { outgoing: outgoing.rows, incoming: incoming.rows };
+    }
+    async findConnectedMemoriesAsOf(memoryId, asOfDate, maxDepth = 2) {
+        const pool = await this.getPool();
+        const asOfStr = asOfDate.toISOString();
+        const visited = new Set([memoryId]);
+        const results = [];
+        let currentLevel = [{ id: memoryId, path: [memoryId] }];
+        for (let depth = 1; depth <= maxDepth; depth++) {
+            const nextLevel = [];
+            for (const { id, path } of currentLevel) {
+                const outgoing = await pool.query(`SELECT target_id FROM memory_links
+           WHERE source_id = $1
+             AND created_at <= $2
+             AND (valid_from IS NULL OR valid_from <= $2)
+             AND (valid_until IS NULL OR valid_until > $2)`, [id, asOfStr]);
+                const incoming = await pool.query(`SELECT source_id FROM memory_links
+           WHERE target_id = $1
+             AND created_at <= $2
+             AND (valid_from IS NULL OR valid_from <= $2)
+             AND (valid_until IS NULL OR valid_until > $2)`, [id, asOfStr]);
+                const neighbors = [
+                    ...outgoing.rows.map((r) => r.target_id),
+                    ...incoming.rows.map((r) => r.source_id),
+                ];
+                for (const neighborId of neighbors) {
+                    if (!visited.has(neighborId)) {
+                        visited.add(neighborId);
+                        const memory = await this.getMemoryById(neighborId);
+                        if (memory) {
+                            const newPath = [...path, neighborId];
+                            results.push({ memory, depth, path: newPath });
+                            nextLevel.push({ id: neighborId, path: newPath });
+                        }
+                    }
+                }
+            }
+            currentLevel = nextLevel;
+        }
+        return results;
+    }
+    async getGraphStatsAsOf(asOfDate) {
+        const pool = await this.getPool();
+        const asOfStr = asOfDate.toISOString();
+        const totalMemories = await pool.query('SELECT COUNT(*) as count FROM memories WHERE created_at <= $1', [asOfStr]);
+        const totalLinks = await pool.query(`SELECT COUNT(*) as count FROM memory_links
+       WHERE created_at <= $1
+         AND (valid_from IS NULL OR valid_from <= $1)
+         AND (valid_until IS NULL OR valid_until > $1)`, [asOfStr]);
+        const relationCounts = await pool.query(`SELECT relation, COUNT(*) as count FROM memory_links
+       WHERE created_at <= $1
+         AND (valid_from IS NULL OR valid_from <= $1)
+         AND (valid_until IS NULL OR valid_until > $1)
+       GROUP BY relation`, [asOfStr]);
+        const relations = {};
+        for (const row of relationCounts.rows) {
+            relations[row.relation] = parseInt(row.count);
+        }
+        const memCount = parseInt(totalMemories.rows[0].count);
+        const linkCount = parseInt(totalLinks.rows[0].count);
+        return {
+            total_memories: memCount,
+            total_links: linkCount,
+            avg_links_per_memory: memCount > 0 ? linkCount / memCount : 0,
+            relations,
+        };
+    }
+}
+/**
+ * Create PostgreSQL backend from storage config.
+ */
+export function createPostgresBackend(config) {
+    const pgConfig = config.postgresql ?? {};
+    return new PostgresBackend({
+        connectionString: pgConfig.connection_string,
+        host: pgConfig.host,
+        port: pgConfig.port,
+        database: pgConfig.database,
+        user: pgConfig.user,
+        password: pgConfig.password,
+        ssl: pgConfig.ssl,
+        poolSize: pgConfig.pool_size,
+    });
+}
+//# sourceMappingURL=postgresql.js.map