@aeriondyseti/vector-memory-mcp 2.2.3 → 2.3.0-rc.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,14 +1,14 @@
 {
   "name": "@aeriondyseti/vector-memory-mcp",
-  "version": "2.2.3",
+  "version": "2.3.0-rc.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",
+    "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/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;
   }