@aeriondyseti/vector-memory-mcp 2.2.2 → 2.2.6

package/server/core/migrations.ts

@@ -0,0 +1,115 @@
+import type { Database } from "bun:sqlite";
+
+/**
+ * Pre-migration step: remove vec0 virtual table entries from sqlite_master
+ * and drop their shadow tables using the sqlite3 CLI.
+ *
+ * Must run BEFORE bun:sqlite opens the database because:
+ *  - bun:sqlite cannot modify sqlite_master (no writable_schema support)
+ *  - DROP TABLE on a virtual table requires the extension module to be loaded
+ *  - SQLite 3.51+ has defensive mode on by default, requiring .dbconfig override
+ *
+ * Safe to call on any database — it's a no-op if there are no vec0 tables.
+ */
+export function removeVec0Tables(dbPath: string): void {
+  const result = Bun.spawnSync({
+    cmd: ["sqlite3", dbPath],
+    stdin: new TextEncoder().encode(
+      [
+        ".dbconfig defensive off",
+        ".dbconfig writable_schema on",
+        // Drop shadow tables (regular tables, no extension needed)
+        "DROP TABLE IF EXISTS memories_vec_rowids;",
+        "DROP TABLE IF EXISTS memories_vec_chunks;",
+        "DROP TABLE IF EXISTS memories_vec_info;",
+        "DROP TABLE IF EXISTS memories_vec_vector_chunks00;",
+        "DROP TABLE IF EXISTS memories_vec_migration_tmp;",
+        "DROP TABLE IF EXISTS conversation_history_vec_rowids;",
+        "DROP TABLE IF EXISTS conversation_history_vec_chunks;",
+        "DROP TABLE IF EXISTS conversation_history_vec_info;",
+        "DROP TABLE IF EXISTS conversation_history_vec_vector_chunks00;",
+        "DROP TABLE IF EXISTS conversation_history_vec_migration_tmp;",
+        // Remove orphaned vec0 virtual table entries from schema
+        "DELETE FROM sqlite_master WHERE sql LIKE '%vec0%';",
+      ].join("\n"),
+    ),
+  });
+  if (result.exitCode !== 0) {
+    const stderr = result.stderr.toString().trim();
+    if (!stderr.includes("unable to open database")) {
+      throw new Error(`vec0 cleanup failed: ${stderr}`);
+    }
+  }
+}
+
+/**
+ * Run all schema migrations. Safe to call on every startup (uses IF NOT EXISTS).
+ *
+ * IMPORTANT: Call removeVec0Tables(dbPath) before opening the database
+ * with bun:sqlite if the database may contain vec0 virtual tables.
+ */
+export function runMigrations(db: Database): void {
+  // -- Memories --
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS memories (
+      id            TEXT PRIMARY KEY,
+      content       TEXT NOT NULL,
+      metadata      TEXT NOT NULL DEFAULT '{}',
+      created_at    INTEGER NOT NULL,
+      updated_at    INTEGER NOT NULL,
+      superseded_by TEXT,
+      usefulness    REAL NOT NULL DEFAULT 0.0,
+      access_count  INTEGER NOT NULL DEFAULT 0,
+      last_accessed INTEGER
+    )
+  `);
+
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS memories_vec (
+      id     TEXT PRIMARY KEY,
+      vector BLOB NOT NULL
+    )
+  `);
+
+  db.exec(`
+    CREATE VIRTUAL TABLE IF NOT EXISTS memories_fts USING fts5(
+      id UNINDEXED,
+      content
+    )
+  `);
+
+  // -- Conversation History --
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS conversation_history (
+      id                  TEXT PRIMARY KEY,
+      content             TEXT NOT NULL,
+      metadata            TEXT NOT NULL DEFAULT '{}',
+      created_at          INTEGER NOT NULL,
+      session_id          TEXT NOT NULL,
+      role                TEXT NOT NULL,
+      message_index_start INTEGER NOT NULL,
+      message_index_end   INTEGER NOT NULL,
+      project             TEXT NOT NULL
+    )
+  `);
+
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS conversation_history_vec (
+      id     TEXT PRIMARY KEY,
+      vector BLOB NOT NULL
+    )
+  `);
+
+  db.exec(`
+    CREATE VIRTUAL TABLE IF NOT EXISTS conversation_history_fts USING fts5(
+      id UNINDEXED,
+      content
+    )
+  `);
+
+  // -- Indexes --
+  db.exec(`CREATE INDEX IF NOT EXISTS idx_conversation_session_id ON conversation_history(session_id)`);
+  db.exec(`CREATE INDEX IF NOT EXISTS idx_conversation_project ON conversation_history(project)`);
+  db.exec(`CREATE INDEX IF NOT EXISTS idx_conversation_role ON conversation_history(role)`);
+  db.exec(`CREATE INDEX IF NOT EXISTS idx_conversation_created_at ON conversation_history(created_at)`);
+}

package/{src/services → server/core}/parsers/claude-code.parser.ts

@@ -1,6 +1,6 @@
 import { readFile, readdir, stat } from "fs/promises";
 import { basename, dirname, join } from "path";
-import type { ParsedMessage, SessionFileInfo } from "../../types/conversation.js";
+import type { ParsedMessage, SessionFileInfo } from "../conversation.js";
 import type { SessionLogParser } from "./types.js";
 
 // UUID pattern for session IDs

package/{src/services → server/core}/parsers/types.ts

@@ -1,4 +1,4 @@
-import type { ParsedMessage, SessionFileInfo } from "../../types/conversation.js";
+import type { ParsedMessage, SessionFileInfo } from "../conversation.js";
 
 /** Interface for parsing session log files into structured messages */
 export interface SessionLogParser {

package/{src → server}/index.ts

@@ -1,14 +1,14 @@
 #!/usr/bin/env bun
 
 import { loadConfig, parseCliArgs } from "./config/index.js";
-import { connectToDatabase } from "./db/connection.js";
-import { MemoryRepository } from "./db/memory.repository.js";
-import { ConversationRepository } from "./db/conversation.repository.js";
-import { EmbeddingsService } from "./services/embeddings.service.js";
-import { MemoryService } from "./services/memory.service.js";
-import { ConversationHistoryService } from "./services/conversation.service.js";
-import { startServer } from "./mcp/server.js";
-import { startHttpServer, removeLockfile } from "./http/server.js";
+import { connectToDatabase } from "./core/connection.js";
+import { MemoryRepository } from "./core/memory.repository.js";
+import { ConversationRepository } from "./core/conversation.repository.js";
+import { EmbeddingsService } from "./core/embeddings.service.js";
+import { MemoryService } from "./core/memory.service.js";
+import { ConversationHistoryService } from "./core/conversation.service.js";
+import { startServer } from "./transports/mcp/server.js";
+import { startHttpServer } from "./transports/http/server.js";
 import { isLanceDbDirectory, migrate, formatMigrationSummary } from "./migration.js";
 
 async function runMigrate(args: string[]): Promise<void> {
@@ -56,7 +56,7 @@ async function main(): Promise<void> {
       `[vector-memory-mcp] ⚠️  Legacy LanceDB data detected at ${config.dbPath}\n` +
       `  Your data must be migrated to the new SQLite format.\n` +
       `  Run: vector-memory-mcp migrate\n` +
-      `  Or:  bun run src/index.ts migrate\n`
+      `  Or:  bun run server/index.ts migrate\n`
     );
     process.exit(1);
   }
@@ -69,6 +69,10 @@ async function main(): Promise<void> {
   const embeddings = new EmbeddingsService(config.embeddingModel, config.embeddingDimension);
   const memoryService = new MemoryService(repository, embeddings);
 
+  if (config.pluginMode) {
+    console.error("[vector-memory-mcp] Running in plugin mode");
+  }
+
   // Conditionally initialize conversation history indexing
   if (config.conversationHistory.enabled) {
     const conversationRepository = new ConversationRepository(db);
@@ -88,7 +92,6 @@ async function main(): Promise<void> {
   // Graceful shutdown handler
   const shutdown = () => {
     console.error("[vector-memory-mcp] Shutting down...");
-    removeLockfile();
     if (httpStop) httpStop();
     db.close();
     process.exit(0);

package/{src → server}/migration.ts

@@ -12,8 +12,8 @@
 import { existsSync, statSync } from "fs";
 import { resolve, dirname } from "path";
 import { fileURLToPath } from "url";
-import { connectToDatabase } from "./db/connection.js";
-import { serializeVector } from "./db/sqlite-utils.js";
+import { connectToDatabase } from "./core/connection.js";
+import { serializeVector } from "./core/sqlite-utils.js";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 

package/{src → server/transports}/http/mcp-transport.ts

@@ -24,8 +24,8 @@ import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
 import { tools } from "../mcp/tools.js";
 import { handleToolCall } from "../mcp/handlers.js";
 import { SERVER_INSTRUCTIONS } from "../mcp/server.js";
-import { VERSION } from "../config/index.js";
-import type { MemoryService } from "../services/memory.service.js";
+import { VERSION } from "../../config/index.js";
+import type { MemoryService } from "../../core/memory.service.js";
 
 interface Session {
   server: Server;

package/{src → server/transports}/http/server.ts

@@ -3,11 +3,12 @@ import { cors } from "hono/cors";
 import { createServer } from "net";
 import { writeFileSync, mkdirSync, unlinkSync } from "fs";
 import { join } from "path";
-import type { MemoryService } from "../services/memory.service.js";
-import type { Config } from "../config/index.js";
-import { isDeleted } from "../types/memory.js";
+import type { MemoryService } from "../../core/memory.service.js";
+import type { Config } from "../../config/index.js";
+import { isDeleted } from "../../core/memory.js";
 import { createMcpRoutes } from "./mcp-transport.js";
-import type { Memory, SearchIntent } from "../types/memory.js";
+import type { Memory, SearchIntent } from "../../core/memory.js";
+import { MigrationService } from "../../core/migration.service.js";
 
 /**
  * Check if a port is available by attempting to bind to it
@@ -109,6 +110,7 @@ export function createHttpApp(memoryService: MemoryService, config: Config): Hon
         embeddingModel: config.embeddingModel,
         embeddingDimension: config.embeddingDimension,
         historyEnabled: config.conversationHistory.enabled,
+        pluginMode: config.pluginMode,
       },
     });
   });
@@ -243,6 +245,34 @@ export function createHttpApp(memoryService: MemoryService, config: Config): Hon
     }
   });
 
+  // Migrate from external memory database
+  app.post("/migrate", async (c) => {
+    try {
+      const body = await c.req.json().catch(() => null);
+      if (!body || typeof body !== "object") {
+        return c.json({ error: "Invalid or missing JSON body" }, 400);
+      }
+      const source = body.source;
+
+      if (!source || typeof source !== "string") {
+        return c.json({ error: "Missing or invalid 'source' field" }, 400);
+      }
+
+      const repository = memoryService.getRepository();
+      const migrationService = new MigrationService(
+        repository,
+        memoryService.getEmbeddings(),
+        repository.getDb(),
+      );
+
+      const result = await migrationService.migrate(source);
+      return c.json(result);
+    } 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 {

package/{src → server/transports}/mcp/handlers.ts

@@ -1,9 +1,9 @@
 import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
-import type { MemoryService } from "../services/memory.service.js";
-import type { ConversationHistoryService } from "../services/conversation.service.js";
-import type { SearchIntent } from "../types/memory.js";
-import type { HistoryFilters, SearchResult } from "../types/conversation.js";
-import { DEBUG } from "../config/index.js";
+import type { MemoryService } from "../../core/memory.service.js";
+import type { ConversationHistoryService } from "../../core/conversation.service.js";
+import type { SearchIntent } from "../../core/memory.js";
+import type { HistoryFilters, SearchResult } from "../../core/conversation.js";
+import { DEBUG } from "../../config/index.js";
 
 /**
  * Safely coerce a tool argument to an array. Handles the case where the MCP

package/server/transports/mcp/resources.ts

@@ -0,0 +1,161 @@
+const MIGRATE_GUIDE = `# Migrating External Memory Databases
+
+The vector-memory-mcp server exposes a \`POST /migrate\` HTTP endpoint that imports
+memories from other database formats into the running instance. All imported
+content is re-embedded with the server's current embedding model to guarantee
+consistency.
+
+## Endpoint
+
+\`\`\`
+POST http://<host>:<port>/migrate
+Content-Type: application/json
+
+{ "source": "/absolute/path/to/source/database" }
+\`\`\`
+
+## Discovering the Server Port
+
+The HTTP server writes a lockfile at \`.vector-memory/server.lock\` in the
+project's working directory. Read it to discover the current port:
+
+\`\`\`json
+{ "port": 3271, "pid": 12345 }
+\`\`\`
+
+## Supported Source Formats
+
+The endpoint auto-detects the source format from the path provided.
+
+### 1. LanceDB Directory
+Provide the path to a LanceDB data directory (contains \`.lance\` files or
+\`_versions\`/\`_indices\` subdirectories). Both memories and conversation
+history are imported.
+
+\`\`\`json
+{ "source": "/path/to/project/.vector-memory" }
+\`\`\`
+
+### 2. Own SQLite (Current or Older Schema)
+Provide the path to a \`.db\` file that was created by any version of
+vector-memory-mcp. The migrator handles missing columns (e.g. \`usefulness\`,
+\`access_count\`) by using sensible defaults. Both memories and conversation
+history are imported.
+
+\`\`\`json
+{ "source": "/path/to/old-project/.vector-memory/memories.db" }
+\`\`\`
+
+### 3. CCCMemory SQLite
+Provide the path to a CCCMemory database. The migrator extracts from the
+\`decisions\`, \`mistakes\`, \`methodologies\`, \`research_findings\`,
+\`solution_patterns\`, and \`working_memory\` tables. Each record is tagged
+with \`source_type: "cccmemory"\` and the appropriate \`memory_type\` in
+metadata.
+
+\`\`\`json
+{ "source": "/path/to/cccmemory.db" }
+\`\`\`
+
+### 4. MCP Memory Service SQLite
+Provide the path to an mcp-memory-service database. Memories with
+\`deleted_at IS NULL\` are imported. Tags and memory type are preserved in
+metadata.
+
+\`\`\`json
+{ "source": "/path/to/mcp-memory-service.db" }
+\`\`\`
+
+### 5. MIF JSON (Shodh Memory Interchange Format)
+Provide the path to a \`.json\` file exported from Shodh Memory. The file must
+contain a top-level \`memories\` array. Memory type, tags, entities, and source
+metadata are preserved.
+
+\`\`\`json
+{ "source": "/path/to/export.mif.json" }
+\`\`\`
+
+## Response
+
+The endpoint returns a JSON summary upon completion:
+
+\`\`\`json
+{
+  "source": "/path/to/source",
+  "format": "own-sqlite",
+  "memoriesImported": 142,
+  "memoriesSkipped": 3,
+  "conversationsImported": 0,
+  "conversationsSkipped": 0,
+  "errors": [],
+  "durationMs": 8320
+}
+\`\`\`
+
+- **memoriesImported**: Number of new memories written to the database.
+- **memoriesSkipped**: Records skipped because a memory with the same ID
+  already exists (safe for idempotent re-runs).
+- **conversationsImported / conversationsSkipped**: Same, for conversation
+  history chunks (LanceDB and own-sqlite formats only).
+- **errors**: Per-record errors that did not abort the migration.
+- **durationMs**: Wall-clock time for the entire operation.
+
+## Important Notes
+
+- **Re-embedding**: All content is re-embedded regardless of the source format.
+  This ensures vector consistency with the server's current model but means the
+  operation can take time for large databases (~50ms per record).
+- **Idempotent**: Running the same migration twice is safe. Duplicate IDs are
+  skipped.
+- **Non-destructive**: The source database is opened read-only and is never
+  modified.
+- **Batched writes**: Records are inserted in batches of 100 within
+  transactions. If the process is interrupted, already-committed batches are
+  durable.
+- **Error isolation**: A single bad record does not abort the migration. Check
+  the \`errors\` array in the response for any per-record failures.
+
+## Workflow Example
+
+1. Locate the source database file or directory.
+2. Read \`.vector-memory/server.lock\` to get the port.
+3. Send the migrate request:
+   \`\`\`bash
+   curl -X POST http://127.0.0.1:3271/migrate \\
+     -H "Content-Type: application/json" \\
+     -d '{"source": "/path/to/old/memories.db"}'
+   \`\`\`
+4. Inspect the response summary.
+5. Verify imported memories with a search:
+   \`\`\`bash
+   curl -X POST http://127.0.0.1:3271/search \\
+     -H "Content-Type: application/json" \\
+     -d '{"query": "test query", "limit": 5}'
+   \`\`\`
+`;
+
+export const resources = [
+  {
+    uri: "vector-memory://guides/migrate",
+    name: "Migration Guide",
+    description:
+      "How to use the POST /migrate HTTP endpoint to import memories from external database formats (LanceDB, older SQLite, CCCMemory, MCP Memory Service, MIF JSON) into the running vector-memory instance.",
+    mimeType: "text/markdown",
+  },
+];
+
+const RESOURCE_CONTENT: Record<string, string> = {
+  "vector-memory://guides/migrate": MIGRATE_GUIDE,
+};
+
+export function readResource(uri: string): {
+  contents: Array<{ uri: string; mimeType: string; text: string }>;
+} {
+  const text = RESOURCE_CONTENT[uri];
+  if (!text) {
+    throw new Error(`Resource not found: ${uri}`);
+  }
+  return {
+    contents: [{ uri, mimeType: "text/markdown", text }],
+  };
+}

package/{src → server/transports}/mcp/server.ts

@@ -3,12 +3,15 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import {
   CallToolRequestSchema,
   ListToolsRequestSchema,
+  ListResourcesRequestSchema,
+  ReadResourceRequestSchema,
 } from "@modelcontextprotocol/sdk/types.js";
+import { resources, readResource } from "./resources.js";
 
 import { tools } from "./tools.js";
 import { handleToolCall } from "./handlers.js";
-import type { MemoryService } from "../services/memory.service.js";
-import { VERSION } from "../config/index.js";
+import type { MemoryService } from "../../core/memory.service.js";
+import { VERSION } from "../../config/index.js";
 
 export const SERVER_INSTRUCTIONS = `This server is the user's canonical memory system. It provides persistent, semantic vector memory that survives across conversations and sessions.
 
@@ -20,7 +23,7 @@ export function createServer(memoryService: MemoryService): Server {
   const server = new Server(
     { name: "vector-memory-mcp", version: VERSION },
     {
-      capabilities: { tools: {} },
+      capabilities: { tools: {}, resources: {} },
       instructions: SERVER_INSTRUCTIONS,
     }
   );
@@ -34,6 +37,14 @@ export function createServer(memoryService: MemoryService): Server {
     return handleToolCall(name, args, memoryService);
   });
 
+  server.setRequestHandler(ListResourcesRequestSchema, async () => {
+    return { resources };
+  });
+
+  server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+    return readResource(request.params.uri);
+  });
+
   return server;
 }
 

package/server/utils/formatting.ts

@@ -0,0 +1,143 @@
+/**
+ * Shared text formatting utilities.
+ *
+ * Provides ANSI styling, Nerd Font icons, horizontal rules, structured
+ * message builders, debug logging, and time formatting. Used by both the
+ * MCP server and the Claude Code plugin hooks.
+ */
+
+// ── ANSI escape codes ───────────────────────────────────────────────
+
+export const ansi = {
+  reset: "\x1b[0m",
+  bold: "\x1b[1m",
+  dim: "\x1b[2m",
+  italic: "\x1b[3m",
+  underline: "\x1b[4m",
+
+  // Foreground colors
+  red: "\x1b[31m",
+  green: "\x1b[32m",
+  yellow: "\x1b[33m",
+  blue: "\x1b[34m",
+  magenta: "\x1b[35m",
+  cyan: "\x1b[36m",
+  white: "\x1b[37m",
+  gray: "\x1b[90m",
+} as const;
+
+// ── Nerd Font glyphs (single-width) ────────────────────────────────
+
+export const icon = {
+  check: "\uf00c", // nf-fa-check
+  cross: "\uf00d", // nf-fa-close
+  book: "\uf02d", // nf-fa-book
+  branch: "\ue0a0", // Powerline branch
+  clock: "\uf017", // nf-fa-clock_o
+  warning: "\uf071", // nf-fa-warning
+  bolt: "\uf0e7", // nf-fa-bolt
+  brain: "\uf5dc", // nf-mdi-brain
+  search: "\uf002", // nf-fa-search
+  gear: "\uf013", // nf-fa-gear
+  database: "\uf1c0", // nf-fa-database
+  arrow: "\uf061", // nf-fa-arrow_right
+  dot: "\u00b7", // middle dot (standard unicode)
+} as const;
+
+// ── Rule line ───────────────────────────────────────────────────────
+
+const RULE_WIDTH = 42;
+
+/**
+ * Create a horizontal rule with an optional inline title.
+ * e.g. "── Vector Memory ──────────────────────"
+ */
+export function rule(title?: string): string {
+  if (!title) {
+    return `${ansi.cyan}${"─".repeat(RULE_WIDTH)}${ansi.reset}`;
+  }
+  const label = ` ${ansi.bold}${title}${ansi.reset} `;
+  // "── " prefix = 3 visual chars
+  const prefix = `${ansi.cyan}── ${ansi.reset}`;
+  // Calculate remaining dashes (account for title visual length)
+  const remaining = RULE_WIDTH - 3 - title.length - 2; // 2 for spaces around title
+  const suffix = `${ansi.cyan}${"─".repeat(Math.max(1, remaining))}${ansi.reset}`;
+  return `${prefix}${label}${suffix}`;
+}
+
+// ── System message builder ──────────────────────────────────────────
+
+export interface MessageLine {
+  icon?: string;
+  iconColor?: string;
+  text: string;
+}
+
+/**
+ * Build a user-facing systemMessage with horizontal rules and content lines.
+ *
+ * Output format:
+ *   ── Title ──────────────────────────────
+ *     icon text
+ *     icon text
+ *   ──────────────────────────────────────
+ *
+ * Prepends an empty line so the content starts below the hook label prefix.
+ */
+export function buildSystemMessage(
+  title: string,
+  lines: MessageLine[]
+): string {
+  const parts = [
+    "", // push below "HookName says:" prefix
+    rule(title),
+  ];
+
+  for (const line of lines) {
+    if (line.icon) {
+      const color = line.iconColor ?? "";
+      const reset = line.iconColor ? ansi.reset : "";
+      parts.push(`  ${color}${line.icon}${reset} ${line.text}`);
+    } else {
+      parts.push(`  ${line.text}`);
+    }
+  }
+
+  parts.push(rule());
+  return parts.join("\n");
+}
+
+// ── Diagnostic logging ──────────────────────────────────────────────
+
+/**
+ * Log a diagnostic message to stderr when VECTOR_MEMORY_DEBUG=1.
+ */
+export function debug(label: string, message: string): void {
+  if (process.env.VECTOR_MEMORY_DEBUG !== "1") return;
+  console.error(
+    `${ansi.gray}[${label}]${ansi.reset} ${ansi.dim}${message}${ansi.reset}`
+  );
+}
+
+// ── Time formatting ─────────────────────────────────────────────────
+
+export function timeAgo(iso: string): string {
+  const now = Date.now();
+  const then = new Date(iso).getTime();
+  if (Number.isNaN(then)) {
+    debug("timeAgo", `invalid ISO string: ${iso}`);
+    return "unknown";
+  }
+  const seconds = Math.floor((now - then) / 1000);
+  if (seconds < 0) {
+    debug("timeAgo", `negative delta (${seconds}s) — clock skew or future timestamp`);
+    return "just now";
+  }
+  if (seconds < 60) return `${seconds}s ago`;
+  const minutes = Math.floor(seconds / 60);
+  if (minutes < 60) return `${minutes}m ago`;
+  const hours = Math.floor(minutes / 60);
+  if (hours < 24) return `${hours}h ago`;
+  const days = Math.floor(hours / 24);
+  return `${days}d ago`;
+}