@vheins/local-memory-mcp 0.1.0

package/src/mcp/client.ts

@@ -0,0 +1,212 @@
+import { spawn, ChildProcess } from "child_process";
+import { createInterface } from "readline";
+import path from "path";
+import { fileURLToPath } from "url";
+import { logger } from "../utils/logger.js";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+// Exponential backoff delays in ms: 1s, 2s, 4s
+const RETRY_DELAYS = [1000, 2000, 4000];
+const MAX_RETRIES = 3;
+const MAX_RESTARTS = 3;
+const REQUEST_TIMEOUT_MS = 10000;
+
+export class MCPClient {
+  private process: ChildProcess | null = null;
+  private requestId = 0;
+  private pendingRequests = new Map<
+    number,
+    { resolve: (value: unknown) => void; reject: (reason: unknown) => void }
+  >();
+  private isInitialized = false;
+  private serverPathOverride?: string;
+  private restartCount = 0;
+
+  constructor(serverPath?: string) {
+    this.serverPathOverride = serverPath;
+  }
+
+  async start() {
+    if (this.process) return;
+
+    const serverPath =
+      this.serverPathOverride || path.join(__dirname, "../server.js");
+    this.process = spawn("node", [serverPath], {
+      stdio: ["pipe", "pipe", "inherit"],
+    });
+
+    if (!this.process.stdout || !this.process.stdin) {
+      throw new Error("Failed to spawn MCP server");
+    }
+
+    // Listen for unexpected process exit and auto-restart
+    this.process.on("close", (code) => {
+      if (this.process === null) {
+        // Intentional stop — do not restart
+        return;
+      }
+      logger.error("MCP server process closed unexpectedly", { code, restartCount: this.restartCount });
+      this.process = null;
+      this.isInitialized = false;
+
+      if (this.restartCount < MAX_RESTARTS) {
+        this.restartCount++;
+        logger.info("Attempting to restart MCP server", { attempt: this.restartCount });
+        this.start().catch((err) => {
+          logger.error("Failed to restart MCP server", { error: String(err) });
+        });
+      } else {
+        logger.error("Max restart attempts reached, giving up", { maxRestarts: MAX_RESTARTS });
+      }
+    });
+
+    const rl = createInterface({
+      input: this.process.stdout,
+      crlfDelay: Infinity,
+    });
+
+    rl.on("line", (line) => {
+      try {
+        const response = JSON.parse(line);
+
+        if (!response.id) return;
+
+        const pending = this.pendingRequests.get(response.id);
+        if (pending) {
+          this.pendingRequests.delete(response.id);
+          if (response.error) {
+            pending.reject(new Error(response.error.message));
+          } else {
+            pending.resolve(response.result);
+          }
+        }
+      } catch (err) {
+        logger.error("Failed to parse MCP response", { error: String(err) });
+      }
+    });
+
+    await this.callWithRetry("initialize", {
+      protocolVersion: "2024-11-05",
+      capabilities: {},
+      clientInfo: { name: "mcp-client", version: "1.0.0" },
+    });
+
+    this.isInitialized = true;
+  }
+
+  /**
+   * Send a single request without retry. Returns a Promise that rejects on timeout.
+   */
+  private callOnce(method: string, params: unknown = {}): Promise<unknown> {
+    if (!this.process || !this.process.stdin) {
+      return Promise.reject(new Error("MCP server not started"));
+    }
+
+    const id = ++this.requestId;
+    const request = { jsonrpc: "2.0", id, method, params };
+
+    return new Promise((resolve, reject) => {
+      this.pendingRequests.set(id, { resolve, reject });
+
+      const timer = setTimeout(() => {
+        if (this.pendingRequests.has(id)) {
+          // Delete entry to prevent memory leak (Req 18.4)
+          this.pendingRequests.delete(id);
+          reject(new Error("Request timeout"));
+        }
+      }, REQUEST_TIMEOUT_MS);
+
+      // Ensure timer doesn't keep the process alive
+      if (timer.unref) timer.unref();
+
+      this.process!.stdin!.write(JSON.stringify(request) + "\n");
+    });
+  }
+
+  /**
+   * Call with retry on timeout — up to MAX_RETRIES retries with exponential backoff.
+   * Req 18.1: retry up to 3x with delays 1s, 2s, 4s.
+   */
+  private async callWithRetry(method: string, params: unknown = {}): Promise<unknown> {
+    let lastError: unknown;
+
+    for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+      try {
+        return await this.callOnce(method, params);
+      } catch (err) {
+        lastError = err;
+        const isTimeout =
+          err instanceof Error && err.message === "Request timeout";
+
+        if (!isTimeout || attempt === MAX_RETRIES) {
+          // Non-timeout error or exhausted retries — propagate
+          logger.error("MCP request failed", {
+            method,
+            attempt,
+            error: String(err),
+          });
+          throw err;
+        }
+
+        const delay = RETRY_DELAYS[attempt];
+        logger.warn("MCP request timed out, retrying", {
+          method,
+          attempt: attempt + 1,
+          delayMs: delay,
+        });
+        await sleep(delay);
+      }
+    }
+
+    throw lastError;
+  }
+
+  async call(method: string, params: unknown = {}): Promise<unknown> {
+    return this.callWithRetry(method, params);
+  }
+
+  async callTool(toolName: string, args: unknown): Promise<unknown> {
+    return this.call("tools/call", { name: toolName, arguments: args });
+  }
+
+  async readResource(uri: string): Promise<unknown> {
+    return this.call("resources/read", { uri });
+  }
+
+  /**
+   * Stop the client: reject all pending requests, then kill the process.
+   * Req 18.3: reject all pending requests with "Client stopped".
+   */
+  stop() {
+    // Reject all pending requests before killing the process
+    for (const [id, pending] of this.pendingRequests) {
+      pending.reject(new Error("Client stopped"));
+      this.pendingRequests.delete(id);
+    }
+
+    if (this.process) {
+      // Set to null BEFORE kill so the 'close' handler knows it was intentional
+      const proc = this.process;
+      this.process = null;
+      this.isInitialized = false;
+      proc.kill();
+    }
+  }
+
+  isConnected(): boolean {
+    return this.isInitialized && this.process !== null;
+  }
+
+  /**
+   * Returns the number of requests currently awaiting a response.
+   * Req 18.5
+   */
+  getPendingCount(): number {
+    return this.pendingRequests.size;
+  }
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/src/prompts/registry.ts

@@ -0,0 +1,89 @@
+export const PROMPTS = {
+  "memory-agent-core": {
+    name: "memory-agent-core",
+    description: "Core behavioral contract for memory-aware agents",
+    arguments: [],
+    messages: [
+      {
+        role: "user",
+        content: {
+          type: "text",
+          text: `You are a coding copilot agent working inside an active software project.
+
+Your primary goal is to help write correct, maintainable, and consistent code.
+
+You are memory-aware:
+- Stored memory represents durable project knowledge
+- Memory is a source of truth, not a suggestion
+- You must respect stored decisions and constraints
+
+Core Behavioral Rules:
+1. Never contradict stored decisions
+2. Never repeat known mistakes
+3. Never invent project rules
+4. Never use memory from another repository
+5. If memory conflicts with the user, ask for clarification
+
+Memory Usage Policy:
+Before generating code:
+1. Read project summary (if available)
+2. Search memory for relevant decisions, mistakes, or patterns
+3. Use memory ONLY if clearly relevant
+4. Prefer fewer, stronger memories over many weak ones
+
+Auto-Memory Creation Policy:
+You MAY store memory ONLY if:
+- The information affects future behavior
+- The scope (repository) is clear
+- The knowledge is durable
+
+Before storing memory:
+- Explain briefly why it should be stored
+- Ask for confirmation if unsure
+
+Behave like a trusted senior engineer who remembers past decisions and protects the long-term health of the codebase.`
+        }
+      }
+    ]
+  },
+  "memory-index-policy": {
+    name: "memory-index-policy",
+    description: "Enforce strict memory discipline",
+    arguments: [],
+    messages: [
+      {
+        role: "user",
+        content: {
+          type: "text",
+          text: `Do not store:
+- Temporary discussions
+- Brainstorming
+- Subjective opinions
+
+Only store durable knowledge that affects future behavior.
+
+Memory is a commit, not a log.`
+        }
+      }
+    ]
+  },
+  "tool-usage-guidelines": {
+    name: "tool-usage-guidelines",
+    description: "Prevent tool abuse",
+    arguments: [],
+    messages: [
+      {
+        role: "user",
+        content: {
+          type: "text",
+          text: `Only call memory.store when:
+- The information affects future behavior
+- The scope (repo) is clear
+- The memory will still matter later
+
+Better to not store anything than to store bad memory.`
+        }
+      }
+    ]
+  }
+};

package/src/resources/index.test.ts

@@ -0,0 +1,132 @@
+// Feature: memory-mcp-optimization, Property 19: memory://index filter repo
+import { describe, it, expect } from "vitest";
+import * as fc from "fast-check";
+import { SQLiteStore } from "../storage/sqlite.js";
+import { readResource } from "./index.js";
+import { MemoryEntry } from "../types.js";
+
+function makeEntry(id: string, repo: string): MemoryEntry {
+  return {
+    id,
+    type: "code_fact",
+    title: `Memory ${id}`,
+    content: `Content for memory ${id} in repo ${repo}`,
+    importance: 3,
+    scope: { repo },
+    created_at: new Date().toISOString(),
+    updated_at: new Date().toISOString(),
+    hit_count: 0,
+    recall_count: 0,
+    last_used_at: null,
+    expires_at: null,
+  };
+}
+
+describe("readResource memory://index", () => {
+  it("returns recent entries when no repo filter", () => {
+    const db = new SQLiteStore(":memory:");
+    db.insert(makeEntry("id-1", "repo-a"));
+    db.insert(makeEntry("id-2", "repo-b"));
+
+    const result = readResource("memory://index", db);
+    const entries = JSON.parse(result.contents[0].text);
+    expect(entries.length).toBeGreaterThan(0);
+    db.close();
+  });
+
+  it("returns only entries for the specified repo when ?repo=X is given", () => {
+    const db = new SQLiteStore(":memory:");
+    db.insert(makeEntry("id-a1", "repo-alpha"));
+    db.insert(makeEntry("id-a2", "repo-alpha"));
+    db.insert(makeEntry("id-b1", "repo-beta"));
+
+    const result = readResource("memory://index?repo=repo-alpha", db);
+    const entries: MemoryEntry[] = JSON.parse(result.contents[0].text);
+
+    expect(entries.length).toBeGreaterThan(0);
+    for (const entry of entries) {
+      expect(entry.scope.repo).toBe("repo-alpha");
+    }
+    db.close();
+  });
+
+  it("returns empty array when repo has no entries", () => {
+    const db = new SQLiteStore(":memory:");
+    db.insert(makeEntry("id-1", "repo-a"));
+
+    const result = readResource("memory://index?repo=nonexistent", db);
+    const entries = JSON.parse(result.contents[0].text);
+    expect(entries).toEqual([]);
+    db.close();
+  });
+
+  /**
+   * Property 19: memory://index dengan filter repo mengembalikan subset yang benar
+   * Validates: Requirements 19.1, 19.3
+   */
+  it("Property 19: all returned entries have repo === queried repo", () => {
+    fc.assert(
+      fc.property(
+        // Generate 2-4 distinct repo names
+        fc.uniqueArray(
+          fc.stringMatching(/^[a-z][a-z0-9-]{2,8}$/),
+          { minLength: 2, maxLength: 4 }
+        ),
+        // Generate 1-5 memories per repo
+        fc.integer({ min: 1, max: 5 }),
+        (repos: string[], memoriesPerRepo: number) => {
+          const db = new SQLiteStore(":memory:");
+
+          // Insert memories for each repo
+          let counter = 0;
+          for (const repo of repos) {
+            for (let i = 0; i < memoriesPerRepo; i++) {
+              db.insert(makeEntry(`id-${counter++}`, repo));
+            }
+          }
+
+          // Query with the first repo as filter
+          const targetRepo = repos[0];
+          const result = readResource(`memory://index?repo=${targetRepo}`, db);
+          const entries: MemoryEntry[] = JSON.parse(result.contents[0].text);
+
+          // All returned entries must belong to targetRepo
+          const allMatch = entries.every((e) => e.scope.repo === targetRepo);
+
+          db.close();
+          return allMatch;
+        }
+      ),
+      { numRuns: 100 }
+    );
+  });
+
+  it("Property 19 (no filter): returns entries from all repos", () => {
+    fc.assert(
+      fc.property(
+        fc.uniqueArray(
+          fc.stringMatching(/^[a-z][a-z0-9-]{2,8}$/),
+          { minLength: 2, maxLength: 3 }
+        ),
+        (repos: string[]) => {
+          const db = new SQLiteStore(":memory:");
+
+          for (const repo of repos) {
+            db.insert(makeEntry(`id-${repo}`, repo));
+          }
+
+          const result = readResource("memory://index", db);
+          const entries: Array<{ id: string; type: string; repo: string }> =
+            JSON.parse(result.contents[0].text);
+
+          // Without filter, should return entries (listRecent returns id/type/repo)
+          expect(entries.length).toBeGreaterThan(0);
+
+          db.close();
+          return true;
+        }
+      ),
+      { numRuns: 100 }
+    );
+  });
+});

package/src/resources/index.ts

@@ -0,0 +1,113 @@
+import { SQLiteStore } from "../storage/sqlite.js";
+
+export function listResources() {
+  return {
+    resources: [
+      {
+        uri: "memory://index",
+        name: "Memory Index",
+        description: "Recent memory entries (metadata only)",
+        mimeType: "application/json"
+      },
+      {
+        uri: "memory://summary/{repo}",
+        name: "Project Summary",
+        description: "Antigravity summary for a repository",
+        mimeType: "text/plain"
+      },
+      {
+        uri: "memory://{id}",
+        name: "Memory by ID",
+        description: "View a specific memory by UUID",
+        mimeType: "application/json"
+      },
+      {
+        uri: "memory://{base64_query}",
+        name: "Search Memories",
+        description: "Search memories by query (base64 encoded)",
+        mimeType: "application/json"
+      }
+    ]
+  };
+}
+
+export function readResource(uri: string, db: SQLiteStore) {
+  if (uri === "memory://index" || uri.startsWith("memory://index?")) {
+    const parsed = new URL(uri.replace("memory://", "http://memory/"));
+    const repo = parsed.searchParams.get("repo");
+
+    const entries = repo
+      ? db.searchByRepo(repo, { limit: 20 })
+      : db.listRecent(20);
+
+    return {
+      contents: [
+        {
+          uri,
+          mimeType: "application/json",
+          text: JSON.stringify(entries, null, 2)
+        }
+      ]
+    };
+  }
+
+  if (uri.startsWith("memory://summary/")) {
+    const repo = uri.replace("memory://summary/", "");
+    const summary = db.getSummary(repo);
+
+    return {
+      contents: [
+        {
+          uri,
+          mimeType: "text/plain",
+          text: summary?.summary || "No summary available for this repository"
+        }
+      ]
+    };
+  }
+
+  // View memory by ID: memory://{uuid}
+  const idMatch = uri.match(/^memory:\/\/([0-9a-f-]{36})$/i);
+  if (idMatch) {
+    const id = idMatch[1];
+    const entry = db.getById(id);
+    
+    if (!entry) {
+      throw new Error(`Memory not found: ${id}`);
+    }
+
+    return {
+      contents: [
+        {
+          uri,
+          mimeType: "application/json",
+          text: JSON.stringify(entry)
+        }
+      ]
+    };
+  }
+
+  // Search by query: memory://{base64_query}
+  if (uri.startsWith("memory://") && !uri.startsWith("memory://index") && !uri.startsWith("memory://summary")) {
+    const searchId = uri.replace("memory://", "");
+    const query = Buffer.from(searchId, 'base64').toString('utf-8');
+    const parsed = new URL(uri.replace("memory://", "http://memory/"));
+    const repo = parsed.searchParams.get("repo") || undefined;
+    
+    const results = repo 
+      ? db.searchBySimilarity(query, repo, 10)
+      : db.searchBySimilarity(query, "", 10);
+    
+    return {
+      contents: [
+        {
+          uri,
+          mimeType: "application/json",
+          text: JSON.stringify({ query, repo, results })
+        }
+      ]
+    };
+  }
+
+  throw new Error(`Unknown resource URI: ${uri}`);
+}

package/src/router.test.ts

@@ -0,0 +1,145 @@
+// Feature: memory-mcp-optimization, Property 11: createRouter() uses provided storage
+import { describe, it, expect, vi } from "vitest";
+import * as fc from "fast-check";
+import { createRouter } from "./router.js";
+import { SQLiteStore } from "./storage/sqlite.js";
+import { VectorStore } from "./types.js";
+
+/**
+ * Property 11: createRouter() menggunakan storage yang diberikan
+ * Validates: Requirements 10.1, 10.4
+ *
+ * For any mock SQLiteStore given to createRouter(mockDb, mockVectors),
+ * all tool operations run through the router SHALL use mockDb and not access the real DB.
+ */
+describe("createRouter() — Property 11: uses provided storage", () => {
+  function makeMockDb(): SQLiteStore {
+    return {
+      insert: vi.fn(),
+      update: vi.fn(),
+      delete: vi.fn(),
+      getById: vi.fn().mockReturnValue(null),
+      searchByRepo: vi.fn().mockReturnValue([]),
+      searchBySimilarity: vi.fn().mockReturnValue([]),
+      getRecentMemories: vi.fn().mockReturnValue([]),
+      getTotalCount: vi.fn().mockReturnValue(0),
+      getSummary: vi.fn().mockReturnValue(null),
+      upsertSummary: vi.fn(),
+      listRepos: vi.fn().mockReturnValue([]),
+      listRecent: vi.fn().mockReturnValue([]),
+      incrementHitCount: vi.fn(),
+      incrementRecallCount: vi.fn(),
+      getStats: vi.fn().mockReturnValue({ total: 0, byType: {}, unused: 0 }),
+      getAllMemoriesWithStats: vi.fn().mockReturnValue([]),
+      upsertVectorEmbedding: vi.fn(),
+      getVectorEmbedding: vi.fn().mockReturnValue(null),
+      archiveExpiredMemories: vi.fn().mockReturnValue(0),
+      logQuery: vi.fn(),
+      getRecentQueries: vi.fn().mockReturnValue([]),
+      close: vi.fn(),
+    } as unknown as SQLiteStore;
+  }
+
+  function makeMockVectors(): VectorStore {
+    return {
+      upsert: vi.fn().mockResolvedValue(undefined),
+      remove: vi.fn().mockResolvedValue(undefined),
+      search: vi.fn().mockResolvedValue([]),
+    };
+  }
+
+  it("memory-recap calls getRecentMemories on the provided mock db", async () => {
+    const mockDb = makeMockDb();
+    const mockVectors = makeMockVectors();
+    const router = createRouter(mockDb, mockVectors);
+
+    await router("tools/call", {
+      name: "memory-recap",
+      arguments: { repo: "test-repo", limit: 5 },
+    });
+
+    expect(mockDb.getRecentMemories).toHaveBeenCalledWith("test-repo", 5, 0);
+    expect(mockDb.getTotalCount).toHaveBeenCalledWith("test-repo");
+  });
+
+  it("memory-search calls searchBySimilarity on the provided mock db", async () => {
+    const mockDb = makeMockDb();
+    const mockVectors = makeMockVectors();
+    const router = createRouter(mockDb, mockVectors);
+
+    await router("tools/call", {
+      name: "memory-search",
+      arguments: { query: "test query", repo: "test-repo", limit: 5 },
+    });
+
+    expect(mockDb.searchBySimilarity).toHaveBeenCalled();
+    // Verify the first argument to searchBySimilarity contains the repo
+    const callArgs = (mockDb.searchBySimilarity as ReturnType<typeof vi.fn>).mock.calls[0];
+    expect(callArgs[1]).toBe("test-repo");
+  });
+
+  it("property: for any repo string, memory-recap always uses the injected db", async () => {
+    await fc.assert(
+      fc.asyncProperty(
+        fc.string({ minLength: 1, maxLength: 50 }).filter((s: string) => s.trim().length > 0),
+        fc.integer({ min: 1, max: 50 }),
+        async (repo: string, limit: number) => {
+          const mockDb = makeMockDb();
+          const mockVectors = makeMockVectors();
+          const router = createRouter(mockDb, mockVectors);
+
+          await router("tools/call", {
+            name: "memory-recap",
+            arguments: { repo, limit },
+          });
+
+          // The mock db methods must have been called (not a real DB)
+          expect(mockDb.getRecentMemories).toHaveBeenCalled();
+          expect(mockDb.getTotalCount).toHaveBeenCalled();
+        }
+      ),
+      { numRuns: 100 }
+    );
+  });
+
+  it("property: for any valid store args, memory-store uses the injected db", async () => {
+    await fc.assert(
+      fc.asyncProperty(
+        fc.record({
+          repo: fc.string({ minLength: 1, maxLength: 30 }).filter((s: string) => s.trim().length > 0),
+          content: fc.string({ minLength: 10, maxLength: 200 }),
+          importance: fc.integer({ min: 1, max: 5 }),
+          type: fc.constantFrom("code_fact", "decision", "mistake", "pattern"),
+        }),
+        async ({ repo, content, importance, type }: { repo: string; content: string; importance: number; type: string }) => {
+          const mockDb = makeMockDb();
+          const mockVectors = makeMockVectors();
+          const router = createRouter(mockDb, mockVectors);
+
+          await router("tools/call", {
+            name: "memory-store",
+            arguments: { type, content, importance, scope: { repo } },
+          });
+
+          expect(mockDb.insert).toHaveBeenCalled();
+        }
+      ),
+      { numRuns: 100 }
+    );
+  });
+
+  it("different router instances use their own injected db independently", () => {
+    const mockDb1 = makeMockDb();
+    const mockDb2 = makeMockDb();
+    const mockVectors = makeMockVectors();
+
+    const router1 = createRouter(mockDb1, mockVectors);
+    const router2 = createRouter(mockDb2, mockVectors);
+
+    // Both routers are distinct functions
+    expect(router1).not.toBe(router2);
+
+    // Each router closes over its own db
+    // (verified by the property tests above that each mock is called independently)
+  });
+});