codex-dev-mcp-suite 1.0.0 → 1.2.0

package/.env.example

@@ -1,19 +1,42 @@
 # All network features are OPTIONAL. Without them, recall falls back to keyword
 # search (fully offline). Any OpenAI-compatible endpoint works: OpenAI, Ollama,
-# LM Studio, OpenRouter, vLLM, LiteLLM, 9router, etc.
+# LM Studio, Groq, Cerebras, OpenRouter, vLLM, LiteLLM, 9router, etc.
+
+# Hard no-network mode. When true, disables embeddings/rerank even if keys exist.
+# Accepted true values: true, 1, yes, on.
+# MCP_DETERMINISTIC_FALLBACK=true
+
+# Optional provider chain for chat/rerank. Configure only primary, or add
+# numbered fallbacks. Groq/Cerebras/OpenRouter are recommended examples; any
+# OpenAI-compatible base URL + API key + model ID works.
+# MCP_PROVIDER_PRIMARY=groq
+# MCP_PROVIDER_PRIMARY_BASE_URL=https://api.groq.com/openai/v1
+# MCP_PROVIDER_PRIMARY_API_KEY=<groq-key>
+# MCP_PROVIDER_PRIMARY_MODEL=llama-3.3-70b-versatile
+# MCP_PROVIDER_CHAIN2=cerebras
+# MCP_PROVIDER_CHAIN2_BASE_URL=https://api.cerebras.ai/v1
+# MCP_PROVIDER_CHAIN2_API_KEY=<cerebras-key>
+# MCP_PROVIDER_CHAIN2_MODEL=llama-3.3-70b
+# MCP_PROVIDER_CHAIN3=openrouter
+# MCP_PROVIDER_CHAIN3_BASE_URL=https://openrouter.ai/api/v1
+# MCP_PROVIDER_CHAIN3_API_KEY=<openrouter-key>
+# MCP_PROVIDER_CHAIN3_MODEL=openai/gpt-4o-mini
+
+# Cooldown (ms) before retrying a provider after a 429/5xx/timeout failure.
+# MCP_PROVIDER_COOLDOWN_MS=60000
 
 # Base URL of an OpenAI-compatible API (must expose /v1/...)
-LLM_BASE_URL=http://localhost:11434/v1
+MCP_LLM_BASE_URL=http://localhost:11434/v1
 # API key for that endpoint (leave blank for local servers that don't need one)
-LLM_API_KEY=
+MCP_LLM_API_KEY=
 
 # Optional: semantic embedding recall (needs /v1/embeddings)
-EMBED_MODEL=nomic-embed-text
+MCP_EMBED_MODEL=nomic-embed-text
 EMBED_TIMEOUT_MS=12000
 
 # Optional: LLM rerank recall (needs /v1/chat/completions)
 # Used automatically when embeddings are unavailable.
-RERANK_MODEL=llama3.1:8b
+MCP_RERANK_MODEL=llama3.1:8b
 RERANK_TIMEOUT_MS=30000
 RERANK_ENABLED=1
 
@@ -22,5 +45,6 @@ RERANK_ENABLED=1
 # JOURNAL_DIR=~/.codex/memories/journal
 # CHECKPOINT_DIR=~/.codex/memories/checkpoints
 
-# Backward-compatible aliases (still honored): NINEROUTER_URL, NINEROUTER_KEY,
-# EMBED_URL, EMBED_KEY, RERANK_URL, RERANK_KEY
+# Backward-compatible aliases (still honored): LLM_BASE_URL, LLM_API_KEY,
+# NINEROUTER_URL, NINEROUTER_KEY, EMBED_MODEL, RERANK_MODEL, EMBED_URL,
+# EMBED_KEY, RERANK_URL, RERANK_KEY

package/CHANGELOG.md

@@ -0,0 +1,46 @@
+# Changelog
+
+## 1.2.0 - 2026-06-15
+
+### Added
+- CLI meta handling for all bins: `--help`, `--version`, and `--doctor` (config diagnostics with API keys redacted) before the stdio server starts.
+- Provider diagnostics `providerChainDiagnostics()` that lists active providers with redacted keys and flags incomplete numbered slots.
+- Per-provider cooldown on `429`/`5xx`/timeout/network failures via `MCP_PROVIDER_COOLDOWN_MS` (default `60000`).
+- CI job that packs the tarball, installs it in a temp dir, and runs each bin `--version`.
+
+### Changed
+- Rerank now skips providers that are cooling down and records success/failure outcomes.
+- Rerank never logs API keys or response bodies.
+
+## 1.1.0 - 2026-06-15
+
+### Added
+- Added optional numbered provider chain for chat/rerank fallback: `MCP_PROVIDER_PRIMARY_*`, `MCP_PROVIDER_CHAIN2_*`, `MCP_PROVIDER_CHAIN3_*`, and higher.
+- Added provider-chain tests for ordered fallback, incomplete slot skipping, deterministic disable, and legacy fallback.
+
+## 1.0.1 - 2026-06-15
+
+### Added
+- Added neutral `MCP_*` environment variables for model configuration:
+  - `MCP_LLM_BASE_URL`, `MCP_LLM_API_KEY`
+  - `MCP_RERANK_BASE_URL`, `MCP_RERANK_API_KEY`, `MCP_RERANK_MODEL`
+  - `MCP_EMBED_BASE_URL`, `MCP_EMBED_API_KEY`, `MCP_EMBED_MODEL`
+- Added client-agnostic docs:
+  - `docs/configuration.md`
+  - `docs/clients/codex.md`
+  - `docs/clients/claude-code.md`
+  - `docs/clients/generic-mcp.md`
+- Added tests proving `MCP_*` env vars override legacy aliases.
+- Added `MCP_DETERMINISTIC_FALLBACK` hard no-network mode for deterministic local-only recall.
+- Added `docs/privacy.md` covering local storage, data flow, and remote provider boundaries.
+- Added provider guidance for Groq, Cerebras, and OpenRouter as optional external endpoints.
+
+### Changed
+- README now presents the project as **Dev MCP Suite** while keeping the npm package name `codex-dev-mcp-suite` for compatibility.
+- Rerank and embedding helpers now describe any OpenAI-compatible endpoint, not 9Router only.
+- `.env.example` now recommends `MCP_*` names for new installs.
+- `memory_recall`, `journal_search`, and `memory_reindex` now explicitly respect deterministic no-network mode.
+
+### Compatibility
+- Legacy env names remain supported: `LLM_*`, `NINEROUTER_*`, `EMBED_*`, and `RERANK_*`.
+- Offline keyword search remains the default if no model endpoint is configured.

package/README.md

@@ -1,6 +1,9 @@
-# Codex Dev MCP Suite
+# Dev MCP Suite
 
 [![CI](https://github.com/verrysimatupang99/codex-dev-mcp-suite/actions/workflows/ci.yml/badge.svg)](https://github.com/verrysimatupang99/codex-dev-mcp-suite/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/codex-dev-mcp-suite.svg)](https://www.npmjs.com/package/codex-dev-mcp-suite)
+
+Published as `codex-dev-mcp-suite` for backward compatibility.
 
 Four local, file-based MCP servers for solo developers and vibecoders who keep
 losing context when sessions hit "input too long" / get compacted / restart.
@@ -8,7 +11,8 @@ Stop re-pasting context across sessions.
 
 All servers are **local, dependency-light (only the MCP SDK), and split storage
 per-project** by the working directory. Works with any MCP-capable client
-(Codex CLI, Claude Code, Cursor, Cline, etc.).
+(Codex CLI, Claude Code, Cursor, Cline, Gemini-compatible launchers, Hermes,
+or any stdio MCP host).
 
 ## The four servers
 
@@ -28,11 +32,46 @@ Recall auto-selects the best available mode:
 3. **keyword** — always-available offline fallback
 
 All network features degrade gracefully: no endpoint = keyword mode, never an error.
+Use the neutral `MCP_*` environment variables for new installs; legacy
+`NINEROUTER_*` and `LLM_*` variables are still supported. See
+[`docs/configuration.md`](docs/configuration.md).
+
+Need hard local-only behavior? Set `MCP_DETERMINISTIC_FALLBACK=true` to disable
+embeddings/rerank even if model keys are present; results are labeled
+`[deterministic]`.
 
 ## Install
 
 Requires Node.js >= 18.
 
+### Quickest: run via npx (no clone)
+
+Point your MCP client at the published package — no install step needed:
+
+```toml
+# Codex CLI ~/.codex/config.toml
+[mcp_servers.project-memory]
+command = "npx"
+args = ["-y", "-p", "codex-dev-mcp-suite", "project-memory-mcp"]
+
+[mcp_servers.devjournal]
+command = "npx"
+args = ["-y", "-p", "codex-dev-mcp-suite", "devjournal-mcp"]
+
+[mcp_servers.checkpoint]
+command = "npx"
+args = ["-y", "-p", "codex-dev-mcp-suite", "checkpoint-mcp"]
+
+[mcp_servers.context-pack]
+command = "npx"
+args = ["-y", "-p", "codex-dev-mcp-suite", "context-pack-mcp"]
+```
+
+Or install globally: `npm i -g codex-dev-mcp-suite` → commands
+`project-memory-mcp`, `devjournal-mcp`, `checkpoint-mcp`, `context-pack-mcp`.
+
+### From source
+
 ```bash
 git clone https://github.com/<you>/codex-dev-mcp-suite.git
 cd codex-dev-mcp-suite
@@ -42,6 +81,12 @@ for s in project-memory checkpoint context-pack devjournal; do (cd "$s" && npm i
 
 ### Register with your MCP client
 
+Client-specific examples:
+
+- [Codex CLI](docs/clients/codex.md)
+- [Claude Code](docs/clients/claude-code.md)
+- [Generic MCP JSON](docs/clients/generic-mcp.md)
+
 **Codex CLI** (`~/.codex/config.toml`):
 
 ```toml
@@ -50,10 +95,10 @@ command = "node"
 args = ["/abs/path/codex-dev-mcp-suite/project-memory/server.js"]
 [mcp_servers.project-memory.env]
 MEMORY_VAULT_DIR = "~/.codex/memories/vault"
-# optional recall upgrades (see .env.example)
-# LLM_BASE_URL = "http://localhost:11434/v1"   # any OpenAI-compatible endpoint
-# LLM_API_KEY = "..."
-# RERANK_MODEL = "llama3.1:8b"
+# optional recall upgrades (see .env.example and docs/configuration.md)
+# MCP_LLM_BASE_URL = "http://localhost:11434/v1"   # any OpenAI-compatible endpoint
+# MCP_LLM_API_KEY = "..."
+# MCP_RERANK_MODEL = "llama3.1:8b"
 
 [mcp_servers.checkpoint]
 command = "node"
@@ -70,8 +115,10 @@ args = ["/abs/path/codex-dev-mcp-suite/devjournal/server.js"]
 JOURNAL_DIR = "~/.codex/memories/journal"
 ```
 
-**Claude Code / Cursor / Cline** (`mcpServers` JSON): same idea — `command: "node"`,
-`args: ["/abs/path/<server>/server.js"]`, optional `env`.
+**Claude Code / Cursor / Cline / other MCP clients** (`mcpServers` JSON): same
+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`.
 
 ## Daily workflow
 
@@ -100,8 +147,10 @@ cd project-memory && npm test
 
 ## Privacy
 
-Everything is stored as plain files on your machine. No data leaves your
-computer unless you explicitly configure an embeddings/rerank endpoint. Your
+Local-first by default: no hosted backend, no built-in telemetry, no project
+account system. Everything is stored as files on your machine. No data leaves
+your machine unless you explicitly configure an external model/API endpoint for
+rerank or embeddings. See [privacy and data flow](docs/privacy.md). Your
 personal vault/journal/checkpoints are gitignored.
 
 ## License

package/bin/_meta.mjs

@@ -0,0 +1,69 @@
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+function pkgVersion() {
+  try {
+    const raw = fs.readFileSync(path.join(__dirname, "..", "package.json"), "utf8");
+    return JSON.parse(raw).version || "unknown";
+  } catch { return "unknown"; }
+}
+
+function redactKey(name) {
+  const v = String(process.env[name] || "");
+  return v ? `set (${v.length} chars)` : "not set";
+}
+
+function doctorLines(meta) {
+  const lines = [];
+  lines.push(`${meta.title} doctor`);
+  lines.push(`version: ${pkgVersion()}`);
+  lines.push(`node: ${process.version}`);
+  for (const [label, name] of meta.storage || []) {
+    lines.push(`${label}: ${process.env[name] || meta.storageDefaults?.[name] || "(default)"}`);
+  }
+  const det = /^(1|true|yes|on)$/i.test(String(process.env.MCP_DETERMINISTIC_FALLBACK || "").trim());
+  lines.push(`deterministic no-network: ${det ? "on" : "off"}`);
+  if (meta.usesModel) {
+    lines.push("model/provider config (keys redacted):");
+    lines.push(`  MCP_LLM_BASE_URL: ${process.env.MCP_LLM_BASE_URL || "(unset)"}`);
+    lines.push(`  MCP_LLM_API_KEY: ${redactKey("MCP_LLM_API_KEY")}`);
+    lines.push(`  MCP_PROVIDER_PRIMARY: ${process.env.MCP_PROVIDER_PRIMARY || "(unset)"}`);
+    lines.push(`  MCP_PROVIDER_PRIMARY_API_KEY: ${redactKey("MCP_PROVIDER_PRIMARY_API_KEY")}`);
+    lines.push(`  MCP_EMBED_API_KEY: ${redactKey("MCP_EMBED_API_KEY")}`);
+    lines.push(`  MCP_RERANK_API_KEY: ${redactKey("MCP_RERANK_API_KEY")}`);
+  } else {
+    lines.push("model/provider config: not used by this server");
+  }
+  return lines;
+}
+
+export function handleCliMeta(meta) {
+  const argv = process.argv.slice(2);
+  if (argv.includes("-v") || argv.includes("--version")) {
+    process.stdout.write(`${pkgVersion()}\n`);
+    process.exit(0);
+  }
+  if (argv.includes("-h") || argv.includes("--help")) {
+    const out = [
+      `${meta.title} (${meta.bin}) v${pkgVersion()}`,
+      "",
+      "An MCP server that speaks JSON-RPC over stdio. Launch it from an MCP client.",
+      "",
+      "Usage:",
+      `  ${meta.bin}            start the MCP stdio server`,
+      `  ${meta.bin} --version  print version`,
+      `  ${meta.bin} --doctor   print config diagnostics (API keys redacted)`,
+      `  ${meta.bin} --help     show this help`,
+    ];
+    process.stdout.write(out.join("\n") + "\n");
+    process.exit(0);
+  }
+  if (argv.includes("--doctor")) {
+    process.stdout.write(doctorLines(meta).join("\n") + "\n");
+    process.exit(0);
+  }
+  return false;
+}

package/bin/checkpoint.mjs

@@ -1,2 +1,9 @@
 #!/usr/bin/env node
-import "../checkpoint/server.js";
+import { handleCliMeta } from "./_meta.mjs";
+handleCliMeta({
+  bin: "checkpoint-mcp",
+  title: "Checkpoint MCP",
+  usesModel: false,
+  storage: [["store", "CHECKPOINT_DIR"]],
+});
+import("../checkpoint/server.js");

package/bin/context-pack.mjs

@@ -1,2 +1,9 @@
 #!/usr/bin/env node
-import "../context-pack/server.js";
+import { handleCliMeta } from "./_meta.mjs";
+handleCliMeta({
+  bin: "context-pack-mcp",
+  title: "Context Pack MCP",
+  usesModel: false,
+  storage: [],
+});
+import("../context-pack/server.js");

package/bin/devjournal.mjs

@@ -1,2 +1,9 @@
 #!/usr/bin/env node
-import "../devjournal/server.js";
+import { handleCliMeta } from "./_meta.mjs";
+handleCliMeta({
+  bin: "devjournal-mcp",
+  title: "Dev Journal MCP",
+  usesModel: true,
+  storage: [["store", "JOURNAL_DIR"]],
+});
+import("../devjournal/server.js");

package/bin/project-memory.mjs

@@ -1,2 +1,9 @@
 #!/usr/bin/env node
-import "../project-memory/server.js";
+import { handleCliMeta } from "./_meta.mjs";
+handleCliMeta({
+  bin: "project-memory-mcp",
+  title: "Project Memory MCP",
+  usesModel: true,
+  storage: [["vault", "MEMORY_VAULT_DIR"]],
+});
+import("../project-memory/server.js");

package/devjournal/env.js

@@ -0,0 +1,3 @@
+export function deterministicEnabled() {
+  return /^(1|true|yes|on)$/i.test(String(process.env.MCP_DETERMINISTIC_FALLBACK || "").trim());
+}

package/devjournal/provider-chain.js

@@ -0,0 +1,109 @@
+import { deterministicEnabled } from "./env.js";
+
+const DEFAULT_BASE = "http://localhost:20128";
+const DEFAULT_MODEL = "kr/claude-haiku-4.5";
+
+function value(name) {
+  return String(process.env[name] || "").trim();
+}
+
+export function redactKey(key) {
+  const k = String(key || "");
+  return k ? `set (${k.length} chars)` : "not set";
+}
+
+function providerEnv(prefix) {
+  const label = value(prefix);
+  const base = value(`${prefix}_BASE_URL`);
+  const key = value(`${prefix}_API_KEY`);
+  const model = value(`${prefix}_MODEL`);
+  if (!label || !base || !key || !model) return null;
+  return { label, base, key, model };
+}
+
+function slotIssues(prefix) {
+  const present = ["", "_BASE_URL", "_API_KEY", "_MODEL"].some((s) => value(`${prefix}${s}`));
+  if (!present) return null;
+  const missing = [];
+  if (!value(prefix)) missing.push(`${prefix}`);
+  if (!value(`${prefix}_BASE_URL`)) missing.push(`${prefix}_BASE_URL`);
+  if (!value(`${prefix}_API_KEY`)) missing.push(`${prefix}_API_KEY`);
+  if (!value(`${prefix}_MODEL`)) missing.push(`${prefix}_MODEL`);
+  return missing.length ? { prefix, missing } : null;
+}
+
+function numberedPrefixes() {
+  const prefixes = ["MCP_PROVIDER_PRIMARY"];
+  const nums = Object.keys(process.env)
+    .map((name) => name.match(/^MCP_PROVIDER_CHAIN(\d+)/)?.[1])
+    .filter(Boolean)
+    .map(Number)
+    .filter((n) => n >= 2);
+  for (const n of [...new Set(nums)].sort((a, b) => a - b)) {
+    prefixes.push(`MCP_PROVIDER_CHAIN${n}`);
+  }
+  return prefixes;
+}
+
+function numberedProviders() {
+  const providers = [];
+  for (const prefix of numberedPrefixes()) {
+    const provider = providerEnv(prefix);
+    if (provider) providers.push(provider);
+  }
+  return providers;
+}
+
+function legacyProvider() {
+  const base = value("MCP_RERANK_BASE_URL") || value("MCP_LLM_BASE_URL") || value("LLM_BASE_URL") || value("RERANK_URL") || value("NINEROUTER_URL") || DEFAULT_BASE;
+  const key = value("MCP_RERANK_API_KEY") || value("MCP_LLM_API_KEY") || value("LLM_API_KEY") || value("RERANK_KEY") || value("NINEROUTER_KEY");
+  const model = value("MCP_RERANK_MODEL") || value("RERANK_MODEL") || DEFAULT_MODEL;
+  if (!key) return null;
+  return { label: "legacy", base, key, model };
+}
+
+export function providerChainConfig() {
+  const deterministic = deterministicEnabled();
+  const rerankEnabled = process.env.RERANK_ENABLED !== "0";
+  if (deterministic || !rerankEnabled) return { providers: [], enabled: false, deterministic };
+  const providers = numberedProviders();
+  if (providers.length === 0) {
+    const legacy = legacyProvider();
+    if (legacy) providers.push(legacy);
+  }
+  return { providers, enabled: providers.length > 0, deterministic };
+}
+
+export function providerChainDiagnostics() {
+  const cfg = providerChainConfig();
+  const issues = [];
+  for (const prefix of numberedPrefixes()) {
+    const issue = slotIssues(prefix);
+    if (issue) issues.push(issue);
+  }
+  return {
+    deterministic: cfg.deterministic,
+    enabled: cfg.enabled,
+    providers: cfg.providers.map((p) => ({ label: p.label, base: p.base, model: p.model, apiKey: redactKey(p.key) })),
+    issues,
+  };
+}
+
+const COOLDOWN_MS = Number(process.env.MCP_PROVIDER_COOLDOWN_MS || 60000);
+const cooldowns = new Map();
+
+export function isCoolingDown(key, now = Date.now()) {
+  const until = cooldowns.get(key);
+  if (!until) return false;
+  if (now >= until) { cooldowns.delete(key); return false; }
+  return true;
+}
+
+export function recordOutcome(key, ok, now = Date.now()) {
+  if (ok) { cooldowns.delete(key); return; }
+  cooldowns.set(key, now + COOLDOWN_MS);
+}
+
+export function _resetCooldowns() {
+  cooldowns.clear();
+}

package/devjournal/rerank.js

@@ -1,29 +1,44 @@
 /**
- * LLM reranker via 9router chat models (e.g. Kiro kr/claude-haiku-4.5).
- * Used when embeddings are unavailable: keyword prefilter -> LLM picks the
- * most relevant candidates. Degrades gracefully: returns null on any failure
- * so callers fall back to keyword ordering. Never throws.
+ * LLM reranker via any OpenAI-compatible /v1/chat/completions model.
+ * Tries provider chain slots in order, skipping any currently cooling down
+ * after a recent failure. Degrades gracefully: returns null on any failure so
+ * callers fall back to keyword ordering. Never throws. Never logs keys/bodies.
  */
 import http from "http";
 import https from "https";
 import { URL } from "url";
+import { deterministicEnabled } from "./env.js";
+import { providerChainConfig, isCoolingDown, recordOutcome } from "./provider-chain.js";
 
-const BASE = process.env.LLM_BASE_URL || process.env.RERANK_URL || process.env.NINEROUTER_URL || "http://localhost:20128";
-const KEY = process.env.LLM_API_KEY || process.env.RERANK_KEY || process.env.NINEROUTER_KEY || "";
-const MODEL = process.env.RERANK_MODEL || "kr/claude-haiku-4.5";
 const TIMEOUT_MS = Number(process.env.RERANK_TIMEOUT_MS || 30000);
 const ENABLED = process.env.RERANK_ENABLED !== "0";
 
 export function rerankConfig() {
-  return { base: BASE, model: MODEL, enabled: Boolean(KEY) && ENABLED };
+  const cfg = providerChainConfig();
+  const first = cfg.providers[0] || {};
+  return {
+    base: first.base,
+    model: first.model,
+    providers: cfg.providers.map(({ label, base, model }) => ({ label, base, model })),
+    enabled: ENABLED && cfg.enabled && !deterministicEnabled(),
+    deterministic: deterministicEnabled(),
+  };
 }
 
-function chat(messages) {
+function providerKey(provider) {
+  return `${provider.label}|${provider.base}|${provider.model}`;
+}
+
+/**
+ * Resolves { content, retryable }. retryable=true means try the next provider
+ * (timeout, network error, 429, or 5xx). retryable=false with null content
+ * means a definitive non-retryable response (e.g. 4xx auth).
+ */
+function chatWithProvider(provider, messages) {
   return new Promise((resolve) => {
-    if (!KEY || !ENABLED) return resolve(null);
     let u;
-    try { u = new URL("/v1/chat/completions", BASE); } catch { return resolve(null); }
-    const payload = Buffer.from(JSON.stringify({ model: MODEL, stream: false, temperature: 0, max_tokens: 200, messages }));
+    try { u = new URL("/v1/chat/completions", provider.base); } catch { return resolve({ content: null, retryable: false }); }
+    const payload = Buffer.from(JSON.stringify({ model: provider.model, stream: false, temperature: 0, max_tokens: 200, messages }));
     const lib = u.protocol === "https:" ? https : http;
     const req = lib.request(
       {
@@ -31,18 +46,21 @@ function chat(messages) {
         port: u.port || (u.protocol === "https:" ? 443 : 80),
         path: u.pathname,
         method: "POST",
-        headers: { "Content-Type": "application/json", "Content-Length": payload.length, Authorization: `Bearer ${KEY}` },
+        headers: { "Content-Type": "application/json", "Content-Length": payload.length, Authorization: `Bearer ${provider.key}` },
         timeout: TIMEOUT_MS,
       },
       (res) => {
         let body = "";
         res.on("data", (c) => (body += c));
         res.on("end", () => {
-          if (res.statusCode !== 200) return resolve(null);
-          // handle plain JSON or SSE stream just in case
+          const status = res.statusCode || 0;
+          if (status !== 200) {
+            const retryable = status === 429 || status >= 500;
+            return resolve({ content: null, retryable });
+          }
           try {
             const j = JSON.parse(body);
-            return resolve(j?.choices?.[0]?.message?.content ?? null);
+            return resolve({ content: j?.choices?.[0]?.message?.content ?? null, retryable: false });
           } catch { /* maybe SSE */ }
           try {
             let acc = "";
@@ -54,24 +72,37 @@ function chat(messages) {
               const j = JSON.parse(d);
               acc += j?.choices?.[0]?.delta?.content || j?.choices?.[0]?.message?.content || "";
             }
-            return resolve(acc || null);
-          } catch { return resolve(null); }
+            return resolve({ content: acc || null, retryable: false });
+          } catch { return resolve({ content: null, retryable: true }); }
         });
       }
     );
-    req.on("error", () => resolve(null));
-    req.on("timeout", () => { req.destroy(); resolve(null); });
+    req.on("error", () => resolve({ content: null, retryable: true }));
+    req.on("timeout", () => { req.destroy(); resolve({ content: null, retryable: true }); });
     req.write(payload);
     req.end();
   });
 }
 
+async function chat(messages) {
+  if (!ENABLED || deterministicEnabled()) return null;
+  const { providers } = providerChainConfig();
+  for (const provider of providers) {
+    const key = providerKey(provider);
+    if (isCoolingDown(key)) continue;
+    const { content, retryable } = await chatWithProvider(provider, messages);
+    if (content) { recordOutcome(key, true); return content; }
+    if (retryable) recordOutcome(key, false);
+  }
+  return null;
+}
+
 /**
  * Given a query and candidates [{id, title, snippet}], ask the model to return
  * the ids ordered by relevance. Returns an array of ids, or null on failure.
  */
 export async function rerank(query, candidates, topK = 5) {
-  if (!KEY || !ENABLED || !candidates || candidates.length === 0) return null;
+  if (!ENABLED || deterministicEnabled() || !candidates || candidates.length === 0 || !providerChainConfig().enabled) return null;
   const list = candidates.map((c, i) => `[${i + 1}] (id:${c.id}) ${c.title}\n    ${String(c.snippet || "").replace(/\s+/g, " ").slice(0, 200)}`).join("\n");
   const sys = "You are a search reranker. Given a user query and a numbered list of notes, return the most relevant notes ordered best-first. Respond with ONLY a comma-separated list of the bracket numbers, e.g. 3,1,5. No prose.";
   const user = `Query: ${query}\n\nNotes:\n${list}\n\nReturn the top ${topK} bracket numbers, best first, comma-separated:`;

package/devjournal/server.js

@@ -32,6 +32,7 @@ import path from "path";
 import os from "os";
 import crypto from "crypto";
 import { rerank, rerankConfig } from "./rerank.js";
+import { deterministicEnabled } from "./env.js";
 
 const ROOT =
   process.env.JOURNAL_DIR ||
@@ -272,7 +273,7 @@ class DevJournalServer {
     let ranked = entries.map((e, i) => ({ e, i, sc: score(e) }))
       .sort((a, b) => b.sc - a.sc || b.i - a.i);
     let pool = ranked.filter((x) => x.sc > 0).slice(0, 20);
-    let mode = "keyword";
+    let mode = deterministicEnabled() ? "deterministic" : "keyword";
     if (pool.length === 0 && rerankConfig().enabled) {
       pool = ranked.slice(0, 20); // fall back to recent for semantic-style queries
     }

package/docs/clients/claude-code.md

@@ -0,0 +1,46 @@
+# Claude Code Setup
+
+Install globally:
+
+```bash
+npm i -g codex-dev-mcp-suite
+```
+
+Add MCP servers using your Claude Code MCP configuration flow. Generic JSON shape:
+
+```json
+{
+  "mcpServers": {
+    "project-memory": {
+      "command": "project-memory-mcp",
+      "env": {
+        "MEMORY_VAULT_DIR": "~/.local/share/dev-mcp-suite/memories/vault",
+        "MCP_LLM_BASE_URL": "http://localhost:11434/v1",
+        "MCP_LLM_API_KEY": "",
+        "MCP_RERANK_MODEL": "llama3.1:8b",
+        "MCP_EMBED_MODEL": "nomic-embed-text"
+      }
+    },
+    "devjournal": {
+      "command": "devjournal-mcp",
+      "env": {
+        "JOURNAL_DIR": "~/.local/share/dev-mcp-suite/memories/journal",
+        "MCP_LLM_BASE_URL": "http://localhost:11434/v1",
+        "MCP_LLM_API_KEY": "",
+        "MCP_RERANK_MODEL": "llama3.1:8b"
+      }
+    },
+    "checkpoint": {
+      "command": "checkpoint-mcp",
+      "env": {
+        "CHECKPOINT_DIR": "~/.local/share/dev-mcp-suite/memories/checkpoints"
+      }
+    },
+    "context-pack": {
+      "command": "context-pack-mcp"
+    }
+  }
+}
+```
+
+If you do not configure model env vars, `memory_recall` and `journal_search` still work in offline keyword mode.