@vheins/local-memory-mcp 0.1.0

package/src/tools/memory.search.ts

@@ -0,0 +1,244 @@
+import { MemorySearchSchema } from "./schemas.js";
+import { SQLiteStore } from "../storage/sqlite.js";
+import { VectorStore, MemoryEntry } from "../types.js";
+import { normalize } from "../utils/normalize.js";
+import { handleMemoryRecap } from "./memory.recap.js";
+import { logger } from "../utils/logger.js";
+import { createMcpResponse, McpResponse } from "../utils/mcp-response.js";
+import { expandQuery } from "../utils/query-expander.js";
+
+// Hybrid search configuration — weights when vector store is active
+const HYBRID_WEIGHTS_VECTOR = {
+  similarity: 0.6,
+  vector: 0.3,
+  importance: 0.1
+};
+
+// Weights when vector store returns no results (normalized to sum = 1.0)
+const HYBRID_WEIGHTS_NO_VECTOR = {
+  similarity: 0.85,
+  importance: 0.15
+};
+
+interface ScoredMemory {
+  memory: MemoryEntry;
+  similarityScore: number;
+  vectorScore: number;
+  importanceBoost: number;
+  finalScore: number;
+}
+
+export async function handleMemorySearch(
+  params: any,
+  db: SQLiteStore,
+  vectors: VectorStore
+): Promise<McpResponse> {
+  // Validate input
+  const validated = MemorySearchSchema.parse(params);
+
+  // STEP 0: Pre-search recap — only if includeRecap === true
+  let recapContext = "";
+  if (validated.includeRecap) {
+    try {
+      const recapResult = await handleMemoryRecap(
+        { repo: validated.repo, limit: 20 },
+        db
+      );
+
+      // Find text content that contains JSON data
+      const textContent = recapResult.content.find((c) => c.type === "text" && c.text);
+      if (textContent && textContent.type === "text") {
+        try {
+          const recapData = JSON.parse(textContent.text) as { summary?: string };
+          if (recapData.summary) {
+            recapContext = recapData.summary;
+          }
+        } catch {
+          // Not JSON, might be plain text summary
+          recapContext = textContent.text;
+        }
+      }
+    } catch (error) {
+      logger.error("Failed to get recap context", { error: String(error) });
+      // Continue anyway - recap is optional
+    }
+  }
+
+  // Expand query using prompt intent
+  const searchQuery = expandQuery(validated.query, validated.prompt);
+
+  // STEP 1: Repo filter (HARD) + Lightweight similarity scoring
+  const similarityResults = db.searchBySimilarity(
+    searchQuery,
+    validated.repo,
+    validated.limit * 3 // Get more candidates for vector re-ranking
+  );
+
+  let candidates: Array<{ memory: MemoryEntry; similarityScore: number }>;
+
+  if (similarityResults.length > 0 && similarityResults[0].similarity > 0.1) {
+    // Use similarity results as candidates
+    candidates = similarityResults.map((result) => ({
+      memory: {
+        id: result.id,
+        type: result.type,
+        title: result.title,
+        content: result.content,
+        importance: result.importance,
+        scope: result.scope,
+        created_at: result.created_at,
+        updated_at: result.updated_at,
+        hit_count: result.hit_count,
+        recall_count: result.recall_count,
+        last_used_at: result.last_used_at,
+        expires_at: result.expires_at,
+      },
+      similarityScore: result.similarity
+    }));
+  } else {
+    // Fallback: keyword search as candidates
+    const allResults = db.searchByRepo(validated.repo, {
+      types: validated.types,
+      minImportance: validated.minImportance,
+      limit: validated.limit * 3
+    });
+
+    const normalized = normalize(searchQuery);
+    const queryWords = normalized.split(/\s+/).filter(w => w.length > 2);
+
+    const filtered = allResults.filter((entry) => {
+      const normalizedContent = normalize(entry.content);
+      return queryWords.some(word => normalizedContent.includes(word));
+    });
+
+    const memoriesToUse = filtered.length > 0 ? filtered : allResults;
+
+    candidates = memoriesToUse.map(memory => ({
+      memory,
+      similarityScore: 0.5 // Default similarity for keyword matches
+    }));
+  }
+
+  // STEP 2: OPTIONAL vector similarity re-rank (only on top candidates)
+  let scoredMemories: ScoredMemory[];
+
+  try {
+    // Attempt vector search on candidates (if available)
+    const vectorResults = await vectors.search(searchQuery, candidates.length);
+
+    if (vectorResults.length > 0) {
+      // Create a map of memory ID to vector score
+      const vectorScoreMap = new Map<string, number>();
+      for (const vr of vectorResults) {
+        vectorScoreMap.set(vr.id, vr.score);
+      }
+
+      // Combine scores using hybrid formula (vector active: 0.6 + 0.3 + 0.1 = 1.0)
+      scoredMemories = candidates.map(({ memory, similarityScore }) => {
+        const vectorScore = vectorScoreMap.get(memory.id) || 0;
+        const importanceBoost = memory.importance / 5;
+
+        const finalScore =
+          (similarityScore * HYBRID_WEIGHTS_VECTOR.similarity) +
+          (vectorScore * HYBRID_WEIGHTS_VECTOR.vector) +
+          (importanceBoost * HYBRID_WEIGHTS_VECTOR.importance);
+
+        return {
+          memory,
+          similarityScore,
+          vectorScore,
+          importanceBoost,
+          finalScore
+        };
+      });
+    } else {
+      // No vector results — use similarity-only ranking (0.85 + 0.15 = 1.0)
+      scoredMemories = candidates.map(({ memory, similarityScore }) => {
+        const importanceBoost = memory.importance / 5;
+
+        const finalScore =
+          (similarityScore * HYBRID_WEIGHTS_NO_VECTOR.similarity) +
+          (importanceBoost * HYBRID_WEIGHTS_NO_VECTOR.importance);
+
+        return {
+          memory,
+          similarityScore,
+          vectorScore: 0,
+          importanceBoost,
+          finalScore
+        };
+      });
+    }
+  } catch (error) {
+    // Vector search failed — gracefully degrade to similarity-only
+    logger.warn("Vector search failed, using similarity-only", { error: String(error) });
+
+    scoredMemories = candidates.map(({ memory, similarityScore }) => {
+      const importanceBoost = memory.importance / 5;
+
+      const finalScore =
+        (similarityScore * HYBRID_WEIGHTS_NO_VECTOR.similarity) +
+        (importanceBoost * HYBRID_WEIGHTS_NO_VECTOR.importance);
+
+      return {
+        memory,
+        similarityScore,
+        vectorScore: 0,
+        importanceBoost,
+        finalScore
+      };
+    });
+  }
+
+  // STEP 3: Sort by final score and take top results
+  scoredMemories.sort((a, b) => b.finalScore - a.finalScore);
+
+  const results = scoredMemories
+    .slice(0, validated.limit)
+    .map(sm => sm.memory);
+
+  // STEP 4: Increment hit_count for returned memories
+  for (const memory of results) {
+    db.incrementHitCount(memory.id);
+  }
+
+  // STEP 5: Log the query for recent queries feature
+  db.logAction('search', validated.repo, { query: validated.query, resultCount: results.length });
+
+  const resultData = {
+    query: validated.query,
+    prompt: validated.prompt || null,
+    results,
+    matchReason: validated.prompt 
+      ? `Results ranked by relevance to "${validated.query}" with context: ${validated.prompt}`
+      : `Results ranked by relevance to "${validated.query}"`,
+    recapContext: recapContext ? `Recent memories context:\n${recapContext}` : undefined
+  };
+
+  const firstResult = results[0];
+  const resultName = firstResult?.title 
+    ? `${firstResult.type} - ${firstResult.title}` 
+    : (firstResult ? `${firstResult.type} - ${firstResult.content.substring(0, 40)}...` : `Found ${results.length} results`);
+    
+  return createMcpResponse(
+    resultData,
+    `Found ${results.length} memories matching "${validated.query}"`,
+    { 
+      query: validated.query,
+      results: results.map(r => ({
+        id: r.id,
+        type: r.type,
+        title: r.title,
+        content: r.content,
+        importance: r.importance,
+        scope: r.scope,
+        created_at: r.created_at,
+        updated_at: r.updated_at,
+        hit_count: r.hit_count,
+        recall_count: r.recall_count,
+        last_used_at: r.last_used_at,
+        expires_at: r.expires_at
+      }))
+    }
+  );
+}

package/src/tools/memory.store.ts

@@ -0,0 +1,56 @@
+import { randomUUID } from "crypto";
+import { MemoryStoreSchema } from "./schemas.js";
+import { SQLiteStore } from "../storage/sqlite.js";
+import { VectorStore, MemoryEntry } from "../types.js";
+import { logger } from "../utils/logger.js";
+import { createMcpResponse, McpResponse } from "../utils/mcp-response.js";
+
+export async function handleMemoryStore(
+  params: any,
+  db: SQLiteStore,
+  vectors: VectorStore
+): Promise<McpResponse> {
+  // Validate input
+  const validated = MemoryStoreSchema.parse(params);
+
+  // Create memory entry
+  const now = new Date().toISOString();
+
+  // Compute expires_at if ttlDays is provided
+  const expires_at = validated.ttlDays != null
+    ? new Date(Date.now() + validated.ttlDays * 86400000).toISOString()
+    : null;
+
+  const entry: MemoryEntry = {
+    id: randomUUID(),
+    type: validated.type,
+    content: validated.content,
+    importance: validated.importance,
+    scope: validated.scope,
+    created_at: now,
+    updated_at: now,
+    hit_count: 0,
+    recall_count: 0,
+    last_used_at: null,
+    expires_at,
+  };
+
+  // Store in SQLite
+  db.insert(entry);
+
+  // Automatically generate and store vector embedding
+  try {
+    await vectors.upsert(entry.id, entry.content);
+  } catch (error) {
+    logger.warn("Failed to generate vector embedding", { error: String(error) });
+    // Continue anyway - vectors are optional for search fallback
+  }
+
+  // Log the write action
+  db.logAction('write', validated.scope.repo, { memoryId: entry.id, resultCount: 1 });
+
+  return createMcpResponse(
+    { success: true, id: entry.id },
+    `Stored memory ${entry.id.slice(0, 8)}...`
+  );
+}

package/src/tools/memory.summarize.ts

@@ -0,0 +1,23 @@
+import { MemorySummarizeSchema } from "./schemas.js";
+import { SQLiteStore } from "../storage/sqlite.js";
+import { createMcpResponse, McpResponse } from "../utils/mcp-response.js";
+
+export async function handleMemorySummarize(
+  params: any,
+  db: SQLiteStore
+): Promise<McpResponse> {
+  // Validate input
+  const validated = MemorySummarizeSchema.parse(params);
+
+  // Create summary from signals
+  const summary = validated.signals.join("\n- ");
+  const fullSummary = `Project summary:\n- ${summary}`;
+
+  // Store summary
+  db.upsertSummary(validated.repo, fullSummary);
+
+  return createMcpResponse(
+    { success: true },
+    `Updated summary for repo "${validated.repo}"`
+  );
+}

package/src/tools/memory.update.ts

@@ -0,0 +1,46 @@
+import { MemoryUpdateSchema } from "./schemas.js";
+import { SQLiteStore } from "../storage/sqlite.js";
+import { VectorStore } from "../types.js";
+import { createMcpResponse, McpResponse } from "../utils/mcp-response.js";
+
+export async function handleMemoryUpdate(
+  params: any,
+  db: SQLiteStore,
+  vectors: VectorStore
+): Promise<McpResponse> {
+  // Validate input
+  const validated = MemoryUpdateSchema.parse(params);
+
+  // Check if memory exists
+  const existing = db.getById(validated.id);
+  if (!existing) {
+    throw new Error(`Memory not found: ${validated.id}`);
+  }
+
+  // Update in SQLite
+  const updates: { title?: string; content?: string; importance?: number } = {};
+  if (validated.title !== undefined) {
+    updates.title = validated.title;
+  }
+  if (validated.content !== undefined) {
+    updates.content = validated.content;
+  }
+  if (validated.importance !== undefined) {
+    updates.importance = validated.importance;
+  }
+
+  db.update(validated.id, updates);
+
+  // Update vector if content changed
+  if (validated.content !== undefined) {
+    await vectors.upsert(validated.id, validated.content);
+  }
+
+  // Log the update action
+  db.logAction('update', existing.scope.repo, { memoryId: validated.id, resultCount: 1 });
+
+  return createMcpResponse(
+    { success: true },
+    `Updated memory ${validated.id.slice(0, 8)}...`
+  );
+}

package/src/tools/schemas.ts

@@ -0,0 +1,261 @@
+import { z } from "zod";
+
+// Shared schema components
+export const MemoryScopeSchema = z.object({
+  repo: z.string().min(1),
+  branch: z.string().optional(),
+  folder: z.string().optional(),
+  language: z.string().optional()
+});
+
+export const MemoryTypeSchema = z.enum(["code_fact", "decision", "mistake", "pattern"]);
+
+// Tool schemas
+export const MemoryStoreSchema = z.object({
+  type: MemoryTypeSchema,
+  title: z.string().min(3).max(100),
+  content: z.string().min(10),
+  importance: z.number().min(1).max(5),
+  scope: MemoryScopeSchema,
+  ttlDays: z.number().min(1).optional()
+});
+
+export const MemoryUpdateSchema = z.object({
+  id: z.string().uuid(),
+  title: z.string().min(3).max(100).optional(),
+  content: z.string().min(10).optional(),
+  importance: z.number().min(1).max(5).optional()
+}).refine(
+  (data) => data.content !== undefined || data.title !== undefined || data.importance !== undefined,
+  { message: "At least one of title, content or importance must be provided" }
+);
+
+export const MemorySearchSchema = z.object({
+  query: z.string().min(3),
+  prompt: z.string().optional(),
+  repo: z.string().min(1),
+  types: z.array(MemoryTypeSchema).optional(),
+  minImportance: z.number().min(1).max(5).optional(),
+  limit: z.number().min(1).max(10).default(5),
+  includeRecap: z.boolean().default(false)
+});
+
+export const MemoryRecapSchema = z.object({
+  repo: z.string().min(1),
+  limit: z.number().min(1).max(50).default(20),
+  offset: z.number().min(0).default(0)
+});
+
+export const MemorySummarizeSchema = z.object({
+  repo: z.string().min(1),
+  signals: z.array(z.string().max(200)).min(1)
+});
+
+// Tool definitions for MCP
+export const TOOL_DEFINITIONS = [
+  {
+    name: "memory-store",
+    description: "Store a new memory entry that affects future behavior",
+    inputSchema: {
+      type: "object",
+      properties: {
+        type: {
+          type: "string",
+          enum: ["code_fact", "decision", "mistake", "pattern"],
+          description: "Type of memory being stored"
+        },
+        title: {
+          type: "string",
+          minLength: 3,
+          maxLength: 100,
+          description: "Short title for the memory (required)"
+        },
+        content: {
+          type: "string",
+          minLength: 10,
+          description: "The memory content (must be durable knowledge)"
+        },
+        importance: {
+          type: "number",
+          minimum: 1,
+          maximum: 5,
+          description: "Importance score (1-5)"
+        },
+        scope: {
+          type: "object",
+          properties: {
+            repo: {
+              type: "string",
+              description: "Repository name (required)"
+            },
+            branch: {
+              type: "string",
+              description: "Git branch (optional)"
+            },
+            folder: {
+              type: "string",
+              description: "Specific folder path (optional)"
+            },
+            language: {
+              type: "string",
+              description: "Programming language (optional)"
+            }
+          },
+          required: ["repo"]
+        },
+        ttlDays: {
+          type: "number",
+          minimum: 1,
+          description: "Time-to-live in days. Memory will expire after this many days (optional)"
+        }
+      },
+      required: ["type", "title", "content", "importance", "scope"]
+    }
+  },
+  {
+    name: "memory-update",
+    description: "Update an existing memory entry",
+    inputSchema: {
+      type: "object",
+      properties: {
+        id: {
+          type: "string",
+          format: "uuid",
+          description: "Memory entry ID"
+        },
+        title: {
+          type: "string",
+          minLength: 3,
+          maxLength: 100,
+          description: "Updated title (optional)"
+        },
+        content: {
+          type: "string",
+          minLength: 10,
+          description: "Updated content (optional)"
+        },
+        importance: {
+          type: "number",
+          minimum: 1,
+          maximum: 5,
+          description: "Updated importance (optional)"
+        }
+      },
+      required: ["id"]
+    }
+  },
+  {
+    name: "memory-search",
+    description: "Search for relevant memories in the current repository",
+    inputSchema: {
+      type: "object",
+      properties: {
+        query: {
+          type: "string",
+          minLength: 3,
+          description: "Search query"
+        },
+        prompt: {
+          type: "string",
+          description: "Context/prompt to help determine relevance. Use this to specify what kind of information you're looking for (optional)"
+        },
+        repo: {
+          type: "string",
+          description: "Repository name (required)"
+        },
+        types: {
+          type: "array",
+          items: {
+            type: "string",
+            enum: ["code_fact", "decision", "mistake", "pattern"]
+          },
+          description: "Filter by memory types (optional)"
+        },
+        minImportance: {
+          type: "number",
+          minimum: 1,
+          maximum: 5,
+          description: "Minimum importance score (optional)"
+        },
+        limit: {
+          type: "number",
+          minimum: 1,
+          maximum: 10,
+          default: 5,
+          description: "Maximum number of results"
+        },
+        includeRecap: {
+          type: "boolean",
+          default: false,
+          description: "Include recent memories recap context in the response (optional, default false)"
+        }
+      },
+      required: ["query", "repo"]
+    }
+  },
+  {
+    name: "memory-summarize",
+    description: "Update the summary for a repository",
+    inputSchema: {
+      type: "object",
+      properties: {
+        repo: {
+          type: "string",
+          description: "Repository name"
+        },
+        signals: {
+          type: "array",
+          items: {
+            type: "string",
+            maxLength: 200
+          },
+          minItems: 1,
+          description: "High-level signals to include in summary"
+        }
+      },
+      required: ["repo", "signals"]
+    }
+  },
+  {
+    name: "memory-delete",
+    description: "Soft-delete a memory entry (remove from active use)",
+    inputSchema: {
+      type: "object",
+      properties: {
+        id: {
+          type: "string",
+          format: "uuid",
+          description: "Memory entry ID to delete"
+        }
+      },
+      required: ["id"]
+    }
+  },
+  {
+    name: "memory-recap",
+    description: "Get the last 20 memories from a repository for context",
+    inputSchema: {
+      type: "object",
+      properties: {
+        repo: {
+          type: "string",
+          description: "Repository name (required)"
+        },
+        limit: {
+          type: "number",
+          minimum: 1,
+          maximum: 50,
+          default: 20,
+          description: "Maximum number of memories to retrieve"
+        },
+        offset: {
+          type: "number",
+          minimum: 0,
+          default: 0,
+          description: "Number of memories to skip for pagination (optional, default 0)"
+        }
+      },
+      required: ["repo"]
+    }
+  }
+];

package/src/types.ts

@@ -0,0 +1,36 @@
+// Shared types for MCP Local Memory
+
+export type MemoryType = "code_fact" | "decision" | "mistake" | "pattern";
+
+export type MemoryScope = {
+  repo: string;
+  branch?: string;
+  folder?: string;
+  language?: string;
+};
+
+export type MemoryEntry = {
+  id: string;
+  type: MemoryType;
+  title?: string;
+  content: string;
+  importance: number;
+  scope: MemoryScope;
+  created_at: string;
+  updated_at: string;
+  hit_count: number;
+  recall_count: number;
+  last_used_at: string | null;
+  expires_at: string | null;
+};
+
+export type VectorResult = {
+  id: string;
+  score: number;
+};
+
+export interface VectorStore {
+  upsert(id: string, text: string): Promise<void>;
+  remove(id: string): Promise<void>;
+  search(query: string, limit: number): Promise<VectorResult[]>;
+}

package/src/utils/git-scope.ts

@@ -0,0 +1,42 @@
+import { execSync } from "child_process";
+import path from "path";
+
+export function resolveGitScope(cwd = process.cwd()) {
+  // 1. Try git root
+  try {
+    const root = execSync("git rev-parse --show-toplevel", {
+      cwd,
+      stdio: ["ignore", "pipe", "ignore"]
+    })
+      .toString()
+      .trim();
+
+    const repo = path.basename(root);
+
+    let branch: string | undefined;
+    try {
+      branch = execSync("git rev-parse --abbrev-ref HEAD", {
+        cwd,
+        stdio: ["ignore", "pipe", "ignore"]
+      })
+        .toString()
+        .trim();
+    } catch {}
+
+    return {
+      repo,
+      branch
+    };
+  } catch {}
+
+  // 2. Fallback: project folder
+  const fallback = path.basename(cwd);
+
+  if (fallback) {
+    return {
+      repo: fallback
+    };
+  }
+
+  throw new Error("Unable to resolve project scope (no git repo, no folder)");
+}