@aeriondyseti/vector-memory-mcp 0.3.0 → 0.5.0

package/README.md

@@ -57,21 +57,44 @@ A production-ready MCP (Model Context Protocol) server that provides semantic me
 
 > **Note:** This server requires Bun to run.
 
-### Installation
+### Installation & Configuration
 
+#### Option 1: Global Install (Recommended)
+
+**Install:**
 ```bash
-# Clone the repository
-git clone https://github.com/AerionDyseti/vector-memory-mcp.git
-cd vector-memory-mcp
+bun install -g @aeriondyseti/vector-memory-mcp
+```
 
-# Install dependencies
-bun install
+> **Note:** The installation automatically downloads ML models (~90MB) and verifies native dependencies. This may take a minute on first install.
+
+**Configure Claude Code** - Add to `~/.claude/config.json`:
+```json
+{
+  "mcpServers": {
+    "memory": {
+      "type": "stdio",
+      "command": "bunx",
+      "args": [
+        "--bun",
+        "@aeriondyseti/vector-memory-mcp"
+      ],
+      "env": {}
+    }
+  }
+}
 ```
 
-### Configure Claude Code
+#### Option 2: Local Development
 
-Add to your `~/.claude/config.json`:
+**Install:**
+```bash
+git clone https://github.com/AerionDyseti/vector-memory-mcp.git
+cd vector-memory-mcp
+bun install
+```
 
+**Configure Claude Code** - Add to `~/.claude/config.json`:
 ```json
 {
   "mcpServers": {
@@ -82,8 +105,17 @@ Add to your `~/.claude/config.json`:
   }
 }
 ```
+*Replace `/absolute/path/to/` with your actual installation path.*
+
+---
+
+**What gets installed:**
+- The vector-memory-mcp package and all dependencies
+- Native binaries for ONNX Runtime (~32MB) and image processing (~10MB)
+- ML model files automatically downloaded during installation (~90MB, cached in `~/.cache/huggingface/`)
+- **Total first-time setup:** ~130MB of downloads
 
-Replace `/absolute/path/to/` with your actual installation path.
+> 💡 **Tip:** If you need to re-download models or verify dependencies, run: `vector-memory-mcp warmup`
 
 ### Start Using It
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aeriondyseti/vector-memory-mcp",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "A zero-configuration RAG memory server for MCP clients",
   "type": "module",
   "main": "src/index.ts",
@@ -9,6 +9,7 @@
   },
   "files": [
     "src",
+    "scripts",
     "README.md",
     "LICENSE"
   ],
@@ -25,21 +26,32 @@
     "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"
+    "test:preload": "bun run tests/preload.ts",
+    "warmup": "bun run scripts/warmup.ts",
+    "postinstall": "bun run scripts/warmup.ts"
   },
-    "keywords": ["mcp", "memory", "rag", "embeddings", "lancedb"],
+  "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",
-    "apache-arrow": "^21.1.0"
+    "hono": "^4.11.3"
   },
   "devDependencies": {
     "@types/bun": "latest",
     "typescript": "^5.0.0"
+  },
+  "trustedDependencies": [
+    "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/scripts/warmup.ts

@@ -0,0 +1,73 @@
+#!/usr/bin/env bun
+
+/**
+ * Warmup script to pre-download ML models and verify dependencies
+ * This runs during installation to ensure everything is ready to use
+ */
+
+import { config } from "../src/config/index.js";
+import { EmbeddingsService } from "../src/services/embeddings.service.js";
+
+async function warmup(): Promise<void> {
+  console.log("🔥 Warming up vector-memory-mcp...");
+  console.log();
+
+  try {
+    // Check native dependencies
+    console.log("✓ Checking native dependencies...");
+    try {
+      await import("onnxruntime-node");
+      console.log("  ✓ onnxruntime-node loaded");
+    } catch (e) {
+      console.error("  ✗ onnxruntime-node failed:", (e as Error).message);
+      process.exit(1);
+    }
+
+    try {
+      await import("sharp");
+      console.log("  ✓ sharp loaded");
+    } catch (e) {
+      console.error("  ✗ sharp failed:", (e as Error).message);
+      process.exit(1);
+    }
+
+    console.log();
+
+    // Initialize embeddings service to download model
+    console.log("📥 Downloading ML model (this may take a minute)...");
+    console.log(`   Model: ${config.embeddingModel}`);
+    console.log(`   Cache: ~/.cache/huggingface/`);
+    console.log();
+
+    const embeddings = new EmbeddingsService(
+      config.embeddingModel,
+      config.embeddingDimension
+    );
+
+    // Trigger model download by generating a test embedding
+    const startTime = Date.now();
+    await embeddings.embed("warmup test");
+    const duration = ((Date.now() - startTime) / 1000).toFixed(2);
+
+    console.log();
+    console.log(`✅ Warmup complete! (${duration}s)`);
+    console.log();
+    console.log("Ready to use! Configure Claude Code and restart to get started.");
+    console.log("See: https://github.com/AerionDyseti/vector-memory-mcp#configure-claude-code");
+    console.log();
+  } catch (error) {
+    console.error();
+    console.error("❌ Warmup failed:", error);
+    console.error();
+    console.error("This is not a critical error - the server will download models on first run.");
+    console.error("You can try running 'vector-memory-mcp warmup' manually later.");
+    process.exit(0); // Exit successfully to not block installation
+  }
+}
+
+// Only run if this is the main module
+if (import.meta.url === `file://${process.argv[1]}`) {
+  warmup();
+}
+
+export { warmup };

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,8 +6,17 @@ 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
+  const args = process.argv.slice(2);
+  if (args[0] === "warmup") {
+    const { warmup } = await import("../scripts/warmup.js");
+    await warmup();
+    return;
+  }
+
   // Initialize database
   const db = await connectToDatabase(config.dbPath);
 
@@ -16,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",