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

package/server/core/parsers/claude-code.parser.ts

@@ -1,6 +1,7 @@
 import { readFile, readdir, stat } from "fs/promises";
 import { basename, dirname, join } from "path";
 import type { ParsedMessage, SessionFileInfo } from "../conversation";
+import { normalizeProject } from "../project";
 import type { SessionLogParser } from "./types";
 
 // UUID pattern for session IDs
@@ -18,16 +19,19 @@ function extractAssistantText(
 }
 
 /**
- * Extract project name from path-encoded directory name.
+ * Fallback project derivation from a path-encoded directory name.
  * Claude Code encodes paths by replacing `/` with `-`, e.g. `/home/user/project` → `-home-user-project`.
  * This is a lossy encoding: directory names containing literal dashes (e.g. `my-project`)
  * cannot be distinguished from path separators, so `my-project` decodes as `my/project`.
- * This is a known limitation of Claude Code's encoding scheme.
+ *
+ * Only used when a session file carries no `cwd` field — the authoritative
+ * project source is the `cwd` recorded on each message (see parse()).
  */
 function extractProjectFromDir(dirName: string): string {
-  return dirName.startsWith("-")
+  const decoded = dirName.startsWith("-")
     ? dirName.slice(1).replace(/-/g, "/")
     : dirName;
+  return normalizeProject(decoded);
 }
 
 export class ClaudeCodeSessionParser implements SessionLogParser {
@@ -53,7 +57,10 @@ export class ClaudeCodeSessionParser implements SessionLogParser {
       ? basename(dirname(dirname(dirname(filePath))))
       : parentDir;
 
-    const project = extractProjectFromDir(projectDir);
+    // Project identity: the `cwd` recorded on session entries is the true
+    // absolute path. The dash-encoded directory name is a lossy fallback.
+    let project = extractProjectFromDir(projectDir);
+    let projectFromCwd = false;
 
     for (const line of lines) {
       let entry: Record<string, unknown>;
@@ -64,6 +71,13 @@ export class ClaudeCodeSessionParser implements SessionLogParser {
         continue;
       }
 
+      if (!projectFromCwd && typeof entry.cwd === "string" && entry.cwd.length > 0) {
+        project = normalizeProject(entry.cwd as string);
+        projectFromCwd = true;
+        // Retroactively fix messages parsed before the first cwd appeared
+        for (const m of messages) m.project = project;
+      }
+
       const type = entry.type as string;
 
       // Skip non-message entries

package/server/core/project.ts

@@ -0,0 +1,25 @@
+import { basename } from "path";
+
+/**
+ * Canonical project identifier: the normalized absolute path of the project
+ * root (e.g. `/home/user/Development/my-repo`).
+ *
+ * This exact function must be used everywhere a project value is produced or
+ * compared — memory stamping, waypoint ID hashing, search filters, the
+ * consolidation re-key, and the hooks' `?project=` param — so values join
+ * byte-for-byte across subsystems.
+ */
+export function normalizeProject(value: string): string {
+  let p = value.trim();
+  if (p.length === 0) return "";
+  // Collapse trailing slashes (but keep bare root "/")
+  p = p.replace(/\/+$/, "");
+  if (p.length === 0) return "/";
+  if (!p.startsWith("/")) p = `/${p}`;
+  return p;
+}
+
+/** Short human-readable name for a project path. */
+export function projectDisplayName(project: string): string {
+  return basename(project) || project;
+}

package/server/core/sqlite-utils.ts

@@ -1,7 +1,7 @@
 import type { Database } from "bun:sqlite";
 
-/** RRF constant matching the previous LanceDB reranker default */
-export const RRF_K = 60;
+/** RRF constant — lower K gives sharper top-rank discrimination in the 1/(K+rank) formula */
+export const RRF_K = 10;
 
 /**
  * Maximum parameters per SQLite query to stay within SQLITE_MAX_VARIABLE_NUMBER.
@@ -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) => {
@@ -116,6 +124,49 @@ export function hybridRRF(
   return scores;
 }
 
+import type { SearchSignals } from "./memory";
+
+/**
+ * Compute hybrid RRF scores while preserving per-result search signals
+ * (cosine similarity, FTS match, rank positions) for confidence scoring.
+ */
+export function hybridRRFWithSignals(
+  vectorResults: Array<{ id: string; distance: number }>,
+  ftsResults: Array<{ id: string }>,
+  k: number = RRF_K
+): Map<string, SearchSignals & { rrfScore: number }> {
+  const knnMap = new Map<string, { similarity: number; rank: number }>();
+  vectorResults.forEach((r, i) => {
+    knnMap.set(r.id, { similarity: 1 - r.distance, rank: i + 1 });
+  });
+
+  const ftsMap = new Map<string, number>();
+  ftsResults.forEach((r, i) => {
+    ftsMap.set(r.id, i + 1);
+  });
+
+  const allIds = new Set([...knnMap.keys(), ...ftsMap.keys()]);
+  const results = new Map<string, SearchSignals & { rrfScore: number }>();
+
+  for (const id of allIds) {
+    const knn = knnMap.get(id);
+    const ftsRank = ftsMap.get(id) ?? null;
+    let rrfScore = 0;
+    if (knn) rrfScore += 1 / (k + knn.rank);
+    if (ftsRank !== null) rrfScore += 1 / (k + ftsRank);
+
+    results.set(id, {
+      rrfScore,
+      cosineSimilarity: knn?.similarity ?? null,
+      ftsMatch: ftsRank !== null,
+      knnRank: knn?.rank ?? null,
+      ftsRank,
+    });
+  }
+
+  return results;
+}
+
 /**
  * Sort ids by RRF score descending and return top N.
  */

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) => ({
@@ -147,6 +192,8 @@ export function createHttpApp(memoryService: MemoryService, config: Config): Hon
           content: r.content,
           metadata: r.metadata,
           source: r.source,
+          confidence: r.confidence,
+          project: r.project,
           createdAt: r.createdAt.toISOString(),
         })),
         count: results.length,
@@ -161,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({
@@ -239,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) {
@@ -298,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,
   };
 }