codex-dev-mcp-suite 1.4.0 → 1.5.0

package/CHANGELOG.md

@@ -1,3 +1,12 @@
+## 1.5.0
+
+- add `memory_link` with wiki-link resolution for `[[id]]`, `[[title]]`, `[[project:id]]`, and `[[project:title]]`, plus backlink inspection
+- add `memory_global_recall` with same-project bias and graceful keyword/semantic fallback across project vaults
+- add `memory_dedup` with non-destructive duplicate suggestions for project or global scope
+- add hybrid lazy graph backfill so link metadata is derived on first graph-aware use and remains rebuildable from canonical notes
+- add graph-aware soft boost in recall paths without making embeddings mandatory
+- 36 project-memory tests pass after graph/global/dedup coverage expansion
+
 # Changelog
 
 ## 1.4.0 - 2026-06-17

package/README.md

@@ -66,7 +66,7 @@ Other clients (Claude Code, Cursor, Cline, ...): see
 
 | Server | What it does | Key tools |
 |---|---|---|
-| **project-memory** | Searchable Markdown knowledge vault (Obsidian-style notes + on-demand recall). Notes are also exposed as MCP resources. | `memory_save`, `memory_recall`, `memory_list`, `memory_get`, `memory_delete`, `memory_reindex` |
+| **project-memory** | Searchable Markdown knowledge vault (Obsidian-style notes + on-demand recall). Notes are also exposed as MCP resources. | `memory_save`, `memory_recall`, `memory_list`, `memory_get`, `memory_delete`, `memory_reindex`, `memory_link`, `memory_global_recall`, `memory_dedup` |
 | **devjournal** | Per-project session timeline + handoff/resume (anti-compaction). | `journal_log`, `journal_handoff`, `journal_resume`, `journal_timeline`, `journal_search`, `journal_clear_handoff` |
 | **checkpoint** | Git-independent file snapshots for safe experimentation. | `checkpoint_create`, `checkpoint_list`, `checkpoint_diff`, `checkpoint_restore`, `checkpoint_delete` |
 | **context-pack** | Token-efficient project briefing (stack, tree, symbols, search). | `pack_overview`, `pack_tree`, `pack_outline`, `pack_search` |
@@ -192,6 +192,16 @@ With `MCP_DETERMINISTIC_FALLBACK=true`, the mode is always `[deterministic]`.
 This means you can run codex-dev-mcp-suite with **zero API keys configured** —
 `memory_recall` still works via keyword scoring, just no semantic similarity.
 
+### New in v1.5.0
+
+`project-memory` now adds a lightweight knowledge-graph layer:
+
+- `memory_link` resolves wiki-style links like `[[id]]`, `[[title]]`, and `[[project:title]]`, and shows backlinks
+- `memory_global_recall` searches across projects with same-project bias and graceful keyword fallback
+- `memory_dedup` suggests duplicate-note merges without deleting anything
+
+Link resolution always prefers the active project first, then falls back globally when appropriate.
+
 ## Daily workflow
 
 - Session start: `pack_overview` + `journal_resume` + `memory_recall "<topic>"`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-dev-mcp-suite",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "Four local, file-based MCP servers for solo devs/vibecoders: persistent project memory, session handoff/resume, git-independent file checkpoints, and token-efficient project briefings. Works with any MCP client.",
   "type": "module",
   "license": "MIT",

package/project-memory/dedup.js

@@ -0,0 +1,49 @@
+function jaccard(left, right) {
+  const leftSet = new Set(left.filter(Boolean));
+  const rightSet = new Set(right.filter(Boolean));
+  const intersection = [...leftSet].filter((item) => rightSet.has(item)).length;
+  const union = new Set([...leftSet, ...rightSet]).size || 1;
+  return intersection / union;
+}
+
+function tokenizeBody(text) {
+  return String(text || "").toLowerCase().split(/\W+/).filter(Boolean);
+}
+
+export function scoreDuplicatePair({ a, b, aBody, bBody }) {
+  const reasons = [];
+  let score = 0;
+
+  if (String(a.title || "").trim().toLowerCase() === String(b.title || "").trim().toLowerCase()) {
+    score += 0.5;
+    reasons.push("exact normalized title match");
+  }
+
+  const bodyScore = jaccard(tokenizeBody(aBody), tokenizeBody(bBody));
+  score += bodyScore * 0.4;
+  if (bodyScore >= 0.75) reasons.push("strong content overlap");
+
+  const linkScore = jaccard((a.links || []).map((link) => `${link.project || ""}:${link.ref || ""}`), (b.links || []).map((link) => `${link.project || ""}:${link.ref || ""}`));
+  score += linkScore * 0.1;
+  if (linkScore >= 0.75 && (a.links || []).length && (b.links || []).length) reasons.push("similar link neighborhood");
+
+  return { score: Math.min(1, score), reasons };
+}
+
+export function findDuplicateCandidates({ rows, threshold }) {
+  const out = [];
+  for (let i = 0; i < rows.length; i += 1) {
+    for (let j = i + 1; j < rows.length; j += 1) {
+      const result = scoreDuplicatePair({
+        a: rows[i].note,
+        b: rows[j].note,
+        aBody: rows[i].body,
+        bBody: rows[j].body,
+      });
+      if (result.score >= threshold) {
+        out.push({ left: rows[i], right: rows[j], score: result.score, reasons: result.reasons });
+      }
+    }
+  }
+  return out.sort((a, b) => b.score - a.score);
+}

package/project-memory/global-index.js

@@ -0,0 +1,46 @@
+import fs from "fs/promises";
+import path from "path";
+
+export async function listProjects(vaultRoot) {
+  let slugs = [];
+  try {
+    slugs = await fs.readdir(vaultRoot);
+  } catch {
+    slugs = [];
+  }
+  return slugs.map((slug) => ({
+    slug,
+    projectDir: path.join(vaultRoot, slug),
+    indexFile: path.join(vaultRoot, slug, "index.json"),
+  }));
+}
+
+export async function loadGlobalNotes(vaultRoot) {
+  const projects = await listProjects(vaultRoot);
+  const rows = [];
+  for (const project of projects) {
+    try {
+      const raw = await fs.readFile(project.indexFile, "utf8");
+      const index = JSON.parse(raw);
+      for (const note of Object.values(index.notes || {})) rows.push({ slug: project.slug, note });
+    } catch {
+      // ignore invalid or incomplete project index
+    }
+  }
+  return rows;
+}
+
+export async function findGlobalCandidates({ vaultRoot, currentSlug, query }) {
+  const q = String(query || "").toLowerCase();
+  const rows = await loadGlobalNotes(vaultRoot);
+  return rows
+    .filter(({ note }) =>
+      String(note.title || "").toLowerCase().includes(q) ||
+      (note.keywords || []).some((keyword) => String(keyword).toLowerCase().includes(q))
+    )
+    .sort((a, b) => {
+      const ap = a.slug === currentSlug ? 0 : 1;
+      const bp = b.slug === currentSlug ? 0 : 1;
+      return ap - bp || (a.note.created < b.note.created ? 1 : -1);
+    });
+}

package/project-memory/graph.js

@@ -0,0 +1,86 @@
+import fs from "fs/promises";
+import path from "path";
+import { parseFrontmatter } from "./server.js";
+
+export function extractWikiLinks(body) {
+  const out = [];
+  const re = /\[\[([^\]]+)\]\]/g;
+  let match;
+  while ((match = re.exec(String(body || "")))) {
+    const raw = match[0];
+    const inner = match[1].trim();
+    const colon = inner.indexOf(":");
+    const project = colon > 0 ? inner.slice(0, colon).trim() : null;
+    const ref = colon > 0 ? inner.slice(colon + 1).trim() : inner;
+    const kind = /^[0-9A-Za-z_-]{6,}$/.test(ref) && !/\s/.test(ref) ? "id" : "title";
+    out.push({ raw, ref, project, kind });
+  }
+  return out;
+}
+
+export async function loadNoteBody(projectDir, file) {
+  const raw = await fs.readFile(path.join(projectDir, file), "utf8");
+  return parseFrontmatter(raw).body;
+}
+
+export async function ensureGraphState({ vaultRoot, projectDir, slug, index, noteLoader }) {
+  void vaultRoot;
+  void slug;
+  let changed = false;
+  const backlinks = new Map();
+  for (const note of Object.values(index.notes || {})) {
+    const body = await noteLoader(projectDir, note.file);
+    const links = extractWikiLinks(body).map((link) => ({
+      raw: link.raw,
+      ref: link.ref,
+      project: link.project,
+      kind: link.kind,
+    }));
+    const next = JSON.stringify(links);
+    const prev = JSON.stringify(note.links || []);
+    if (next !== prev) {
+      note.links = links;
+      changed = true;
+    }
+  }
+  for (const note of Object.values(index.notes || {})) {
+    for (const link of note.links || []) {
+      if (link.project || link.kind !== "id") continue;
+      const arr = backlinks.get(link.ref) || [];
+      arr.push({ id: note.id, title: note.title });
+      backlinks.set(link.ref, arr);
+    }
+  }
+  for (const note of Object.values(index.notes || {})) {
+    const next = backlinks.get(note.id) || [];
+    if (JSON.stringify(next) !== JSON.stringify(note.backlinks || [])) {
+      note.backlinks = next;
+      changed = true;
+    }
+  }
+  return { index, changed };
+}
+
+export async function resolveLink({ vaultRoot, currentSlug, ref, project, kind }) {
+  const targetSlug = project || currentSlug;
+  const indexFile = path.join(vaultRoot, targetSlug, "index.json");
+  let index;
+  try {
+    index = JSON.parse(await fs.readFile(indexFile, "utf8"));
+  } catch {
+    return { status: "missing" };
+  }
+
+  const notes = Object.values(index.notes || {});
+  let candidates;
+  if (kind === "id") {
+    candidates = notes.filter((note) => note.id === ref);
+  } else {
+    const target = String(ref || "").trim().toLowerCase();
+    candidates = notes.filter((note) => String(note.title || "").trim().toLowerCase() === target);
+  }
+
+  if (candidates.length === 0) return { status: "missing" };
+  if (candidates.length === 1) return { status: "resolved", match: candidates[0] };
+  return { status: "ambiguous", candidates };
+}

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(
@@ -222,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.",
@@ -247,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}`);
         }
@@ -321,7 +377,15 @@ class ProjectMemoryServer {
     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.` }] };
     }
@@ -352,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));
 
@@ -411,6 +475,70 @@ class ProjectMemoryServer {
     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 }) {
     const p = this.paths(dir);
     const index = await this.loadIndex(p);
@@ -444,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).` }] };
@@ -488,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 };