@aeriondyseti/vector-memory-mcp 2.2.3 → 2.2.6-dev.1

package/README.md

@@ -20,14 +20,27 @@ A local-first MCP server that provides vector-based memory storage. Uses local e
 
 ---
 
-## Quick Start
+## Installation
 
-### Prerequisites
+There are two ways to install Vector Memory, depending on how much integration you want.
 
-- [Bun](https://bun.sh/) 1.0+
-- An MCP-compatible client (Claude Code, Claude Desktop, etc.)
+### Option A: Claude Code Plugin (recommended)
+
+Install as a plugin to get the full experience: MCP server, session lifecycle hooks, waypoint skills, and context monitoring — all managed automatically.
+
+```bash
+# Add the marketplace
+claude plugin marketplace add AerionDyseti/vector-memory-mcp
+
+# Install the plugin
+claude plugin install vector-memory@vector-memory-mcp
+```
+
+This clones the repo and runs the MCP server directly from source. Hooks handle session start/clear/compact events, and skills provide `/waypoint:set`, `/waypoint:get`, and memory usage guidance.
+
+### Option B: MCP Server Only
 
-### Install
+Install just the MCP server via npm if you want memory storage without hooks or skills, or if you're using a non-Claude Code MCP client.
 
 ```bash
 bun install -g @aeriondyseti/vector-memory-mcp
@@ -35,9 +48,7 @@ bun install -g @aeriondyseti/vector-memory-mcp
 
 > First install downloads ML models (~90MB). This may take a minute.
 
-### Configure
-
-Add to your MCP client config (e.g., `~/.claude/settings.json`):
+Then add to your MCP client config (e.g., `~/.claude/settings.json`):
 
 ```json
 {
@@ -51,9 +62,16 @@ Add to your MCP client config (e.g., `~/.claude/settings.json`):
 }
 ```
 
-### Use
+### Prerequisites
 
-Restart your MCP client. You now have access to:
+- [Bun](https://bun.sh/) 1.0+
+- An MCP-compatible client (Claude Code, Claude Desktop, etc.)
+
+---
+
+## Tools
+
+Restart your MCP client after installation. You now have access to:
 
 | Tool | Description |
 |------|-------------|
@@ -116,7 +134,9 @@ CLI flags:
 
 ## Release Channels
 
-The stable release is what you get by default:
+**Plugin users:** The plugin tracks the repo's default branch. To switch channels, reinstall from a specific branch or tag.
+
+**npm users:** The stable release is what you get by default:
 
 ```bash
 bun install -g @aeriondyseti/vector-memory-mcp
@@ -124,8 +144,8 @@ bun install -g @aeriondyseti/vector-memory-mcp
 
 Pre-release channels are available for testing upcoming changes. **These are unstable and may break without notice — use at your own risk.**
 
-| Channel | Install | Description |
-|---------|---------|-------------|
+| Channel | npm | Description |
+|---------|-----|-------------|
 | `@latest` | *(default)* | Stable releases |
 | `@rc` | `@aeriondyseti/vector-memory-mcp@rc` | Release candidates — final testing before stable |
 | `@dev` | `@aeriondyseti/vector-memory-mcp@dev` | Development builds — latest features, least stable |

package/package.json

@@ -1,15 +1,14 @@
 {
   "name": "@aeriondyseti/vector-memory-mcp",
-  "version": "2.2.3",
+  "version": "2.2.6-dev.1",
   "description": "A zero-configuration RAG memory server for MCP clients",
   "type": "module",
-  "main": "src/index.ts",
+  "main": "server/index.ts",
   "bin": {
-    "vector-memory-mcp": "src/index.ts"
+    "vector-memory-mcp": "server/index.ts"
   },
   "files": [
-    "src",
-    "scripts",
+    "server",
     "README.md",
     "LICENSE"
   ],
@@ -23,8 +22,8 @@
   },
   "homepage": "https://github.com/aeriondyseti/vector-memory-mcp#readme",
   "scripts": {
-    "start": "bun run src/index.ts",
-    "dev": "bun --watch run src/index.ts",
+    "start": "bun run server/index.ts",
+    "dev": "bun --watch run server/index.ts",
     "typecheck": "bunx tsc --noEmit",
     "test": "bun run scripts/test-runner.ts",
     "test:raw": "bun test --preload ./tests/preload.ts",
@@ -35,7 +34,8 @@
     "smoke": "bun run scripts/smoke-test.ts",
     "warmup": "bun run scripts/warmup.ts",
     "postinstall": "bun run scripts/warmup.ts",
-    "prepublishOnly": "bunx tsc --noEmit"
+    "prepublishOnly": "bunx tsc --noEmit",
+    "postversion": "bun scripts/sync-version.ts"
   },
   "keywords": [
     "mcp",
@@ -46,18 +46,18 @@
   ],
   "license": "MIT",
   "dependencies": {
-    "@huggingface/transformers": "^3.8.0",
+    "@huggingface/tokenizers": "^0.1.3",
     "@lancedb/lancedb": "^0.26.2",
     "@modelcontextprotocol/sdk": "^1.0.0",
     "arg": "^5.0.2",
-    "hono": "^4.11.3"
+    "hono": "^4.11.3",
+    "onnxruntime-node": "^1.21.0"
   },
   "devDependencies": {
     "@types/bun": "latest",
     "typescript": "^5.0.0"
   },
   "trustedDependencies": [
-    "protobufjs",
-    "sharp"
+    "protobufjs"
   ]
 }

package/{src → server}/config/index.ts

@@ -28,6 +28,7 @@ export interface Config {
   httpPort: number;
   httpHost: string;
   enableHttp: boolean;
+  pluginMode: boolean;
   transportMode: TransportMode;
   conversationHistory: ConversationHistoryConfig;
 }
@@ -36,6 +37,7 @@ export interface ConfigOverrides {
   dbPath?: string;
   httpPort?: number;
   enableHttp?: boolean;
+  pluginMode?: boolean;
   transportMode?: TransportMode;
   enableHistory?: boolean;
   historyPath?: string;
@@ -55,8 +57,11 @@ function resolvePath(path: string): string {
 
 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;
+  const pluginMode = overrides.pluginMode ?? false;
+  // HTTP enabled only in plugin mode (hooks need it). --no-http overrides.
+  // Force HTTP on if transport mode requires it, regardless of plugin mode.
+  const enableHttp = overrides.enableHttp
+    ?? (transportMode === "http" || transportMode === "both" || pluginMode);
 
   return {
     dbPath: resolvePath(
@@ -74,6 +79,7 @@ export function loadConfig(overrides: ConfigOverrides = {}): Config {
       ?? DEFAULT_HTTP_PORT,
     httpHost: DEFAULT_HTTP_HOST,
     enableHttp,
+    pluginMode,
     transportMode,
     conversationHistory: {
       enabled: overrides.enableHistory ?? false,
@@ -95,6 +101,7 @@ export function parseCliArgs(argv: string[]): ConfigOverrides {
       "--db-file": String,
       "--port": Number,
       "--no-http": Boolean,
+      "--plugin": Boolean,
       "--enable-history": Boolean,
       "--history-path": String,
       "--history-weight": Number,
@@ -110,6 +117,7 @@ export function parseCliArgs(argv: string[]): ConfigOverrides {
     dbPath: args["--db-file"],
     httpPort: args["--port"],
     enableHttp: args["--no-http"] ? false : undefined,
+    pluginMode: args["--plugin"] ?? undefined,
     enableHistory: args["--enable-history"] ?? undefined,
     historyPath: args["--history-path"],
     historyWeight: args["--history-weight"],

package/{src/db → server/core}/connection.ts

@@ -1,7 +1,7 @@
 import { Database } from "bun:sqlite";
-import { mkdirSync } from "fs";
+import { existsSync, mkdirSync } from "fs";
 import { dirname } from "path";
-import { runMigrations } from "./migrations.js";
+import { removeVec0Tables, runMigrations } from "./migrations.js";
 
 /**
  * Open (or create) a SQLite database at the given path
@@ -9,6 +9,14 @@ import { runMigrations } from "./migrations.js";
  */
 export function connectToDatabase(dbPath: string): Database {
   mkdirSync(dirname(dbPath), { recursive: true });
+
+  // Remove orphaned vec0 virtual table entries before bun:sqlite opens the
+  // database. bun:sqlite cannot modify sqlite_master, so this uses the
+  // sqlite3 CLI while no other connection holds a lock.
+  if (existsSync(dbPath)) {
+    removeVec0Tables(dbPath);
+  }
+
   const db = new Database(dbPath);
 
   // WAL mode for concurrent read performance

package/{src/db → server/core}/conversation.repository.ts

@@ -2,7 +2,7 @@ import type { Database } from "bun:sqlite";
 import type {
   ConversationHybridRow,
   HistoryFilters,
-} from "../types/conversation.js";
+} from "./conversation.js";
 import {
   serializeVector,
   safeParseJsonObject,

package/{src/services → server/core}/conversation.service.ts

@@ -1,7 +1,7 @@
 import { createHash } from "crypto";
 import { readFile, writeFile, mkdir } from "fs/promises";
 import { dirname, join } from "path";
-import type { ConversationRepository } from "../db/conversation.repository.js";
+import type { ConversationRepository } from "./conversation.repository.js";
 import type {
   ConversationChunk,
   ConversationHybridRow,
@@ -10,7 +10,7 @@ import type {
   ParsedMessage,
   SessionFileInfo,
   SessionIndexDetail,
-} from "../types/conversation.js";
+} from "./conversation.js";
 import type { ConversationHistoryConfig } from "../config/index.js";
 import { resolveSessionLogPath } from "../config/index.js";
 import type { EmbeddingsService } from "./embeddings.service.js";

package/server/core/embeddings.service.ts

@@ -0,0 +1,125 @@
+import * as ort from "onnxruntime-node";
+import { Tokenizer } from "@huggingface/tokenizers";
+import { join, dirname } from "path";
+import { mkdir } from "fs/promises";
+import { existsSync } from "fs";
+
+const HF_CDN = "https://huggingface.co";
+const MAX_SEQ_LENGTH = 512;
+
+export class EmbeddingsService {
+  private modelName: string;
+  private session: ort.InferenceSession | null = null;
+  private tokenizer: Tokenizer | null = null;
+  private initPromise: Promise<void> | null = null;
+  private _dimension: number;
+
+  constructor(modelName: string, dimension: number) {
+    this.modelName = modelName;
+    this._dimension = dimension;
+  }
+
+  get dimension(): number {
+    return this._dimension;
+  }
+
+  private async initialize(): Promise<void> {
+    if (this.session) return;
+    if (!this.initPromise) {
+      this.initPromise = this._init();
+    }
+    await this.initPromise;
+  }
+
+  private get cacheDir(): string {
+    const packageRoot = join(dirname(Bun.main), "..");
+    return join(packageRoot, ".cache", "models", this.modelName);
+  }
+
+  private async downloadIfMissing(fileName: string): Promise<string> {
+    const filePath = join(this.cacheDir, fileName);
+    if (existsSync(filePath)) return filePath;
+
+    const url = `${HF_CDN}/${this.modelName}/resolve/main/${fileName}`;
+    await mkdir(dirname(filePath), { recursive: true });
+    const response = await fetch(url);
+    if (!response.ok) throw new Error(`Failed to download ${url}: ${response.status}`);
+    const buffer = await response.arrayBuffer();
+    await Bun.write(filePath, buffer);
+    return filePath;
+  }
+
+  private async _init(): Promise<void> {
+    const modelPath = await this.downloadIfMissing("onnx/model.onnx");
+    const tokenizerJsonPath = await this.downloadIfMissing("tokenizer.json");
+    const tokenizerConfigPath = await this.downloadIfMissing("tokenizer_config.json");
+
+    this.session = await ort.InferenceSession.create(modelPath, {
+      executionProviders: ["cpu"],
+    });
+
+    const tokenizerJson = await Bun.file(tokenizerJsonPath).json();
+    const tokenizerConfig = await Bun.file(tokenizerConfigPath).json();
+    this.tokenizer = new Tokenizer(tokenizerJson, tokenizerConfig);
+  }
+
+  async embed(text: string): Promise<number[]> {
+    await this.initialize();
+
+    const encoded = this.tokenizer!.encode(text);
+
+    // Truncate to model's max sequence length
+    const seqLen = Math.min(encoded.ids.length, MAX_SEQ_LENGTH);
+    const ids = encoded.ids.slice(0, seqLen);
+    const mask = encoded.attention_mask.slice(0, seqLen);
+
+    const inputIds = BigInt64Array.from(ids.map(BigInt));
+    const attentionMask = BigInt64Array.from(mask.map(BigInt));
+    const tokenTypeIds = new BigInt64Array(seqLen); // zeros for single-sequence input
+
+    const feeds: Record<string, ort.Tensor> = {
+      input_ids: new ort.Tensor("int64", inputIds, [1, seqLen]),
+      attention_mask: new ort.Tensor("int64", attentionMask, [1, seqLen]),
+      token_type_ids: new ort.Tensor("int64", tokenTypeIds, [1, seqLen]),
+    };
+
+    const output = await this.session!.run(feeds);
+    const lastHidden = output["last_hidden_state"];
+
+    const pooled = this.meanPool(lastHidden.data as Float32Array, mask, seqLen);
+    return this.normalize(pooled);
+  }
+
+  async embedBatch(texts: string[]): Promise<number[][]> {
+    const results: number[][] = [];
+    for (const text of texts) {
+      results.push(await this.embed(text));
+    }
+    return results;
+  }
+
+  private meanPool(data: Float32Array, mask: number[], seqLen: number): number[] {
+    const dim = this._dimension;
+    const pooled = new Array(dim).fill(0);
+    let maskSum = 0;
+    for (let t = 0; t < seqLen; t++) {
+      if (mask[t]) {
+        maskSum += 1;
+        for (let d = 0; d < dim; d++) {
+          pooled[d] += data[t * dim + d];
+        }
+      }
+    }
+    for (let d = 0; d < dim; d++) {
+      pooled[d] /= maskSum;
+    }
+    return pooled;
+  }
+
+  private normalize(vec: number[]): number[] {
+    let norm = 0;
+    for (const v of vec) norm += v * v;
+    norm = Math.sqrt(norm);
+    return vec.map(v => v / norm);
+  }
+}

package/{src/db → server/core}/memory.repository.ts

@@ -12,11 +12,15 @@ import {
   type Memory,
   type HybridRow,
   DELETED_TOMBSTONE,
-} from "../types/memory.js";
+} from "./memory.js";
 
 export class MemoryRepository {
   constructor(private db: Database) {}
 
+  getDb(): Database {
+    return this.db;
+  }
+
   // ---------------------------------------------------------------------------
   // Row mapping
   // ---------------------------------------------------------------------------

package/{src/services → server/core}/memory.service.ts

@@ -1,8 +1,8 @@
 import { randomUUID, createHash } from "crypto";
-import type { Memory, SearchIntent, IntentProfile, HybridRow } from "../types/memory.js";
-import { isDeleted } from "../types/memory.js";
-import type { SearchResult, SearchOptions } from "../types/conversation.js";
-import type { MemoryRepository } from "../db/memory.repository.js";
+import type { Memory, SearchIntent, IntentProfile, HybridRow } from "./memory.js";
+import { isDeleted } from "./memory.js";
+import type { SearchResult, SearchOptions } from "./conversation.js";
+import type { MemoryRepository } from "./memory.repository.js";
 import type { EmbeddingsService } from "./embeddings.service.js";
 import type { ConversationHistoryService } from "./conversation.service.js";
 
@@ -32,6 +32,14 @@ export class MemoryService {
     return this.conversationService;
   }
 
+  getRepository(): MemoryRepository {
+    return this.repository;
+  }
+
+  getEmbeddings(): EmbeddingsService {
+    return this.embeddings;
+  }
+
   async store(
     content: string,
     metadata: Record<string, unknown> = {},
@@ -366,6 +374,14 @@ ${list(args.memory_ids)}`;
     };
 
     await this.repository.upsert(memory);
+
+    // Always update the global (no-project) waypoint so the session-start
+    // hook can find the most recent waypoint without knowing the project name.
+    const globalId = MemoryService.UUID_ZERO;
+    if (memory.id !== globalId) {
+      await this.repository.upsert({ ...memory, id: globalId });
+    }
+
     return memory;
   }