codex-dev-mcp-suite 1.0.0 → 1.1.0

package/.env.example

@@ -1,19 +1,39 @@
 # 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
 
 # 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 +42,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,34 @@
+# Changelog
+
+## 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/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,56 @@
+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();
+}
+
+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 numberedProviders() {
+  const providers = [];
+  const primary = providerEnv("MCP_PROVIDER_PRIMARY");
+  if (primary) providers.push(primary);
+
+  const slots = Object.keys(process.env)
+    .map((name) => name.match(/^MCP_PROVIDER_CHAIN(\d+)$/)?.[1])
+    .filter(Boolean)
+    .map(Number)
+    .filter((n) => n >= 2)
+    .sort((a, b) => a - b);
+
+  for (const n of slots) {
+    const provider = providerEnv(`MCP_PROVIDER_CHAIN${n}`);
+    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 };
+}

package/devjournal/rerank.js

@@ -1,5 +1,5 @@
 /**
- * LLM reranker via 9router chat models (e.g. Kiro kr/claude-haiku-4.5).
+ * LLM reranker via any OpenAI-compatible /v1/chat/completions model.
  * 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.
@@ -7,23 +7,29 @@
 import http from "http";
 import https from "https";
 import { URL } from "url";
+import { deterministicEnabled } from "./env.js";
+import { providerChainConfig } 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 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(null); }
+    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,7 +37,7 @@ 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) => {
@@ -39,7 +45,6 @@ function chat(messages) {
         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
           try {
             const j = JSON.parse(body);
             return resolve(j?.choices?.[0]?.message?.content ?? null);
@@ -66,12 +71,22 @@ function chat(messages) {
   });
 }
 
+async function chat(messages) {
+  if (!ENABLED || deterministicEnabled()) return null;
+  const { providers } = providerChainConfig();
+  for (const provider of providers) {
+    const out = await chatWithProvider(provider, messages);
+    if (out) return out;
+  }
+  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.

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,109 @@
+# 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.
+
+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.