codex-dev-mcp-suite 1.3.0 → 1.5.0

package/project-memory/server.js

@@ -26,9 +26,13 @@ import fs from "fs/promises";
 import path from "path";
 import os from "os";
 import crypto from "crypto";
+import { fileURLToPath } from "url";
 import { embed, embedOne, cosine, embeddingConfig } from "./embedding.js";
 import { rerank, rerankConfig } from "./rerank.js";
 import { deterministicEnabled } from "./env.js";
+import { ensureGraphState, resolveLink, loadNoteBody } from "./graph.js";
+import { loadGlobalNotes } from "./global-index.js";
+import { findDuplicateCandidates } from "./dedup.js";
 import { computeStats, formatText, formatJson } from "../lib/stats.js";
 
 const VAULT_ROOT =
@@ -44,7 +48,7 @@ const STOPWORDS = new Set([
   "not", "no", "do", "did", "does", "can", "will", "so", "my", "our", "your",
 ]);
 
-function projectSlug(dir) {
+export function projectSlug(dir) {
   const resolved = path.resolve(dir || process.cwd());
   const base = path.basename(resolved) || "root";
   const hash = crypto.createHash("sha1").update(resolved).digest("hex").slice(0, 8);
@@ -76,7 +80,7 @@ function limit(value, name, max, required = true) {
   return text;
 }
 
-function parseFrontmatter(raw) {
+export function parseFrontmatter(raw) {
   const m = raw.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
   if (!m) return { meta: {}, body: raw };
   const meta = {};
@@ -105,6 +109,16 @@ function buildFrontmatter(meta) {
   return lines.join("\n");
 }
 
+function graphBoost(note, queryTokens) {
+  let score = 0;
+  for (const link of note.links || []) {
+    for (const token of queryTokens) {
+      if (String(link.ref || "").toLowerCase().includes(token)) score += 0.05;
+    }
+  }
+  return Math.min(0.15, score);
+}
+
 class ProjectMemoryServer {
   constructor() {
     this.server = new Server(
@@ -163,7 +177,7 @@ class ProjectMemoryServer {
         {
           name: "memory_recall",
           description:
-            "Retrieve the most relevant saved notes for a query using the keyword index. Call this at the start of a new session instead of re-pasting context.",
+            "Retrieve the most relevant saved notes for a query. Falls back gracefully: semantic -> keyword -> LLM rerank. Set mode to control behavior: 'auto' (default), 'semantic' (require embedding), 'keyword' (skip embedding).",
           inputSchema: {
             type: "object",
             properties: {
@@ -171,6 +185,7 @@ class ProjectMemoryServer {
               dir: { type: "string", description: "Project directory (defaults to CWD)" },
               limit: { type: "number", description: "Max notes to return", default: 5 },
               full: { type: "boolean", description: "Return full bodies instead of excerpts", default: false },
+              mode: { type: "string", enum: ["auto", "semantic", "keyword"], default: "auto", description: "Retrieval mode: 'auto' (default, smart fallback), 'semantic' (require embedding), 'keyword' (skip embedding)" },
             },
             required: ["query"],
           },
@@ -221,6 +236,45 @@ class ProjectMemoryServer {
             },
           },
         },
+        {
+          name: "memory_link",
+          description: "Resolve wiki-style note links and show backlinks for a note.",
+          inputSchema: {
+            type: "object",
+            properties: {
+              id: { type: "string", description: "Note id to inspect" },
+              dir: { type: "string", description: "Project directory (defaults to CWD)" },
+              include_unresolved: { type: "boolean", description: "Include unresolved links in output", default: true },
+            },
+            required: ["id"],
+          },
+        },
+        {
+          name: "memory_global_recall",
+          description: "Recall relevant notes across projects with same-project bias and graceful keyword fallback.",
+          inputSchema: {
+            type: "object",
+            properties: {
+              query: { type: "string", description: "What you need context about" },
+              dir: { type: "string", description: "Project directory (defaults to CWD)" },
+              limit: { type: "number", description: "Max notes to return", default: 5 },
+              full: { type: "boolean", description: "Return full bodies instead of excerpts", default: false },
+            },
+            required: ["query"],
+          },
+        },
+        {
+          name: "memory_dedup",
+          description: "Find likely duplicate notes and suggest non-destructive merges.",
+          inputSchema: {
+            type: "object",
+            properties: {
+              dir: { type: "string", description: "Project directory (defaults to CWD)" },
+              threshold: { type: "number", description: "Duplicate threshold", default: 0.9 },
+              scope: { type: "string", enum: ["project", "global"], description: "Dedup scope", default: "project" },
+            },
+          },
+        },
         {
           name: "memory_stats",
           description: "Summarize local memory storage across vault / journal / checkpoints: totals, top projects, recent activity, and temp-slug cleanup candidates. Returns the same text as the `stats` CLI.",
@@ -246,6 +300,9 @@ class ProjectMemoryServer {
           case "memory_get": return await this.get(args || {});
           case "memory_delete": return await this.del(args || {});
           case "memory_reindex": return await this.reindex(args || {});
+          case "memory_link": return await this.link(args || {});
+          case "memory_global_recall": return await this.globalRecall(args || {});
+          case "memory_dedup": return await this.dedup(args || {});
           case "memory_stats": return await this.stats(args || {});
           default: throw new Error(`Unknown tool: ${name}`);
         }
@@ -316,11 +373,19 @@ class ProjectMemoryServer {
     return { content: [{ type: "text", text: `Saved note ${id} → ${p.slug}\nFile: ${file}\nKeywords indexed: ${keywords.length}${embedded ? " (semantic embedding stored)" : " (keyword-only; embeddings unavailable)"}` }] };
   }
 
-  async recall({ query, dir, limit: lim = 5, full = false }) {
+  async recall({ query, dir, limit: lim = 5, full = false, mode: requestedMode = "auto" }) {
     query = limit(query, "query", 2000);
     const p = this.paths(dir);
     const index = await this.loadIndex(p);
-    const notes = Object.values(index.notes || {});
+    const ensured = await ensureGraphState({
+      vaultRoot: VAULT_ROOT,
+      projectDir: p.projectDir,
+      slug: p.slug,
+      index,
+      noteLoader: loadNoteBody,
+    });
+    if (ensured.changed) await this.saveIndex(p, ensured.index);
+    const notes = Object.values(ensured.index.notes || {});
     if (notes.length === 0) {
       return { content: [{ type: "text", text: `No memories for ${p.slug} yet. Use memory_save first.` }] };
     }
@@ -333,10 +398,17 @@ class ProjectMemoryServer {
       return score;
     };
 
+    // Tier 2.1: respect requested mode. "auto" = smart fallback.
     let mode = deterministicEnabled() ? "deterministic" : "keyword";
-    const qVec = deterministicEnabled() ? null : await embedOne(query);
+    const useEmbed = requestedMode !== "keyword" && !deterministicEnabled();
+    const qVec = useEmbed ? await embedOne(query) : null;
     const haveEmb = qVec && notes.some((n) => Array.isArray(n.embedding));
 
+    // Tier 2.1: "semantic" requested but unavailable -> error
+    if (requestedMode === "semantic" && !haveEmb) {
+      return { content: [{ type: "text", text: `memory_recall(mode=semantic) requested but no embeddings available. Set MCP_EMBED_API_KEY + MCP_EMBED_MODEL, or omit mode for keyword fallback.` }], isError: true };
+    }
+
     let scored;
     if (haveEmb) {
       mode = "semantic";
@@ -344,14 +416,14 @@ class ProjectMemoryServer {
       scored = notes.map((n) => {
         const sim = Array.isArray(n.embedding) ? cosine(qVec, n.embedding) : 0;
         const kwNorm = kw(n) / maxKw;
-        const score = 0.8 * sim + 0.2 * kwNorm;
+        const score = 0.8 * sim + 0.2 * kwNorm + graphBoost(n, [...qTokens]);
         return { n, score, sim };
       }).filter((x) => x.score > 0.05)
         .sort((a, b) => b.score - a.score || (a.n.created < b.n.created ? 1 : -1))
         .slice(0, Math.max(1, Math.min(20, lim)));
     } else {
       const want = Math.max(1, Math.min(20, lim));
-      const kwRanked = notes.map((n) => ({ n, score: kw(n) }))
+      const kwRanked = notes.map((n) => ({ n, score: kw(n) + graphBoost(n, [...qTokens]) }))
         .filter((x) => x.score > 0)
         .sort((a, b) => b.score - a.score || (a.n.created < b.n.created ? 1 : -1));
 
@@ -395,7 +467,76 @@ class ProjectMemoryServer {
       const tag = mode === "semantic" ? `sim:${(sim ?? 0).toFixed(3)}` : (mode === "rerank" ? "llm-ranked" : `score:${score}`);
       blocks.push(`### ${n.title}  (id:${n.id}, ${tag}, ${n.created})\n${text}`);
     }
-    return { content: [{ type: "text", text: `Recall for "${query}" in ${p.slug} [${mode}]:\n\n${blocks.join("\n\n---\n\n")}` }] };
+    // Tier 2.2: annotate mode with rerank indicator
+    const isReranked = rerankConfig().enabled && blocks.length > 1;
+    const displayMode = mode === "semantic" && isReranked ? "semantic+rerank"
+      : mode === "keyword" && isReranked ? "keyword+rerank"
+      : mode;
+    return { content: [{ type: "text", text: `Recall for "${query}" in ${p.slug} [${displayMode}]:\n\n${blocks.join("\n\n---\n\n")}` }] };
+  }
+
+  async dedup({ dir, threshold = 0.9, scope = "project" }) {
+    const p = this.paths(dir);
+    const rows = await loadGlobalNotes(VAULT_ROOT);
+    const filtered = scope === "project" ? rows.filter((row) => row.slug === p.slug) : rows;
+    const withBodies = await Promise.all(filtered.map(async ({ slug, note }) => {
+      const raw = await fs.readFile(path.join(VAULT_ROOT, slug, note.file), "utf8").catch(() => "");
+      const { body } = parseFrontmatter(raw);
+      return { slug, note, body };
+    }));
+    const pairs = findDuplicateCandidates({ rows: withBodies, threshold });
+    if (!pairs.length) {
+      return { content: [{ type: "text", text: `No duplicate suggestions above ${threshold} in ${scope} scope.` }] };
+    }
+    const lines = [`Duplicate suggestions [threshold=${threshold}, scope=${scope}]:`, ""];
+    for (const pair of pairs) {
+      lines.push(`- suggested merge: [${pair.left.slug}] ${pair.left.note.title} <-> [${pair.right.slug}] ${pair.right.note.title} (score=${pair.score.toFixed(3)})`);
+      lines.push(`  reasons: ${pair.reasons.join(", ")}`);
+    }
+    return { content: [{ type: "text", text: lines.join("\n") }] };
+  }
+
+  async globalRecall({ query, dir, limit: lim = 5, full = false }) {
+    query = limit(query, "query", 2000);
+    const p = this.paths(dir);
+    const currentIndex = await this.loadIndex(p);
+    const ensured = await ensureGraphState({
+      vaultRoot: VAULT_ROOT,
+      projectDir: p.projectDir,
+      slug: p.slug,
+      index: currentIndex,
+      noteLoader: loadNoteBody,
+    });
+    if (ensured.changed) await this.saveIndex(p, ensured.index);
+    const rows = await loadGlobalNotes(VAULT_ROOT);
+    const qTokens = new Set(tokenize(query));
+    const qVec = deterministicEnabled() ? null : await embedOne(query);
+    const haveEmbeddings = !!(qVec && rows.some((row) => Array.isArray(row.note.embedding)));
+
+    const scored = rows.map(({ slug, note }) => {
+      let kwScore = 0;
+      for (const keyword of note.keywords || []) if (qTokens.has(keyword)) kwScore += 1;
+      for (const word of tokenize(note.title)) if (qTokens.has(word)) kwScore += 2;
+      const sameProjectBoost = slug === p.slug ? 0.25 : 0;
+      const sim = haveEmbeddings && Array.isArray(note.embedding) ? cosine(qVec, note.embedding) : 0;
+      const score = (haveEmbeddings ? (0.8 * sim) : 0) + (0.2 * kwScore) + sameProjectBoost + graphBoost(note, [...qTokens]);
+      return { slug, note, sim, score };
+    }).filter((entry) => entry.score > 0)
+      .sort((a, b) => b.score - a.score || (a.note.created < b.note.created ? 1 : -1))
+      .slice(0, Math.max(1, Math.min(20, lim)));
+
+    if (scored.length === 0) {
+      return { content: [{ type: "text", text: `No relevant global memories for "${query}". Try memory_list or memory_recall.` }] };
+    }
+
+    const mode = haveEmbeddings ? "semantic+graph" : "keyword+graph";
+    const blocks = await Promise.all(scored.map(async ({ slug, note, sim, score }) => {
+      const raw = await fs.readFile(path.join(VAULT_ROOT, slug, note.file), "utf8").catch(() => "");
+      const { body } = parseFrontmatter(raw);
+      const text = full ? body.trim() : body.trim().split("\n").slice(0, 12).join("\n");
+      return `### ${note.title}  ([${slug}], ${haveEmbeddings ? `sim:${sim.toFixed(3)}` : `score:${score.toFixed(2)}`})\n${text}`;
+    }));
+    return { content: [{ type: "text", text: `Global recall for "${query}" [${mode}]:\n\n${blocks.join("\n\n---\n\n")}` }] };
   }
 
   async list({ dir, limit: lim = 20 }) {
@@ -431,6 +572,47 @@ class ProjectMemoryServer {
     return { content: [{ type: "text", text: `Deleted note ${id} from ${p.slug}` }] };
   }
 
+  async link({ id, dir, include_unresolved = true }) {
+    id = limit(id, "id", 100);
+    const p = this.paths(dir);
+    const index = await this.loadIndex(p);
+    const note = index.notes?.[id];
+    if (!note) throw new Error(`Note ${id} not found in ${p.slug}`);
+
+    const ensured = await ensureGraphState({
+      vaultRoot: VAULT_ROOT,
+      projectDir: p.projectDir,
+      slug: p.slug,
+      index,
+      noteLoader: loadNoteBody,
+    });
+    if (ensured.changed) await this.saveIndex(p, ensured.index);
+
+    const current = ensured.index.notes[id];
+    const links = [];
+    for (const link of current.links || []) {
+      const resolved = await resolveLink({
+        vaultRoot: VAULT_ROOT,
+        currentSlug: p.slug,
+        ref: link.ref,
+        project: link.project,
+        kind: link.kind,
+      });
+      if (resolved.status !== "missing" || include_unresolved) links.push({ link, resolved });
+    }
+
+    const lines = [
+      `Links for ${current.title} (${current.id})`,
+      "",
+      "Outgoing:",
+      ...links.map(({ link, resolved }) => `- ${link.raw} -> ${resolved.status}${resolved.match ? ` (${resolved.match.title})` : ""}`),
+      "",
+      "Backlinks:",
+      ...((current.backlinks || []).length ? current.backlinks.map((b) => `- ${b.title} (${b.id})`) : ["- none"]),
+    ];
+    return { content: [{ type: "text", text: lines.join("\n") }] };
+  }
+
   async reindex({ dir, force = false }) {
     const p = this.paths(dir);
     if (deterministicEnabled()) return { content: [{ type: "text", text: `Reindex ${p.slug}: skipped (deterministic no-network mode; embeddings disabled).` }] };
@@ -475,5 +657,9 @@ class ProjectMemoryServer {
   }
 }
 
-const server = new ProjectMemoryServer();
-server.run().catch(console.error);
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  const server = new ProjectMemoryServer();
+  server.run().catch(console.error);
+}
+
+export { ProjectMemoryServer };