codex-dev-mcp-suite 1.3.0 → 1.5.0

package/lib/provider-smoke.js

@@ -0,0 +1,234 @@
+/**
+ * Dev MCP Suite — provider smoke library.
+ *
+ * Builds a "matrix" of providers from environment variables (matching the
+ * convention used by project-memory / devjournal servers: `MCP_*` neutral,
+ * `NINEROUTER_*` / `LLM_*` / `EMBED_*` legacy aliases), then exposes
+ * helpers to shape probe results and format them as text/JSON/markdown.
+ *
+ * The actual HTTP probes are NOT done here — the CLI wires real `fetch`.
+ * Keeping the lib free of network I/O makes it trivially testable offline.
+ */
+
+import os from "os";
+
+/**
+ * Static metadata for well-known providers. `supportsEmbed: false` means
+ * the provider does not expose an OpenAI-compatible /v1/embeddings endpoint
+ * (e.g. Groq, Cerebras — they focus on inference speed).
+ */
+export function isCloudflareURL(urlStr) {
+  return typeof urlStr === "string" && urlStr.includes("api.cloudflare.com/client/v4/accounts");
+}
+
+export const KNOWN_PROVIDERS = {
+  // Inference-only (no embeddings endpoint)
+  groq:       { supportsChat: true,  supportsEmbed: false, defaultBase: "https://api.groq.com/openai/v1",              defaultModel: "llama-3.3-70b-versatile", notes: "OpenAI-compatible; inference-only" },
+  cerebras:   { supportsChat: true,  supportsEmbed: false, defaultBase: "https://api.cerebras.ai/v1",                 defaultModel: "gpt-oss-120b",          notes: "OpenAI-compatible; inference-only" },
+  anthropic:  { supportsChat: true,  supportsEmbed: false, defaultBase: "https://api.anthropic.com/v1",                defaultModel: null,                   notes: "No embeddings API" },
+
+  // Embeddings + chat
+  openai:     { supportsChat: true,  supportsEmbed: true,  defaultBase: "https://api.openai.com/v1",                  defaultModel: "text-embedding-3-small", notes: "Reference impl; paid (~$0.02/1M tok)" },
+  mistral:    { supportsChat: true,  supportsEmbed: true,  defaultBase: "https://api.mistral.ai/v1",                  defaultModel: "mistral-embed",          notes: "OpenAI-compatible; paid w/ free tier" },
+  openrouter: { supportsChat: true,  supportsEmbed: true,  defaultBase: "https://openrouter.ai/api/v1",                defaultModel: "openai/text-embedding-3-small", notes: "Aggregator; many free models available" },
+  gemini:     { supportsChat: true,  supportsEmbed: true,  defaultBase: "https://generativelanguage.googleapis.com/v1beta/openai", defaultModel: "text-embedding-004", notes: "Google; OpenAI-compatible; generous free tier" },
+  cohere:     { supportsChat: true,  supportsEmbed: true,  defaultBase: "https://api.cohere.ai/v1",                   defaultModel: "embed-multilingual-v3.0", notes: "Top multilingual; trial + paid" },
+  voyage:     { supportsChat: false, supportsEmbed: true,  defaultBase: "https://api.voyageai.com/v1",                defaultModel: "voyage-3",               notes: "Embeddings-only; 200M free on signup" },
+
+  // Local (free, unlimited, uses laptop resources)
+  ollama:     { supportsChat: true,  supportsEmbed: true,  defaultBase: "http://localhost:11434/v1",                  defaultModel: "nomic-embed-text",       notes: "Local; runs on laptop CPU/GPU/RAM" },
+
+  // Non-OpenAI-compatible (requires custom code path in embedding.js)
+  cloudflare: { supportsChat: true,  supportsEmbed: true,  defaultBase: null,                                          defaultModel: "@cf/baai/bge-base-en-v1.5", endpoint: "cloudflare", notes: "REST-only API; NOT OpenAI-compatible; 10K neurons/day free; model goes in URL path" },
+
+  // Local proxy / aggregator (not OpenAI by default; configured via env)
+  "9router":  { supportsChat: true,  supportsEmbed: true,  defaultBase: null,                                          defaultModel: null,                   notes: "Self-hosted OpenAI-compatible aggregator" },
+};
+
+function pickEnv(env, names) {
+  for (const n of names) if (env[n]) return env[n];
+  return undefined;
+}
+
+/** Read a provider slot (PRIMARY, CHAIN2..N) into a normalized record. */
+function readProviderSlot(env, slot /* PRIMARY | CHAIN2 | CHAIN3 | ... */) {
+  const upper = slot.toUpperCase();
+  const name = pickEnv(env, [
+    `MCP_PROVIDER_${upper}`,
+    `MCP_PROVIDER_${upper}_NAME`,
+  ]);
+  if (!name) return null;
+  const lower = name.toLowerCase();
+  const baseUrl = pickEnv(env, [`MCP_PROVIDER_${upper}_BASE_URL`]);
+  const apiKey  = pickEnv(env, [`MCP_PROVIDER_${upper}_API_KEY`]);
+  const chatModel = pickEnv(env, [`MCP_PROVIDER_${upper}_MODEL`, `MCP_PROVIDER_${upper}_CHAT_MODEL`]);
+  const embedModel = pickEnv(env, [`MCP_PROVIDER_${upper}_EMBED_MODEL`]);
+  const meta = KNOWN_PROVIDERS[lower] || {};
+  return {
+    id: lower,
+    name,
+    baseUrl: baseUrl || meta.defaultBase || null,
+    apiKey: apiKey || null,
+    chatModel: chatModel || meta.defaultModel || null,
+    embedModel: embedModel || null,
+    supportsChat: meta.supportsChat !== false,
+    supportsEmbed: meta.supportsEmbed === true && Boolean(embedModel || meta.defaultModel),
+    source: `MCP_PROVIDER_${upper}`,
+  };
+}
+
+/** Read a "named" provider from explicit env (e.g. MISTRAL_*, OPENAI_*, GROQ_*). */
+function readNamedProvider(env, id) {
+  const upper = id.toUpperCase();
+  const apiKey = pickEnv(env, [`${upper}_API_KEY`, `${upper}_KEY`, `MCP_${upper}_API_KEY`]);
+  const baseUrl = pickEnv(env, [`${upper}_BASE_URL`, `${upper}_URL`, `MCP_${upper}_BASE_URL`]);
+  const chatModel = pickEnv(env, [`${upper}_MODEL`, `${upper}_CHAT_MODEL`, `MCP_${upper}_MODEL`]);
+  const embedModel = pickEnv(env, [`${upper}_EMBED_MODEL`, `MCP_EMBED_MODEL`, `${upper}_MODEL`]);
+  if (!apiKey && !baseUrl) return null;
+  const meta = KNOWN_PROVIDERS[id] || {};
+  // For single-model providers (e.g. Cloudflare), the configured model is used for both chat and embed.
+  const effectiveChatModel = chatModel || meta.defaultModel || embedModel || null;
+  const effectiveEmbedModel = embedModel || meta.defaultModel || chatModel || null;
+  const effectiveBaseUrl = baseUrl || meta.defaultBase || null;
+  return {
+    id,
+    name: id,
+    baseUrl: effectiveBaseUrl,
+    apiKey: apiKey || null,
+    chatModel: effectiveChatModel,
+    embedModel: effectiveEmbedModel,
+    supportsChat: meta.supportsChat !== false,
+    supportsEmbed: meta.supportsEmbed === true && Boolean(effectiveEmbedModel),
+    endpoint: meta.endpoint || (effectiveBaseUrl && isCloudflareURL(effectiveBaseUrl) ? "cloudflare" : "openai-compatible"),
+    source: `${upper}_*`,
+  };
+}
+
+/** Read the existing 9router/agentrouter config used by project-memory / devjournal. */
+function read9routerLike(env) {
+  const baseUrl = pickEnv(env, [
+    "MCP_LLM_BASE_URL", "MCP_RERANK_BASE_URL", "MCP_EMBED_BASE_URL",
+    "LLM_BASE_URL", "EMBED_URL", "NINEROUTER_URL", "RERANK_URL",
+  ]);
+  const apiKey = pickEnv(env, [
+    "MCP_LLM_API_KEY", "MCP_RERANK_API_KEY", "MCP_EMBED_API_KEY",
+    "LLM_API_KEY", "EMBED_KEY", "NINEROUTER_KEY", "RERANK_KEY",
+  ]);
+  if (!baseUrl && !apiKey) return null;
+  // Heuristic: label the catch-all based on host for clarity in output.
+  const host = baseUrl ? new URL(baseUrl).hostname : "";
+  let id = "openai-compatible";
+  if (/9router|agentrouter/i.test(host)) id = "9router";
+  return {
+    id,
+    name: id,
+    baseUrl: baseUrl || null,
+    apiKey: apiKey || null,
+    chatModel: pickEnv(env, [
+      "MCP_RERANK_MODEL", "MCP_LLM_MODEL", "RERANK_MODEL", "LLM_MODEL",
+      "NINEROUTER_CHAT_MODEL", "NINEROUTER_RERANK_MODEL", "NINEROUTER_MODEL",
+    ]) || null,
+    embedModel: pickEnv(env, [
+      "MCP_EMBED_MODEL", "EMBED_MODEL", "NINEROUTER_EMBED_MODEL",
+    ]) || null,
+    supportsChat: true,
+    supportsEmbed: true,
+    source: "MCP_LLM_BASE_URL",
+  };
+}
+
+/**
+ * Build the provider matrix from environment variables.
+ * Returns a deduplicated list of provider records.
+ * @param {Record<string,string|undefined>} env
+ * @returns {Array<{id, name, baseUrl, apiKey, chatModel, embedModel, supportsChat, supportsEmbed, source}>}
+ */
+export function buildProviderMatrix(env) {
+  const out = [];
+  const seen = new Set();
+
+  const push = (p) => {
+    if (!p || !p.baseUrl && !p.apiKey) return;
+    if (seen.has(p.id)) return;
+    seen.add(p.id);
+    out.push(p);
+  };
+
+  // 1. Primary + numbered slots
+  push(readProviderSlot(env, "PRIMARY"));
+  for (let i = 2; i <= 10; i++) {
+    push(readProviderSlot(env, `CHAIN${i}`));
+  }
+
+  // 2. Named providers (Groq, Cerebras, Mistral, OpenRouter, OpenAI, Ollama)
+  for (const id of ["groq", "cerebras", "mistral", "openrouter", "openai", "ollama", "anthropic", "gemini", "cohere", "voyage", "cloudflare"]) {
+    push(readNamedProvider(env, id));
+  }
+
+  // 3. Catch-all: existing 9router-like config from MCP_LLM_BASE_URL etc.
+  push(read9routerLike(env));
+
+  return out;
+}
+
+/**
+ * Shape a probe result into the canonical record used by formatting helpers.
+ */
+export function shapeProbe({ name, kind, ok, latencyMs = null, status = null, sample = null, error = null, dim = null }) {
+  return { name, kind, ok, latencyMs, status, sample, error, dim };
+}
+
+// ---- formatting ----
+
+function fmtLatency(ms) {
+  if (ms == null) return "—";
+  if (ms < 1000) return `${ms}ms`;
+  return `${(ms / 1000).toFixed(2)}s`;
+}
+
+export function formatText(results) {
+  const lines = [];
+  lines.push("Dev MCP Suite — provider smoke");
+  lines.push("==============================");
+  // group by provider
+  const byName = new Map();
+  for (const r of results) {
+    if (!byName.has(r.name)) byName.set(r.name, []);
+    byName.get(r.name).push(r);
+  }
+  for (const [name, rs] of byName) {
+    lines.push(`\n[${name}]`);
+    for (const r of rs) {
+      const mark = r.ok ? "✓" : "✗";
+      const lat = r.ok ? fmtLatency(r.latencyMs) : "";
+      const detail = r.ok
+        ? `${r.status || ""} ${lat}${r.sample ? `  "${String(r.sample).slice(0, 40)}"` : ""}${r.dim ? `  dim=${r.dim}` : ""}`.trim()
+        : `${r.status || "—"}  ${r.error || "unknown error"}`;
+      lines.push(`  ${mark} ${r.kind.padEnd(10)} ${detail}`);
+    }
+  }
+  lines.push("");
+  return lines.join("\n");
+}
+
+export function formatJson(results) {
+  return JSON.stringify(results, null, 2);
+}
+
+export function formatMarkdown(results) {
+  const lines = [];
+  lines.push("# Provider smoke matrix");
+  lines.push("");
+  lines.push(`_Generated ${new Date().toISOString()}_`);
+  lines.push("");
+  lines.push("| Provider | Kind | Status | Latency | HTTP | Sample / dim | Error |");
+  lines.push("|---|---|---|---|---|---|---|");
+  for (const r of results) {
+    const okMark = r.ok ? "✓" : "✗";
+    const sample = r.ok ? (r.sample ? `\`${String(r.sample).slice(0, 30)}\`` : (r.dim ? `dim=${r.dim}` : "—")) : "—";
+    const err = r.ok ? "" : (r.error || "").replace(/\|/g, "\\|");
+    lines.push(`| ${r.name} | ${r.kind} | ${okMark} | ${fmtLatency(r.latencyMs)} | ${r.status || "—"} | ${sample} | ${err} |`);
+  }
+  lines.push("");
+  return lines.join("\n");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-dev-mcp-suite",
-  "version": "1.3.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",
@@ -34,7 +34,8 @@
     "checkpoint-mcp": "bin/checkpoint.mjs",
     "context-pack-mcp": "bin/context-pack.mjs",
     "stats": "bin/stats.mjs",
-    "prune": "bin/prune.mjs"
+    "prune": "bin/prune.mjs",
+    "provider-smoke": "bin/provider-smoke.mjs"
   },
   "scripts": {
     "test": "node run-tests.mjs",

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/embedding.js

@@ -1,47 +1,96 @@
 /**
- * Embedding helper for any OpenAI-compatible /v1/embeddings endpoint.
- * Degrades gracefully: returns null on any failure so callers fall back
+ * Embedding helper for any OpenAI-compatible /v1/embeddings endpoint,
+ * with first-class support for Cloudflare Workers AI (REST-only, non-OpenAI).
+ *
+ * Degrades gracefully: returns null/[] on any failure so callers fall back
  * to keyword search. Never throws.
+ *
+ * Endpoint formats:
+ *  - OpenAI-compatible:  POST {base}/v1/embeddings   body: {model, input:[...]}
+ *                        response: {data:[{embedding:[...], index}]}
+ *  - Cloudflare Workers: POST {base}/{model}          body: {text:[...]}
+ *                        response: {result:{data:[[...]], shape:[n,dim]}}
+ *
+ * Cloudflare is auto-detected by URL pattern (contains "api.cloudflare.com/client/v4/accounts").
+ * To use it: set MCP_EMBED_BASE_URL=https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/ai/run/
+ * and MCP_EMBED_MODEL=@cf/baai/bge-base-en-v1.5
  */
 import http from "http";
 import https from "https";
 import { URL } from "url";
 import { deterministicEnabled } from "./env.js";
 
-const BASE = process.env.MCP_EMBED_BASE_URL || process.env.MCP_LLM_BASE_URL || process.env.LLM_BASE_URL || process.env.EMBED_URL || process.env.NINEROUTER_URL || "http://localhost:20128";
-const KEY = process.env.MCP_EMBED_API_KEY || process.env.MCP_LLM_API_KEY || process.env.LLM_API_KEY || process.env.EMBED_KEY || process.env.NINEROUTER_KEY || "";
-const MODEL = process.env.MCP_EMBED_MODEL || process.env.EMBED_MODEL || "bm/baai/bge-m3";
-const TIMEOUT_MS = Number(process.env.EMBED_TIMEOUT_MS || 15000);
+/** Read env at runtime (not module-load time) so tests can override and config is dynamic). */
+function readEnv() {
+  return {
+    base: process.env.MCP_EMBED_BASE_URL || process.env.MCP_LLM_BASE_URL || process.env.LLM_BASE_URL || process.env.EMBED_URL || process.env.NINEROUTER_URL || "http://localhost:20128",
+    key: process.env.MCP_EMBED_API_KEY || process.env.MCP_LLM_API_KEY || process.env.LLM_API_KEY || process.env.EMBED_KEY || process.env.NINEROUTER_KEY || "",
+    model: process.env.MCP_EMBED_MODEL || process.env.EMBED_MODEL || "bm/baai/bge-m3",
+    timeoutMs: Number(process.env.EMBED_TIMEOUT_MS || 15000),
+  };
+}
+
+/**
+ * Resolve what retrieval mode memory_recall will use, given current env.
+ * Returns one of: "deterministic" | "semantic" | "keyword".
+ * Independent of MCP_RERANK_ENABLED (rerank layers on top of either).
+ */
+export function recallMode() {
+  if (deterministicEnabled()) return "deterministic";
+  const { key } = readEnv();
+  return key ? "semantic" : "keyword";
+}
 
 export function embeddingConfig() {
-  return { base: BASE, model: MODEL, enabled: Boolean(KEY) && !deterministicEnabled(), deterministic: deterministicEnabled() };
+  const { base, key, model } = readEnv();
+  return {
+    base,
+    model,
+    enabled: Boolean(key) && !deterministicEnabled(),
+    deterministic: deterministicEnabled(),
+    endpoint: isCloudflareURL(base) ? "cloudflare" : "openai-compatible",
+    mode: recallMode(),
+  };
 }
 
-function postJson(urlStr, payload) {
+/** Detect Cloudflare Workers AI by URL pattern. */
+export function isCloudflareURL(urlStr) {
+  return typeof urlStr === "string" && urlStr.includes("api.cloudflare.com/client/v4/accounts");
+}
+
+/**
+ * POST a JSON body to an absolute URL with Bearer auth. Returns:
+ *   { status: 200, body: <parsed JSON> } on success
+ *   { status: <code>, body: <raw text> } on non-200
+ *   null on network/timeout/parse error
+ * Caller is responsible for building the full URL (we don't append /v1/embeddings etc).
+ */
+function httpPostJson(urlStr, payload) {
   return new Promise((resolve) => {
     let u;
-    try { u = new URL("/v1/embeddings", urlStr); } catch { return resolve(null); }
+    try { u = new URL(urlStr); } catch { return resolve(null); }
     const data = Buffer.from(JSON.stringify(payload));
+    const { key, timeoutMs } = readEnv();
     const lib = u.protocol === "https:" ? https : http;
     const req = lib.request(
       {
         hostname: u.hostname,
         port: u.port || (u.protocol === "https:" ? 443 : 80),
-        path: u.pathname,
+        path: u.pathname + (u.search || ""),
         method: "POST",
         headers: {
           "Content-Type": "application/json",
           "Content-Length": data.length,
-          Authorization: `Bearer ${KEY}`,
+          ...(key ? { Authorization: `Bearer ${key}` } : {}),
         },
-        timeout: TIMEOUT_MS,
+        timeout: timeoutMs,
       },
       (res) => {
         let body = "";
         res.on("data", (c) => (body += c));
         res.on("end", () => {
-          if (res.statusCode !== 200) return resolve(null);
-          try { resolve(JSON.parse(body)); } catch { resolve(null); }
+          if (res.statusCode !== 200) return resolve({ status: res.statusCode, body });
+          try { resolve({ status: 200, body: JSON.parse(body) }); } catch { resolve({ status: res.statusCode, body }); }
         });
       }
     );
@@ -52,30 +101,59 @@ function postJson(urlStr, payload) {
   });
 }
 
-/** Returns array of vectors aligned to inputs, or null if unavailable. */
+async function embedOpenAI(inputs) {
+  const { base, key, model } = readEnv();
+  if (!key) return [];
+  try {
+    const res = await httpPostJson(`${base.replace(/\/$/, "")}/v1/embeddings`, { model, input: inputs });
+    if (!res || res.status !== 200 || !res.body || !Array.isArray(res.body.data)) return [];
+    const json = res.body;
+    const sorted = [...json.data].sort((a, b) => (a.index ?? 0) - (b.index ?? 0));
+    return sorted.map((d) => d.embedding).filter(Boolean);
+  } catch { return []; }
+}
+
+async function embedCloudflare(inputs) {
+  const { base: rawBase, key, model } = readEnv();
+  if (!key) return [];
+  // Cloudflare: model is in URL path; do NOT URL-encode ("@" and "/" must stay literal).
+  const base = rawBase.replace(/\/$/, "");
+  const url = `${base}/${model}`;
+  try {
+    const res = await httpPostJson(url, { text: inputs });
+    if (!res || res.status !== 200 || !res.body || !res.body.result) return [];
+    const data = res.body.result.data;
+    if (!Array.isArray(data)) return [];
+    return data.filter((v) => Array.isArray(v));
+  } catch { return []; }
+}
+
+/**
+ * Embed an array of strings (or a single string) and return an array of
+ * numeric vectors. Returns [] when no API key is configured, deterministic
+ * mode is on, or the endpoint fails.
+ */
 export async function embed(inputs) {
-  if (!KEY || deterministicEnabled()) return null;
+  if (deterministicEnabled()) return [];
+  const { base, key } = readEnv();
+  if (!key) return [];
   const arr = Array.isArray(inputs) ? inputs : [inputs];
-  if (arr.length === 0) return [];
-  const json = await postJson(BASE, { model: MODEL, input: arr });
-  if (!json || !Array.isArray(json.data)) return null;
-  try {
-    const sorted = json.data.slice().sort((a, b) => (a.index ?? 0) - (b.index ?? 0));
-    const vecs = sorted.map((d) => d.embedding);
-    if (vecs.some((v) => !Array.isArray(v) || v.length === 0)) return null;
-    return vecs;
-  } catch { return null; }
+  if (isCloudflareURL(base)) return await embedCloudflare(arr);
+  return await embedOpenAI(arr);
 }
 
 export async function embedOne(text) {
   const v = await embed([text]);
-  return v ? v[0] : null;
+  return v[0] || null;
 }
 
 export function cosine(a, b) {
-  if (!a || !b || a.length !== b.length) return 0;
+  if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length) return 0;
   let dot = 0, na = 0, nb = 0;
-  for (let i = 0; i < a.length; i++) { dot += a[i] * b[i]; na += a[i] * a[i]; nb += b[i] * b[i]; }
-  if (na === 0 || nb === 0) return 0;
-  return dot / (Math.sqrt(na) * Math.sqrt(nb));
+  for (let i = 0; i < a.length; i++) {
+    const x = a[i], y = b[i];
+    dot += x * y; na += x * x; nb += y * y;
+  }
+  const denom = Math.sqrt(na) * Math.sqrt(nb);
+  return denom === 0 ? 0 : dot / denom;
 }

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