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

package/server/core/memory.service.ts

@@ -1,10 +1,12 @@
 import { randomUUID, createHash } from "crypto";
+import { basename } from "path";
 import type { Memory, SearchIntent, IntentProfile, HybridRow } from "./memory";
 import { isDeleted, computeConfidence } from "./memory";
-import type { SearchResult, SearchOptions } from "./conversation";
+import type { SearchResult, SearchOptions, HistoryFilters } from "./conversation";
 import type { MemoryRepository } from "./memory.repository";
 import type { EmbeddingsService } from "./embeddings.service";
 import type { ConversationHistoryService } from "./conversation.service";
+import { normalizeProject } from "./project";
 
 // Jitter values halved from original (0.02/0.05/0.15) because RRF_K=10 produces
 // ~6x more score spread than K=60, amplifying jitter's disruption effect.
@@ -18,14 +20,23 @@ const INTENT_PROFILES: Record<SearchIntent, IntentProfile> = {
 
 const sigmoid = (x: number): number => 1 / (1 + Math.exp(-x));
 
+// Modest same-project ranking boost for scope:"all" searches — same-repo
+// memories win ties without hiding cross-project results.
+const CURRENT_PROJECT_BOOST = 1.15;
+
 export class MemoryService {
   private conversationService: ConversationHistoryService | null = null;
 
   constructor(
     private repository: MemoryRepository,
-    private embeddings: EmbeddingsService
+    private embeddings: EmbeddingsService,
+    private project: string | null = null
   ) {}
 
+  getProject(): string | null {
+    return this.project;
+  }
+
   setConversationService(service: ConversationHistoryService): void {
     this.conversationService = service;
   }
@@ -45,7 +56,8 @@ export class MemoryService {
   async store(
     content: string,
     metadata: Record<string, unknown> = {},
-    embeddingText?: string
+    embeddingText?: string,
+    project?: string
   ): Promise<Memory> {
     const id = randomUUID();
     const now = new Date();
@@ -63,6 +75,7 @@ export class MemoryService {
       usefulness: 0,
       accessCount: 0,
       lastAccessed: now, // Initialize to createdAt for fair discovery
+      project: project !== undefined ? normalizeProject(project) : this.project,
     };
 
     await this.repository.insert(memory);
@@ -200,11 +213,51 @@ export class MemoryService {
     // Widen the candidate pool to account for offset
     const effectiveLimit = offset + limit;
 
+    // Resolve project scope: "all" = no filter (with same-project ranking
+    // boost), "project" = current project, anything else = explicit path.
+    const scope = options?.scope ?? "all";
+    const projectFilter: string | undefined =
+      scope === "all"
+        ? undefined
+        : scope === "project"
+          ? (this.project ?? undefined)
+          : normalizeProject(scope);
+
+    const hasDateFilters = options?.after || options?.before;
+    const memoryFilters =
+      hasDateFilters || projectFilter !== undefined
+        ? {
+            after: options?.after,
+            before: options?.before,
+            project: projectFilter,
+          }
+        : undefined;
+
+    // Merge top-level date filters into history filters so after/before
+    // apply uniformly. Explicit history_after/history_before take precedence,
+    // as does an explicit historyFilters.project.
+    const historyFilters = options?.historyFilters;
+    const effectiveHistoryFilters: HistoryFilters | undefined =
+      hasDateFilters || projectFilter !== undefined || historyFilters
+        ? {
+            ...historyFilters,
+            after: historyFilters?.after ?? options?.after,
+            before: historyFilters?.before ?? options?.before,
+            project: historyFilters?.project ?? projectFilter,
+          }
+        : historyFilters;
+
+    // Same-project boost only applies to unscoped searches
+    const boost = (resultProject: string | null): number =>
+      scope === "all" && this.project && resultProject === this.project
+        ? CURRENT_PROJECT_BOOST
+        : 1;
+
     // Run memory + history queries in parallel
     const memoryPromise =
       !historyOnly
         ? this.repository
-            .findHybrid(queryEmbedding, query, effectiveLimit * 5)
+            .findHybrid(queryEmbedding, query, effectiveLimit * 5, memoryFilters)
             .then((candidates) =>
               candidates
                 .filter((m) => includeDeleted || !isDeleted(m))
@@ -215,8 +268,11 @@ export class MemoryService {
                   createdAt: candidate.createdAt,
                   updatedAt: candidate.updatedAt,
                   source: "memory" as const,
-                  score: this.computeMemoryScore(candidate, profile, now),
+                  score:
+                    this.computeMemoryScore(candidate, profile, now) *
+                    boost(candidate.project),
                   confidence: computeConfidence(candidate.signals),
+                  project: candidate.project,
                   supersededBy: candidate.supersededBy,
                   usefulness: candidate.usefulness,
                   accessCount: candidate.accessCount,
@@ -232,24 +288,28 @@ export class MemoryService {
               query,
               queryEmbedding,
               historyOnly ? effectiveLimit * 5 : effectiveLimit * 3,
-              options?.historyFilters
+              effectiveHistoryFilters
             )
             .then((historyRows) =>
-              historyRows.map((row) => ({
-                id: row.id,
-                content: row.content,
-                metadata: row.metadata,
-                createdAt: row.createdAt,
-                updatedAt: row.createdAt,
-                source: "conversation_history" as const,
-                score: row.rrfScore * historyWeight,
-                confidence: computeConfidence(row.signals),
-                supersededBy: null,
-                sessionId: (row.metadata?.session_id as string) ?? "",
-                role: (row.metadata?.role as string) ?? "unknown",
-                messageIndexStart: (row.metadata?.message_index_start as number) ?? 0,
-                messageIndexEnd: (row.metadata?.message_index_end as number) ?? 0,
-              }))
+              historyRows.map((row) => {
+                const rowProject = (row.metadata?.project as string) ?? null;
+                return {
+                  id: row.id,
+                  content: row.content,
+                  metadata: row.metadata,
+                  createdAt: row.createdAt,
+                  updatedAt: row.createdAt,
+                  source: "conversation_history" as const,
+                  score: row.rrfScore * historyWeight * boost(rowProject),
+                  confidence: computeConfidence(row.signals),
+                  project: rowProject,
+                  supersededBy: null,
+                  sessionId: (row.metadata?.session_id as string) ?? "",
+                  role: (row.metadata?.role as string) ?? "unknown",
+                  messageIndexStart: (row.metadata?.message_index_start as number) ?? 0,
+                  messageIndexEnd: (row.metadata?.message_index_end as number) ?? 0,
+                };
+              })
             )
         : Promise.resolve([] as SearchResult[]);
 
@@ -294,8 +354,17 @@ export class MemoryService {
     ].join("-");
   }
 
+  /**
+   * Resolve a caller-supplied project (possibly a legacy display name or
+   * relative value) or fall back to the server's configured project.
+   */
+  private resolveProject(project?: string): string | undefined {
+    if (project && project.trim().length > 0) return normalizeProject(project);
+    return this.project ?? undefined;
+  }
+
   async setWaypoint(args: {
-    project: string;
+    project?: string;
     branch?: string;
     summary: string;
     completed?: string[];
@@ -310,6 +379,7 @@ export class MemoryService {
       await this.trackAccess(args.memory_ids);
     }
 
+    const project = this.resolveProject(args.project);
     const now = new Date();
     const date = now.toISOString().slice(0, 10);
     const time = now.toISOString().slice(11, 16);
@@ -321,7 +391,7 @@ export class MemoryService {
       return items.map((i) => `- ${i}`).join("\n");
     };
 
-    const content = `# Waypoint - ${args.project}
+    const content = `# Waypoint - ${project ?? "unknown project"}
 **Date:** ${date} ${time} | **Branch:** ${args.branch ?? "unknown"}
 
 ## Summary
@@ -345,14 +415,14 @@ ${list(args.memory_ids)}`;
     const metadata: Record<string, unknown> = {
       ...(args.metadata ?? {}),
       type: "waypoint",
-      project: args.project,
+      project: project ?? null,
       date,
       branch: args.branch ?? "unknown",
       memory_ids: args.memory_ids ?? [],
     };
 
     const memory: Memory = {
-      id: MemoryService.waypointId(args.project),
+      id: MemoryService.waypointId(project),
       content,
       embedding: new Array(this.embeddings.dimension).fill(0),
       metadata,
@@ -362,35 +432,83 @@ ${list(args.memory_ids)}`;
       usefulness: 0,
       accessCount: 0,
       lastAccessed: now, // Initialize to now for consistency
+      project: project ?? null,
     };
 
+    // NOTE: deliberately no UUID_ZERO "global latest" copy — in a shared
+    // database that becomes last-writer-wins across projects. Readers that
+    // don't know their project resolve it from cwd instead.
     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;
   }
 
+  /**
+   * Find the latest waypoint for a project, trying legacy ID schemes in
+   * order and migrating hits to the canonical ID:
+   *  1. canonical: waypointId(normalized absolute path)
+   *  2. legacy skill-supplied display name: waypointId(basename)
+   *  3. legacy UUID-formatted IDs for both of the above
+   *  4. UUID_ZERO "global latest" — only when its metadata.project matches,
+   *     so one project's pre-migration waypoint never leaks into another
+   */
   async getLatestWaypoint(project?: string): Promise<Memory | null> {
-    const waypoint = await this.get(MemoryService.waypointId(project));
-    if (waypoint) return waypoint;
+    const resolved = this.resolveProject(project);
+    const canonicalId = MemoryService.waypointId(resolved);
+
+    const waypoint = await this.get(canonicalId);
+    if (waypoint && !isDeleted(waypoint)) return waypoint;
+
+    const candidateIds: string[] = [];
+    if (resolved) {
+      const display = basename(resolved);
+      candidateIds.push(MemoryService.waypointId(display));
+      const legacyPath = MemoryService.legacyWaypointId(resolved);
+      if (legacyPath) candidateIds.push(legacyPath);
+      const legacyDisplay = MemoryService.legacyWaypointId(display);
+      if (legacyDisplay) candidateIds.push(legacyDisplay);
+    } else {
+      const legacyId = MemoryService.legacyWaypointId(resolved);
+      if (legacyId) candidateIds.push(legacyId);
+    }
 
-    // Fallback: try legacy UUID-formatted waypoint ID and migrate on read
-    const legacyId = MemoryService.legacyWaypointId(project);
-    if (!legacyId) return null;
+    for (const id of candidateIds) {
+      if (id === canonicalId) continue;
+      const legacy = await this.repository.findById(id);
+      if (!legacy || isDeleted(legacy)) continue;
+
+      // Migrate: write under canonical ID, delete old
+      await this.repository.upsert({
+        ...legacy,
+        id: canonicalId,
+        project: resolved ?? legacy.project,
+      });
+      await this.repository.markDeleted(id);
+      return { ...legacy, id: canonicalId, project: resolved ?? legacy.project };
+    }
 
-    const legacy = await this.repository.findById(legacyId);
-    if (!legacy) return null;
+    // Last resort: the pre-migration UUID_ZERO copy, guarded by project match
+    if (resolved && canonicalId !== MemoryService.UUID_ZERO) {
+      const global = await this.repository.findById(MemoryService.UUID_ZERO);
+      if (global && !isDeleted(global)) {
+        const metaProject = (global.metadata.project as string | undefined) ?? "";
+        const matches =
+          metaProject.length > 0 &&
+          (normalizeProject(metaProject) === resolved ||
+            metaProject.trim().toLowerCase() ===
+              basename(resolved).toLowerCase());
+        if (matches) {
+          await this.repository.upsert({
+            ...global,
+            id: canonicalId,
+            project: resolved,
+          });
+          await this.repository.markDeleted(MemoryService.UUID_ZERO);
+          return { ...global, id: canonicalId, project: resolved };
+        }
+      }
+    }
 
-    // Migrate: write under new ID, delete old
-    const newId = MemoryService.waypointId(project);
-    await this.repository.upsert({ ...legacy, id: newId });
-    await this.repository.markDeleted(legacyId);
-    return { ...legacy, id: newId };
+    return null;
   }
 }

package/server/core/memory.ts

@@ -11,6 +11,8 @@ export interface Memory {
   usefulness: number;
   accessCount: number;
   lastAccessed: Date | null;
+  /** Canonical project path this memory belongs to (null = untagged/legacy). */
+  project: string | null;
 }
 
 export function isDeleted(memory: Memory): boolean {
@@ -28,6 +30,7 @@ export function memoryToDict(memory: Memory): Record<string, unknown> {
     usefulness: memory.usefulness,
     accessCount: memory.accessCount,
     lastAccessed: memory.lastAccessed?.toISOString() ?? null,
+    project: memory.project,
   };
 }
 

package/server/core/migrations.ts

@@ -1,5 +1,8 @@
 import type { Database } from "bun:sqlite";
+import { readFile } from "fs/promises";
+import { dirname, join } from "path";
 import type { EmbeddingsService } from "./embeddings.service";
+import { normalizeProject } from "./project";
 import { serializeVector } from "./sqlite-utils";
 
 /**
@@ -62,7 +65,8 @@ export function runMigrations(db: Database): void {
       superseded_by TEXT,
       usefulness    REAL NOT NULL DEFAULT 0.0,
       access_count  INTEGER NOT NULL DEFAULT 0,
-      last_accessed INTEGER
+      last_accessed INTEGER,
+      project       TEXT
     )
   `);
 
@@ -109,11 +113,185 @@ export function runMigrations(db: Database): void {
     )
   `);
 
+  // -- Conversation index state (replaces conversation_index_state.json) --
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS conversation_index_state (
+      session_id       TEXT PRIMARY KEY,
+      file_path        TEXT NOT NULL,
+      project          TEXT NOT NULL,
+      last_modified    INTEGER NOT NULL,
+      chunk_count      INTEGER NOT NULL,
+      message_count    INTEGER NOT NULL,
+      indexed_at       INTEGER NOT NULL,
+      first_message_at INTEGER NOT NULL,
+      last_message_at  INTEGER NOT NULL
+    )
+  `);
+
+  // -- Versioned migrations (non-idempotent schema changes) --
+  runVersionedMigrations(db);
+
   // -- 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)`);
+  db.exec(`CREATE INDEX IF NOT EXISTS idx_memories_created_at ON memories(created_at)`);
+  db.exec(`CREATE INDEX IF NOT EXISTS idx_memories_project ON memories(project)`);
+}
+
+/** Current schema version. Bump when adding a versioned migration below. */
+const SCHEMA_VERSION = 1;
+
+function getUserVersion(db: Database): number {
+  const row = db.prepare("PRAGMA user_version").get() as
+    | { user_version: number }
+    | null;
+  return row?.user_version ?? 0;
+}
+
+/**
+ * Non-idempotent migrations (e.g. ALTER TABLE) gated by PRAGMA user_version.
+ *
+ * Concurrency-safe for multiple processes opening the same database: the
+ * version is re-checked inside BEGIN IMMEDIATE, so the loser of a startup
+ * race blocks on busy_timeout, then sees the bumped version and no-ops.
+ */
+function runVersionedMigrations(db: Database): void {
+  if (getUserVersion(db) >= SCHEMA_VERSION) return;
+
+  db.exec("BEGIN IMMEDIATE");
+  try {
+    const version = getUserVersion(db);
+
+    if (version < 1) {
+      // v1: project column on memories (fresh databases get it via CREATE
+      // TABLE above; pre-existing databases need the ALTER).
+      const columns = db
+        .prepare("PRAGMA table_info(memories)")
+        .all() as Array<{ name: string }>;
+      if (!columns.some((c) => c.name === "project")) {
+        db.exec("ALTER TABLE memories ADD COLUMN project TEXT");
+      }
+
+      // Backfill from metadata where a project was recorded (waypoints).
+      // Values are stored raw — they may be legacy display names rather than
+      // canonical paths; consolidation re-stamps them with the real project.
+      db.exec(`
+        UPDATE memories
+        SET project = json_extract(metadata, '$.project')
+        WHERE project IS NULL
+          AND json_extract(metadata, '$.project') IS NOT NULL
+      `);
+
+      db.exec(`PRAGMA user_version = ${SCHEMA_VERSION}`);
+    }
+
+    db.exec("COMMIT");
+  } catch (e) {
+    db.exec("ROLLBACK");
+    throw e;
+  }
+}
+
+/**
+ * Repair legacy `conversation_history.project` values.
+ *
+ * Rows indexed before the cwd-based parser carry lossy dash-decoded project
+ * values (no leading slash; any dash in a directory name decoded as "/").
+ * This re-derives the true project from each session file's `cwd` field.
+ * Rows whose session file is gone get a best-effort "/" prefix so they gain
+ * the canonical-path invariant and are not re-scanned on every startup.
+ *
+ * Identifies legacy rows by the missing leading slash, so it converges to a
+ * no-op once all rows are repaired.
+ */
+export async function repairConversationProjects(
+  db: Database,
+  dbPath: string,
+): Promise<void> {
+  const legacy = db
+    .prepare(
+      "SELECT DISTINCT session_id FROM conversation_history WHERE project NOT LIKE '/%'",
+    )
+    .all() as Array<{ session_id: string }>;
+
+  if (legacy.length === 0) return;
+
+  // session_id -> file_path, from the index state table or the legacy JSON
+  const filePaths = new Map<string, string>();
+  const stateRows = db
+    .prepare("SELECT session_id, file_path FROM conversation_index_state")
+    .all() as Array<{ session_id: string; file_path: string }>;
+  for (const row of stateRows) filePaths.set(row.session_id, row.file_path);
+
+  if (filePaths.size === 0) {
+    try {
+      const raw = await readFile(
+        join(dirname(dbPath), "conversation_index_state.json"),
+        "utf-8",
+      );
+      const entries = JSON.parse(raw) as Array<{
+        sessionId: string;
+        filePath: string;
+      }>;
+      for (const e of entries) filePaths.set(e.sessionId, e.filePath);
+    } catch {
+      // No legacy state file — fall through to best-effort repair
+    }
+  }
+
+  console.error(
+    `[vector-memory-mcp] Repairing project values for ${legacy.length} legacy sessions...`,
+  );
+
+  const updateExact = db.prepare(`
+    UPDATE conversation_history
+    SET project = ?, metadata = json_set(metadata, '$.project', ?)
+    WHERE session_id = ?
+  `);
+  const updateBestEffort = db.prepare(`
+    UPDATE conversation_history
+    SET project = '/' || project
+    WHERE session_id = ? AND project NOT LIKE '/%'
+  `);
+  const updateState = db.prepare(
+    "UPDATE conversation_index_state SET project = ? WHERE session_id = ?",
+  );
+
+  for (const { session_id } of legacy) {
+    const filePath = filePaths.get(session_id);
+    const cwd = filePath ? await readSessionCwd(filePath) : null;
+    if (cwd) {
+      const project = normalizeProject(cwd);
+      updateExact.run(project, project, session_id);
+      updateState.run(project, session_id);
+    } else {
+      updateBestEffort.run(session_id);
+    }
+  }
+}
+
+/** Read the first `cwd` value from a Claude Code session JSONL file. */
+async function readSessionCwd(filePath: string): Promise<string | null> {
+  let content: string;
+  try {
+    content = await readFile(filePath, "utf-8");
+  } catch {
+    return null;
+  }
+  for (const line of content.split("\n")) {
+    if (!line.includes('"cwd"')) continue;
+    try {
+      const entry = JSON.parse(line) as { cwd?: unknown };
+      if (typeof entry.cwd === "string" && entry.cwd.length > 0) {
+        return entry.cwd;
+      }
+    } catch {
+      // malformed line — keep scanning
+    }
+  }
+  return null;
 }
 
 /**
@@ -215,27 +393,30 @@ export async function backfillVectors(
       "INSERT OR REPLACE INTO conversation_history_vec (id, vector) VALUES (?, ?)",
     );
 
-    // Batch embed in chunks of 32
+    // Batch embed in chunks of 32. Embedding happens OUTSIDE the write
+    // transaction and each batch commits separately — holding the write lock
+    // across model inference would block every other process sharing the db.
     const BATCH_SIZE = 32;
-    db.exec("BEGIN");
-    try {
-      for (let i = 0; i < missingConvos.length; i += BATCH_SIZE) {
-        const batch = missingConvos.slice(i, i + BATCH_SIZE);
-        const vecs = await embeddings.embedBatch(batch.map((r) => r.content));
+    for (let i = 0; i < missingConvos.length; i += BATCH_SIZE) {
+      const batch = missingConvos.slice(i, i + BATCH_SIZE);
+      const vecs = await embeddings.embedBatch(batch.map((r) => r.content));
+
+      db.exec("BEGIN");
+      try {
         for (let j = 0; j < batch.length; j++) {
           insertConvoVec.run(batch[j].id, serializeVector(vecs[j]));
         }
+        db.exec("COMMIT");
+      } catch (e) {
+        db.exec("ROLLBACK");
+        throw e;
+      }
 
-        if ((i + BATCH_SIZE) % 100 < BATCH_SIZE) {
-          console.error(
-            `[vector-memory-mcp]   ...${Math.min(i + BATCH_SIZE, missingConvos.length)}/${missingConvos.length} conversation chunks`,
-          );
-        }
+      if ((i + BATCH_SIZE) % 100 < BATCH_SIZE) {
+        console.error(
+          `[vector-memory-mcp]   ...${Math.min(i + BATCH_SIZE, missingConvos.length)}/${missingConvos.length} conversation chunks`,
+        );
       }
-      db.exec("COMMIT");
-    } catch (e) {
-      db.exec("ROLLBACK");
-      throw e;
     }
 
     console.error(

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;
+}