@aeriondyseti/vector-memory-mcp 0.4.0 → 0.8.0

package/README.md

@@ -4,7 +4,7 @@
 
 A production-ready MCP (Model Context Protocol) server that provides semantic memory storage for AI assistants. Uses local embeddings and vector search to automatically retrieve relevant context without cloud dependencies.
 
-**Perfect for:** Software teams maintaining architectural knowledge, developers juggling multiple projects, and anyone building with AI assistants like Claude Code.
+**Perfect for:** Software teams maintaining architectural knowledge, developers juggling multiple projects, and anyone building with MCP-compatible AI assistants.
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)
@@ -36,9 +36,7 @@ A production-ready MCP (Model Context Protocol) server that provides semantic me
 - CPU-optimized local embeddings (no GPU required)
 
 ### 🔌 **MCP Native Integration**
-- Works seamlessly with Claude Code
-- Session hooks for automatic context injection
-- Standard MCP protocol (compatible with future clients)
+- Standard MCP protocol (compatible with any client)
 
 ### 🛠️ **Developer-Friendly**
 - Zero-configuration setup
@@ -53,7 +51,7 @@ A production-ready MCP (Model Context Protocol) server that provides semantic me
 ### Prerequisites
 
 - [Bun](https://bun.sh/) 1.0+
-- Claude Code or another MCP-compatible client
+- An MCP-compatible client
 
 > **Note:** This server requires Bun to run.
 
@@ -68,12 +66,18 @@ bun install -g @aeriondyseti/vector-memory-mcp
 
 > **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`:
+**Configure your MCP client** (example config for clients that use `~/.claude/config.json`):
 ```json
 {
   "mcpServers": {
     "memory": {
-      "command": "vector-memory-mcp"
+      "type": "stdio",
+      "command": "bunx",
+      "args": [
+        "--bun",
+        "@aeriondyseti/vector-memory-mcp"
+      ],
+      "env": {}
     }
   }
 }
@@ -88,7 +92,7 @@ cd vector-memory-mcp
 bun install
 ```
 
-**Configure Claude Code** - Add to `~/.claude/config.json`:
+**Configure your MCP client** (example config for clients that use `~/.claude/config.json`):
 ```json
 {
   "mcpServers": {
@@ -113,11 +117,14 @@ bun install
 
 ### Start Using It
 
-That's it! Restart Claude Code and you'll have access to memory tools:
-- `store_memory` - Save information for later recall
+That's it! Restart your MCP client and you'll have access to memory tools:
+- `store_memories` - Save memories for later recall (always pass array)
 - `search_memories` - Find relevant memories semantically
-- `get_memory` - Retrieve a specific memory by ID
-- `delete_memory` - Remove a memory
+- `get_memories` - Retrieve memories by ID (always pass array)
+- `update_memories` - Update existing memories in place
+- `delete_memories` - Remove memories (always pass array of IDs)
+- `store_handoff` - Store a handoff-style project snapshot
+- `get_handoff` - Retrieve the latest handoff (includes referenced memories)
 
 ---
 
@@ -125,14 +132,14 @@ That's it! Restart Claude Code and you'll have access to memory tools:
 
 ### Storing Memories
 
-Ask Claude Code to remember things for you:
+Ask your MCP client/agent to remember things for you:
 
 ```
 You: "Remember that we use Drizzle ORM for database access"
-Claude: [calls store_memory tool]
+Claude: [calls store_memories tool]
 ```
 
-Or Claude Code can store memories directly:
+Or your MCP client/agent can store memories directly:
 ```json
 {
   "content": "Use Drizzle ORM for type-safe database access",
@@ -145,7 +152,7 @@ Or Claude Code can store memories directly:
 
 ### Searching Memories
 
-Claude Code automatically searches memories when relevant, or you can ask:
+Your MCP client/agent can automatically search memories when relevant, or you can ask:
 
 ```
 You: "What did we decide about the database?"
@@ -217,7 +224,7 @@ vector-memory-mcp/
 ### 1. Memory Storage
 
 ```
-Claude Code calls store_memory tool
+An MCP client calls store_memories tool
          ↓
 Content → @huggingface/transformers → 384d vector
          ↓
@@ -229,7 +236,7 @@ Store in LanceDB with metadata
 ### 2. Memory Retrieval
 
 ```
-Claude Code calls search_memories
+An MCP client calls search_memories
          ↓
 Query → @huggingface/transformers → 384d vector
          ↓
@@ -246,7 +253,9 @@ Return top N relevant memories
 
 The server uses environment variables for configuration:
 
-- `VECTOR_MEMORY_DB_PATH` - Custom database path (default: `~/.local/share/vector-memory-mcp/memories.db`)
+- `VECTOR_MEMORY_DB_PATH` - Custom database path (default: `./.claude/vector-memories.db`)
+
+> Note: if you point multiple projects at the same DB path, `store_handoff` uses UUID.ZERO and will overwrite the previous handoff (by design).
 - `VECTOR_MEMORY_MODEL` - Embedding model to use (default: `Xenova/all-MiniLM-L6-v2`)
 
 Example:
@@ -255,7 +264,7 @@ export VECTOR_MEMORY_DB_PATH="/path/to/custom/memories.db"
 export VECTOR_MEMORY_MODEL="Xenova/all-MiniLM-L6-v2"
 ```
 
-Or in your Claude Code config:
+Or in your MCP client config:
 ```json
 {
   "mcpServers": {
@@ -276,7 +285,10 @@ Or in your Claude Code config:
 ### Running Tests
 
 ```bash
-# Run all tests
+# Run all tests (recommended - includes model preload)
+bun run test
+
+# Run tests directly (skips 19 embedding tests, faster)
 bun test
 
 # Run with coverage
@@ -286,6 +298,8 @@ bun test --coverage
 bun run typecheck
 ```
 
+> **Note:** `bun run test` uses a wrapper that preloads the embedding model, running all 98 tests. `bun test` directly is faster but skips embedding-specific tests.
+
 ### Development Mode
 
 ```bash
@@ -381,7 +395,7 @@ MIT License - see [LICENSE](LICENSE) for details.
 ## 🔗 Related Projects
 
 - [Model Context Protocol](https://modelcontextprotocol.io) - Official MCP specification
-- [Claude Code](https://claude.ai/code) - AI coding assistant from Anthropic
+- Any MCP-compatible client
 - [LanceDB](https://lancedb.com/) - Fast, local vector search
 - [Transformers.js](https://huggingface.co/docs/transformers.js) - Run transformers in JavaScript
 
@@ -402,7 +416,7 @@ MIT License - see [LICENSE](LICENSE) for details.
 ```
 You: "Remember that we decided to use Drizzle ORM for type-safe database access"
 Claude: I'll store that for you.
-  [Calls store_memory tool with content and metadata]
+  [Calls store_memories tool with content and metadata]
   ✓ Memory stored successfully
 ```
 

package/hooks/session-start.ts

@@ -0,0 +1,100 @@
+#!/usr/bin/env bun
+/**
+ * SessionStart hook for Claude Code
+ *
+ * Fetches config from the running vector-memory server's /health endpoint,
+ * then retrieves and outputs the latest handoff.
+ *
+ * Requires the server to be running with HTTP enabled.
+ *
+ * Usage in ~/.claude/settings.json:
+ * {
+ *   "hooks": {
+ *     "SessionStart": [{
+ *       "hooks": [{
+ *         "type": "command",
+ *         "command": "bun /path/to/vector-memory-mcp/hooks/session-start.ts"
+ *       }]
+ *     }]
+ *   }
+ * }
+ */
+
+import { existsSync } from "fs";
+import { connectToDatabase } from "../src/db/connection.js";
+import { MemoryRepository } from "../src/db/memory.repository.js";
+import { EmbeddingsService } from "../src/services/embeddings.service.js";
+import { MemoryService } from "../src/services/memory.service.js";
+
+const VECTOR_MEMORY_URL = process.env.VECTOR_MEMORY_URL ?? "http://127.0.0.1:3271";
+
+interface HealthResponse {
+  status: string;
+  config: {
+    dbPath: string;
+    embeddingModel: string;
+    embeddingDimension: number;
+  };
+}
+
+async function main() {
+  // Get config from running server
+  let health: HealthResponse;
+  try {
+    const response = await fetch(`${VECTOR_MEMORY_URL}/health`);
+    if (!response.ok) {
+      throw new Error(`Server returned ${response.status}`);
+    }
+    health = await response.json();
+  } catch (error) {
+    if (error instanceof Error && error.message.includes("ECONNREFUSED")) {
+      console.log("Vector memory server not running. Starting fresh session.");
+      return;
+    }
+    throw error;
+  }
+
+  const { dbPath, embeddingModel, embeddingDimension } = health.config;
+
+  // Check if DB exists
+  if (!existsSync(dbPath)) {
+    console.log("Vector memory database not found. Starting fresh session.");
+    return;
+  }
+
+  const db = await connectToDatabase(dbPath);
+  const repository = new MemoryRepository(db);
+  const embeddings = new EmbeddingsService(embeddingModel, embeddingDimension);
+  const service = new MemoryService(repository, embeddings);
+
+  const handoff = await service.getLatestHandoff();
+
+  if (!handoff) {
+    console.log("No handoff found. Starting fresh session.");
+    return;
+  }
+
+  // Fetch referenced memories if any
+  const memoryIds = (handoff.metadata.memory_ids as string[] | undefined) ?? [];
+  let memoriesSection = "";
+
+  if (memoryIds.length > 0) {
+    const memories: string[] = [];
+    for (const id of memoryIds) {
+      const memory = await service.get(id);
+      if (memory) {
+        memories.push(`### Memory: ${id}\n${memory.content}`);
+      }
+    }
+    if (memories.length > 0) {
+      memoriesSection = `\n\n## Referenced Memories\n\n${memories.join("\n\n")}`;
+    }
+  }
+
+  console.log(handoff.content + memoriesSection);
+}
+
+main().catch((err) => {
+  console.error("Error loading handoff:", err.message);
+  process.exit(1);
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aeriondyseti/vector-memory-mcp",
-  "version": "0.4.0",
+  "version": "0.8.0",
   "description": "A zero-configuration RAG memory server for MCP clients",
   "type": "module",
   "main": "src/index.ts",
@@ -10,6 +10,7 @@
   "files": [
     "src",
     "scripts",
+    "hooks",
     "README.md",
     "LICENSE"
   ],
@@ -25,20 +26,32 @@
   "scripts": {
     "start": "bun run src/index.ts",
     "dev": "bun --watch run src/index.ts",
+    "build": "bun run typecheck",
     "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",
     "warmup": "bun run scripts/warmup.ts",
-    "postinstall": "bun run scripts/warmup.ts"
+    "postinstall": "bun run scripts/warmup.ts",
+    "publish:check": "bun run scripts/publish.ts --dry-run",
+    "publish:npm": "bun run scripts/publish.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"
+    "arg": "^5.0.2",
+    "hono": "^4.11.3"
   },
   "devDependencies": {
     "@types/bun": "latest",
@@ -48,5 +61,8 @@
     "onnxruntime-node",
     "protobufjs",
     "sharp"
-  ]
+  ],
+  "overrides": {
+    "onnxruntime-node": "1.23.2"
+  }
 }

package/scripts/publish.ts

@@ -0,0 +1,61 @@
+#!/usr/bin/env bun
+/**
+ * Publish script for vector-memory-mcp
+ *
+ * Prerequisites:
+ * 1. Create a granular access token at https://www.npmjs.com/settings/tokens
+ * 2. Store it: npm config set //registry.npmjs.org/:_authToken=npm_YOUR_TOKEN
+ *    Or set NPM_TOKEN environment variable
+ *
+ * Usage: bun run scripts/publish.ts [--dry-run]
+ */
+
+import { $ } from "bun";
+
+const dryRun = process.argv.includes("--dry-run");
+
+async function main() {
+  // Check for authentication
+  console.log("🔐 Checking NPM authentication...");
+  try {
+    const whoami = await $`npm whoami`.text();
+    console.log(`✅ Authenticated as: ${whoami.trim()}`);
+  } catch {
+    console.error("❌ Not authenticated with NPM.");
+    console.error("   Option 1: npm login");
+    console.error("   Option 2: npm config set //registry.npmjs.org/:_authToken=npm_YOUR_TOKEN");
+    console.error("   Option 3: Set NPM_TOKEN environment variable");
+    process.exit(1);
+  }
+
+  // Run tests
+  console.log("🧪 Running tests...");
+  const testResult = await $`bun run test`.quiet();
+  if (testResult.exitCode !== 0) {
+    console.error("❌ Tests failed. Aborting publish.");
+    process.exit(1);
+  }
+  console.log("✅ Tests passed");
+
+  // Build
+  console.log("🔨 Building...");
+  await $`bun run build`;
+  console.log("✅ Build complete");
+
+  // Get version info
+  const pkg = await Bun.file("package.json").json();
+  console.log(`\n📦 Publishing ${pkg.name}@${pkg.version}...`);
+
+  if (dryRun) {
+    console.log("🔍 Dry run - would publish:");
+    await $`npm publish --dry-run`;
+  } else {
+    await $`npm publish --access public`;
+    console.log(`\n✅ Published ${pkg.name}@${pkg.version}`);
+  }
+}
+
+main().catch((err) => {
+  console.error("❌ Publish failed:", err.message);
+  process.exit(1);
+});

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

@@ -52,8 +52,7 @@ async function warmup(): Promise<void> {
     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("Ready to use! Configure your MCP client and restart to get started.");
     console.log();
   } catch (error) {
     console.error();

package/src/config/index.ts

@@ -1,29 +1,75 @@
+import arg from "arg";
 import { join } from "path";
-import { homedir } from "os";
+
+export type TransportMode = "stdio" | "http" | "both";
 
 export interface Config {
   dbPath: string;
   embeddingModel: string;
   embeddingDimension: number;
+  httpPort: number;
+  httpHost: string;
+  enableHttp: boolean;
+  transportMode: TransportMode;
 }
 
-const DEFAULT_DB_PATH = join(
-  homedir(),
-  ".local",
-  "share",
-  "vector-memory-mcp",
-  "memories.db"
-);
+export interface ConfigOverrides {
+  dbPath?: string;
+  httpPort?: number;
+  enableHttp?: boolean;
+  transportMode?: TransportMode;
+}
 
+// Defaults - always use repo-local .vector-memory folder
+const DEFAULT_DB_PATH = join(process.cwd(), ".vector-memory", "memories.db");
 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";
+
+function resolvePath(path: string): string {
+  return path.startsWith("/") ? path : join(process.cwd(), path);
+}
+
+export function loadConfig(overrides: ConfigOverrides = {}): Config {
+  const transportMode = overrides.transportMode ?? "stdio";
+  // HTTP enabled by default (needed for hooks), can disable with --no-http
+  const enableHttp = overrides.enableHttp ?? true;
 
-export function loadConfig(): Config {
   return {
-    dbPath: process.env.VECTOR_MEMORY_DB_PATH ?? DEFAULT_DB_PATH,
-    embeddingModel: process.env.VECTOR_MEMORY_MODEL ?? DEFAULT_EMBEDDING_MODEL,
+    dbPath: resolvePath(overrides.dbPath ?? DEFAULT_DB_PATH),
+    embeddingModel: DEFAULT_EMBEDDING_MODEL,
     embeddingDimension: DEFAULT_EMBEDDING_DIMENSION,
+    httpPort: overrides.httpPort ?? DEFAULT_HTTP_PORT,
+    httpHost: DEFAULT_HTTP_HOST,
+    enableHttp,
+    transportMode,
+  };
+}
+
+/**
+ * Parse CLI arguments into config overrides.
+ */
+export function parseCliArgs(argv: string[]): ConfigOverrides {
+  const args = arg(
+    {
+      "--db-file": String,
+      "--port": Number,
+      "--no-http": Boolean,
+
+      // Aliases
+      "-d": "--db-file",
+      "-p": "--port",
+    },
+    { argv, permissive: true }
+  );
+
+  return {
+    dbPath: args["--db-file"],
+    httpPort: args["--port"],
+    enableHttp: args["--no-http"] ? false : undefined,
   };
 }
 
+// Default config for imports that don't use CLI args
 export const config = loadConfig();

package/src/db/memory.repository.ts

@@ -33,6 +33,27 @@ export class MemoryRepository {
     ]);
   }
 
+  async upsert(memory: Memory): Promise<void> {
+    const table = await this.getTable();
+    const existing = await table.query().where(`id = '${memory.id}'`).limit(1).toArray();
+
+    if (existing.length === 0) {
+      return await this.insert(memory);
+    }
+
+    await table.update({
+      where: `id = '${memory.id}'`,
+      values: {
+        vector: memory.embedding,
+        content: memory.content,
+        metadata: JSON.stringify(memory.metadata),
+        created_at: memory.createdAt.getTime(),
+        updated_at: memory.updatedAt.getTime(),
+        superseded_by: memory.supersededBy,
+      },
+    });
+  }
+
   async findById(id: string): Promise<Memory | null> {
     const table = await this.getTable();
     const results = await table.query().where(`id = '${id}'`).limit(1).toArray();

package/src/db/schema.ts

@@ -31,3 +31,4 @@ export const memorySchema = new Schema([
   ),
   new Field("superseded_by", new Utf8(), true), // Nullable
 ]);
+