codex-dev-mcp-suite 1.0.0 → 1.2.0

package/docs/clients/codex.md

@@ -0,0 +1,39 @@
+# Codex CLI Setup
+
+Install globally:
+
+```bash
+npm i -g codex-dev-mcp-suite
+```
+
+Add to `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.project-memory]
+command = "project-memory-mcp"
+[mcp_servers.project-memory.env]
+MEMORY_VAULT_DIR = "~/.codex/memories/vault"
+# Optional model features; omit for offline keyword mode.
+MCP_LLM_BASE_URL = "http://localhost:20128"
+MCP_LLM_API_KEY = "sk-..."
+MCP_RERANK_MODEL = "kr/claude-haiku-4.5"
+MCP_EMBED_MODEL = "bm/baai/bge-m3"
+
+[mcp_servers.devjournal]
+command = "devjournal-mcp"
+[mcp_servers.devjournal.env]
+JOURNAL_DIR = "~/.codex/memories/journal"
+MCP_LLM_BASE_URL = "http://localhost:20128"
+MCP_LLM_API_KEY = "sk-..."
+MCP_RERANK_MODEL = "kr/claude-haiku-4.5"
+
+[mcp_servers.checkpoint]
+command = "checkpoint-mcp"
+[mcp_servers.checkpoint.env]
+CHECKPOINT_DIR = "~/.codex/memories/checkpoints"
+
+[mcp_servers.context-pack]
+command = "context-pack-mcp"
+```
+
+Important: the server name is `project-memory` with a hyphen. `project_memory` is not a configured MCP server name in Codex.

package/docs/clients/generic-mcp.md

@@ -0,0 +1,45 @@
+# Generic MCP Client Setup
+
+Any MCP client that can start stdio servers can use Dev MCP Suite.
+
+Install globally:
+
+```bash
+npm i -g codex-dev-mcp-suite
+```
+
+Generic server definitions:
+
+```json
+{
+  "mcpServers": {
+    "project-memory": {
+      "command": "project-memory-mcp",
+      "args": [],
+      "env": {
+        "MEMORY_VAULT_DIR": "~/.local/share/dev-mcp-suite/memories/vault"
+      }
+    },
+    "devjournal": {
+      "command": "devjournal-mcp",
+      "args": [],
+      "env": {
+        "JOURNAL_DIR": "~/.local/share/dev-mcp-suite/memories/journal"
+      }
+    },
+    "checkpoint": {
+      "command": "checkpoint-mcp",
+      "args": [],
+      "env": {
+        "CHECKPOINT_DIR": "~/.local/share/dev-mcp-suite/memories/checkpoints"
+      }
+    },
+    "context-pack": {
+      "command": "context-pack-mcp",
+      "args": []
+    }
+  }
+}
+```
+
+Optional model configuration can be added to `project-memory` and `devjournal` env blocks. See `docs/configuration.md`.

package/docs/configuration.md

@@ -0,0 +1,123 @@
+# Configuration
+
+Dev MCP Suite is MCP-client agnostic. The servers run locally over stdio and work in any client that can launch MCP servers: Codex CLI, Claude Code, Cursor, Cline, Gemini-compatible launchers, Hermes, and generic MCP hosts.
+
+## Storage
+
+All storage is local and file-based.
+
+| Env var | Used by | Default |
+|---|---|---|
+| `MEMORY_VAULT_DIR` | `project-memory` | `~/.codex/memories/vault` |
+| `JOURNAL_DIR` | `devjournal` | `~/.codex/memories/journal` |
+| `CHECKPOINT_DIR` | `checkpoint` | `~/.codex/memories/checkpoints` |
+
+Use a different base path if your MCP client is not Codex, for example `~/.local/share/dev-mcp-suite/...`.
+
+## Optional model features
+
+`context-pack` and `checkpoint` never need a model. `project-memory` and `devjournal` work offline by keyword search and can optionally use an OpenAI-compatible API for better recall.
+
+No remote calls are made unless you configure a model endpoint. For strict local-only behavior even when model env vars are present, set `MCP_DETERMINISTIC_FALLBACK=true`.
+
+| Env var | Purpose |
+|---|---|
+| `MCP_LLM_BASE_URL` | Base URL for an OpenAI-compatible API, e.g. `http://localhost:11434/v1` or `http://localhost:20128` |
+| `MCP_LLM_API_KEY` | API key for that endpoint; leave blank for local servers that do not require auth |
+| `MCP_RERANK_MODEL` | Chat model for LLM reranking, e.g. `llama3.1:8b`, `kr/claude-haiku-4.5`, `gpt-4o-mini` |
+| `MCP_RERANK_BASE_URL` | Optional rerank-specific base URL; falls back to `MCP_LLM_BASE_URL` |
+| `MCP_RERANK_API_KEY` | Optional rerank-specific API key; falls back to `MCP_LLM_API_KEY` |
+| `RERANK_ENABLED` | Set `0` to disable reranking |
+| `RERANK_TIMEOUT_MS` | Rerank request timeout; default `30000` |
+| `MCP_EMBED_MODEL` | Embedding model for semantic recall, e.g. `nomic-embed-text`, `text-embedding-3-small`, `bm/baai/bge-m3` |
+| `MCP_EMBED_BASE_URL` | Optional embedding-specific base URL; falls back to `MCP_LLM_BASE_URL` |
+| `MCP_EMBED_API_KEY` | Optional embedding-specific API key; falls back to `MCP_LLM_API_KEY` |
+| `EMBED_TIMEOUT_MS` | Embedding request timeout; default `15000` |
+| `MCP_DETERMINISTIC_FALLBACK` | Hard no-network fallback when true; accepts `true`, `1`, `yes`, `on` |
+
+Recall mode order:
+
+1. `deterministic` if `MCP_DETERMINISTIC_FALLBACK=true`.
+2. `semantic` if embeddings are configured and available.
+3. `rerank` if a chat model is configured and enabled.
+4. `keyword` offline fallback, always available.
+
+Failures degrade gracefully. If your embedding endpoint returns `503`, recall falls back to rerank/keyword instead of failing the tool call.
+
+## Provider strategy
+
+The suite is provider-neutral. A practical remote setup is:
+
+1. **Groq** for fast rerank/chat when model quality is sufficient.
+2. **Cerebras** as a second fast provider for outages or model fit.
+3. **OpenRouter** as broad fallback for many OpenAI-compatible models.
+
+In `v1.1`, chat/rerank can use built-in numbered fallback slots. Configure only primary if you want one provider, or add more numbered chain entries.
+
+```bash
+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
+```
+
+You can add `MCP_PROVIDER_CHAIN4_*`, `MCP_PROVIDER_CHAIN5_*`, and so on. The provider name is only a label; any OpenAI-compatible endpoint works when `BASE_URL`, `API_KEY`, and `MODEL` are set.
+
+On a `429`, `5xx`, timeout, or network error, a provider is put on a short cooldown and the next slot is tried. Tune the window with `MCP_PROVIDER_COOLDOWN_MS` (default `60000`).
+
+## Diagnostics
+
+Each server bin supports inspection flags that never start the server:
+
+```bash
+project-memory-mcp --version
+project-memory-mcp --doctor   # storage + model/provider config, API keys redacted
+project-memory-mcp --help
+```
+
+`--doctor` reports configured providers and storage paths and shows API keys only as `set (<n> chars)` or `not set`, never the raw value.
+
+Example OpenRouter-style config:
+
+```bash
+MCP_LLM_BASE_URL=https://openrouter.ai/api/v1
+MCP_LLM_API_KEY=<your-key>
+MCP_RERANK_MODEL=openai/gpt-4o-mini
+```
+
+Example local-only deterministic config:
+
+```bash
+MCP_DETERMINISTIC_FALLBACK=true
+```
+
+See [privacy and data flow](privacy.md) before using remote providers with sensitive projects.
+
+## Legacy aliases
+
+These older names still work for backward compatibility:
+
+| Legacy | Preferred |
+|---|---|
+| `LLM_BASE_URL` | `MCP_LLM_BASE_URL` |
+| `LLM_API_KEY` | `MCP_LLM_API_KEY` |
+| `NINEROUTER_URL` | `MCP_LLM_BASE_URL` |
+| `NINEROUTER_KEY` | `MCP_LLM_API_KEY` |
+| `EMBED_MODEL` | `MCP_EMBED_MODEL` |
+| `RERANK_MODEL` | `MCP_RERANK_MODEL` |
+| `EMBED_URL` | `MCP_EMBED_BASE_URL` |
+| `EMBED_KEY` | `MCP_EMBED_API_KEY` |
+| `RERANK_URL` | `MCP_RERANK_BASE_URL` |
+| `RERANK_KEY` | `MCP_RERANK_API_KEY` |
+
+Prefer the `MCP_*` names for new installs.

package/docs/privacy.md

@@ -0,0 +1,39 @@
+# Privacy and Data Flow
+
+Dev MCP Suite is local-first. It has no hosted backend, no built-in telemetry, and no account system owned by this project.
+
+## What is stored locally
+
+| Server | Local data |
+|---|---|
+| `project-memory` | Markdown notes, keyword index, optional embedding vectors if you run `memory_reindex` with embeddings configured |
+| `devjournal` | Session logs, handoff files, timeline entries |
+| `checkpoint` | Text-file snapshots for rollback |
+| `context-pack` | No persistent project data by default |
+
+Default storage paths are under `~/.codex/memories/...`; you can override them with `MEMORY_VAULT_DIR`, `JOURNAL_DIR`, and `CHECKPOINT_DIR`.
+
+## What can leave your machine
+
+Nothing leaves your machine by default. `project-memory` and `devjournal` use offline keyword scoring unless you configure an external OpenAI-compatible model endpoint.
+
+If you set model environment variables such as `MCP_LLM_BASE_URL`, `MCP_EMBED_BASE_URL`, `MCP_RERANK_BASE_URL`, or numbered provider slots like `MCP_PROVIDER_PRIMARY_BASE_URL`, the related query text and candidate snippets may be sent to that endpoint for embeddings or reranking. The endpoint can be local (Ollama, LM Studio, vLLM, LiteLLM) or remote (Groq, Cerebras, OpenRouter, 9Router, OpenAI-compatible gateways).
+
+## Hard no-network mode
+
+Set this when you want deterministic local-only recall even if model keys are present:
+
+```bash
+MCP_DETERMINISTIC_FALLBACK=true
+```
+
+Accepted true values: `true`, `1`, `yes`, `on` (case-insensitive). In this mode:
+
+- Embeddings are disabled.
+- LLM reranking is disabled.
+- `memory_reindex` skips embedding generation.
+- Results are labeled `[deterministic]`.
+
+## Recommended provider posture
+
+For remote providers, use least-privilege API keys and configure them per MCP client environment. Do not commit API keys to this repository or project repos. Prefer local models for sensitive work; use remote providers only for projects where sending snippets to that provider is acceptable.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-dev-mcp-suite",
-  "version": "1.0.0",
+  "version": "1.2.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",
@@ -42,24 +42,34 @@
   },
   "files": [
     "bin/*.mjs",
+    "bin/_meta.mjs",
     "project-memory/*.js",
-    "project-memory/*.mjs",
+    "project-memory/server.js",
+    "project-memory/embedding.js",
+    "project-memory/env.js",
+    "project-memory/provider-chain.js",
+    "project-memory/rerank.js",
     "project-memory/package.json",
     "devjournal/*.js",
-    "devjournal/*.mjs",
+    "devjournal/server.js",
+    "devjournal/env.js",
+    "devjournal/provider-chain.js",
+    "devjournal/rerank.js",
     "devjournal/package.json",
     "checkpoint/*.js",
-    "checkpoint/*.mjs",
+    "checkpoint/server.js",
     "checkpoint/package.json",
     "context-pack/*.js",
-    "context-pack/*.mjs",
+    "context-pack/server.js",
     "context-pack/package.json",
-    "_testkit/*.mjs",
-    "run-tests.mjs",
     "backfill-sessions-v2.mjs",
+    "docs/configuration.md",
+    "docs/privacy.md",
+    "docs/clients/*.md",
     "CODEX_DEV_MCP_GUIDE.md",
+    "CHANGELOG.md",
     "README.md",
     "LICENSE",
     ".env.example"
   ]
-}
+}

package/project-memory/embedding.js

@@ -1,19 +1,20 @@
 /**
- * Embedding helper for 9router (OpenAI-compatible /v1/embeddings).
+ * Embedding helper for any OpenAI-compatible /v1/embeddings endpoint.
  * Degrades gracefully: returns null on any failure so callers fall back
  * to keyword search. Never throws.
  */
 import http from "http";
 import https from "https";
 import { URL } from "url";
+import { deterministicEnabled } from "./env.js";
 
-const BASE = process.env.LLM_BASE_URL || process.env.EMBED_URL || process.env.NINEROUTER_URL || "http://localhost:20128";
-const KEY = process.env.LLM_API_KEY || process.env.EMBED_KEY || process.env.NINEROUTER_KEY || "";
-const MODEL = process.env.EMBED_MODEL || "bm/baai/bge-m3";
+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);
 
 export function embeddingConfig() {
-  return { base: BASE, model: MODEL, enabled: Boolean(KEY) };
+  return { base: BASE, model: MODEL, enabled: Boolean(KEY) && !deterministicEnabled(), deterministic: deterministicEnabled() };
 }
 
 function postJson(urlStr, payload) {
@@ -53,7 +54,7 @@ function postJson(urlStr, payload) {
 
 /** Returns array of vectors aligned to inputs, or null if unavailable. */
 export async function embed(inputs) {
-  if (!KEY) return null;
+  if (!KEY || deterministicEnabled()) return null;
   const arr = Array.isArray(inputs) ? inputs : [inputs];
   if (arr.length === 0) return [];
   const json = await postJson(BASE, { model: MODEL, input: arr });

package/project-memory/env.js

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

package/project-memory/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/project-memory/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/project-memory/server.js

@@ -28,6 +28,7 @@ import os from "os";
 import crypto from "crypto";
 import { embed, embedOne, cosine, embeddingConfig } from "./embedding.js";
 import { rerank, rerankConfig } from "./rerank.js";
+import { deterministicEnabled } from "./env.js";
 
 const VAULT_ROOT =
   process.env.MEMORY_VAULT_DIR ||
@@ -318,8 +319,8 @@ class ProjectMemoryServer {
       return score;
     };
 
-    let mode = "keyword";
-    const qVec = await embedOne(query);
+    let mode = deterministicEnabled() ? "deterministic" : "keyword";
+    const qVec = deterministicEnabled() ? null : await embedOne(query);
     const haveEmb = qVec && notes.some((n) => Array.isArray(n.embedding));
 
     let scored;
@@ -418,6 +419,7 @@ class ProjectMemoryServer {
 
   async reindex({ dir, force = false }) {
     const p = this.paths(dir);
+    if (deterministicEnabled()) return { content: [{ type: "text", text: `Reindex ${p.slug}: skipped (deterministic no-network mode; embeddings disabled).` }] };
     const index = await this.loadIndex(p);
     const notes = Object.values(index.notes || {});
     if (notes.length === 0) return { content: [{ type: "text", text: `No memories for ${p.slug} yet.` }] };