codex-dev-mcp-suite 1.6.0 → 1.8.0

package/docs/superpowers/specs/2026-06-15-provider-chain-v1-1-design.md

@@ -0,0 +1,89 @@
+# Provider Chain v1.1 Design
+
+## Goal
+
+Add built-in optional provider fallback for `project-memory` and `devjournal` model calls while keeping local-first privacy guarantees and deterministic no-network override.
+
+## User-facing config
+
+Use numbered provider slots so users can configure one provider or many without learning router syntax.
+
+Recommended slots:
+
+```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
+```
+
+Rules:
+
+- `MCP_PROVIDER_PRIMARY` is slot 1.
+- `MCP_PROVIDER_CHAIN2`, `MCP_PROVIDER_CHAIN3`, ... are fallback slots.
+- If only primary exists, use only primary.
+- If users want more, they can add `MCP_PROVIDER_CHAIN4_*`, etc.
+- Provider name is a label for logs/docs, not a lock-in. Any OpenAI-compatible provider works if `BASE_URL`, `API_KEY`, and `MODEL` are set.
+- Existing `MCP_LLM_*`, `MCP_RERANK_*`, and `MCP_EMBED_*` remain supported as compatibility fallback.
+
+## Recommended providers
+
+Docs recommend Groq, Cerebras, and OpenRouter because they commonly offer free/low-friction tiers and solid model quality. Users may use any provider/model ID.
+
+## Runtime behavior
+
+For chat/rerank calls:
+
+1. If `MCP_DETERMINISTIC_FALLBACK=true`, make no network calls and return keyword/deterministic mode.
+2. Build provider list from numbered slots.
+3. Try providers in order with the existing timeout.
+4. On timeout, 429, 5xx, network error, or invalid JSON: try next provider.
+5. On auth error 401/403: log provider label as unavailable and try next provider, without printing key.
+6. If all fail: return `null` and let existing keyword fallback handle results.
+
+For embeddings:
+
+- Keep current explicit embedding config in v1.1 unless a provider slot declares an embedding model later.
+- Do not guess embedding model from chat model.
+
+## Auto-import/probe
+
+MVP probe is read-only and optional:
+
+- Validate `/chat/completions` compatibility with a tiny low-token request.
+- Detect model availability only if provider exposes a safe model list endpoint.
+- Never store keys outside the user's MCP client env/config.
+- Never send project content during probe.
+
+Future CLI/import helper can generate `.env` snippets, but v1.1 runtime only reads env.
+
+## Privacy and observability
+
+- Default remains offline keyword mode if no provider is configured.
+- Deterministic mode overrides provider chain.
+- Logs may show provider label and status, never prompts, snippets, API keys, or full response bodies.
+- Docs must explain that query text/candidate snippets leave the machine only when provider slots or legacy model envs are configured.
+
+## Compatibility
+
+- Existing installs using `MCP_LLM_BASE_URL`/`MCP_LLM_API_KEY` keep working.
+- Existing `MCP_RERANK_*` continues to override generic LLM config for rerank if no numbered provider slots exist.
+- Legacy `NINEROUTER_*`, `LLM_*`, `RERANK_*`, and `EMBED_*` aliases remain supported.
+
+## Out of scope for v1.1
+
+- Hosted auth/dashboard.
+- Persisted provider credentials.
+- Automatic remote model selection based on benchmarks.
+- Embedding provider chain.
+- Publishing any telemetry.

package/docs/superpowers/specs/2026-06-15-trust-release-design.md

@@ -0,0 +1,164 @@
+# Trust Release Design
+
+**Project:** Dev MCP Suite (`codex-dev-mcp-suite`)  
+**Target release:** `v1.0.1` trust release  
+**Future release:** `v1.1` built-in provider chain
+
+## Goal
+
+Make Dev MCP Suite safe and understandable for new users by making privacy, local storage, optional model providers, and deterministic no-network behavior explicit.
+
+## Problem
+
+Calon pengguna punya kegelisahan wajar:
+
+1. Mereka takut data proyek/memory/journal dikirim ke author/package owner.
+2. Mereka tidak selalu pakai Codex; client bisa Claude Code, Cursor, Gemini-compatible launcher, Hermes, atau MCP host lain.
+3. Mereka perlu rekomendasi provider model yang jelas kalau ingin recall/rerank lebih bagus.
+4. Mereka perlu mode deterministic/no-network yang eksplisit, bukan sekadar fallback implisit.
+
+## Principles
+
+- **Local-first by default:** fresh install works without model provider or network calls.
+- **No hidden telemetry:** package has no hosted backend and no built-in telemetry.
+- **Opt-in remote model calls:** data leaves machine only if user configures external embedding/rerank provider.
+- **Precise privacy claims:** avoid overclaiming; document exact data flow.
+- **Client-agnostic:** docs refer to MCP clients/agents generally; Codex is one supported client, not the product identity.
+- **Deterministic means no network:** if enabled, LLM/embedding/rerank calls are hard-disabled.
+
+## v1.0.1 Scope
+
+### Privacy documentation
+
+Add `docs/privacy.md` with this core statement:
+
+> Dev MCP Suite has no built-in telemetry and no hosted backend. Your project memory, journal, and checkpoints are stored as local files on your machine. Data leaves your machine only if you configure an external embedding or rerank provider.
+
+The doc must explain:
+
+- What is stored locally:
+  - project-memory notes
+  - devjournal entries/handoffs
+  - checkpoints
+  - context-pack reads only; it does not persist project files
+- Who can access it:
+  - local OS user and tools with filesystem permission
+  - not the package author/owner
+- When data leaves the machine:
+  - only external `MCP_*` model endpoints for embedding/rerank
+  - only the text sent for that feature call
+- What never happens by default:
+  - no telemetry
+  - no hosted backend
+  - no automatic upload to repo/npm/author
+- Security caveats:
+  - vault/journal/checkpoints are plaintext local files
+  - do not store secrets unless intentionally desired
+  - if using remote model providers, review their privacy policies
+
+### Deterministic mode
+
+Add `MCP_DETERMINISTIC_FALLBACK=true`.
+
+Behavior:
+
+- In `project-memory`:
+  - `memory_recall` does not call embeddings.
+  - `memory_recall` does not call rerank LLM.
+  - `memory_reindex` should report deterministic/no-network mode instead of attempting embeddings.
+  - recall output uses `[deterministic]` label.
+- In `devjournal`:
+  - `journal_search` does not call rerank LLM.
+  - search output uses `[deterministic]` label.
+- Existing fallback behavior remains:
+  - if env is not true and no provider is configured, fallback remains `[keyword]`.
+  - if env is not true and provider fails, fallback remains `[keyword]`.
+
+Accepted true values: `true`, `1`, `yes`, `on` case-insensitive.
+
+### Provider recommendation docs
+
+Add provider setup section in `docs/configuration.md`:
+
+Recommended external provider strategy for users who want better recall/rerank:
+
+1. **Groq** as primary fast rerank provider.
+2. **Cerebras** as secondary fast fallback.
+3. **OpenRouter** as broad model fallback.
+
+For `v1.0.1`, this is docs-only. Users should wire the chain through an OpenAI-compatible gateway they control, such as LiteLLM or 9router, then point Dev MCP Suite at that gateway with:
+
+```env
+MCP_LLM_BASE_URL=http://localhost:4000/v1
+MCP_LLM_API_KEY=...
+MCP_RERANK_MODEL=...
+```
+
+Docs must say this chain is optional and disabled by default.
+
+### README updates
+
+README must include:
+
+- one local-first privacy paragraph
+- link to `docs/privacy.md`
+- link to provider config docs
+- clear deterministic example:
+
+```env
+MCP_DETERMINISTIC_FALLBACK=true
+```
+
+### Tests
+
+Add tests for:
+
+- `MCP_DETERMINISTIC_FALLBACK=true` disables project-memory embedding/rerank and labels recall `[deterministic]`.
+- `MCP_DETERMINISTIC_FALLBACK=true` disables devjournal rerank and labels search `[deterministic]`.
+- env parsing accepts `true`, `1`, `yes`, `on`.
+
+## v1.1 Future Scope: Built-In Provider Chain
+
+Built-in chain is attractive but out of scope for `v1.0.1` because it expands the trust/security surface.
+
+Future opt-in design:
+
+```env
+MCP_PROVIDER_CHAIN=groq,cerebras,openrouter
+GROQ_API_KEY=...
+CEREBRAS_API_KEY=...
+OPENROUTER_API_KEY=...
+```
+
+Behavior:
+
+1. Try Groq.
+2. On rate limit/error/timeout, try Cerebras.
+3. On failure, try OpenRouter.
+4. On total failure, fallback deterministic local.
+
+Requirements before v1.1 implementation:
+
+- provider-specific default models
+- retry/backoff and timeout policy
+- redacted logging
+- tests with mocked HTTP endpoints
+- docs explaining exactly what text is sent to which provider
+- opt-in only; no built-in chain unless `MCP_PROVIDER_CHAIN` is set
+
+## Non-Goals
+
+- Do not publish under a new package name in `v1.0.1`.
+- Do not add telemetry.
+- Do not add a hosted backend.
+- Do not implement built-in Groq/Cerebras/OpenRouter chain in `v1.0.1`.
+- Do not make remote model calls by default.
+
+## Acceptance Criteria
+
+- Fresh install works offline with deterministic/keyword local recall.
+- Users can read a privacy doc and understand exactly where data is stored and when it leaves their machine.
+- `MCP_DETERMINISTIC_FALLBACK=true` hard-disables all model network calls in suite recall/search paths.
+- Tests pass.
+- `npm pack --dry-run` includes public docs and excludes internal planning docs.
+- Secret scan finds no real secrets.

package/docs/superpowers/specs/2026-06-18-dev-mcp-suite-v1-5-0-knowledge-graph-design.md

@@ -0,0 +1,386 @@
+# Dev MCP Suite v1.5.0 Knowledge Graph Design
+
+## Summary
+
+`v1.5.0` introduces the first knowledge-graph layer for Dev MCP Suite. The release is intentionally narrow and focuses on three capabilities only:
+
+- `memory_link`
+- `memory_global_recall`
+- `memory_dedup`
+
+The goal is to improve note connectivity, cross-project discovery, and duplicate detection without making embeddings mandatory and without forcing existing users through a hard migration.
+
+This release must remain backward-compatible with existing vaults and must degrade gracefully when semantic retrieval is unavailable.
+
+## Goals
+
+- Add explicit note-to-note linking with resolvable references and backlinks.
+- Add cross-project recall that still prefers the active project first.
+- Add duplicate-note discovery with safe, reviewable suggestions.
+- Keep retrieval useful even when no embeddings provider is configured.
+- Avoid destructive automation in any dedup flow.
+- Create a foundation that later releases can observe, score, and maintain.
+
+## Non-Goals
+
+- Auto-merging or auto-deleting notes.
+- Introducing a monolithic graph subsystem with many unrelated features.
+- Requiring embeddings as a prerequisite for graph features.
+- Shipping observability, lifecycle cleanup, or automated repair workflows in this release.
+- Changing the existing public tool surface outside the three scoped tools unless strictly required for compatibility.
+
+## Release Scope
+
+`v1.5.0` includes exactly these tools and behaviors:
+
+1. `memory_link`
+2. `memory_global_recall`
+3. `memory_dedup`
+
+Future work is explicitly deferred:
+
+- `v1.5.1`: Observability
+- `v1.5.2`: Lifecycle
+
+## User Problems
+
+Current retrieval is strong within a single project, but the suite still lacks a first-class model for relationships between notes. The main pain points are:
+
+- users cannot explicitly connect notes and traverse those connections reliably;
+- similarly named notes across projects are hard to distinguish and reuse safely;
+- duplicate notes accumulate over time with no guided cleanup path;
+- semantic recall quality depends too heavily on whether embeddings are configured.
+
+The knowledge-graph release solves these by adding link awareness, global lookup, and safe dedup suggestions while keeping the existing retrieval architecture intact.
+
+## Design Principles
+
+### Backward-compatible first
+
+Existing vaults must continue to function without manual migration. Graph metadata can be introduced lazily and rebuilt later if needed.
+
+### Safe by default
+
+No destructive actions happen automatically. When ambiguity exists, the system should return candidates rather than silently guessing.
+
+### Embeddings are optional, not required
+
+Graph features must still provide value with keyword and deterministic retrieval only. Semantic enhancements improve quality but are not a hard dependency.
+
+### Same-project bias
+
+When resolving links or ranking recall results, the active project has priority. Global behavior is additive, not a replacement for project locality.
+
+### Rebuildable state
+
+Any derived graph or link index must be reconstructible from note content and note metadata.
+
+## Capability 1: `memory_link`
+
+### Purpose
+
+`memory_link` provides explicit note-link parsing, resolution, and backlink support.
+
+### Supported Link Syntax
+
+The tool supports both:
+
+- `[[id]]`
+- `[[title]]`
+
+It also supports explicit cross-project override syntax:
+
+- `[[project:id]]`
+- `[[project:title]]`
+
+### Resolution Rules
+
+Link resolution follows this order:
+
+1. If the link contains an explicit project prefix, resolve within that target project.
+2. Otherwise, search the active project first.
+3. If no same-project match exists, fall back to global search.
+4. If multiple valid matches remain, return ambiguity information and candidate matches.
+5. If no match exists, return an unresolved-link result rather than fabricating one.
+
+### Backlinks
+
+The tool must expose backlink information for a note so users can inspect inbound relationships. Backlinks are derived data and should not require separate manual authoring.
+
+### Expected Behavior
+
+- Same-project linking should feel local and predictable.
+- Title-based linking should remain ergonomic.
+- Cross-project references should be explicit when needed.
+- Ambiguous links should be surfaced clearly.
+
+## Capability 2: `memory_global_recall`
+
+### Purpose
+
+`memory_global_recall` retrieves relevant notes across multiple projects while preserving a strong active-project bias.
+
+### Retrieval Strategy
+
+Global recall should be layered rather than all-or-nothing:
+
+1. Search/rank the active project first.
+2. Expand to global candidates only as a fallback or augmentation layer.
+3. Apply graph-aware boost after candidate generation.
+4. Return results with enough metadata to explain where they came from.
+
+### Ranking Model
+
+The ranking model should use a soft graph boost. Graph connectivity helps reorder candidates, but it must not act as a hard filter that hides otherwise relevant notes.
+
+Possible ranking inputs:
+
+- lexical/keyword match
+- semantic similarity, if embeddings are available
+- graph/link proximity
+- same-project prior
+- note freshness or other existing recall signals if already available in the current architecture
+
+### Behavior Without Embeddings
+
+If no embeddings model is configured, `memory_global_recall` must still work by combining:
+
+- keyword/deterministic candidate retrieval
+- same-project prioritization
+- graph-based soft boosting
+
+This ensures cross-project recall remains usable in “zero semantic config” environments.
+
+### Output Expectations
+
+The tool should make it clear whether a result came primarily from:
+
+- active-project recall
+- global fallback
+- graph-supported re-ranking
+- semantic retrieval, if enabled
+
+That transparency matters for debugging user trust later, especially in `v1.5.1` observability.
+
+## Capability 3: `memory_dedup`
+
+### Purpose
+
+`memory_dedup` identifies likely duplicate notes and suggests merge candidates.
+
+### Safety Policy
+
+This tool is advisory only in `v1.5.0`.
+
+It must:
+
+- suggest possible duplicates;
+- explain why the pair/group was flagged;
+- avoid deleting or merging anything automatically.
+
+It must not:
+
+- auto-delete notes;
+- auto-merge notes;
+- rewrite content without an explicit future tool designed for that purpose.
+
+### Default Threshold
+
+The default duplicate threshold is `0.90`.
+
+That threshold should be overridable, but the default should favor precision over aggressive cleanup.
+
+### Matching Signals
+
+Dedup suggestions may consider:
+
+- normalized title similarity
+- content overlap
+- link neighborhood similarity
+- semantic similarity if embeddings are available
+- metadata similarity if cheap and already available
+
+### Output Expectations
+
+The output should contain enough information for manual review, such as:
+
+- note identifiers
+- titles
+- project locations
+- similarity score or confidence
+- a short explanation of why the pair was flagged
+
+## Backfill and Migration Strategy
+
+### Chosen Strategy
+
+The backfill strategy is hybrid:
+
+- lazy auto-backfill on first graph-tool use;
+- explicit rebuild/backfill path available for repair and mass reindexing.
+
+### Why Hybrid
+
+Pure manual backfill adds friction for existing users. Purely automatic migration hides too much state change and makes repair harder.
+
+Hybrid gives the best trade-off:
+
+- old vaults keep working immediately;
+- derived graph state appears when needed;
+- operators still have a deterministic rebuild path if state gets stale or corrupted.
+
+### Requirements
+
+- First-time graph access must not require a full blocking migration unless unavoidable.
+- Backfill must be resumable or rebuildable.
+- Any rebuild path should produce the same derived state from the same note corpus.
+
+## Storage Model
+
+### Chosen Model
+
+Storage is hybrid.
+
+### Intent
+
+Per-note and per-project source data stays close to existing storage boundaries, while link/global lookup indexes may be maintained in a derived structure optimized for recall and traversal.
+
+### Requirements
+
+- Graph state must be derived from canonical note content and metadata.
+- Rebuilding graph state must be possible without manual note editing.
+- Storage decisions should not break existing project isolation assumptions.
+- Global lookup structures must still preserve project attribution for every note.
+
+## Tool Surface
+
+The MCP surface remains separated into three tools:
+
+- `memory_link`
+- `memory_global_recall`
+- `memory_dedup`
+
+### Why Separate Tools
+
+Separate tools are easier to reason about, easier to test, and easier to evolve independently.
+
+They also map cleanly to user intent:
+
+- linking/traversal
+- cross-project search
+- duplicate analysis
+
+A monolithic graph tool would complicate input/output contracts too early.
+
+## Fallback Behavior Matrix
+
+### Fully configured environment
+
+If keyword, embeddings, and graph metadata are all available:
+
+- use standard retrieval candidate generation;
+- use semantic similarity where supported;
+- apply graph-aware soft boosting;
+- return explanatory provenance.
+
+### No embeddings configured
+
+If embeddings are unavailable:
+
+- use keyword/deterministic candidate generation;
+- still use same-project bias and graph-aware boosting;
+- maintain tool usability without surfacing provider errors as hard blockers.
+
+### No graph-derived state yet
+
+If graph state is missing:
+
+- trigger lazy backfill where appropriate;
+- if backfill cannot complete immediately, fall back to non-graph retrieval behavior and explain that graph augmentation is incomplete.
+
+## Error Handling Expectations
+
+### Ambiguous links
+
+Return candidate matches and ambiguity metadata.
+
+### Missing project target
+
+Return a clear unresolved-reference result.
+
+### Missing embeddings provider
+
+Do not fail the request if semantic retrieval is optional for that path.
+
+### Derived-state drift
+
+Expose enough information for future rebuild/repair tooling rather than silently masking corruption.
+
+## Testing Implications
+
+`v1.5.0` should add tests for at least:
+
+- same-project `[[title]]` resolution
+- same-project `[[id]]` resolution
+- explicit cross-project override resolution
+- ambiguous title resolution behavior
+- unresolved link behavior
+- global recall preferring same-project hits
+- global recall fallback to other projects
+- dedup suggestions with default threshold `0.90`
+- dedup non-destructive behavior
+- recall fallback behavior when embeddings are unavailable
+- lazy backfill behavior for pre-existing vault state
+
+## Open Implementation Notes
+
+These are implementation notes, not unresolved design questions:
+
+- The graph layer should reuse as much existing note indexing infrastructure as practical.
+- Derived state should be cheap to invalidate and rebuild.
+- Output shapes should be designed for future observability fields, even if `v1.5.0` does not yet expose all diagnostics.
+- Existing recall-mode behavior introduced in `v1.4.0` should remain conceptually compatible with the new global recall path.
+
+## Risks
+
+### Scope creep
+
+Knowledge graph features can expand very quickly. The release avoids that by limiting scope to three tools only.
+
+### Ambiguity explosion
+
+Title-based linking across projects can create ambiguity. This is handled with same-project bias and explicit project override syntax.
+
+### Over-dependence on semantic infrastructure
+
+If graph quality depends too much on embeddings, many users lose value. This is mitigated by requiring a strong keyword/deterministic fallback path.
+
+### Hidden state issues
+
+Any lazy derived-state system can drift or fail partially. This is mitigated by keeping state rebuildable and by preserving an explicit rebuild path.
+
+## Out of Scope for Later Releases
+
+### `v1.5.1` Observability
+
+Likely follow-up concerns:
+
+- graph/index health visibility
+- recall provenance inspection
+- stats/watch-style diagnostics
+- duplicate trend metrics
+
+### `v1.5.2` Lifecycle
+
+Likely follow-up concerns:
+
+- cleanup workflows
+- archival guidance
+- merge-assist flows
+- stale-link repair flows
+
+## Final Recommendation
+
+Ship `v1.5.0` as a focused knowledge-graph release with three separate tools, hybrid backfill, safe dedup suggestions, and graph-aware recall that still works without embeddings.
+
+This gives Dev MCP Suite a meaningful relationship layer without overcommitting the release to automation, destructive behavior, or provider-specific assumptions.

package/package.json

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