codex-dev-mcp-suite 1.3.0 → 1.4.0

package/.env.example

@@ -40,6 +40,25 @@ MCP_RERANK_MODEL=llama3.1:8b
 RERANK_TIMEOUT_MS=30000
 RERANK_ENABLED=1
 
+
+# === Cloudflare Workers AI (REST-only, NOT OpenAI-compatible) ===
+# Free tier: 10,000 neurons/day. No laptop resource usage.
+# To get started: dash.cloudflare.com → Workers & Pages → Create Worker → Workers AI → enable
+# Account ID: from dashboard sidebar. API Token: My Profile → API Tokens → "Edit Cloudflare Workers".
+# Note: base URL has trailing slash; model name goes in URL path, not body.
+# Set CLOUDFLARE_EMBED_MODEL (e.g. @cf/baai/bge-base-en-v1.5) to enable semantic recall
+# via Cloudflare instead of 9router/OpenAI/etc.
+# MCP_EMBED_BASE_URL=https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/ai/run/
+# MCP_EMBED_API_KEY=<cf-token>
+# MCP_EMBED_MODEL=@cf/baai/bge-base-en-v1.5
+
+# === Google Gemini (OpenAI-compatible, generous free tier) ===
+# Get key: https://aistudio.google.com/app/apikey
+# Free tier: 60 req/min, 1500/day for text-embedding-004
+# GEMINI_BASE_URL=https://generativelanguage.googleapis.com/v1beta/openai
+# GEMINI_API_KEY=<gemini-key>
+# GEMINI_MODEL=text-embedding-004
+
 # Storage locations (defaults shown; override if you want)
 # MEMORY_VAULT_DIR=~/.codex/memories/vault
 # JOURNAL_DIR=~/.codex/memories/journal

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # Changelog
 
+## 1.4.0 - 2026-06-17
+
+### Added
+- **`provider-smoke` CLI** (`bin/provider-smoke.mjs`): probe every configured LLM provider (chat + embeddings) and print a matrix of latency / status / sample. Useful after adding a new API key or comparing providers.
+  - Usage: `npx -y -p codex-dev-mcp-suite provider-smoke` (or globally `provider-smoke`)
+  - Flags: `--json`, `--markdown`, `--save-md <path>`, `--chat-only`, `--embed-only`, `--env-file <path>`, `--only a,b,c`, `--timeout <ms>`, `--help`, `--version`
+  - Auto-detects providers from `MCP_PROVIDER_*` slots + named env (`GROQ_*`, `CEREBRAS_*`, `MISTRAL_*`, `OPENROUTER_*`, `OPENAI_*`, `OLLAMA_*`, `ANTHROPIC_*`, `GEMINI_*`, `COHERE_*`, `VOYAGE_*`, `CLOUDFLARE_*`) + `MCP_LLM_BASE_URL` / `NINEROUTER_URL` fallback.
+  - Pure-function library at `lib/provider-smoke.js` (18 offline tests).
+  - `KNOWN_PROVIDERS` registry covers 11 providers with `supportsChat` / `supportsEmbed` flags + `endpoint: "openai-compatible" | "cloudflare"`.
+  - Cloudflare embed-only models (`@cf/baai/*`, `@cf/google/embedding*`, etc.) are detected and the chat probe is skipped with a clear annotation.
+- **Cloudflare Workers AI support** for embeddings: drop-in alternative when 9router/OpenAI are unavailable. Set `MCP_EMBED_BASE_URL=https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/ai/run/`, `MCP_EMBED_API_KEY=<token>`, `MCP_EMBED_MODEL=@cf/baai/bge-base-en-v1.5`.
+  - Cloudflare's REST API (non-OpenAI-compatible, model-in-path) is auto-detected by URL pattern and dispatched to a separate code path in `project-memory/embedding.js`.
+  - New `isCloudflareURL()` + `httpPostJson()` helpers; `embedCloudflare()` handles `{text: [...]}` body and `{result: {data: [[...]]}}` response.
+  - `embeddingConfig().mode` and `recallMode()` helpers expose what retrieval mode is active (`semantic` / `keyword` / `deterministic`).
+- **`memory_recall` mode arg** (default `"auto"`): explicit control over fallback behavior. `mode: "semantic"` requires embedding (returns `isError: true` if unavailable), `mode: "keyword"` skips embedding entirely.
+- **Recall output annotation** now shows `[semantic+rerank]` / `[keyword+rerank]` when LLM rerank is active, making the active mode fully transparent.
+- **Top-level test runner hook** (added in 1.3.0, expanded in 1.4.0): `tests/*.test.mjs` are auto-picked-up by `node run-tests.mjs`.
+
+### Tests
+- 85 tests pass (was 60 in v1.3.0): 26 project-memory + 6 checkpoint + 6 context-pack + 11 devjournal + 18 provider-smoke + 9 prune + 9 stats.
+- New fallback tests: `mode=keyword` skips semantic, `mode=semantic` without embed key returns isError, default mode=auto, no `+rerank` suffix when rerank disabled.
+
+### Docs
+- `docs/providers.md` rewritten: 11-provider matrix, Cloudflare setup caveat, Ollama resource cost, "no API key" graceful degradation notes.
+- `README.md` updated: "Memory Recall Modes" section, Cloudflare + Gemini setup examples, 4-mode annotation examples.
+- `.env.example` updated: copy-pasteable config blocks for Cloudflare Workers AI and Google Gemini.
+
+
+
 ## 1.3.0 - 2026-06-17
 
 ### Added
@@ -8,6 +37,14 @@
   - Flags: `--root <path>`, `--json`, `--top N`, `--help`, `--version`
   - Pure-function library at `lib/stats.js` (no MCP / no stdio); tested offline.
 - New top-level test runner hook: `tests/*.test.mjs` are auto-picked-up by `node run-tests.mjs`.
+- New `provider-smoke` CLI: probe every configured LLM provider (chat + embeddings) and print a matrix of latency / status / sample. Useful after adding a new API key or to compare providers.
+  - Usage: `npx -y -p codex-dev-mcp-suite provider-smoke`
+  - Flags: `--json`, `--markdown`, `--save-md <path>`, `--chat-only`, `--embed-only`, `--env-file <path>`, `--timeout <ms>`
+  - Detects providers from `MCP_PROVIDER_*` slots + named env (`GROQ_*`, `CEREBRAS_*`, `MISTRAL_*`, `OPENROUTER_*`, `OPENAI_*`, `OLLAMA_*`, `ANTHROPIC_*`, `GEMINI_*`, `COHERE_*`) + `MCP_LLM_BASE_URL` / `NINEROUTER_URL` fallback.
+  - Pure-function library at `lib/provider-smoke.js`; tested offline.
+- New docs page `docs/providers.md` — auto-generated smoke matrix from latest run.
+
+
 
 
 
@@ -21,6 +58,12 @@
 - New MCP tool `memory_stats` on the project-memory server: returns the same summary as the `stats` CLI. Useful for in-session introspection from an MCP client.
   - Args: `root?`, `top?` (default 10), `json?` (default false).
 
+
+
+### Added
+- **Cloudflare Workers AI support** for embeddings and chat: drop-in alternative when 9router/OpenAI are unavailable. Set `MCP_EMBED_BASE_URL=https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/ai/run/`, `MCP_EMBED_API_KEY=<token>`, `MCP_EMBED_MODEL=@cf/baai/bge-base-en-v1.5`. Cloudflare's REST API (non-OpenAI-compatible) is auto-detected by URL pattern and dispatched to a separate code path in `project-memory/embedding.js`. Includes `isCloudflareURL()` detection + `endpoint: "cloudflare"` field in provider matrix.
+- `provider-smoke` CLI: probe Cloudflare alongside OpenAI-compatible providers. Cloudflare chat returns 400 for embed-only models (expected — they don't support chat).
+
 ## 1.2.0 - 2026-06-15
 
 ### Added

package/README.md

@@ -168,6 +168,30 @@ idea — use the npm bin commands (`project-memory-mcp`, `devjournal-mcp`,
 `checkpoint-mcp`, `context-pack-mcp`) or `node /abs/path/<server>/server.js`,
 with optional `env`.
 
+## Memory Recall Modes
+
+`memory_recall` supports a `mode` arg (default `"auto"`) that controls fallback behavior:
+
+| Mode | Behavior |
+|---|---|
+| `auto` (default) | Smart: try semantic → keyword → LLM rerank |
+| `semantic` | Require embedding. Returns `isError: true` if no embed key configured |
+| `keyword` | Skip embedding entirely (faster, pure keyword scoring) |
+
+The recall output annotates the active mode for transparency:
+
+```
+Recall for "how do users sign in" in my-project [semantic+rerank]:
+### JWT login flow (id:..., sim:0.603, ...)
+```
+
+The `+rerank` suffix is appended when LLM rerank is active (MCP_RERANK_ENABLED + key).
+Without embeddings, recall falls back to `[keyword]` or `[keyword+rerank]`.
+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.
+
 ## Daily workflow
 
 - Session start: `pack_overview` + `journal_resume` + `memory_recall "<topic>"`
@@ -230,6 +254,50 @@ directly from your own scripts. The default storage root is
 `JOURNAL_DIR` / `CHECKPOINT_DIR` env vars) override it.
 
 
+## Provider Smoke CLI
+
+Verify every configured LLM provider (chat + embeddings) with one command.
+Useful after adding a new API key, or when comparing provider latency.
+
+```bash
+npx -y -p codex-dev-mcp-suite provider-smoke                          # uses process.env
+npx -y -p codex-dev-mcp-suite provider-smoke --env-file ~/secrets.env  # separate secrets file
+npx -y -p codex-dev-mcp-suite provider-smoke --markdown --save-md docs/providers.md
+```
+
+Auto-detects providers from these env vars (highest precedence first):
+
+- **Numbered slots**: `MCP_PROVIDER_PRIMARY` / `_CHAIN2` / `_CHAIN3` / ...
+- **Named env**: `GROQ_*`, `CEREBRAS_*`, `MISTRAL_*`, `OPENROUTER_*`, `OPENAI_*`, `GEMINI_*`, `COHERE_*`, `VOYAGE_*`, `OLLAMA_*`, `ANTHROPIC_*`
+- **Catch-all**: `MCP_LLM_BASE_URL` / `MCP_RERANK_BASE_URL` / `MCP_EMBED_BASE_URL` / `NINEROUTER_URL` / `LLM_BASE_URL` (any OpenAI-compatible endpoint)
+
+For each detected provider, runs:
+- **chat probe** (`/v1/chat/completions`) — if the provider supports it
+- **embed probe** (`/v1/embeddings`) — if the provider supports it
+
+**Inference-only providers** (Groq, Cerebras, Anthropic) skip the embed probe automatically.
+**Non-OpenAI-compatible providers** (Cloudflare Workers AI) require a custom code path in
+`project-memory/embedding.js` — see [docs/providers.md](docs/providers.md).
+
+**No provider assumption is baked in**: the tool only probes what's in your env. Zero-config users
+get an empty matrix; pass `--env-file` to point at a secrets file.
+
+Chat-only providers (Groq, Cerebras) skip the embeddings probe automatically
+— they don't expose `/v1/embeddings`. Embedding-capable providers (Mistral,
+OpenRouter, OpenAI, Ollama, Gemini, Cohere) run both probes.
+
+Example output (Groq + Cerebras, both configured):
+
+```
+[groq]
+  ✓ chat       200 310ms  "OK"
+
+[cerebras]
+  ✓ chat       200 476ms
+```
+
+See [`docs/providers.md`](docs/providers.md) for a saved smoke matrix.
+
 ## Prune CLI
 
 Remove temp project slugs (prefix `tmp.`) from vault / journal / checkpoints.

package/bin/provider-smoke.mjs

@@ -0,0 +1,278 @@
+#!/usr/bin/env node
+/**
+ * bin/provider-smoke.mjs — Dev MCP Suite provider smoke test.
+ *
+ * Probes every provider that can be derived from the current env:
+ *   - MCP_LLM_BASE_URL / NINEROUTER_URL / LLM_BASE_URL (9router-like)
+ *   - MCP_PROVIDER_PRIMARY / _CHAIN2 / _CHAIN3 / ... (numbered slots)
+ *   - Named: GROQ_*, CEREBRAS_*, MISTRAL_*, OPENROUTER_*, OPENAI_*, OLLAMA_*, ...
+ *
+ * For each provider, runs:
+ *   - chat probe (/v1/chat/completions, short prompt)         if supportsChat
+ *   - embed probe (/v1/embeddings, single string)             if supportsEmbed
+ *
+ * Output: human text by default; --json for machines; --markdown for docs.
+ *
+ * Env override:
+ *   --env-file <path>   Source env from this file before probing (e.g. /tmp/secrets.env)
+ *
+ * Exit code:
+ *   0 = all probes ok
+ *   1 = at least one probe failed
+ */
+import fs from "fs";
+import os from "os";
+import path from "path";
+import { fileURLToPath } from "url";
+import { buildProviderMatrix, shapeProbe, formatText, formatJson, formatMarkdown, isCloudflareURL } from "../lib/provider-smoke.js";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+function pkgVersion() {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(__dirname, "..", "package.json"), "utf8")).version || "unknown";
+  } catch { return "unknown"; }
+}
+
+
+/** Strip a trailing /v1 (only the literal segment, not /openai/v1) so we can re-append /v1/<endpoint>. */
+function stripV1(baseUrl) {
+  return String(baseUrl || "").replace(/\/v1\/?$/, "").replace(/\/$/, "");
+}
+
+function parseArgs(argv) {
+  const opts = {
+    help: false, version: false,
+    json: false, markdown: false,
+    saveMd: null, envFile: null,
+    chatOnly: false, embedOnly: false,
+    timeoutMs: 15000,
+    only: null,
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "-h" || a === "--help") opts.help = true;
+    else if (a === "-v" || a === "--version") opts.version = true;
+    else if (a === "--json") opts.json = true;
+    else if (a === "--markdown") opts.markdown = true;
+    else if (a === "--save-md") opts.saveMd = argv[++i];
+    else if (a === "--env-file") opts.envFile = argv[++i];
+    else if (a === "--chat-only") opts.chatOnly = true;
+    else if (a === "--embed-only") opts.embedOnly = true;
+    else if (a === "--timeout") opts.timeoutMs = parseInt(argv[++i], 10) || 15000;
+    else if (a === "--only") opts.only = (argv[++i] || "").split(",").map(s => s.trim()).filter(Boolean);
+    else { process.stderr.write(`provider-smoke: unknown flag: ${a}\n`); process.exit(2); }
+  }
+  return opts;
+}
+
+function printHelp() {
+  const out = [
+    `provider-smoke (Dev MCP Suite) v${pkgVersion()}`,
+    "",
+    "Probe every configured LLM provider (chat + embeddings) and print a matrix.",
+    "",
+    "Usage:",
+    "  provider-smoke [--json] [--markdown] [--save-md <path>]",
+    "                 [--chat-only | --embed-only] [--env-file <path>]",
+    "  provider-smoke --help | --version",
+    "",
+    "Options:",
+    "  --json            Machine-readable JSON output",
+    "  --markdown        Markdown table (for docs/)",
+    "  --save-md <path>  Write markdown report to this file",
+    "  --env-file <path> Source env vars from this file before probing",
+    "                    (KEY=value lines, one per line)",
+    "  --chat-only       Only probe /v1/chat/completions",
+    "  --embed-only      Only probe /v1/embeddings",
+    "  --timeout <ms>    Per-probe timeout (default 15000)",
+    "  --only a,b,c      Only probe these provider ids (comma-separated); others ignored",
+    "",
+    "Detected providers (precedence):",
+    "  MCP_PROVIDER_PRIMARY / _CHAIN2 / _CHAIN3 / ...   (numbered slots)",
+    "  GROQ_*, CEREBRAS_*, MISTRAL_*, OPENROUTER_*,     (named)",
+    "  OPENAI_*, OLLAMA_*, ANTHROPIC_*, GEMINI_*, COHERE_*",
+    "  MCP_LLM_BASE_URL / NINEROUTER_URL / LLM_BASE_URL  (9router / agentrouter)",
+    "",
+    "Examples:",
+    "  provider-smoke",
+    "  provider-smoke --env-file /tmp/codex-dev-smoke.env",
+    "  provider-smoke --json | jq '.[] | select(.ok == false)'",
+    "  provider-smoke --markdown --save-md docs/providers.md",
+  ];
+  process.stdout.write(out.join("\n") + "\n");
+}
+
+function loadEnvFile(file) {
+  if (!file) return {};
+  const text = fs.readFileSync(file, "utf8");
+  const env = {};
+  for (const raw of text.split(/\r?\n/)) {
+    const line = raw.trim();
+    if (!line || line.startsWith("#")) continue;
+    const m = line.match(/^([A-Z_][A-Z0-9_]*)=(.*)$/);
+    if (m) env[m[1]] = m[2];
+  }
+  return env;
+}
+
+function buildHeaders(provider) {
+  const h = { "Content-Type": "application/json" };
+  if (provider.apiKey) h["Authorization"] = `Bearer ${provider.apiKey}`;
+  return h;
+}
+
+
+const CF_EMBED_ONLY_PREFIXES = ["@cf/baai/", "@cf/google/embedding", "@cf/baai/sentence-"];
+
+function isEmbedOnlyModel(model) {
+  if (!model) return false;
+  return CF_EMBED_ONLY_PREFIXES.some((p) => model.startsWith(p));
+}
+
+async function probeCloudflare(provider, timeoutMs, kind) {
+  // Skip chat probe for known embed-only Cloudflare model prefixes (annotate, not error).
+  if (kind === "chat" && isEmbedOnlyModel(provider.chatModel || provider.embedModel)) {
+    return shapeProbe({ name: provider.id, kind: "chat", ok: false, error: "embed-only model (chat not supported)" });
+  }
+  // Cloudflare Workers AI REST: POST {baseUrl}/{model}, body shape depends on kind.
+  // Cloudflare model names contain "/" (e.g. "@cf/baai/bge-base-en-v1.5"); do NOT URL-encode.
+  const url = `${provider.baseUrl.replace(/\/$/, "")}/${provider.chatModel || provider.embedModel}`;
+  let body;
+  if (kind === "chat") {
+    body = JSON.stringify({
+      messages: [{ role: "user", content: "Say the single word: OK" }],
+      max_tokens: 8,
+    });
+  } else {
+    body = JSON.stringify({ text: ["ping"] });
+  }
+  const t0 = Date.now();
+  try {
+    const res = await fetch(url, { method: "POST", headers: buildHeaders(provider), body, signal: AbortSignal.timeout(timeoutMs) });
+    const text = await res.text();
+    const latencyMs = Date.now() - t0;
+    if (res.status !== 200) {
+      return shapeProbe({ name: provider.id, kind, ok: false, status: res.status, latencyMs, error: text.slice(0, 200) });
+    }
+    let sample = null, dim = null;
+    try {
+      const j = JSON.parse(text);
+      if (kind === "embed") {
+        const data = j?.result?.data;
+        if (Array.isArray(data) && Array.isArray(data[0])) dim = data[0].length;
+      } else {
+        sample = j?.result?.response ?? null;
+      }
+    } catch { /* ignore */ }
+    return shapeProbe({ name: provider.id, kind, ok: true, status: res.status, latencyMs, sample, dim });
+  } catch (e) {
+    return shapeProbe({ name: provider.id, kind, ok: false, latencyMs: Date.now() - t0, error: String(e && e.message || e) });
+  }
+}
+
+async function probeChat(provider, timeoutMs) {
+  if (!provider.baseUrl || !provider.chatModel) {
+    return shapeProbe({ name: provider.id, kind: "chat", ok: false, error: "missing baseUrl or chatModel" });
+  }
+  const endpoint = provider.endpoint || (isCloudflareURL(provider.baseUrl) ? "cloudflare" : "openai-compatible");
+  if (endpoint === "cloudflare") return probeCloudflare(provider, timeoutMs, "chat");
+  const url = `${stripV1(provider.baseUrl)}/v1/chat/completions`;
+  const body = JSON.stringify({
+    model: provider.chatModel,
+    messages: [{ role: "user", content: "Say the single word: OK" }],
+    max_tokens: 8,
+    temperature: 0,
+  });
+  const t0 = Date.now();
+  try {
+    const res = await fetch(url, { method: "POST", headers: buildHeaders(provider), body, signal: AbortSignal.timeout(timeoutMs) });
+    const text = await res.text();
+    const latencyMs = Date.now() - t0;
+    if (res.status !== 200) {
+      return shapeProbe({ name: provider.id, kind: "chat", ok: false, status: res.status, latencyMs, error: text.slice(0, 200) });
+    }
+    let sample = null;
+    try {
+      const j = JSON.parse(text);
+      sample = j?.choices?.[0]?.message?.content ?? null;
+    } catch { /* ignore */ }
+    return shapeProbe({ name: provider.id, kind: "chat", ok: true, status: res.status, latencyMs, sample });
+  } catch (e) {
+    return shapeProbe({ name: provider.id, kind: "chat", ok: false, latencyMs: Date.now() - t0, error: String(e && e.message || e) });
+  }
+}
+
+async function probeEmbed(provider, timeoutMs) {
+  if (!provider.supportsEmbed) {
+    return shapeProbe({ name: provider.id, kind: "embed", ok: false, error: "provider has no /v1/embeddings endpoint" });
+  }
+  if (!provider.baseUrl || !provider.embedModel) {
+    return shapeProbe({ name: provider.id, kind: "embed", ok: false, error: "missing baseUrl or embedModel" });
+  }
+  if (provider.endpoint === "cloudflare" || isCloudflareURL(provider.baseUrl)) return probeCloudflare(provider, timeoutMs, "embed");
+  const url = `${stripV1(provider.baseUrl)}/v1/embeddings`;
+  const body = JSON.stringify({ model: provider.embedModel, input: "ping" });
+  const t0 = Date.now();
+  try {
+    const res = await fetch(url, { method: "POST", headers: buildHeaders(provider), body, signal: AbortSignal.timeout(timeoutMs) });
+    const text = await res.text();
+    const latencyMs = Date.now() - t0;
+    if (res.status !== 200) {
+      return shapeProbe({ name: provider.id, kind: "embed", ok: false, status: res.status, latencyMs, error: text.slice(0, 200) });
+    }
+    let dim = null;
+    try {
+      const j = JSON.parse(text);
+      dim = Array.isArray(j?.data?.[0]?.embedding) ? j.data[0].embedding.length : null;
+    } catch { /* ignore */ }
+    return shapeProbe({ name: provider.id, kind: "embed", ok: true, status: res.status, latencyMs, dim });
+  } catch (e) {
+    return shapeProbe({ name: provider.id, kind: "embed", ok: false, latencyMs: Date.now() - t0, error: String(e && e.message || e) });
+  }
+}
+
+const opts = parseArgs(process.argv.slice(2));
+if (opts.version) { process.stdout.write(`${pkgVersion()}\n`); process.exit(0); }
+if (opts.help) { printHelp(); process.exit(0); }
+
+// Merge env: process.env + (optional) env file
+const fileEnv = loadEnvFile(opts.envFile);
+const env = { ...process.env, ...fileEnv };
+
+let matrix = buildProviderMatrix(env);
+if (opts.only && opts.only.length) {
+  matrix = matrix.filter(p => opts.only.includes(p.id));
+}
+if (matrix.length === 0) {
+  const hint = opts.only && opts.only.length ? " (--only filter: " + opts.only.join(",") + ")" : "";
+  process.stderr.write("No providers detected. Set MCP_PROVIDER_PRIMARY / GROQ_API_KEY / NINEROUTER_URL etc., or pass --env-file." + hint + "\n");
+  process.exit(2);
+}
+
+process.stderr.write(`Probing ${matrix.length} provider${matrix.length === 1 ? "" : "s"}...\n`);
+const results = [];
+for (const p of matrix) {
+  if (!opts.embedOnly && p.supportsChat) {
+    results.push(await probeChat(p, opts.timeoutMs));
+  }
+  if (!opts.chatOnly && p.supportsEmbed) {
+    results.push(await probeEmbed(p, opts.timeoutMs));
+  }
+}
+
+let out;
+if (opts.markdown) out = formatMarkdown(results);
+else if (opts.json) out = formatJson(results);
+else out = formatText(results);
+
+process.stdout.write(out + "\n");
+
+if (opts.saveMd) {
+  fs.mkdirSync(path.dirname(opts.saveMd), { recursive: true });
+  fs.writeFileSync(opts.saveMd, formatMarkdown(results));
+  process.stderr.write(`Markdown saved to ${opts.saveMd}\n`);
+}
+
+const failed = results.filter((r) => !r.ok).length;
+process.exit(failed === 0 ? 0 : 1);

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.4.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/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/server.js

@@ -163,7 +163,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 +171,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"],
           },
@@ -316,7 +317,7 @@ 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);
@@ -333,10 +334,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";
@@ -395,7 +403,12 @@ 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 list({ dir, limit: lim = 20 }) {