@aeriondyseti/vector-memory-mcp 2.4.4-dev.1 → 2.5.0-dev.1

package/server/core/sqlite-utils.ts

@@ -53,6 +53,11 @@ export function cosineSimilarity(a: Float32Array, b: Float32Array): number {
  * Brute-force KNN search over a vector blob table.
  * Loads all vectors, computes cosine similarity, returns top-K results
  * sorted by descending similarity (ascending distance).
+ *
+ * `candidates` overrides the candidate query — used to pre-filter the scan
+ * (e.g. by project) so filtered searches rank within the filtered set instead
+ * of post-filtering a global top-K (which can return false-empty results).
+ * The SQL must select `id` and `vector` columns.
  */
 type VecTable = "memories_vec" | "conversation_history_vec";
 
@@ -61,10 +66,13 @@ export function knnSearch(
   table: VecTable,
   queryVec: number[],
   k: number,
+  candidates?: { sql: string; params: Array<string | number> },
 ): Array<{ id: string; distance: number }> {
-  const rows = db
-    .prepare(`SELECT id, vector FROM ${table}`)
-    .all() as Array<{ id: string; vector: Buffer }>;
+  const rows = (
+    candidates
+      ? db.prepare(candidates.sql).all(...candidates.params)
+      : db.prepare(`SELECT id, vector FROM ${table}`).all()
+  ) as Array<{ id: string; vector: Buffer }>;
 
   const qv = new Float32Array(queryVec);
   const scored = rows.map((r) => {

package/server/core/time-expr.ts

@@ -0,0 +1,77 @@
+const PATTERN =
+  /^(?:past|last)\s+(\d+)\s+(minute|hour|day|week|month|year)s?$/i;
+
+export function parseTimeExpr(
+  expr: string,
+  now: Date = new Date(),
+): Date | null {
+  const match = expr.trim().match(PATTERN);
+  if (!match) return null;
+
+  const n = parseInt(match[1], 10);
+  const unit = match[2].toLowerCase();
+  const result = new Date(now);
+
+  switch (unit) {
+    case "minute":
+      result.setMinutes(result.getMinutes() - n);
+      break;
+    case "hour":
+      result.setHours(result.getHours() - n);
+      break;
+    case "day":
+      result.setDate(result.getDate() - n);
+      break;
+    case "week":
+      result.setDate(result.getDate() - n * 7);
+      break;
+    case "month":
+      result.setMonth(result.getMonth() - n);
+      break;
+    case "year":
+      result.setFullYear(result.getFullYear() - n);
+      break;
+  }
+
+  return result;
+}
+
+export interface DateFilters {
+  after?: Date;
+  before?: Date;
+}
+
+export function resolveDateFilters(raw: {
+  after?: unknown;
+  before?: unknown;
+  time_expr?: unknown;
+}): DateFilters {
+  let after: Date | undefined;
+  let before: Date | undefined;
+
+  if (raw.after !== undefined) {
+    after = new Date(raw.after as string);
+    if (isNaN(after.getTime())) throw new Error("'after' is not a valid date");
+  }
+  if (raw.before !== undefined) {
+    before = new Date(raw.before as string);
+    if (isNaN(before.getTime())) throw new Error("'before' is not a valid date");
+  }
+
+  if (!after && typeof raw.time_expr === "string") {
+    const resolved = parseTimeExpr(raw.time_expr);
+    if (!resolved) {
+      throw new Error(
+        `Unsupported time_expr format: "${raw.time_expr}". ` +
+        `Use "past N unit" or "last N unit" (e.g. "past 7 days", "last 2 weeks").`,
+      );
+    }
+    after = resolved;
+  }
+
+  if (after && before && after >= before) {
+    throw new Error("'after' date must be before 'before' date");
+  }
+
+  return { after, before };
+}

package/server/index.ts

@@ -1,8 +1,11 @@
 #!/usr/bin/env bun
 
+import { existsSync } from "fs";
+import { join } from "path";
+import arg from "arg";
 import { loadConfig, parseCliArgs } from "./config/index";
 import { connectToDatabase } from "./core/connection";
-import { backfillVectors } from "./core/migrations";
+import { backfillVectors, repairConversationProjects } from "./core/migrations";
 import { MemoryRepository } from "./core/memory.repository";
 import { ConversationRepository } from "./core/conversation.repository";
 import { EmbeddingsService } from "./core/embeddings.service";
@@ -21,18 +24,39 @@ async function main(): Promise<void> {
     return;
   }
 
+  // Consolidate repo-local databases into the global store
+  if (args[0] === "consolidate") {
+    await runConsolidate(args.slice(1));
+    return;
+  }
+
   // Parse CLI args and load config
   const overrides = parseCliArgs(args);
   const config = loadConfig(overrides);
 
+  // Nudge: a repo-local database exists but the global store is active —
+  // suggest consolidating it. Skipped when the user explicitly chose a db.
+  if (
+    !overrides.dbPath &&
+    !process.env.VECTOR_MEMORY_DB_PATH &&
+    existsSync(join(process.cwd(), ".vector-memory", "memories.db"))
+  ) {
+    console.error(
+      "[vector-memory-mcp] Found a repo-local .vector-memory/memories.db — " +
+        "memories now live in a global store (~/.vector-memory). " +
+        "Run `bunx @aeriondyseti/vector-memory-mcp consolidate` to import it."
+    );
+  }
+
   // Initialize database and backfill any missing vectors before services start
   const db = connectToDatabase(config.dbPath);
   const embeddings = new EmbeddingsService(config.embeddingModel, config.embeddingDimension);
   await backfillVectors(db, embeddings);
+  await repairConversationProjects(db, config.dbPath);
 
   // Initialize layers
   const repository = new MemoryRepository(db);
-  const memoryService = new MemoryService(repository, embeddings);
+  const memoryService = new MemoryService(repository, embeddings, config.project);
 
   if (config.pluginMode) {
     console.error("[vector-memory-mcp] Running in plugin mode");
@@ -88,4 +112,70 @@ async function main(): Promise<void> {
   }
 }
 
+async function runConsolidate(argv: string[]): Promise<void> {
+  const flags = arg(
+    {
+      "--recursive": Boolean,
+      "--dry-run": Boolean,
+      "--archive": Boolean,
+      "--force": Boolean,
+      "--db-file": String,
+      "-d": "--db-file",
+      "-r": "--recursive",
+    },
+    { argv, permissive: true }
+  );
+
+  const root = flags._.find((a) => !a.startsWith("-")) ?? process.cwd();
+  const config = loadConfig({ dbPath: flags["--db-file"] });
+
+  const { ConsolidationService } = await import("./core/consolidation.service");
+  const db = connectToDatabase(config.dbPath);
+  const embeddings = new EmbeddingsService(
+    config.embeddingModel,
+    config.embeddingDimension
+  );
+  const service = new ConsolidationService(db, config.dbPath, embeddings);
+
+  const summary = await service.consolidate({
+    root,
+    recursive: flags["--recursive"] ?? false,
+    dryRun: flags["--dry-run"] ?? false,
+    archive: flags["--archive"] ?? false,
+    force: flags["--force"] ?? false,
+  });
+
+  const log = console.error;
+  log(`\nConsolidation ${summary.dryRun ? "(dry run) " : ""}-> ${summary.targetDb}`);
+  if (summary.backupPath) log(`Backup: ${summary.backupPath}`);
+  log(`Import batch: ${summary.importBatch}`);
+
+  if (summary.sources.length === 0) {
+    log(`No repo-local .vector-memory/memories.db found under ${root}.`);
+    db.close();
+    return;
+  }
+
+  for (const s of summary.sources) {
+    log(`\n${s.sourceDb}`);
+    log(`  project: ${s.project}`);
+    log(`  memories: ${s.memoriesImported} imported, ${s.memoriesSkipped} skipped, ${s.memoriesRekeyed} re-keyed`);
+    log(`  conversations: ${s.conversationsImported} imported, ${s.conversationsSkipped} skipped`);
+    log(`  index state: ${s.indexStateImported} sessions`);
+    for (const [oldId, newId] of Object.entries(s.rekeyMap)) {
+      log(`  re-key: ${oldId} -> ${newId}`);
+    }
+    for (const ref of s.unresolvedReferences) {
+      log(`  unresolved reference: ${ref}`);
+    }
+    for (const err of s.errors) {
+      log(`  ERROR: ${err}`);
+    }
+  }
+
+  const failed = summary.sources.some((s) => s.errors.length > 0);
+  db.close();
+  if (failed) process.exit(1);
+}
+
 main().catch(console.error);

package/server/transports/http/server.ts

@@ -1,13 +1,18 @@
 import { Hono } from "hono";
 import { cors } from "hono/cors";
+import { createHash } from "crypto";
 import { createServer } from "net";
-import { writeFileSync, mkdirSync, unlinkSync } from "fs";
+import { existsSync, readFileSync, writeFileSync, mkdirSync, unlinkSync } from "fs";
+import { homedir } from "os";
 import { join } from "path";
 import type { MemoryService } from "../../core/memory.service";
 import type { Config } from "../../config/index";
 import { isDeleted } from "../../core/memory";
 import { createMcpRoutes } from "./mcp-transport";
 import type { Memory, SearchIntent } from "../../core/memory";
+import { resolveDateFilters } from "../../core/time-expr";
+
+const VALID_INTENTS = new Set(["continuity", "fact_check", "frequent", "associative", "explore"]);
 
 
 /**
@@ -56,27 +61,54 @@ async function findAvailablePort(
 }
 
 /**
- * Write a lockfile so hooks can discover which port this server bound to.
- * Written atomically after the HTTP server successfully binds.
+ * Per-project lock path under the global data directory. Keyed by a hash of
+ * the canonical project path so hooks (which know their cwd) can compute the
+ * same path without any per-repo files. Must stay in sync with the copy in
+ * plugin/hooks/scripts/hooks-lib.ts.
  */
-function writeLockfile(port: number): void {
-  const dir = join(process.cwd(), ".vector-memory");
-  mkdirSync(dir, { recursive: true });
-  writeFileSync(
-    join(dir, "server.lock"),
-    JSON.stringify({ port, pid: process.pid }),
-    "utf8"
-  );
+export function globalLockPath(project: string): string {
+  const hash = createHash("sha256").update(project).digest("hex").slice(0, 16);
+  return join(homedir(), ".vector-memory", "locks", `${hash}.lock`);
+}
+
+function legacyLockPath(): string {
+  return join(process.cwd(), ".vector-memory", "server.lock");
+}
+
+/**
+ * Write lockfiles so hooks can discover which port this server bound to.
+ * Written after the HTTP server successfully binds.
+ *
+ * Writes the global per-project lock, plus the legacy per-repo lock when a
+ * `.vector-memory/` directory already exists in the repo (so pre-2.5 plugins
+ * keep working without us creating new per-repo litter). Legacy dual-write
+ * is temporary — remove after one stable release cycle.
+ */
+function writeLockfiles(port: number, project: string): void {
+  const payload = JSON.stringify({ port, pid: process.pid, project });
+
+  const globalPath = globalLockPath(project);
+  mkdirSync(join(homedir(), ".vector-memory", "locks"), { recursive: true });
+  writeFileSync(globalPath, payload, "utf8");
+
+  if (existsSync(join(process.cwd(), ".vector-memory"))) {
+    writeFileSync(legacyLockPath(), payload, "utf8");
+  }
 }
 
 /**
- * Remove the lockfile on clean shutdown so stale files don't linger.
+ * Remove this process's lockfiles on clean shutdown. Only deletes a lock
+ * whose recorded pid is ours — another session in the same project may have
+ * written its own lock since.
  */
-export function removeLockfile(): void {
-  try {
-    unlinkSync(join(process.cwd(), ".vector-memory", "server.lock"));
-  } catch {
-    // already gone — fine
+export function removeLockfiles(project: string): void {
+  for (const path of [globalLockPath(project), legacyLockPath()]) {
+    try {
+      const { pid } = JSON.parse(readFileSync(path, "utf8"));
+      if (pid === process.pid) unlinkSync(path);
+    } catch {
+      // missing or unreadable — fine
+    }
   }
 }
 
@@ -132,14 +164,27 @@ export function createHttpApp(memoryService: MemoryService, config: Config): Hon
     try {
       const body = await c.req.json();
       const query = body.query;
-      const intent = (body.intent as SearchIntent) ?? "fact_check";
-      const limit = body.limit ?? 10;
-
       if (!query || typeof query !== "string") {
         return c.json({ error: "Missing or invalid 'query' field" }, 400);
       }
+      if (body.intent && !VALID_INTENTS.has(body.intent)) {
+        return c.json({ error: "Invalid 'intent' value" }, 400);
+      }
+      const intent = (body.intent as SearchIntent) ?? "fact_check";
+      const limit = Math.max(1, Math.min(1000, Math.floor(typeof body.limit === "number" ? body.limit : 10)));
 
-      const results = await memoryService.search(query, intent, { limit });
+      let dateFilters: { after?: Date; before?: Date };
+      try {
+        dateFilters = resolveDateFilters({ after: body.after, before: body.before, time_expr: body.time_expr });
+      } catch (e) {
+        return c.json({ error: e instanceof Error ? e.message : String(e) }, 400);
+      }
+
+      const results = await memoryService.search(query, intent, {
+        limit,
+        scope: typeof body.scope === "string" ? body.scope : undefined,
+        ...dateFilters,
+      });
 
       return c.json({
         results: results.map((r) => ({
@@ -148,6 +193,7 @@ export function createHttpApp(memoryService: MemoryService, config: Config): Hon
           metadata: r.metadata,
           source: r.source,
           confidence: r.confidence,
+          project: r.project,
           createdAt: r.createdAt.toISOString(),
         })),
         count: results.length,
@@ -162,16 +208,21 @@ export function createHttpApp(memoryService: MemoryService, config: Config): Hon
   app.post("/store", async (c) => {
     try {
       const body = await c.req.json();
-      const { content, metadata, embeddingText } = body;
+      const { content, embeddingText } = body;
 
       if (!content || typeof content !== "string") {
         return c.json({ error: "Missing or invalid 'content' field" }, 400);
       }
 
+      const metadata = typeof body.metadata === "object" && body.metadata !== null && !Array.isArray(body.metadata)
+        ? body.metadata as Record<string, unknown>
+        : {};
+
       const memory = await memoryService.store(
         content,
-        metadata ?? {},
-        embeddingText
+        metadata,
+        typeof embeddingText === "string" ? embeddingText : undefined,
+        typeof body.project === "string" ? body.project : undefined
       );
 
       return c.json({
@@ -240,16 +291,14 @@ export function createHttpApp(memoryService: MemoryService, config: Config): Hon
 
       const body = await c.req.json().catch(() => ({}));
       let since: Date | undefined;
-      if (body.since) {
-        since = new Date(body.since as string);
+      if (typeof body.since === "string") {
+        since = new Date(body.since);
         if (isNaN(since.getTime())) {
           return c.json({ error: "Invalid 'since' date format" }, 400);
         }
       }
-      const result = await conversationService.indexConversations(
-        body.path as string | undefined,
-        since
-      );
+      const path = typeof body.path === "string" ? body.path : undefined;
+      const result = await conversationService.indexConversations(path, since);
 
       return c.json(result);
     } catch (error) {
@@ -299,13 +348,13 @@ export async function startHttpServer(
     fetch: app.fetch,
   });
 
-  writeLockfile(actualPort);
+  writeLockfiles(actualPort, config.project);
   console.error(
     `[vector-memory-mcp] HTTP server listening on http://${config.httpHost}:${actualPort}`
   );
 
   return {
-    stop: () => { removeLockfile(); server.stop(); },
+    stop: () => { removeLockfiles(config.project); server.stop(); },
     port: actualPort,
   };
 }

package/server/transports/mcp/handlers.ts

@@ -3,6 +3,7 @@ import type { MemoryService } from "../../core/memory.service";
 import type { ConversationHistoryService } from "../../core/conversation.service";
 import type { SearchIntent } from "../../core/memory";
 import type { HistoryFilters, SearchResult } from "../../core/conversation";
+import { resolveDateFilters } from "../../core/time-expr";
 import { DEBUG } from "../../config/index";
 
 /**
@@ -59,6 +60,32 @@ function requireString(args: Record<string, unknown> | undefined, field: string)
   return value;
 }
 
+const VALID_INTENTS = new Set(["continuity", "fact_check", "frequent", "associative", "explore"]);
+
+function asIntent(value: unknown): SearchIntent {
+  if (typeof value === "string" && VALID_INTENTS.has(value)) return value as SearchIntent;
+  return "fact_check";
+}
+
+function asInt(value: unknown, fallback: number, min: number, max: number): number {
+  if (typeof value !== "number" || !Number.isFinite(value)) return fallback;
+  return Math.max(min, Math.min(max, Math.floor(value)));
+}
+
+function asBool(value: unknown, fallback: boolean): boolean {
+  return typeof value === "boolean" ? value : fallback;
+}
+
+function asOptionalString(value: unknown): string | undefined {
+  return typeof value === "string" ? value : undefined;
+}
+
+function asObject(value: unknown): Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+    ? value as Record<string, unknown>
+    : {};
+}
+
 export async function handleStoreMemories(
   args: Record<string, unknown> | undefined,
   service: MemoryService
@@ -67,6 +94,7 @@ export async function handleStoreMemories(
     content: string;
     embedding_text?: string;
     metadata?: Record<string, unknown>;
+    project?: string;
   }>;
   try {
     memories = asArray(args?.memories, "memories");
@@ -79,7 +107,8 @@ export async function handleStoreMemories(
     const memory = await service.store(
       item.content,
       item.metadata ?? {},
-      item.embedding_text
+      item.embedding_text,
+      typeof item.project === "string" ? item.project : undefined
     );
     ids.push(memory.id);
   }
@@ -182,13 +211,13 @@ export async function handleSearchMemories(
   if (typeof query !== "string" || query.trim() === "") {
     return errorResult("query is required and must be a non-empty string");
   }
-  const intent = (args?.intent as SearchIntent) ?? "fact_check";
-  const limit = (args?.limit as number) ?? 10;
-  const offset = (args?.offset as number) ?? 0;
-  const includeDeleted = (args?.include_deleted as boolean) ?? false;
-  const historyOnly = (args?.history_only as boolean) ?? false;
+  const intent = asIntent(args?.intent);
+  const limit = asInt(args?.limit, 10, 1, 1000);
+  const offset = asInt(args?.offset, 0, 0, 10000);
+  const includeDeleted = asBool(args?.include_deleted, false);
+  const historyOnly = asBool(args?.history_only, false);
   // history_only implies include_history
-  const includeHistory = historyOnly ? true : (args?.include_history as boolean | undefined);
+  const includeHistory = historyOnly ? true : (typeof args?.include_history === "boolean" ? args.include_history : undefined);
 
   let historyFilters: HistoryFilters;
   try {
@@ -197,13 +226,27 @@ export async function handleSearchMemories(
     return errorResult(errorText(e));
   }
 
+  let dateFilters: { after?: Date; before?: Date };
+  try {
+    dateFilters = resolveDateFilters({
+      after: args?.after,
+      before: args?.before,
+      time_expr: args?.time_expr,
+    });
+  } catch (e) {
+    return errorResult(errorText(e));
+  }
+
   const results = await service.search(query, intent, {
     limit,
+    scope: asOptionalString(args?.scope),
     includeDeleted,
     includeHistory,
     historyOnly,
     historyFilters,
     offset,
+    after: dateFilters.after,
+    before: dateFilters.before,
   });
 
   if (results.length === 0) {
@@ -240,7 +283,11 @@ function formatMemoryDetail(
 }
 
 function formatSearchResult(r: SearchResult, includeDeleted: boolean): string {
-  let result = `[${r.source}] ID: ${r.id}\nConfidence: ${r.confidence.toFixed(2)}\nContent: ${r.content}`;
+  let result = `[${r.source}] ID: ${r.id}\nConfidence: ${r.confidence.toFixed(2)}`;
+  if (r.project) {
+    result += `\nProject: ${r.project}`;
+  }
+  result += `\nContent: ${r.content}`;
   if (r.metadata && Object.keys(r.metadata).length > 0) {
     result += `\nMetadata: ${JSON.stringify(r.metadata)}`;
   }
@@ -305,25 +352,23 @@ export async function handleSetWaypoint(
   args: Record<string, unknown> | undefined,
   service: MemoryService
 ): Promise<CallToolResult> {
-  let project: string;
   let summary: string;
   try {
-    project = requireString(args, "project");
     summary = requireString(args, "summary");
   } catch (e) {
     return errorResult(errorText(e));
   }
 
   const memory = await service.setWaypoint({
-    project,
-    branch: args?.branch as string | undefined,
+    project: asOptionalString(args?.project),
+    branch: asOptionalString(args?.branch),
     summary,
-    completed: (args?.completed as string[] | undefined) ?? [],
-    in_progress_blocked: (args?.in_progress_blocked as string[] | undefined) ?? [],
-    key_decisions: (args?.key_decisions as string[] | undefined) ?? [],
-    next_steps: (args?.next_steps as string[] | undefined) ?? [],
-    memory_ids: (args?.memory_ids as string[] | undefined) ?? [],
-    metadata: (args?.metadata as Record<string, unknown>) ?? {},
+    completed: args?.completed ? asArray(args.completed, "completed") : [],
+    in_progress_blocked: args?.in_progress_blocked ? asArray(args.in_progress_blocked, "in_progress_blocked") : [],
+    key_decisions: args?.key_decisions ? asArray(args.key_decisions, "key_decisions") : [],
+    next_steps: args?.next_steps ? asArray(args.next_steps, "next_steps") : [],
+    memory_ids: args?.memory_ids ? asArray(args.memory_ids, "memory_ids") : [],
+    metadata: asObject(args?.metadata),
   });
 
   return {
@@ -335,7 +380,7 @@ export async function handleGetWaypoint(
   args: Record<string, unknown> | undefined,
   service: MemoryService
 ): Promise<CallToolResult> {
-  const project = args?.project as string | undefined;
+  const project = asOptionalString(args?.project);
   const waypoint = await service.getLatestWaypoint(project);
 
   if (!waypoint) {
@@ -365,8 +410,8 @@ function parseHistoryFilters(
   args: Record<string, unknown> | undefined
 ): HistoryFilters {
   return {
-    sessionId: args?.session_id as string | undefined,
-    role: args?.role_filter as string | undefined,
+    sessionId: asOptionalString(args?.session_id),
+    role: asOptionalString(args?.role_filter),
     after: parseDate(args?.history_after, "history_after"),
     before: parseDate(args?.history_before, "history_before"),
   };
@@ -394,8 +439,8 @@ export async function handleIndexConversations(
   if ("error" in conv) return conv.error;
   const conversationService = conv.service;
 
-  const path = args?.path as string | undefined;
-  const sinceStr = args?.since as string | undefined;
+  const path = asOptionalString(args?.path);
+  const sinceStr = asOptionalString(args?.since);
   const since = sinceStr ? new Date(sinceStr) : undefined;
   if (since && isNaN(since.getTime())) {
     return errorResult("Invalid 'since' date format");
@@ -425,8 +470,8 @@ export async function handleListIndexedSessions(
   if ("error" in conv) return conv.error;
   const conversationService = conv.service;
 
-  const limit = (args?.limit as number) ?? 20;
-  const offset = (args?.offset as number) ?? 0;
+  const limit = asInt(args?.limit, 20, 1, 1000);
+  const offset = asInt(args?.offset, 0, 0, 10000);
   const { sessions, total } =
     await conversationService.listIndexedSessions(limit, offset);
 
@@ -464,7 +509,7 @@ export async function handleReindexSession(
   if ("error" in conv) return conv.error;
   const conversationService = conv.service;
 
-  const sessionId = args?.session_id as string | undefined;
+  const sessionId = asOptionalString(args?.session_id);
   if (!sessionId) {
     return errorResult("session_id is required");
   }