@aeriondyseti/vector-memory-mcp 2.2.2 → 2.2.6

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,14 +1,14 @@
 {
   "name": "@aeriondyseti/vector-memory-mcp",
-  "version": "2.2.2",
+  "version": "2.2.6",
   "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",
+    "server",
     "scripts",
     "README.md",
     "LICENSE"
@@ -23,8 +23,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 +35,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",

package/scripts/lancedb-extract.ts

@@ -14,24 +14,59 @@ if (!source) {
   process.exit(1);
 }
 
-/**
- * Read a value from an Arrow column at a given row index.
- * Arrow timestamp columns return BigInt — we convert to epoch-ms here
- * without going through Arrow's bigIntToNumber safety check.
- */
+// Arrow TimeUnit enum → divisor to convert to milliseconds.
+// 0=SECOND, 1=MILLISECOND, 2=MICROSECOND, 3=NANOSECOND
+// Negative divisor = multiply (seconds → ms needs ×1000).
+const TIME_UNIT_TO_MS_DIVISOR: Record<number, bigint> = {
+  0: -1000n,   // seconds → ms (multiply by 1000)
+  1: 1n,       // ms → no conversion
+  2: 1000n,    // μs → ms
+  3: 1000000n, // ns → ms
+};
+
+function buildTimestampDivisors(schema: any): Map<string, bigint> {
+  const map = new Map<string, bigint>();
+  for (const field of schema.fields) {
+    if (field.type.typeId === 10) {
+      map.set(field.name, TIME_UNIT_TO_MS_DIVISOR[field.type.unit] ?? 1n);
+    }
+  }
+  return map;
+}
+
 function columnValue(batch: any, colName: string, rowIdx: number): unknown {
   const col = batch.getChild(colName);
   if (!col) return undefined;
-  return col.get(rowIdx);
+  try {
+    return col.get(rowIdx);
+  } catch {
+    // Arrow's getter can throw on BigInt timestamps exceeding MAX_SAFE_INTEGER;
+    // fall back to the raw typed array.
+    let offset = rowIdx;
+    for (const data of col.data) {
+      if (offset < data.length) {
+        return (data.values instanceof BigInt64Array || data.values instanceof BigUint64Array)
+          ? data.values[offset]
+          : null;
+      }
+      offset -= data.length;
+    }
+    return null;
+  }
 }
 
-function toEpochMs(value: unknown): number {
-  if (typeof value === "number") return value;
+function toEpochMs(value: unknown, divisor: bigint = 1n): number {
+  if (value == null) return Date.now();
   if (value instanceof Date) return value.getTime();
   if (typeof value === "bigint") {
-    // Arrow timestamps are microseconds; convert to milliseconds.
-    const ms = value / 1000n;
-    return Number(ms);
+    if (divisor < 0n) return Number(value * -divisor);  // seconds → ms
+    if (divisor === 1n) return Number(value);
+    return Number(value / divisor);
+  }
+  if (typeof value === "number") {
+    if (divisor < 0n) return value * Number(-divisor);
+    if (divisor === 1n) return value;
+    return Math.floor(value / Number(divisor));
   }
   return Date.now();
 }
@@ -49,6 +84,7 @@ function toFloatArray(vec: unknown): number[] {
   return [];
 }
 
+const BATCH_SIZE = 100;
 const lancedb = await import("@lancedb/lancedb");
 const db = await lancedb.connect(source);
 const tableNames = await db.tableNames();
@@ -64,27 +100,45 @@ if (tableNames.includes("memories")) {
   const total = await table.countRows();
   console.error(`Reading ${total} memories...`);
 
-  // Use toArrow() to get raw Arrow RecordBatches, bypassing StructRow
-  // property accessors that throw on BigInt timestamps.
-  const arrowTable = await table.query().toArrow();
-  for (const batch of arrowTable.batches) {
-    for (let i = 0; i < batch.numRows; i++) {
-      const lastAccessed = columnValue(batch, "last_accessed", i);
-      result.memories.push({
-        id: columnValue(batch, "id", i),
-        content: columnValue(batch, "content", i),
-        metadata: columnValue(batch, "metadata", i) ?? "{}",
-        vector: toFloatArray(columnValue(batch, "vector", i)),
-        created_at: toEpochMs(columnValue(batch, "created_at", i)),
-        updated_at: toEpochMs(columnValue(batch, "updated_at", i)),
-        last_accessed: lastAccessed != null ? toEpochMs(lastAccessed) : null,
-        superseded_by: columnValue(batch, "superseded_by", i) ?? null,
-        usefulness: columnValue(batch, "usefulness", i) ?? 0,
-        access_count: columnValue(batch, "access_count", i) ?? 0,
-      });
+  // Paginated scan — query().toArrow() without offset/limit returns
+  // non-deterministic results that can duplicate some rows and skip others.
+  const schemaSample = await table.query().limit(1).toArrow();
+  const tsDivisors = buildTimestampDivisors(schemaSample.schema);
+  const seen = new Map<string, any>();
+
+  for (let offset = 0; offset < total; offset += BATCH_SIZE) {
+    const arrowTable = await table.query().offset(offset).limit(BATCH_SIZE).toArrow();
+    for (const batch of arrowTable.batches) {
+      for (let i = 0; i < batch.numRows; i++) {
+        const id = columnValue(batch, "id", i) as string;
+        const content = columnValue(batch, "content", i) as string;
+        const lastAccessed = columnValue(batch, "last_accessed", i);
+        const accessedMs = lastAccessed != null ? toEpochMs(lastAccessed, tsDivisors.get("last_accessed")) : null;
+        // Deduplicate by ID: prefer most recently accessed, then longest content.
+        const existing = seen.get(id);
+        if (existing) {
+          const existingAccess = existing.last_accessed ?? 0;
+          const newAccess = accessedMs ?? 0;
+          if (newAccess < existingAccess) continue;
+          if (newAccess === existingAccess && content.length <= existing.content.length) continue;
+        }
+        seen.set(id, {
+          id,
+          content,
+          metadata: columnValue(batch, "metadata", i) ?? "{}",
+          vector: toFloatArray(columnValue(batch, "vector", i)),
+          created_at: toEpochMs(columnValue(batch, "created_at", i), tsDivisors.get("created_at")),
+          updated_at: toEpochMs(columnValue(batch, "updated_at", i), tsDivisors.get("updated_at")),
+          last_accessed: accessedMs,
+          superseded_by: columnValue(batch, "superseded_by", i) ?? null,
+          usefulness: columnValue(batch, "usefulness", i) ?? 0,
+          access_count: columnValue(batch, "access_count", i) ?? 0,
+        });
+      }
     }
   }
-  console.error(`  ${result.memories.length} memories read`);
+  result.memories = [...seen.values()];
+  console.error(`  ${result.memories.length} unique memories read (${total} rows scanned)`);
 }
 
 if (tableNames.includes("conversation_history")) {
@@ -92,24 +146,35 @@ if (tableNames.includes("conversation_history")) {
   const total = await table.countRows();
   console.error(`Reading ${total} conversation chunks...`);
 
-  const arrowTable = await table.query().toArrow();
-  for (const batch of arrowTable.batches) {
-    for (let i = 0; i < batch.numRows; i++) {
-      result.conversations.push({
-        id: columnValue(batch, "id", i),
-        content: columnValue(batch, "content", i),
-        metadata: columnValue(batch, "metadata", i) ?? "{}",
-        vector: toFloatArray(columnValue(batch, "vector", i)),
-        created_at: toEpochMs(columnValue(batch, "created_at", i)),
-        session_id: columnValue(batch, "session_id", i),
-        role: columnValue(batch, "role", i),
-        message_index_start: columnValue(batch, "message_index_start", i) ?? 0,
-        message_index_end: columnValue(batch, "message_index_end", i) ?? 0,
-        project: columnValue(batch, "project", i) ?? "",
-      });
+  const schemaSample = await table.query().limit(1).toArrow();
+  const tsDivisors = buildTimestampDivisors(schemaSample.schema);
+  const seen = new Map<string, any>();
+
+  for (let offset = 0; offset < total; offset += BATCH_SIZE) {
+    const arrowTable = await table.query().offset(offset).limit(BATCH_SIZE).toArrow();
+    for (const batch of arrowTable.batches) {
+      for (let i = 0; i < batch.numRows; i++) {
+        const id = columnValue(batch, "id", i) as string;
+        const content = columnValue(batch, "content", i) as string;
+        const existing = seen.get(id);
+        if (existing && existing.content.length >= content.length) continue;
+        seen.set(id, {
+          id,
+          content,
+          metadata: columnValue(batch, "metadata", i) ?? "{}",
+          vector: toFloatArray(columnValue(batch, "vector", i)),
+          created_at: toEpochMs(columnValue(batch, "created_at", i), tsDivisors.get("created_at")),
+          session_id: columnValue(batch, "session_id", i),
+          role: columnValue(batch, "role", i),
+          message_index_start: columnValue(batch, "message_index_start", i) ?? 0,
+          message_index_end: columnValue(batch, "message_index_end", i) ?? 0,
+          project: columnValue(batch, "project", i) ?? "",
+        });
+      }
     }
   }
-  console.error(`  ${result.conversations.length} conversation chunks read`);
+  result.conversations = [...seen.values()];
+  console.error(`  ${result.conversations.length} unique conversation chunks read (${total} rows scanned)`);
 }
 
 await db.close?.();

package/scripts/migrate-from-lancedb.ts

@@ -2,7 +2,7 @@
 /**
  * Standalone migration script: LanceDB → SQLite (sqlite-vec)
  *
- * This is a thin wrapper around src/migration.ts for direct invocation.
+ * This is a thin wrapper around server/migration.ts for direct invocation.
  * The preferred way to migrate is `vector-memory-mcp migrate`.
  *
  * Usage:
@@ -16,7 +16,7 @@
  *   removed in the next major version.
  */
 
-import { migrate, formatMigrationSummary } from "../src/migration.js";
+import { migrate, formatMigrationSummary } from "../server/migration.js";
 
 function parseArgs(): { source: string; target: string } {
   const args = process.argv.slice(2);

package/scripts/smoke-test.ts

@@ -30,7 +30,7 @@ import { tmpdir } from "os";
 
 // ── Helpers ─────────────────────────────────────────────────────────
 
-const SERVER_PATH = join(import.meta.dir, "../src/index.ts");
+const SERVER_PATH = join(import.meta.dir, "../server/index.ts");
 
 let passed = 0;
 let failed = 0;

package/scripts/sync-version.ts

@@ -0,0 +1,35 @@
+#!/usr/bin/env bun
+/**
+ * Sync version into .claude-plugin/ manifest files.
+ *
+ * Usage:
+ *   bun scripts/sync-version.ts           # reads version from package.json
+ *   bun scripts/sync-version.ts 2.2.3-dev.4  # uses explicit version
+ */
+
+import { readFileSync, writeFileSync } from "fs";
+import { join } from "path";
+
+const ROOT = join(import.meta.dir, "..");
+const PKG_PATH = join(ROOT, "package.json");
+const PLUGIN_PATH = join(ROOT, ".claude-plugin", "plugin.json");
+const MARKETPLACE_PATH = join(ROOT, ".claude-plugin", "marketplace.json");
+
+const explicit = process.argv[2];
+const pkg = JSON.parse(readFileSync(PKG_PATH, "utf-8"));
+const version: string = explicit ?? pkg.version;
+
+// Stamp plugin.json
+const plugin = JSON.parse(readFileSync(PLUGIN_PATH, "utf-8"));
+plugin.version = version;
+writeFileSync(PLUGIN_PATH, JSON.stringify(plugin, null, 2) + "\n");
+
+// Stamp marketplace.json
+const marketplace = JSON.parse(readFileSync(MARKETPLACE_PATH, "utf-8"));
+marketplace.metadata.version = version;
+for (const p of marketplace.plugins) {
+  p.version = version;
+}
+writeFileSync(MARKETPLACE_PATH, JSON.stringify(marketplace, null, 2) + "\n");
+
+console.error(`Synced version ${version} → plugin.json, marketplace.json`);

package/scripts/warmup.ts

@@ -5,8 +5,8 @@
  * 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";
+import { config } from "../server/config/index.js";
+import { EmbeddingsService } from "../server/core/embeddings.service.js";
 
 async function warmup(): Promise<void> {
   console.log("🔥 Warming up vector-memory-mcp...");

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/{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;
   }