@aeriondyseti/vector-memory-mcp 0.4.0 → 0.5.0

package/README.md

@@ -73,7 +73,13 @@ bun install -g @aeriondyseti/vector-memory-mcp
 {
   "mcpServers": {
     "memory": {
-      "command": "vector-memory-mcp"
+      "type": "stdio",
+      "command": "bunx",
+      "args": [
+        "--bun",
+        "@aeriondyseti/vector-memory-mcp"
+      ],
+      "env": {}
     }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aeriondyseti/vector-memory-mcp",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "A zero-configuration RAG memory server for MCP clients",
   "type": "module",
   "main": "src/index.ts",
@@ -26,7 +26,8 @@
     "start": "bun run src/index.ts",
     "dev": "bun --watch run src/index.ts",
     "typecheck": "bunx tsc --noEmit",
-    "test": "bun test --preload ./tests/preload.ts",
+    "test": "bun run scripts/test-runner.ts",
+    "test:raw": "bun test --preload ./tests/preload.ts",
     "test:quick": "bun test",
     "test:coverage": "bun test --preload ./tests/preload.ts --coverage",
     "test:preload": "bun run tests/preload.ts",
@@ -36,9 +37,10 @@
   "keywords": ["mcp", "memory", "rag", "embeddings", "lancedb"],
   "license": "MIT",
   "dependencies": {
+    "@huggingface/transformers": "^3.8.0",
     "@lancedb/lancedb": "^0.22.3",
     "@modelcontextprotocol/sdk": "^1.0.0",
-    "@huggingface/transformers": "^3.8.0"
+    "hono": "^4.11.3"
   },
   "devDependencies": {
     "@types/bun": "latest",
@@ -48,5 +50,8 @@
     "onnxruntime-node",
     "protobufjs",
     "sharp"
-  ]
+  ],
+  "overrides": {
+    "onnxruntime-node": "1.23.2"
+  }
 }

package/scripts/test-runner.ts

@@ -0,0 +1,66 @@
+#!/usr/bin/env bun
+/**
+ * Test runner wrapper that handles Bun's post-test crash gracefully.
+ *
+ * Bun crashes during native module cleanup after tests complete successfully.
+ * This wrapper captures the output, verifies tests passed, and exits cleanly.
+ */
+
+import { spawn } from "bun";
+
+const proc = spawn(["bun", "test", "--preload", "./tests/preload.ts"], {
+  stdout: "pipe",
+  stderr: "pipe",
+  env: { ...process.env, FORCE_COLOR: "1" },
+});
+
+let stdout = "";
+let stderr = "";
+
+const decoder = new TextDecoder();
+
+// Stream stdout in real-time
+const stdoutReader = proc.stdout.getReader();
+(async () => {
+  while (true) {
+    const { done, value } = await stdoutReader.read();
+    if (done) break;
+    const text = decoder.decode(value);
+    stdout += text;
+    process.stdout.write(text);
+  }
+})();
+
+// Stream stderr in real-time
+const stderrReader = proc.stderr.getReader();
+(async () => {
+  while (true) {
+    const { done, value } = await stderrReader.read();
+    if (done) break;
+    const text = decoder.decode(value);
+    stderr += text;
+    process.stderr.write(text);
+  }
+})();
+
+await proc.exited;
+
+// Check if tests actually passed by looking for the summary line
+const output = stdout + stderr;
+const passMatch = output.match(/(\d+) pass/);
+const failMatch = output.match(/(\d+) fail/);
+
+const passed = passMatch ? parseInt(passMatch[1], 10) : 0;
+const failed = failMatch ? parseInt(failMatch[1], 10) : 0;
+
+// Exit based on test results, not Bun's crash
+if (failed > 0) {
+  console.error(`\n❌ ${failed} test(s) failed`);
+  process.exit(1);
+} else if (passed > 0) {
+  console.log(`\n✅ All ${passed} tests passed (ignoring Bun cleanup crash)`);
+  process.exit(0);
+} else {
+  console.error("\n⚠️  Could not determine test results");
+  process.exit(1);
+}

package/src/config/index.ts

@@ -5,6 +5,9 @@ export interface Config {
   dbPath: string;
   embeddingModel: string;
   embeddingDimension: number;
+  httpPort: number;
+  httpHost: string;
+  enableHttp: boolean;
 }
 
 const DEFAULT_DB_PATH = join(
@@ -17,12 +20,17 @@ const DEFAULT_DB_PATH = join(
 
 const DEFAULT_EMBEDDING_MODEL = "Xenova/all-MiniLM-L6-v2";
 const DEFAULT_EMBEDDING_DIMENSION = 384;
+const DEFAULT_HTTP_PORT = 3271;
+const DEFAULT_HTTP_HOST = "127.0.0.1";
 
 export function loadConfig(): Config {
   return {
     dbPath: process.env.VECTOR_MEMORY_DB_PATH ?? DEFAULT_DB_PATH,
     embeddingModel: process.env.VECTOR_MEMORY_MODEL ?? DEFAULT_EMBEDDING_MODEL,
     embeddingDimension: DEFAULT_EMBEDDING_DIMENSION,
+    httpPort: parseInt(process.env.VECTOR_MEMORY_HTTP_PORT ?? String(DEFAULT_HTTP_PORT), 10),
+    httpHost: process.env.VECTOR_MEMORY_HTTP_HOST ?? DEFAULT_HTTP_HOST,
+    enableHttp: process.env.VECTOR_MEMORY_ENABLE_HTTP !== "false",
   };
 }
 

package/src/http/server.ts

@@ -0,0 +1,173 @@
+import { Hono } from "hono";
+import { cors } from "hono/cors";
+import type { MemoryService } from "../services/memory.service.js";
+import type { Config } from "../config/index.js";
+import { isDeleted } from "../types/memory.js";
+
+export interface HttpServerOptions {
+  memoryService: MemoryService;
+  config: Config;
+}
+
+export function createHttpApp(memoryService: MemoryService): Hono {
+  const app = new Hono();
+
+  // Enable CORS for local development
+  app.use("/*", cors());
+
+  // Health check endpoint
+  app.get("/health", (c) => {
+    return c.json({ status: "ok", timestamp: new Date().toISOString() });
+  });
+
+  // Context endpoint for Claude Code hooks
+  // Returns relevant memories formatted for injection into conversation
+  app.post("/context", async (c) => {
+    try {
+      const body = await c.req.json();
+      const query = body.query;
+
+      if (!query || typeof query !== "string") {
+        return c.json({ error: "Missing or invalid 'query' field" }, 400);
+      }
+
+      const memories = await memoryService.search(query, 5);
+
+      if (memories.length === 0) {
+        return c.json({ context: null });
+      }
+
+      // Format memories for context injection
+      const contextLines = memories.map((m, i) => {
+        const metadata = m.metadata as Record<string, unknown>;
+        const type = metadata.type ? `[${metadata.type}]` : "";
+        const date = m.createdAt.toISOString().split("T")[0];
+        return `${i + 1}. ${type} (${date}): ${m.content}`;
+      });
+
+      const context = `<relevant-memories>\n${contextLines.join("\n")}\n</relevant-memories>`;
+
+      return c.json({ context, count: memories.length });
+    } catch (error) {
+      const message = error instanceof Error ? error.message : "Unknown error";
+      return c.json({ error: message }, 500);
+    }
+  });
+
+  // Search endpoint (more detailed than /context)
+  app.post("/search", async (c) => {
+    try {
+      const body = await c.req.json();
+      const query = body.query;
+      const limit = body.limit ?? 10;
+
+      if (!query || typeof query !== "string") {
+        return c.json({ error: "Missing or invalid 'query' field" }, 400);
+      }
+
+      const memories = await memoryService.search(query, limit);
+
+      return c.json({
+        memories: memories.map((m) => ({
+          id: m.id,
+          content: m.content,
+          metadata: m.metadata,
+          createdAt: m.createdAt.toISOString(),
+        })),
+        count: memories.length,
+      });
+    } catch (error) {
+      const message = error instanceof Error ? error.message : "Unknown error";
+      return c.json({ error: message }, 500);
+    }
+  });
+
+  // Store endpoint
+  app.post("/store", async (c) => {
+    try {
+      const body = await c.req.json();
+      const { content, metadata, embeddingText } = body;
+
+      if (!content || typeof content !== "string") {
+        return c.json({ error: "Missing or invalid 'content' field" }, 400);
+      }
+
+      const memory = await memoryService.store(
+        content,
+        metadata ?? {},
+        embeddingText
+      );
+
+      return c.json({
+        id: memory.id,
+        createdAt: memory.createdAt.toISOString(),
+      });
+    } catch (error) {
+      const message = error instanceof Error ? error.message : "Unknown error";
+      return c.json({ error: message }, 500);
+    }
+  });
+
+  // Delete endpoint
+  app.delete("/memories/:id", async (c) => {
+    try {
+      const id = c.req.param("id");
+      const deleted = await memoryService.delete(id);
+
+      if (!deleted) {
+        return c.json({ error: "Memory not found" }, 404);
+      }
+
+      return c.json({ deleted: true });
+    } catch (error) {
+      const message = error instanceof Error ? error.message : "Unknown error";
+      return c.json({ error: message }, 500);
+    }
+  });
+
+  // Get single memory
+  app.get("/memories/:id", async (c) => {
+    try {
+      const id = c.req.param("id");
+      const memory = await memoryService.get(id);
+
+      if (!memory || isDeleted(memory)) {
+        return c.json({ error: "Memory not found" }, 404);
+      }
+
+      return c.json({
+        id: memory.id,
+        content: memory.content,
+        metadata: memory.metadata,
+        createdAt: memory.createdAt.toISOString(),
+        updatedAt: memory.updatedAt.toISOString(),
+      });
+    } catch (error) {
+      const message = error instanceof Error ? error.message : "Unknown error";
+      return c.json({ error: message }, 500);
+    }
+  });
+
+  return app;
+}
+
+export async function startHttpServer(
+  memoryService: MemoryService,
+  config: Config
+): Promise<{ stop: () => void }> {
+  const app = createHttpApp(memoryService);
+
+  const server = Bun.serve({
+    port: config.httpPort,
+    hostname: config.httpHost,
+    fetch: app.fetch,
+  });
+
+  console.error(
+    `[vector-memory-mcp] HTTP server listening on http://${config.httpHost}:${config.httpPort}`
+  );
+
+  return {
+    stop: () => server.stop(),
+  };
+}

package/src/index.ts

@@ -6,6 +6,7 @@ import { MemoryRepository } from "./db/memory.repository.js";
 import { EmbeddingsService } from "./services/embeddings.service.js";
 import { MemoryService } from "./services/memory.service.js";
 import { startServer } from "./mcp/server.js";
+import { startHttpServer } from "./http/server.js";
 
 async function main(): Promise<void> {
   // Check for warmup command
@@ -24,7 +25,12 @@ async function main(): Promise<void> {
   const embeddings = new EmbeddingsService(config.embeddingModel, config.embeddingDimension);
   const memoryService = new MemoryService(repository, embeddings);
 
-  // Start MCP server
+  // Start HTTP server if enabled
+  if (config.enableHttp) {
+    await startHttpServer(memoryService, config);
+  }
+
+  // Start MCP server (stdio)
   await startServer(memoryService);
 }
 

package/src/mcp/tools.ts

@@ -3,7 +3,13 @@ import type { Tool } from "@modelcontextprotocol/sdk/types.js";
 export const storeMemoryTool: Tool = {
   name: "store_memory",
   description:
-    "Store a new memory. Use this to save information for later recall. " +
+    "Store a new memory for later recall. " +
+    "PROACTIVELY store memories when: " +
+    "(1) Important decisions are made (technical choices, architecture decisions, tradeoffs); " +
+    "(2) Problems are solved (bugs fixed, errors resolved - include the solution); " +
+    "(3) User preferences or conventions are established; " +
+    "(4) Project-specific patterns or configurations are discussed; " +
+    "(5) Key information would be valuable in future sessions. " +
     "IMPORTANT: If the content exceeds 1000 characters, you MUST provide an embedding_text " +
     "parameter with a concise summary (under 1000 characters) that captures the key semantic " +
     "meaning for search purposes. The full content will still be stored and returned in search results.",
@@ -12,18 +18,21 @@ export const storeMemoryTool: Tool = {
     properties: {
       content: {
         type: "string",
-        description: "The text content to store as a memory",
+        description:
+          "The text content to store. Write in a way that will be useful when retrieved later - " +
+          "include context, reasoning, and outcomes, not just bare facts.",
       },
       embedding_text: {
         type: "string",
         description:
           "A concise summary (under 1000 characters) used for generating the search embedding. " +
-          "REQUIRED when content exceeds 1000 characters. If not provided, the full content is used for embedding, " +
-          "which may be truncated by the embedding model and result in poor search relevance.",
+          "REQUIRED when content exceeds 1000 characters. Should capture the key topics and terms " +
+          "someone might search for to find this memory.",
       },
       metadata: {
         type: "object",
-        description: "Optional key-value metadata to attach to the memory",
+        description:
+          "Optional key-value metadata. Recommended keys: 'project' (project name), 'type' (decision/solution/preference/pattern), 'tags' (array of keywords).",
         additionalProperties: true,
       },
     },
@@ -50,13 +59,22 @@ export const deleteMemoryTool: Tool = {
 export const searchMemoriesTool: Tool = {
   name: "search_memories",
   description:
-    "Search for memories using semantic similarity. Returns the most relevant memories for the given query.",
+    "Search for memories using semantic similarity. Returns the most relevant memories for the given query. " +
+    "IMPORTANT: Use this tool PROACTIVELY without being asked when you detect: " +
+    "(1) References to past decisions or discussions ('what did we decide', 'as we discussed', 'previously'); " +
+    "(2) Questions about prior work ('how did we', 'similar to before', 'like last time'); " +
+    "(3) Project continuations or returning to earlier topics; " +
+    "(4) Debugging issues that may have been solved before; " +
+    "(5) Questions about established patterns, conventions, or preferences. " +
+    "When in doubt, search - it's better to check for relevant context than to miss important prior decisions.",
   inputSchema: {
     type: "object",
     properties: {
       query: {
         type: "string",
-        description: "The search query to find relevant memories",
+        description:
+          "The search query to find relevant memories. Use natural language describing what context you need. " +
+          "Include relevant keywords, project names, or technical terms for better results.",
       },
       limit: {
         type: "integer",