@vheins/local-memory-mcp 0.1.0

package/src/storage/vectors.stub.ts

@@ -0,0 +1,101 @@
+import { VectorStore, VectorResult } from "../types.js";
+import { SQLiteStore } from "./sqlite.js";
+
+// Simple vector store using SQLite - lightweight embeddings without ollama
+export class StubVectorStore implements VectorStore {
+  private db: SQLiteStore;
+
+  constructor(db?: SQLiteStore) {
+    if (!db) {
+      throw new Error("SQLiteStore required for vector operations");
+    }
+    this.db = db;
+  }
+
+  // Generate simple text-based vector (TF-IDF style) without external embeddings
+  private generateTextVector(text: string): string[] {
+    const normalized = text.toLowerCase()
+      // Remove punctuation and special characters, but keep Indonesian characters
+      .replace(/[^\w\s\u00C0-\u017F]/g, ' ')
+      // Normalize multiple spaces to single space
+      .replace(/\s+/g, ' ')
+      .trim()
+      .split(/\s+/)
+      .filter(word => word.length > 2);
+    
+    const stopwords = new Set([
+      // English stopwords
+      'the', 'is', 'at', 'which', 'on', 'and', 'or', 'but', 'for', 'with', 
+      'to', 'from', 'by', 'as', 'in', 'of', 'a', 'an', 'be', 'this', 'that',
+      'are', 'was', 'were', 'been', 'have', 'has', 'had', 'do', 'does', 'did',
+      // Indonesian stopwords
+      'yang', 'di', 'ke', 'dari', 'untuk', 'dengan', 'oleh', 'pada', 'dalam', 'atas',
+      'bawah', 'depan', 'belakang', 'samping', 'sebelah', 'antara', 'diantara', 'melalui',
+      'selama', 'sampai', 'hingga', 'sejak', 'sebelum', 'sesudah', 'setelah', 'sebelumnya',
+      'kemudian', 'selanjutnya', 'lagi', 'juga', 'pun', 'bahkan', 'malah', 'bahwa',
+      'karena', 'sebab', 'oleh', 'karena', 'sehingga', 'maka', 'lalu', 'kemudian',
+      'saya', 'kamu', 'dia', 'kami', 'kalian', 'mereka', 'aku', 'engkau', 'ia', 'kita',
+      'anda', 'beliau', 'mereka', 'siapa', 'apa', 'dimana', 'kapan', 'bagaimana', 'mengapa',
+      'berapa', 'banyak', 'sedikit', 'semua', 'beberapa', 'banyak', 'sedikit', 'hampir',
+      'hanya', 'sudah', 'belum', 'masih', 'lagi', 'selalu', 'kadang', 'sering', 'jarang',
+      'pernah', 'belum', 'sudah', 'akan', 'sedang', 'telah', 'baru', 'lama', 'cepat',
+      'lambat', 'besar', 'kecil', 'panjang', 'pendek', 'tinggi', 'rendah', 'lebar', 'sempit',
+      'tebal', 'tipis', 'berat', 'ringan', 'kuat', 'lemah', 'baik', 'buruk', 'benar', 'salah',
+      'cantik', 'jelek', 'indah', 'buruk', 'bagus', 'jelek', 'suka', 'tidak', 'bukan',
+      'jangan', 'harus', 'boleh', 'bisa', 'mampu', 'dapat', 'mau', 'ingin', 'perlu', 'penting',
+      // Additional common Indonesian words
+      'dan', 'atau', 'tapi', 'namun', 'lalu', 'kemudian', 'jadi', 'maka', 'yaitu', 'yakni'
+    ]);
+    
+    return normalized.filter(word => !stopwords.has(word));
+  }
+
+  // Calculate similarity between two token sets
+  private calculateSimilarity(tokens1: string[], tokens2: string[]): number {
+    if (tokens1.length === 0 || tokens2.length === 0) return 0;
+    
+    const set1 = new Set(tokens1);
+    const set2 = new Set(tokens2);
+    
+    // Jaccard similarity: intersection / union
+    const intersection = new Set([...set1].filter(x => set2.has(x)));
+    const union = new Set([...set1, ...set2]);
+    
+    return union.size > 0 ? intersection.size / union.size : 0;
+  }
+
+  async upsert(id: string, text: string): Promise<void> {
+    try {
+      // Generate simple vector from text tokens
+      const tokens = this.generateTextVector(text);
+      
+      // Store tokens as JSON array for better retrieval
+      this.db.upsertVectorEmbedding(id, tokens);
+    } catch (error) {
+      console.error("Error upserting vector:", error);
+      // Silently fail - vector is optional for search fallback
+    }
+  }
+
+  async remove(id: string): Promise<void> {
+    // Vectors are automatically removed by CASCADE when memory is deleted
+  }
+
+  async search(query: string, limit: number): Promise<VectorResult[]> {
+    try {
+      // Get all memories and compute similarity to query
+      const queryTokens = this.generateTextVector(query);
+      
+      if (queryTokens.length === 0) {
+        return [];
+      }
+      
+      // For now, return empty - we'll use similarity search in SQLite instead
+      // In production, you could implement approximate nearest neighbor search here
+      return [];
+    } catch (error) {
+      console.error("Error searching vectors:", error);
+      return [];
+    }
+  }
+}

package/src/tools/memory.delete.ts

@@ -0,0 +1,37 @@
+import { z } from "zod";
+import { SQLiteStore } from "../storage/sqlite.js";
+import { VectorStore } from "../types.js";
+import { createMcpResponse, McpResponse } from "../utils/mcp-response.js";
+
+export const MemoryDeleteSchema = z.object({
+  id: z.string().uuid()
+});
+
+export async function handleMemoryDelete(
+  params: any,
+  db: SQLiteStore,
+  vectors: VectorStore
+): Promise<McpResponse> {
+  // Validate input
+  const validated = MemoryDeleteSchema.parse(params);
+
+  // Check if memory exists
+  const existing = db.getById(validated.id);
+  if (!existing) {
+    throw new Error(`Memory not found: ${validated.id}`);
+  }
+
+  // Delete from SQLite
+  db.delete(validated.id);
+
+  // Delete from vector store
+  await vectors.remove(validated.id);
+
+  // Log the delete action
+  db.logAction('delete', existing.scope.repo, { memoryId: validated.id, resultCount: 1 });
+
+  return createMcpResponse(
+    { success: true },
+    `Deleted memory ${validated.id.slice(0, 8)}...`
+  );
+}

package/src/tools/memory.recap.ts

@@ -0,0 +1,61 @@
+import { MemoryRecapSchema } from "./schemas.js";
+import { SQLiteStore } from "../storage/sqlite.js";
+import { createMcpResponse, McpResponse } from "../utils/mcp-response.js";
+
+export async function handleMemoryRecap(
+  params: any,
+  db: SQLiteStore
+): Promise<McpResponse> {
+  // Validate input
+  const validated = MemoryRecapSchema.parse(params);
+
+  // Get total count for pagination metadata
+  const total = db.getTotalCount(validated.repo);
+
+  // Get recent memories using public API (no type-unsafe cast)
+  const rows = db.getRecentMemories(validated.repo, validated.limit, validated.offset);
+
+  if (rows.length === 0) {
+    return createMcpResponse(
+      {
+        repo: validated.repo,
+        count: 0,
+        total,
+        offset: validated.offset,
+        memories: [],
+        message: `No memories found for repo: ${validated.repo}`
+      },
+      `No memories for repo "${validated.repo}"`
+    );
+  }
+
+  // Format memories for recap
+  const formattedMemories = rows.map((row, index) => ({
+    number: validated.offset + index + 1,
+    id: row.id,
+    type: row.type,
+    importance: row.importance,
+    preview: row.content.substring(0, 100) + (row.content.length > 100 ? "..." : ""),
+    created_at: row.created_at
+  }));
+
+  // Create summary text
+  const summary = formattedMemories
+    .map(
+      (m) =>
+        `${m.number}. [${m.type.toUpperCase()}] (importance: ${m.importance}) ${m.preview}`
+    )
+    .join("\n");
+
+  return createMcpResponse(
+    {
+      repo: validated.repo,
+      count: rows.length,
+      total,
+      offset: validated.offset,
+      memories: formattedMemories,
+      summary: `Recent ${rows.length} memories:\n\n${summary}`
+    },
+    `Retrieved ${rows.length} memories for repo "${validated.repo}"`
+  );
+}

package/src/tools/memory.search.test.ts

@@ -0,0 +1,276 @@
+import { describe, it, expect } from "vitest";
+import * as fc from "fast-check";
+
+// ─── Property 2: Recap conditional ───────────────────────────────────────────
+// Feature: memory-mcp-optimization, Property 2: Recap conditional
+
+// We test the weight constants directly by importing them from the module.
+// For Property 2 we need to verify the conditional recap call logic.
+// We do this by extracting the logic into a testable helper and verifying
+// the branching behaviour with fast-check.
+
+/**
+ * Mirrors the weight selection logic from memory.search.ts.
+ * Returns the weights object that would be used given whether vector results
+ * are present or not.
+ */
+function selectWeights(vectorResultsEmpty: boolean): {
+  similarity: number;
+  vector?: number;
+  importance: number;
+} {
+  if (vectorResultsEmpty) {
+    return { similarity: 0.85, importance: 0.15 };
+  }
+  return { similarity: 0.6, vector: 0.3, importance: 0.1 };
+}
+
+/**
+ * Mirrors the recap-call decision from memory.search.ts.
+ * Returns true if handleMemoryRecap should be called.
+ */
+function shouldCallRecap(includeRecap: boolean | undefined): boolean {
+  return includeRecap === true;
+}
+
+// ─── Property 2 tests ────────────────────────────────────────────────────────
+
+describe("Property 2: Recap dipanggil jika dan hanya jika includeRecap = true", () => {
+  // Feature: memory-mcp-optimization, Property 2: Recap conditional
+  // Validates: Requirements 2.1, 2.2, 2.3
+
+  it("should NOT call recap when includeRecap is false or absent", () => {
+    fc.assert(
+      fc.property(
+        fc.oneof(
+          fc.constant<boolean | undefined>(false),
+          fc.constant<boolean | undefined>(undefined)
+        ),
+        (includeRecap: boolean | undefined) => {
+          expect(shouldCallRecap(includeRecap)).toBe(false);
+        }
+      ),
+      { numRuns: 100 }
+    );
+  });
+
+  it("should call recap when includeRecap is true", () => {
+    fc.assert(
+      fc.property(
+        fc.constant<boolean>(true),
+        (includeRecap: boolean) => {
+          expect(shouldCallRecap(includeRecap)).toBe(true);
+        }
+      ),
+      { numRuns: 100 }
+    );
+  });
+
+  it("recap is called if and only if includeRecap === true (combined property)", () => {
+    fc.assert(
+      fc.property(
+        fc.oneof(
+          fc.constant<boolean | undefined>(true),
+          fc.constant<boolean | undefined>(false),
+          fc.constant<boolean | undefined>(undefined)
+        ),
+        (includeRecap: boolean | undefined) => {
+          const called = shouldCallRecap(includeRecap);
+          // The iff condition: called ↔ (includeRecap === true)
+          expect(called).toBe(includeRecap === true);
+        }
+      ),
+      { numRuns: 200 }
+    );
+  });
+});
+
+// ─── Property 3: Hybrid score weights sum to 1.0 ─────────────────────────────
+
+describe("Property 3: Total bobot Hybrid Score selalu = 1.0", () => {
+  // Feature: memory-mcp-optimization, Property 3: Hybrid score weights sum to 1.0
+  // Validates: Requirements 3.1, 3.2, 3.4
+
+  it("weights sum to 1.0 when vector store is empty (no vector results)", () => {
+    fc.assert(
+      fc.property(
+        fc.constant<boolean>(true), // vectorResultsEmpty = true
+        (vectorResultsEmpty: boolean) => {
+          const weights = selectWeights(vectorResultsEmpty);
+          const sum = weights.similarity + (weights.vector ?? 0) + weights.importance;
+          expect(Math.abs(sum - 1.0)).toBeLessThan(1e-10);
+        }
+      ),
+      { numRuns: 100 }
+    );
+  });
+
+  it("weights sum to 1.0 when vector store is active (has vector results)", () => {
+    fc.assert(
+      fc.property(
+        fc.constant<boolean>(false), // vectorResultsEmpty = false
+        (vectorResultsEmpty: boolean) => {
+          const weights = selectWeights(vectorResultsEmpty);
+          const sum = weights.similarity + (weights.vector ?? 0) + weights.importance;
+          expect(Math.abs(sum - 1.0)).toBeLessThan(1e-10);
+        }
+      ),
+      { numRuns: 100 }
+    );
+  });
+
+  it("weights always sum to 1.0 for both vector conditions", () => {
+    fc.assert(
+      fc.property(
+        fc.boolean(), // arbitrary vectorResultsEmpty flag
+        (vectorResultsEmpty: boolean) => {
+          const weights = selectWeights(vectorResultsEmpty);
+          const sum = weights.similarity + (weights.vector ?? 0) + weights.importance;
+          expect(Math.abs(sum - 1.0)).toBeLessThan(1e-10);
+        }
+      ),
+      { numRuns: 200 }
+    );
+  });
+
+  it("vector-active weights are exactly 0.6 + 0.3 + 0.1 = 1.0", () => {
+    const weights = selectWeights(false);
+    expect(weights.similarity).toBe(0.6);
+    expect(weights.vector).toBe(0.3);
+    expect(weights.importance).toBe(0.1);
+    expect(weights.similarity + (weights.vector ?? 0) + weights.importance).toBeCloseTo(1.0, 10);
+  });
+
+  it("vector-empty weights are exactly 0.85 + 0.15 = 1.0", () => {
+    const weights = selectWeights(true);
+    expect(weights.similarity).toBe(0.85);
+    expect(weights.vector).toBeUndefined();
+    expect(weights.importance).toBe(0.15);
+    expect(weights.similarity + weights.importance).toBe(1.0);
+  });
+});
+
+// ─── Prompt parameter tests ─────────────────────────────────────────────────
+
+describe("Property: prompt parameter in memory-search", () => {
+  it("prompt is optional - search works without prompt", () => {
+    const params = {
+      query: "database orm",
+      repo: "test-repo",
+      limit: 5
+    };
+    
+    // If prompt is not provided, searchQuery should equal query
+    const hasPrompt = 'prompt' in params && params.prompt;
+    const searchQuery = hasPrompt
+      ? `${params.query} ${params.prompt}`
+      : params.query;
+    
+    expect(searchQuery).toBe("database orm");
+  });
+
+  it("prompt is combined with query when provided", () => {
+    const params = {
+      query: "database orm",
+      prompt: "I need user authentication",
+      repo: "test-repo",
+      limit: 5
+    };
+    
+    const searchQuery = params.prompt
+      ? `${params.query} ${params.prompt}`
+      : params.query;
+    
+    expect(searchQuery).toBe("database orm I need user authentication");
+  });
+
+  it("prompt can be empty string - treated as no prompt (empty string is falsy)", () => {
+    const params = {
+      query: "database orm",
+      prompt: "",
+      repo: "test-repo",
+      limit: 5
+    };
+    
+    // Empty string is falsy in JS, so it uses just query
+    const searchQuery = params.prompt
+      ? `${params.query} ${params.prompt}`
+      : params.query;
+    
+    expect(searchQuery).toBe("database orm");
+  });
+
+  it("matchReason includes prompt when provided", () => {
+    const query = "database orm";
+    const prompt = "user authentication context";
+    
+    const matchReason = prompt 
+      ? `Results ranked by relevance to "${query}" with context: ${prompt}`
+      : `Results ranked by relevance to "${query}"`;
+    
+    expect(matchReason).toContain("database orm");
+    expect(matchReason).toContain("user authentication context");
+    expect(matchReason).toContain("with context:");
+  });
+
+  it("matchReason does not include prompt when not provided", () => {
+    const query = "database orm";
+    const prompt = undefined;
+    
+    const matchReason = prompt 
+      ? `Results ranked by relevance to "${query}" with context: ${prompt}`
+      : `Results ranked by relevance to "${query}"`;
+    
+    expect(matchReason).toBe(`Results ranked by relevance to "${query}"`);
+    expect(matchReason).not.toContain("with context:");
+  });
+
+  it("property: searchQuery combines query and prompt consistently", () => {
+    fc.assert(
+      fc.property(
+        fc.string({ minLength: 3, maxLength: 50 }),
+        fc.string({ minLength: 1, maxLength: 100 }),
+        (query, prompt) => {
+          const searchQuery = `${query} ${prompt}`;
+          
+          // Search query should always start with the original query
+          expect(searchQuery.startsWith(query)).toBe(true);
+          
+          // Search query should contain the prompt
+          expect(searchQuery.includes(prompt)).toBe(true);
+          
+          // There should be exactly one space between query and prompt
+          expect(searchQuery).toBe(`${query} ${prompt}`);
+        }
+      ),
+      { numRuns: 50 }
+    );
+  });
+
+  it("property: matchReason format is correct with and without prompt", () => {
+    fc.assert(
+      fc.property(
+        fc.string({ minLength: 1, maxLength: 30 }),
+        fc.option(fc.string({ minLength: 1, maxLength: 50 })),
+        (query, prompt) => {
+          const matchReason = prompt 
+            ? `Results ranked by relevance to "${query}" with context: ${prompt}`
+            : `Results ranked by relevance to "${query}"`;
+          
+          // Should always contain the query
+          expect(matchReason).toContain(query);
+          
+          if (prompt) {
+            // Should contain "with context:" when prompt exists
+            expect(matchReason).toContain("with context:");
+            expect(matchReason).toContain(prompt);
+          } else {
+            // Should NOT contain "with context:" when prompt is absent
+            expect(matchReason).not.toContain("with context:");
+          }
+        }
+      ),
+      { numRuns: 50 }
+    );
+  });
+});