specmem-hardwicksoftware 3.5.99

package/dist/code-explanations/schema.js

@@ -0,0 +1,221 @@
+/**
+ * Code Explanation System - Database Schema
+ *
+ * Tables:
+ * - code_explanations: Store explanations for code locations
+ * - code_prompt_links: Link code to conversation prompts/memories
+ * - code_access_patterns: Track access patterns for learning
+ *
+ * EMBEDDING DIMENSION NOTE:
+ * DEPRECATED: SPECMEM_EMBEDDING_DIMENSIONS is no longer used.
+ * Embedding dimensions are AUTO-DETECTED from the database pgvector column.
+ * The system auto-migrates when dimension mismatch is detected at startup.
+ */
+import { logger } from '../utils/logger.js';
+/**
+ * Initialize the code explanation schema
+ * This creates all necessary tables for the active recall system
+ */
+export async function initializeCodeExplanationSchema(db) {
+    logger.info('Initializing code explanation schema...');
+    try {
+        // Create code_explanations table
+        await db.query(`
+      CREATE TABLE IF NOT EXISTS code_explanations (
+        id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+        code_id UUID REFERENCES codebase_files(id) ON DELETE CASCADE,
+        file_path TEXT NOT NULL,
+        line_start INTEGER,
+        line_end INTEGER,
+        code_snippet TEXT,
+        explanation_text TEXT NOT NULL,
+        explanation_type VARCHAR(50) DEFAULT 'general',
+        -- NOTE: Dimension is auto-detected from memories table, unbounded initially
+        embedding vector,
+        quality_score FLOAT DEFAULT 0.5,
+        use_count INTEGER DEFAULT 0,
+        feedback_positive INTEGER DEFAULT 0,
+        feedback_negative INTEGER DEFAULT 0,
+        created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+        updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+        created_by VARCHAR(100) DEFAULT 'assistant',
+        metadata JSONB DEFAULT '{}',
+
+        CONSTRAINT quality_score_range CHECK (quality_score >= 0 AND quality_score <= 1),
+        CONSTRAINT line_range_valid CHECK (line_start IS NULL OR line_end IS NULL OR line_start <= line_end)
+      )
+    `);
+        // Create indexes for code_explanations
+        await db.query(`
+      CREATE INDEX IF NOT EXISTS idx_code_explanations_code_id
+      ON code_explanations(code_id)
+    `);
+        await db.query(`
+      CREATE INDEX IF NOT EXISTS idx_code_explanations_file_path
+      ON code_explanations(file_path)
+    `);
+        await db.query(`
+      CREATE INDEX IF NOT EXISTS idx_code_explanations_embedding
+      ON code_explanations USING ivfflat (embedding vector_cosine_ops)
+      WITH (lists = 100)
+    `);
+        await db.query(`
+      CREATE INDEX IF NOT EXISTS idx_code_explanations_quality
+      ON code_explanations(quality_score DESC)
+    `);
+        await db.query(`
+      CREATE INDEX IF NOT EXISTS idx_code_explanations_type
+      ON code_explanations(explanation_type)
+    `);
+        logger.info('code_explanations table created');
+        // Create code_prompt_links table
+        await db.query(`
+      CREATE TABLE IF NOT EXISTS code_prompt_links (
+        id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+        code_id UUID REFERENCES codebase_files(id) ON DELETE CASCADE,
+        memory_id UUID REFERENCES memories(id) ON DELETE CASCADE,
+        explanation_id UUID REFERENCES code_explanations(id) ON DELETE SET NULL,
+        relationship_type VARCHAR(50) NOT NULL DEFAULT 'referenced',
+        context TEXT,
+        strength FLOAT DEFAULT 1.0,
+        created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+        metadata JSONB DEFAULT '{}',
+
+        CONSTRAINT strength_range CHECK (strength >= 0 AND strength <= 1),
+        CONSTRAINT unique_code_memory UNIQUE (code_id, memory_id, relationship_type)
+      )
+    `);
+        // Create indexes for code_prompt_links
+        await db.query(`
+      CREATE INDEX IF NOT EXISTS idx_code_prompt_links_code_id
+      ON code_prompt_links(code_id)
+    `);
+        await db.query(`
+      CREATE INDEX IF NOT EXISTS idx_code_prompt_links_memory_id
+      ON code_prompt_links(memory_id)
+    `);
+        await db.query(`
+      CREATE INDEX IF NOT EXISTS idx_code_prompt_links_relationship
+      ON code_prompt_links(relationship_type)
+    `);
+        await db.query(`
+      CREATE INDEX IF NOT EXISTS idx_code_prompt_links_strength
+      ON code_prompt_links(strength DESC)
+    `);
+        logger.info('code_prompt_links table created');
+        // Create code_access_patterns table
+        await db.query(`
+      CREATE TABLE IF NOT EXISTS code_access_patterns (
+        id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+        code_id UUID REFERENCES codebase_files(id) ON DELETE CASCADE,
+        access_count INTEGER DEFAULT 1,
+        last_accessed TIMESTAMPTZ DEFAULT NOW(),
+        common_queries TEXT[] DEFAULT '{}',
+        query_embeddings JSONB DEFAULT '[]',
+        access_contexts TEXT[] DEFAULT '{}',
+        hourly_access_pattern INTEGER[] DEFAULT ARRAY[0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
+        daily_access_pattern INTEGER[] DEFAULT ARRAY[0,0,0,0,0,0,0],
+        first_accessed TIMESTAMPTZ DEFAULT NOW(),
+        metadata JSONB DEFAULT '{}',
+
+        CONSTRAINT unique_code_pattern UNIQUE (code_id)
+      )
+    `);
+        // Create indexes for code_access_patterns
+        await db.query(`
+      CREATE INDEX IF NOT EXISTS idx_code_access_patterns_code_id
+      ON code_access_patterns(code_id)
+    `);
+        await db.query(`
+      CREATE INDEX IF NOT EXISTS idx_code_access_patterns_access_count
+      ON code_access_patterns(access_count DESC)
+    `);
+        await db.query(`
+      CREATE INDEX IF NOT EXISTS idx_code_access_patterns_last_accessed
+      ON code_access_patterns(last_accessed DESC)
+    `);
+        logger.info('code_access_patterns table created');
+        // Create trigger to update updated_at on code_explanations
+        await db.query(`
+      CREATE OR REPLACE FUNCTION update_code_explanation_modified()
+      RETURNS TRIGGER AS $$
+      BEGIN
+        NEW.updated_at = NOW();
+        RETURN NEW;
+      END;
+      $$ LANGUAGE plpgsql
+    `);
+        await db.query(`
+      DROP TRIGGER IF EXISTS code_explanations_updated_at ON code_explanations
+    `);
+        await db.query(`
+      CREATE TRIGGER code_explanations_updated_at
+        BEFORE UPDATE ON code_explanations
+        FOR EACH ROW
+        EXECUTE FUNCTION update_code_explanation_modified()
+    `);
+        // Create function to update quality score based on feedback
+        await db.query(`
+      CREATE OR REPLACE FUNCTION update_explanation_quality()
+      RETURNS TRIGGER AS $$
+      BEGIN
+        -- Calculate quality based on positive vs negative feedback
+        IF (NEW.feedback_positive + NEW.feedback_negative) > 0 THEN
+          NEW.quality_score = NEW.feedback_positive::FLOAT /
+            (NEW.feedback_positive + NEW.feedback_negative)::FLOAT;
+        END IF;
+        RETURN NEW;
+      END;
+      $$ LANGUAGE plpgsql
+    `);
+        await db.query(`
+      DROP TRIGGER IF EXISTS explanation_quality_update ON code_explanations
+    `);
+        await db.query(`
+      CREATE TRIGGER explanation_quality_update
+        BEFORE UPDATE ON code_explanations
+        FOR EACH ROW
+        WHEN (OLD.feedback_positive IS DISTINCT FROM NEW.feedback_positive
+              OR OLD.feedback_negative IS DISTINCT FROM NEW.feedback_negative)
+        EXECUTE FUNCTION update_explanation_quality()
+    `);
+        logger.info('Code explanation schema initialized successfully');
+    }
+    catch (error) {
+        logger.error({ error }, 'Failed to initialize code explanation schema');
+        throw error;
+    }
+}
+/**
+ * Check if code explanation schema exists
+ */
+export async function schemaExists(db) {
+    try {
+        const result = await db.query(`
+      SELECT EXISTS (
+        SELECT FROM information_schema.tables
+        WHERE table_name = 'code_explanations'
+      ) as exists
+    `);
+        return result.rows[0]?.exists ?? false;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Get schema statistics
+ */
+export async function getSchemaStats(db) {
+    const [explanations, links, patterns] = await Promise.all([
+        db.query('SELECT COUNT(*) as count FROM code_explanations'),
+        db.query('SELECT COUNT(*) as count FROM code_prompt_links'),
+        db.query('SELECT COUNT(*) as count FROM code_access_patterns')
+    ]);
+    return {
+        explanations: parseInt(explanations.rows[0]?.count ?? '0', 10),
+        links: parseInt(links.rows[0]?.count ?? '0', 10),
+        patterns: parseInt(patterns.rows[0]?.count ?? '0', 10)
+    };
+}
+//# sourceMappingURL=schema.js.map

package/dist/code-explanations/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../src/code-explanations/schema.ts"],"names":[],"mappings":"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"}

package/dist/code-explanations/semanticSearch.d.ts

@@ -0,0 +1,75 @@
+/**
+ * semantic_search_explanations - Search code explanations by meaning
+ *
+ * Uses vector embeddings to find explanations semantically similar
+ * to a search query, enabling natural language code discovery.
+ */
+import { MCPTool } from '../mcp/toolRegistry.js';
+import { DatabaseManager } from '../database.js';
+import { EmbeddingProvider } from '../types/index.js';
+import { SemanticSearchParams, SemanticSearchResult } from './types.js';
+/**
+ * SemanticSearchExplanations - Natural language code search
+ *
+ * Features:
+ * - Vector similarity search
+ * - Quality filtering
+ * - Type filtering
+ * - Relevance scoring
+ */
+export declare class SemanticSearchExplanations implements MCPTool<SemanticSearchParams, SemanticSearchResult> {
+    private db;
+    private embeddingProvider;
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            query: {
+                type: string;
+                description: string;
+            };
+            limit: {
+                type: string;
+                minimum: number;
+                maximum: number;
+                default: number;
+                description: string;
+            };
+            threshold: {
+                type: string;
+                minimum: number;
+                maximum: number;
+                default: number;
+                description: string;
+            };
+            explanationTypes: {
+                type: string;
+                items: {
+                    type: string;
+                    enum: string[];
+                };
+                description: string;
+            };
+            minQuality: {
+                type: string;
+                minimum: number;
+                maximum: number;
+                default: number;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+    constructor(db: DatabaseManager, embeddingProvider: EmbeddingProvider);
+    execute(params: SemanticSearchParams): Promise<SemanticSearchResult>;
+    /**
+     * Update use counts for retrieved explanations
+     */
+    private updateUseCounts;
+    /**
+     * Track query for learning improvement
+     */
+    private trackQuery;
+}
+//# sourceMappingURL=semanticSearch.d.ts.map

package/dist/code-explanations/semanticSearch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"semanticSearch.d.ts","sourceRoot":"","sources":["../../src/code-explanations/semanticSearch.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACjD,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAEtD,OAAO,EAEL,oBAAoB,EACpB,oBAAoB,EAGrB,MAAM,YAAY,CAAC;AAEpB;;;;;;;;GAQG;AACH,qBAAa,0BAA2B,YAAW,OAAO,CAAC,oBAAoB,EAAE,oBAAoB,CAAC;IAkDlG,OAAO,CAAC,EAAE;IACV,OAAO,CAAC,iBAAiB;IAlD3B,IAAI,SAAkC;IACtC,WAAW,SAI8B;IAEzC,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;MAuCT;gBAGQ,EAAE,EAAE,eAAe,EACnB,iBAAiB,EAAE,iBAAiB;IAGxC,OAAO,CAAC,MAAM,EAAE,oBAAoB,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAsI1E;;OAEG;YACW,eAAe;IAS7B;;OAEG;YACW,UAAU;CAgCzB"}

package/dist/code-explanations/semanticSearch.js

@@ -0,0 +1,203 @@
+/**
+ * semantic_search_explanations - Search code explanations by meaning
+ *
+ * Uses vector embeddings to find explanations semantically similar
+ * to a search query, enabling natural language code discovery.
+ */
+import { logger } from '../utils/logger.js';
+import { SemanticSearchInput } from './types.js';
+/**
+ * SemanticSearchExplanations - Natural language code search
+ *
+ * Features:
+ * - Vector similarity search
+ * - Quality filtering
+ * - Type filtering
+ * - Relevance scoring
+ */
+export class SemanticSearchExplanations {
+    db;
+    embeddingProvider;
+    name = 'semantic_search_explanations';
+    description = `Search code explanations using natural language. Find explanations
+semantically similar to your query. Great for questions like:
+- "How does authentication work?"
+- "Where is the database connection handled?"
+- "What are the security considerations?"`;
+    inputSchema = {
+        type: 'object',
+        properties: {
+            query: {
+                type: 'string',
+                description: 'Natural language search query'
+            },
+            limit: {
+                type: 'number',
+                minimum: 1,
+                maximum: 100,
+                default: 10,
+                description: 'Maximum results to return'
+            },
+            threshold: {
+                type: 'number',
+                minimum: 0,
+                maximum: 1,
+                default: 0.7,
+                description: 'Minimum similarity threshold (0-1)'
+            },
+            explanationTypes: {
+                type: 'array',
+                items: {
+                    type: 'string',
+                    enum: ['general', 'architectural', 'algorithmic', 'usage', 'gotchas',
+                        'performance', 'security', 'debugging', 'history', 'todo']
+                },
+                description: 'Filter by explanation type(s)'
+            },
+            minQuality: {
+                type: 'number',
+                minimum: 0,
+                maximum: 1,
+                default: 0,
+                description: 'Minimum quality score (0-1)'
+            }
+        },
+        required: ['query']
+    };
+    constructor(db, embeddingProvider) {
+        this.db = db;
+        this.embeddingProvider = embeddingProvider;
+    }
+    async execute(params) {
+        const validatedParams = SemanticSearchInput.parse(params);
+        logger.debug({ query: validatedParams.query }, 'Performing semantic search');
+        try {
+            // Generate embedding for query
+            const queryEmbedding = await this.embeddingProvider.generateEmbedding(validatedParams.query);
+            if (!queryEmbedding || queryEmbedding.length === 0) {
+                logger.warn('Failed to generate query embedding');
+                return {
+                    success: false,
+                    results: [],
+                    total: 0,
+                    message: 'Failed to generate query embedding'
+                };
+            }
+            const embeddingStr = `[${queryEmbedding.join(',')}]`;
+            // Build query
+            let searchQuery = `
+        SELECT
+          ce.*,
+          cf.content as code_content,
+          1 - (ce.embedding <=> $1::vector) as similarity
+        FROM code_explanations ce
+        LEFT JOIN codebase_files cf ON ce.code_id = cf.id
+        WHERE ce.embedding IS NOT NULL
+        AND 1 - (ce.embedding <=> $1::vector) >= $2
+        AND ce.quality_score >= $3
+      `;
+            const values = [
+                embeddingStr,
+                validatedParams.threshold,
+                validatedParams.minQuality
+            ];
+            let paramIndex = 4;
+            if (validatedParams.explanationTypes && validatedParams.explanationTypes.length > 0) {
+                searchQuery += ` AND ce.explanation_type = ANY($${paramIndex++})`;
+                values.push(validatedParams.explanationTypes);
+            }
+            searchQuery += `
+        ORDER BY similarity DESC
+        LIMIT $${paramIndex}
+      `;
+            values.push(validatedParams.limit);
+            const result = await this.db.query(searchQuery, values);
+            const results = result.rows.map((row) => ({
+                explanation: {
+                    id: row.id,
+                    codeId: row.code_id ?? undefined,
+                    filePath: row.file_path,
+                    lineStart: row.line_start ?? undefined,
+                    lineEnd: row.line_end ?? undefined,
+                    codeSnippet: row.code_snippet ?? undefined,
+                    explanationText: row.explanation_text,
+                    explanationType: row.explanation_type,
+                    qualityScore: row.quality_score,
+                    useCount: row.use_count,
+                    feedbackPositive: row.feedback_positive,
+                    feedbackNegative: row.feedback_negative,
+                    createdAt: row.created_at,
+                    updatedAt: row.updated_at,
+                    createdBy: row.created_by,
+                    metadata: row.metadata
+                },
+                similarity: row.similarity,
+                codeSnippet: row.code_snippet ?? row.code_content?.slice(0, 500) ?? undefined
+            }));
+            // Update use counts
+            const explanationIds = results.map((r) => r.explanation.id);
+            if (explanationIds.length > 0) {
+                await this.updateUseCounts(explanationIds);
+            }
+            // Track this query for learning
+            await this.trackQuery(validatedParams.query, queryEmbedding, results.map((r) => r.explanation.codeId).filter(Boolean));
+            logger.info({
+                resultCount: results.length,
+                topSimilarity: results[0]?.similarity ?? 0
+            }, 'Semantic search completed');
+            return {
+                success: true,
+                results,
+                total: results.length,
+                message: `Found ${results.length} matching explanation(s)`
+            };
+        }
+        catch (error) {
+            logger.error({ error, query: validatedParams.query }, 'Semantic search failed');
+            return {
+                success: false,
+                results: [],
+                total: 0,
+                message: error instanceof Error ? error.message : 'Search failed'
+            };
+        }
+    }
+    /**
+     * Update use counts for retrieved explanations
+     */
+    async updateUseCounts(explanationIds) {
+        await this.db.query(`UPDATE code_explanations
+       SET use_count = use_count + 1
+       WHERE id = ANY($1)`, [explanationIds]);
+    }
+    /**
+     * Track query for learning improvement
+     */
+    async trackQuery(query, embedding, foundCodeIds) {
+        // Store query in access patterns for learning
+        for (const codeId of foundCodeIds) {
+            try {
+                await this.db.query(`INSERT INTO code_access_patterns (
+            code_id, common_queries, query_embeddings, access_count, last_accessed
+          ) VALUES ($1, $2, $3, 1, NOW())
+          ON CONFLICT (code_id) DO UPDATE SET
+            access_count = code_access_patterns.access_count + 1,
+            last_accessed = NOW(),
+            common_queries = CASE
+              WHEN NOT ($4 = ANY(code_access_patterns.common_queries))
+              THEN array_append(
+                (SELECT common_queries[array_length(common_queries, 1) - 49:array_length(common_queries, 1)]
+                 FROM code_access_patterns WHERE code_id = $1),
+                $4
+              )
+              ELSE code_access_patterns.common_queries
+            END`, [codeId, [query], [embedding], query]);
+            }
+            catch (error) {
+                // Log but don't fail the search
+                logger.warn({ error, codeId }, 'Failed to track query');
+            }
+        }
+    }
+}
+//# sourceMappingURL=semanticSearch.js.map

package/dist/code-explanations/semanticSearch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"semanticSearch.js","sourceRoot":"","sources":["../../src/code-explanations/semanticSearch.ts"],"names":[],"mappings":"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"}