@maximalabs/dev-mcp-suite 0.0.0-stage → 3.6.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.env.example +69 -0
- package/CHANGELOG.md +271 -0
- package/CODEX_DEV_MCP_GUIDE.md +297 -0
- package/LICENSE +21 -0
- package/README.md +193 -2
- package/armada/package.json +14 -0
- package/armada/server.js +329 -0
- package/backfill-sessions-v2.mjs +288 -0
- package/bin/_meta.mjs +73 -0
- package/bin/armada-mcp.mjs +12 -0
- package/bin/checkpoint.mjs +9 -0
- package/bin/context-pack.mjs +9 -0
- package/bin/devjournal.mjs +9 -0
- package/bin/init.mjs +25 -0
- package/bin/project-memory.mjs +10 -0
- package/bin/provider-smoke.mjs +278 -0
- package/bin/prune.mjs +158 -0
- package/bin/stats.mjs +101 -0
- package/bin/ui.mjs +5 -0
- package/checkpoint/package.json +14 -0
- package/checkpoint/server.js +318 -0
- package/context-pack/package.json +14 -0
- package/context-pack/server.js +747 -0
- package/devjournal/compress.js +75 -0
- package/devjournal/env.js +3 -0
- package/devjournal/package.json +14 -0
- package/devjournal/provider-chain.js +109 -0
- package/devjournal/rerank.js +120 -0
- package/devjournal/server.js +415 -0
- package/docs/ROADMAP.md +77 -0
- package/docs/clients/antigravity.md +52 -0
- package/docs/clients/claude-code.md +46 -0
- package/docs/clients/codex.md +39 -0
- package/docs/clients/generic-mcp.md +45 -0
- package/docs/clients/hermes.md +48 -0
- package/docs/configuration.md +123 -0
- package/docs/privacy.md +39 -0
- package/docs/providers.md +13 -0
- package/docs/superpowers/plans/2026-06-15-hardening-v1-2-implementation.md +60 -0
- package/docs/superpowers/plans/2026-06-15-provider-chain-v1-1-implementation.md +65 -0
- package/docs/superpowers/plans/2026-06-15-provider-client-agnostic-config.md +41 -0
- package/docs/superpowers/plans/2026-06-15-trust-release-implementation.md +62 -0
- package/docs/superpowers/plans/2026-06-18-v1-5-0-knowledge-graph.md +792 -0
- package/docs/superpowers/specs/2026-06-15-provider-chain-v1-1-design.md +89 -0
- package/docs/superpowers/specs/2026-06-15-trust-release-design.md +164 -0
- package/docs/superpowers/specs/2026-06-18-dev-mcp-suite-v1-5-0-knowledge-graph-design.md +386 -0
- package/docs/superpowers/specs/2026-07-22-v2-0-0-peak-intelligence.md +50 -0
- package/docs/superpowers/specs/2026-07-22-v3-0-0-god-tier.md +32 -0
- package/lib/init-wizard.js +120 -0
- package/lib/provider-smoke.js +234 -0
- package/lib/prune.js +114 -0
- package/lib/stats.js +269 -0
- package/lib/ui-server.js +151 -0
- package/lib/update-check.js +125 -0
- package/package.json +71 -4
- package/project-memory/auto-indexer.js +152 -0
- package/project-memory/dedup.js +49 -0
- package/project-memory/embedding.js +174 -0
- package/project-memory/env.js +3 -0
- package/project-memory/global-index.js +46 -0
- package/project-memory/graph.js +93 -0
- package/project-memory/local-embed.js +92 -0
- package/project-memory/package.json +14 -0
- package/project-memory/provider-chain.js +109 -0
- package/project-memory/rerank.js +120 -0
- package/project-memory/server.js +931 -0
- package/project-memory/swarm.js +56 -0
- package/run-tests.mjs +54 -0
package/.env.example
ADDED
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
# All network features are OPTIONAL. Without them, recall falls back to keyword
|
|
2
|
+
# search (fully offline). Any OpenAI-compatible endpoint works: OpenAI, Ollama,
|
|
3
|
+
# LM Studio, Groq, Cerebras, OpenRouter, vLLM, LiteLLM, 9router, etc.
|
|
4
|
+
|
|
5
|
+
# Hard no-network mode. When true, disables embeddings/rerank even if keys exist.
|
|
6
|
+
# Accepted true values: true, 1, yes, on.
|
|
7
|
+
# MCP_DETERMINISTIC_FALLBACK=true
|
|
8
|
+
|
|
9
|
+
# Optional provider chain for chat/rerank. Configure only primary, or add
|
|
10
|
+
# numbered fallbacks. Groq/Cerebras/OpenRouter are recommended examples; any
|
|
11
|
+
# OpenAI-compatible base URL + API key + model ID works.
|
|
12
|
+
# MCP_PROVIDER_PRIMARY=groq
|
|
13
|
+
# MCP_PROVIDER_PRIMARY_BASE_URL=https://api.groq.com/openai/v1
|
|
14
|
+
# MCP_PROVIDER_PRIMARY_API_KEY=<groq-key>
|
|
15
|
+
# MCP_PROVIDER_PRIMARY_MODEL=llama-3.3-70b-versatile
|
|
16
|
+
# MCP_PROVIDER_CHAIN2=cerebras
|
|
17
|
+
# MCP_PROVIDER_CHAIN2_BASE_URL=https://api.cerebras.ai/v1
|
|
18
|
+
# MCP_PROVIDER_CHAIN2_API_KEY=<cerebras-key>
|
|
19
|
+
# MCP_PROVIDER_CHAIN2_MODEL=llama-3.3-70b
|
|
20
|
+
# MCP_PROVIDER_CHAIN3=openrouter
|
|
21
|
+
# MCP_PROVIDER_CHAIN3_BASE_URL=https://openrouter.ai/api/v1
|
|
22
|
+
# MCP_PROVIDER_CHAIN3_API_KEY=<openrouter-key>
|
|
23
|
+
# MCP_PROVIDER_CHAIN3_MODEL=openai/gpt-4o-mini
|
|
24
|
+
|
|
25
|
+
# Cooldown (ms) before retrying a provider after a 429/5xx/timeout failure.
|
|
26
|
+
# MCP_PROVIDER_COOLDOWN_MS=60000
|
|
27
|
+
|
|
28
|
+
# Base URL of an OpenAI-compatible API (must expose /v1/...)
|
|
29
|
+
MCP_LLM_BASE_URL=http://localhost:11434/v1
|
|
30
|
+
# API key for that endpoint (leave blank for local servers that don't need one)
|
|
31
|
+
MCP_LLM_API_KEY=
|
|
32
|
+
|
|
33
|
+
# Optional: semantic embedding recall (needs /v1/embeddings)
|
|
34
|
+
MCP_EMBED_MODEL=nomic-embed-text
|
|
35
|
+
EMBED_TIMEOUT_MS=12000
|
|
36
|
+
|
|
37
|
+
# Optional: LLM rerank recall (needs /v1/chat/completions)
|
|
38
|
+
# Used automatically when embeddings are unavailable.
|
|
39
|
+
MCP_RERANK_MODEL=llama3.1:8b
|
|
40
|
+
RERANK_TIMEOUT_MS=30000
|
|
41
|
+
RERANK_ENABLED=1
|
|
42
|
+
|
|
43
|
+
|
|
44
|
+
# === Cloudflare Workers AI (REST-only, NOT OpenAI-compatible) ===
|
|
45
|
+
# Free tier: 10,000 neurons/day. No laptop resource usage.
|
|
46
|
+
# To get started: dash.cloudflare.com → Workers & Pages → Create Worker → Workers AI → enable
|
|
47
|
+
# Account ID: from dashboard sidebar. API Token: My Profile → API Tokens → "Edit Cloudflare Workers".
|
|
48
|
+
# Note: base URL has trailing slash; model name goes in URL path, not body.
|
|
49
|
+
# Set CLOUDFLARE_EMBED_MODEL (e.g. @cf/baai/bge-base-en-v1.5) to enable semantic recall
|
|
50
|
+
# via Cloudflare instead of 9router/OpenAI/etc.
|
|
51
|
+
# MCP_EMBED_BASE_URL=https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/ai/run/
|
|
52
|
+
# MCP_EMBED_API_KEY=<cf-token>
|
|
53
|
+
# MCP_EMBED_MODEL=@cf/baai/bge-base-en-v1.5
|
|
54
|
+
|
|
55
|
+
# === Google Gemini (OpenAI-compatible, generous free tier) ===
|
|
56
|
+
# Get key: https://aistudio.google.com/app/apikey
|
|
57
|
+
# Free tier: 60 req/min, 1500/day for text-embedding-004
|
|
58
|
+
# GEMINI_BASE_URL=https://generativelanguage.googleapis.com/v1beta/openai
|
|
59
|
+
# GEMINI_API_KEY=<gemini-key>
|
|
60
|
+
# GEMINI_MODEL=text-embedding-004
|
|
61
|
+
|
|
62
|
+
# Storage locations (defaults shown; override if you want)
|
|
63
|
+
# MEMORY_VAULT_DIR=~/.codex/memories/vault
|
|
64
|
+
# JOURNAL_DIR=~/.codex/memories/journal
|
|
65
|
+
# CHECKPOINT_DIR=~/.codex/memories/checkpoints
|
|
66
|
+
|
|
67
|
+
# Backward-compatible aliases (still honored): LLM_BASE_URL, LLM_API_KEY,
|
|
68
|
+
# NINEROUTER_URL, NINEROUTER_KEY, EMBED_MODEL, RERANK_MODEL, EMBED_URL,
|
|
69
|
+
# EMBED_KEY, RERANK_URL, RERANK_KEY
|
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,271 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
## 3.6.0 - 2026-11-22 — Rebrand @maximalabs + Armada Fleet MCP 🛰️
|
|
4
|
+
|
|
5
|
+
### Changed
|
|
6
|
+
- **Package renamed `codex-dev-mcp-suite` → `@maximalabs/dev-mcp-suite`**:
|
|
7
|
+
umbrella brand MaximaLabs (npm org + GitHub org). Repository moves to
|
|
8
|
+
`github.com/MaximaLabs/dev-mcp-suite`. npm cannot rename a published
|
|
9
|
+
package — the old name stays installable and gets a `npm deprecate`
|
|
10
|
+
pointer; bin names unchanged, self-named bin is now `dev-mcp-suite`
|
|
11
|
+
(npx strips the scope).
|
|
12
|
+
- `lib/update-check.js`: registry URL encodes the scope (`%2F`) so
|
|
13
|
+
update checks hit the scoped package.
|
|
14
|
+
- `lib/init-wizard.js`, `bin/init.mjs`, `docs/clients/*`, badges and all
|
|
15
|
+
living docs updated; dated specs and past CHANGELOG entries keep the
|
|
16
|
+
historical name on purpose.
|
|
17
|
+
|
|
18
|
+
### Added
|
|
19
|
+
- **`armada` MCP server (5th, optional)**: bridges MCP clients to an
|
|
20
|
+
[Armada](https://github.com/verrysimatupang99/armada) bus — append-only
|
|
21
|
+
mailbox + policy-gated job queue for fleets of hosts. 9 tools:
|
|
22
|
+
`fleet_health`, `fleet_jobs`, `job_post`, `job_status`, `job_watch`,
|
|
23
|
+
`job_tail`, `job_cancel`, `bus_note`, `bus_read`.
|
|
24
|
+
- Config via `ARMADA_BUS_URL` / `ARMADA_BUS_TOKEN` / `ARMADA_AGENT` env or
|
|
25
|
+
`~/.config/armada/agent.env` (shared with the `armada` CLI).
|
|
26
|
+
- `armada-mcp` bin entry; **not** auto-registered by `init` — it points at
|
|
27
|
+
the user's own fleet and needs credentials.
|
|
28
|
+
- `armada/test.mjs`: 9 tests against an in-memory fake bus (list tools,
|
|
29
|
+
health board, note/read, job lifecycle, dedupe, cancel, missing-token
|
|
30
|
+
error) using the shared `_testkit` harness.
|
|
31
|
+
- Verified end-to-end against the real Python `bus/server.py`: job_post →
|
|
32
|
+
job_status → bus_note → bus_read.
|
|
33
|
+
|
|
34
|
+
## 3.5.1 - 2026-09-13 — Docs Sync Release 📄
|
|
35
|
+
|
|
36
|
+
### Fixed
|
|
37
|
+
- **Published Package Docs**: The v3.5.0 npm tarball was built before the docs commit, shipping a stale `CHANGELOG.md` (missing the 3.5.0 entry) and `docs/ROADMAP.md` (still v1.7.0 content). This release syncs both into the published package.
|
|
38
|
+
- No code changes — identical to v3.5.0 logic (113/113 unit tests pass).
|
|
39
|
+
|
|
40
|
+
## 3.5.0 - 2026-09-01 — Token-Dense Briefing, Standup Digest & Semantic Session Import ⚡
|
|
41
|
+
|
|
42
|
+
### Added
|
|
43
|
+
- **Ultra High-Density Project Briefing (`context-pack`)**:
|
|
44
|
+
- Added `pack_dense_brief` tool providing ultra-compact project overviews (stack, active branch, entry points, exported symbols, test commands) optimized to save 30–50% context window tokens on session start.
|
|
45
|
+
- **Cross-Session Standup & Daily Summary (`devjournal`)**:
|
|
46
|
+
- Added `journal_standup` tool aggregating recent session handoffs, recent bugfixes, and active blockers into a structured daily standup report.
|
|
47
|
+
- **Direct Session Transcript Import (`project-memory`)**:
|
|
48
|
+
- Added `memory_import_session` tool to ingest conversation logs (`.jsonl`, `.json`, `.log`) directly into permanent knowledge notes with automatic decision extraction.
|
|
49
|
+
- **Fast Content & Pattern Search (`context-pack`)**:
|
|
50
|
+
- Added `pack_find_todos` to surface `@todo`, `FIXME`, and pending task markers across codebase.
|
|
51
|
+
- Added `pack_search` for fast path-and-content substring search without spawning external processes.
|
|
52
|
+
- **Unified Change Inspection (`checkpoint`)**:
|
|
53
|
+
- Unified multi-file diff detection and status reporting in `checkpoint_diff`.
|
|
54
|
+
|
|
55
|
+
### Fixed
|
|
56
|
+
- **MCP Schema Compatibility**:
|
|
57
|
+
- Cleaned double-brace escaping across all 4 MCP server tool definitions ensuring 100% compliance with strict JSON-RPC validators.
|
|
58
|
+
|
|
59
|
+
## 3.2.0 - 2026-07-27 — Session Conversation Watchdog & Transcript Digesting 🧠
|
|
60
|
+
|
|
61
|
+
### Added
|
|
62
|
+
- **Session Conversation Watchdog & Transcript Digesting (`project-memory`)**:
|
|
63
|
+
- Added `scanSessionLogs()` helper in `auto-indexer.js` to autonomously scan recent `.jsonl`, `.json`, or `.log` session transcript files across `.codex/`, `.gemini/`, `.agents/logs/`, and custom session directories.
|
|
64
|
+
- Heuristic keyword analysis automatically detects architectural decisions, migration plans, and strategy discussions (e.g., V1 vs V2 trading bots).
|
|
65
|
+
- Upgraded `memory_auto_index` tool schema (`server.js`) with `scanSessions` and `sessionDir` parameters.
|
|
66
|
+
- Auto-derived decisions are now persisted directly into the Obsidian knowledge vault as individual notes (`notesCreated`), ensuring key chat discussions are permanently indexed and searchable via `memory_recall`.
|
|
67
|
+
## 3.1.1 - 2026-07-22 — CI/CD Hardening & Complete Wizard Tracking 🛡️
|
|
68
|
+
|
|
69
|
+
### Fixed
|
|
70
|
+
- Verified 100% GREEN GitHub Actions CI status across Node 18.x, 20.x, and 22.x matrix.
|
|
71
|
+
- Ensure all installer wizard binaries (`bin/init.mjs`, `bin/ui.mjs`, `lib/init-wizard.js`) are fully tracked and published.
|
|
72
|
+
|
|
73
|
+
## 3.1.0 - 2026-07-22 — Interactive Installer Wizard & CI Suite 🛠️
|
|
74
|
+
|
|
75
|
+
### Added
|
|
76
|
+
- **`npx codex-dev-mcp-suite init` (Auto-Config Installer Wizard)**:
|
|
77
|
+
- Interactive CLI wizard (`lib/init-wizard.js` & `bin/init.mjs`) that automatically detects installed AI clients (Codex CLI, Claude Code, Cursor, Windsurf, Hermes Agent, Antigravity CLI) and injects the 4 MCP server configurations into their respective config files.
|
|
78
|
+
- **GitHub Actions Smoke Expansion**:
|
|
79
|
+
- Extended `.github/workflows/ci.yml` package-smoke test to verify all 6 executable binaries and the `init` wizard.
|
|
80
|
+
- **Real-World Multi-Agent Vibe Coding Guide (`examples/multi-agent-vibe-coding.md`)**:
|
|
81
|
+
- Sample workflows demonstrating how to combine Antigravity, Hermes, Claude Code, and Codex CLI using swarm streams, checkpoints, and impact prediction.
|
|
82
|
+
|
|
83
|
+
## 3.0.0 - 2026-07-22 — The Autonomous Agent OS Edition (God-Tier) 🌌
|
|
84
|
+
|
|
85
|
+
### Added
|
|
86
|
+
- **Pillar 1: Live Dev-Server & Log Telemetry (`pack_telemetry`)**:
|
|
87
|
+
- Surface live dev server errors (`dev.log`, `error.log`, `/tmp/dev.log`, `.next/server.log`) directly into agent context without manual copy-pasting (`context-pack`).
|
|
88
|
+
- **Pillar 2: Autonomous Background Git & Mtime Observer (`memory_auto_index`)**:
|
|
89
|
+
- Automatically inspect recent git commits, branch switches, and file modifications to auto-derive project notes (`project-memory`).
|
|
90
|
+
- **Pillar 3: Predictive Contract & Schema Impact Simulation (`pack_predictive_diff`)**:
|
|
91
|
+
- Simulate proposed file diffs against caller files to predict breaking API signatures or database schema changes (`context-pack`).
|
|
92
|
+
- **Pillar 4: Built-in Interactive Web GUI Dashboard (`mcp-ui`)**:
|
|
93
|
+
- Launch a zero-dependency 3D/2D Knowledge Graph & Memory Web Dashboard on `http://localhost:3333` via `mcp-ui` (`bin/ui.mjs`).
|
|
94
|
+
|
|
95
|
+
## 2.0.0 - 2026-07-22 — The Peak Intelligence Edition 🚀
|
|
96
|
+
|
|
97
|
+
### Added
|
|
98
|
+
- **Pillar 1: Dependency Blast-Radius (`pack_impact`)**:
|
|
99
|
+
- Analyze code imports (`import`/`export`/`require`) and compute caller fan-out scores before refactoring files (`context-pack`).
|
|
100
|
+
- **Pillar 2: Self-Healing Pre-flight Diagnostics (`pack_guard`)**:
|
|
101
|
+
- Run typechecks (`tsc`), lints, and test suites with built-in timeout guards to ensure 100% bug-free AI output (`context-pack`).
|
|
102
|
+
- **Pillar 3: Multi-Agent Swarm Stream (`memory_broadcast` & `memory_swarm_timeline`)**:
|
|
103
|
+
- Real-time event stream broadcasting across peer subagents (Antigravity, Hermes, Codex, Claude Code, Cursor) working in the same workspace (`project-memory`).
|
|
104
|
+
- **Pillar 4: Session Time-Machine & Token Compressor (`journal_compress`)**:
|
|
105
|
+
- Condense 50+ turns of verbose session logs into a 500-token compact snapshot to cut token costs by ~90% (`devjournal`).
|
|
106
|
+
|
|
107
|
+
## 1.9.0 - 2026-07-22
|
|
108
|
+
|
|
109
|
+
### Added
|
|
110
|
+
- **Non-Blocking Upstream Update Checker (`lib/update-check.js`)**:
|
|
111
|
+
- Automatically queries npm registry in the background once every 24 hours (cached locally).
|
|
112
|
+
- Notifies users via `stderr` when a new version of `codex-dev-mcp-suite` is published to upstream npm.
|
|
113
|
+
- Safe for stdio MCP JSON-RPC protocol transport; sub-millisecond execution, zero startup latency.
|
|
114
|
+
|
|
115
|
+
## 1.8.0 - 2026-07-22
|
|
116
|
+
|
|
117
|
+
### Added
|
|
118
|
+
- **Zero-Dependency Local Offline Vector Embedding Engine**:
|
|
119
|
+
- Pure JS 384-dimensional term-frequency hashing vector engine with sublinear $1 + \log(tf)$ scaling and L2 normalization (`project-memory/local-embed.js`).
|
|
120
|
+
- Activated via `MCP_LOCAL_EMBED=true` / `LOCAL_EMBED=true` env flag when no remote embedding API key is available.
|
|
121
|
+
- Sub-millisecond execution, zero network calls, zero external npm dependencies.
|
|
122
|
+
- Full compatibility with existing `cosine(a, b)` and graph ranking in `project-memory`.
|
|
123
|
+
- **Universal Multi-Client Guides**:
|
|
124
|
+
- Hermes Agent setup guide (`docs/clients/hermes.md`).
|
|
125
|
+
- Google Antigravity CLI (AGY CLI) setup guide (`docs/clients/antigravity.md`).
|
|
126
|
+
- Claude Code & Generic MCP setup guides (`docs/clients/claude-code.md`, `docs/clients/generic-mcp.md`).
|
|
127
|
+
- **Test Suite**: 100/100 unit tests passing (100% green across 8 test suites).
|
|
128
|
+
|
|
129
|
+
## 1.7.0 - 2026-07-22
|
|
130
|
+
|
|
131
|
+
### Added
|
|
132
|
+
- **Obsidian Vault Parity & MOC Tools**:
|
|
133
|
+
- `memory_moc` Map of Content generator & `.obsidian` vault structure integration.
|
|
134
|
+
- `memory_graph` knowledge graph visualization & backlinks.
|
|
135
|
+
- **Codebase Security Audit Tool (`pack_audit`)**:
|
|
136
|
+
- Detect missing `.gitignore`, exposed secrets/keys (`.env`, `.pem`, `id_rsa`), and overly large files.
|
|
137
|
+
|
|
138
|
+
## 1.5.0
|
|
139
|
+
|
|
140
|
+
- add `memory_link` with wiki-link resolution for `[[id]]`, `[[title]]`, `[[project:id]]`, and `[[project:title]]`, plus backlink inspection
|
|
141
|
+
- add `memory_global_recall` with same-project bias and graceful keyword/semantic fallback across project vaults
|
|
142
|
+
- add `memory_dedup` with non-destructive duplicate suggestions for project or global scope
|
|
143
|
+
- add hybrid lazy graph backfill so link metadata is derived on first graph-aware use and remains rebuildable from canonical notes
|
|
144
|
+
- add graph-aware soft boost in recall paths without making embeddings mandatory
|
|
145
|
+
- 36 project-memory tests pass after graph/global/dedup coverage expansion
|
|
146
|
+
|
|
147
|
+
|
|
148
|
+
## 1.4.0 - 2026-06-17
|
|
149
|
+
|
|
150
|
+
### Added
|
|
151
|
+
- **`provider-smoke` CLI** (`bin/provider-smoke.mjs`): probe every configured LLM provider (chat + embeddings) and print a matrix of latency / status / sample. Useful after adding a new API key or comparing providers.
|
|
152
|
+
- Usage: `npx -y -p codex-dev-mcp-suite provider-smoke` (or globally `provider-smoke`)
|
|
153
|
+
- Flags: `--json`, `--markdown`, `--save-md <path>`, `--chat-only`, `--embed-only`, `--env-file <path>`, `--only a,b,c`, `--timeout <ms>`, `--help`, `--version`
|
|
154
|
+
- Auto-detects providers from `MCP_PROVIDER_*` slots + named env (`GROQ_*`, `CEREBRAS_*`, `MISTRAL_*`, `OPENROUTER_*`, `OPENAI_*`, `OLLAMA_*`, `ANTHROPIC_*`, `GEMINI_*`, `COHERE_*`, `VOYAGE_*`, `CLOUDFLARE_*`) + `MCP_LLM_BASE_URL` / `NINEROUTER_URL` fallback.
|
|
155
|
+
- Pure-function library at `lib/provider-smoke.js` (18 offline tests).
|
|
156
|
+
- `KNOWN_PROVIDERS` registry covers 11 providers with `supportsChat` / `supportsEmbed` flags + `endpoint: "openai-compatible" | "cloudflare"`.
|
|
157
|
+
- Cloudflare embed-only models (`@cf/baai/*`, `@cf/google/embedding*`, etc.) are detected and the chat probe is skipped with a clear annotation.
|
|
158
|
+
- **Cloudflare Workers AI support** for embeddings: drop-in alternative when 9router/OpenAI are unavailable. Set `MCP_EMBED_BASE_URL=https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/ai/run/`, `MCP_EMBED_API_KEY=<token>`, `MCP_EMBED_MODEL=@cf/baai/bge-base-en-v1.5`.
|
|
159
|
+
- Cloudflare's REST API (non-OpenAI-compatible, model-in-path) is auto-detected by URL pattern and dispatched to a separate code path in `project-memory/embedding.js`.
|
|
160
|
+
- New `isCloudflareURL()` + `httpPostJson()` helpers; `embedCloudflare()` handles `{text: [...]}` body and `{result: {data: [[...]]}}` response.
|
|
161
|
+
- `embeddingConfig().mode` and `recallMode()` helpers expose what retrieval mode is active (`semantic` / `keyword` / `deterministic`).
|
|
162
|
+
- **`memory_recall` mode arg** (default `"auto"`): explicit control over fallback behavior. `mode: "semantic"` requires embedding (returns `isError: true` if unavailable), `mode: "keyword"` skips embedding entirely.
|
|
163
|
+
- **Recall output annotation** now shows `[semantic+rerank]` / `[keyword+rerank]` when LLM rerank is active, making the active mode fully transparent.
|
|
164
|
+
- **Top-level test runner hook** (added in 1.3.0, expanded in 1.4.0): `tests/*.test.mjs` are auto-picked-up by `node run-tests.mjs`.
|
|
165
|
+
|
|
166
|
+
### Tests
|
|
167
|
+
- 85 tests pass (was 60 in v1.3.0): 26 project-memory + 6 checkpoint + 6 context-pack + 11 devjournal + 18 provider-smoke + 9 prune + 9 stats.
|
|
168
|
+
- New fallback tests: `mode=keyword` skips semantic, `mode=semantic` without embed key returns isError, default mode=auto, no `+rerank` suffix when rerank disabled.
|
|
169
|
+
|
|
170
|
+
### Docs
|
|
171
|
+
- `docs/providers.md` rewritten: 11-provider matrix, Cloudflare setup caveat, Ollama resource cost, "no API key" graceful degradation notes.
|
|
172
|
+
- `README.md` updated: "Memory Recall Modes" section, Cloudflare + Gemini setup examples, 4-mode annotation examples.
|
|
173
|
+
- `.env.example` updated: copy-pasteable config blocks for Cloudflare Workers AI and Google Gemini.
|
|
174
|
+
|
|
175
|
+
|
|
176
|
+
|
|
177
|
+
## 1.3.0 - 2026-06-17
|
|
178
|
+
|
|
179
|
+
### Added
|
|
180
|
+
- New `stats` CLI: summarize local memory storage across vault / journal / checkpoints. Shows totals, top projects by notes, most recent activity, and temp-slug cleanup candidates.
|
|
181
|
+
- Usage: `npx -y -p codex-dev-mcp-suite stats` (or globally `stats`)
|
|
182
|
+
- Flags: `--root <path>`, `--json`, `--top N`, `--help`, `--version`
|
|
183
|
+
- Pure-function library at `lib/stats.js` (no MCP / no stdio); tested offline.
|
|
184
|
+
- New top-level test runner hook: `tests/*.test.mjs` are auto-picked-up by `node run-tests.mjs`.
|
|
185
|
+
- New `provider-smoke` CLI: probe every configured LLM provider (chat + embeddings) and print a matrix of latency / status / sample. Useful after adding a new API key or to compare providers.
|
|
186
|
+
- Usage: `npx -y -p codex-dev-mcp-suite provider-smoke`
|
|
187
|
+
- Flags: `--json`, `--markdown`, `--save-md <path>`, `--chat-only`, `--embed-only`, `--env-file <path>`, `--timeout <ms>`
|
|
188
|
+
- Detects providers from `MCP_PROVIDER_*` slots + named env (`GROQ_*`, `CEREBRAS_*`, `MISTRAL_*`, `OPENROUTER_*`, `OPENAI_*`, `OLLAMA_*`, `ANTHROPIC_*`, `GEMINI_*`, `COHERE_*`) + `MCP_LLM_BASE_URL` / `NINEROUTER_URL` fallback.
|
|
189
|
+
- Pure-function library at `lib/provider-smoke.js`; tested offline.
|
|
190
|
+
- New docs page `docs/providers.md` — auto-generated smoke matrix from latest run.
|
|
191
|
+
|
|
192
|
+
|
|
193
|
+
|
|
194
|
+
|
|
195
|
+
|
|
196
|
+
|
|
197
|
+
### Added
|
|
198
|
+
- New `prune` CLI: remove temp project slugs (prefix `tmp.`) from vault, journal, and checkpoints. Default is DRY-RUN — nothing is deleted without `--yes`.
|
|
199
|
+
- Usage: `npx -y -p codex-dev-mcp-suite prune` (or globally `prune`)
|
|
200
|
+
- Flags: `--root <path>`, `--yes`, `--json`, `--help`, `--version`
|
|
201
|
+
- Pure-function library at `lib/prune.js`; tested offline.
|
|
202
|
+
- Safety: refuses to delete any slug that does not start with `tmp.`.
|
|
203
|
+
- New MCP tool `memory_stats` on the project-memory server: returns the same summary as the `stats` CLI. Useful for in-session introspection from an MCP client.
|
|
204
|
+
- Args: `root?`, `top?` (default 10), `json?` (default false).
|
|
205
|
+
|
|
206
|
+
|
|
207
|
+
|
|
208
|
+
### Added
|
|
209
|
+
- **Cloudflare Workers AI support** for embeddings and chat: drop-in alternative when 9router/OpenAI are unavailable. Set `MCP_EMBED_BASE_URL=https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/ai/run/`, `MCP_EMBED_API_KEY=<token>`, `MCP_EMBED_MODEL=@cf/baai/bge-base-en-v1.5`. Cloudflare's REST API (non-OpenAI-compatible) is auto-detected by URL pattern and dispatched to a separate code path in `project-memory/embedding.js`. Includes `isCloudflareURL()` detection + `endpoint: "cloudflare"` field in provider matrix.
|
|
210
|
+
- `provider-smoke` CLI: probe Cloudflare alongside OpenAI-compatible providers. Cloudflare chat returns 400 for embed-only models (expected — they don't support chat).
|
|
211
|
+
|
|
212
|
+
## 1.2.0 - 2026-06-15
|
|
213
|
+
|
|
214
|
+
### Added
|
|
215
|
+
- CLI meta handling for all bins: `--help`, `--version`, and `--doctor` (config diagnostics with API keys redacted) before the stdio server starts.
|
|
216
|
+
- Provider diagnostics `providerChainDiagnostics()` that lists active providers with redacted keys and flags incomplete numbered slots.
|
|
217
|
+
- Per-provider cooldown on `429`/`5xx`/timeout/network failures via `MCP_PROVIDER_COOLDOWN_MS` (default `60000`).
|
|
218
|
+
- CI job that packs the tarball, installs it in a temp dir, and runs each bin `--version`.
|
|
219
|
+
|
|
220
|
+
### Changed
|
|
221
|
+
- Rerank now skips providers that are cooling down and records success/failure outcomes.
|
|
222
|
+
- Rerank never logs API keys or response bodies.
|
|
223
|
+
|
|
224
|
+
## 1.1.0 - 2026-06-15
|
|
225
|
+
|
|
226
|
+
### Added
|
|
227
|
+
- Added optional numbered provider chain for chat/rerank fallback: `MCP_PROVIDER_PRIMARY_*`, `MCP_PROVIDER_CHAIN2_*`, `MCP_PROVIDER_CHAIN3_*`, and higher.
|
|
228
|
+
- Added provider-chain tests for ordered fallback, incomplete slot skipping, deterministic disable, and legacy fallback.
|
|
229
|
+
|
|
230
|
+
## 1.0.1 - 2026-06-15
|
|
231
|
+
|
|
232
|
+
### Added
|
|
233
|
+
- Added neutral `MCP_*` environment variables for model configuration:
|
|
234
|
+
- `MCP_LLM_BASE_URL`, `MCP_LLM_API_KEY`
|
|
235
|
+
- `MCP_RERANK_BASE_URL`, `MCP_RERANK_API_KEY`, `MCP_RERANK_MODEL`
|
|
236
|
+
- `MCP_EMBED_BASE_URL`, `MCP_EMBED_API_KEY`, `MCP_EMBED_MODEL`
|
|
237
|
+
- Added client-agnostic docs:
|
|
238
|
+
- `docs/configuration.md`
|
|
239
|
+
- `docs/clients/codex.md`
|
|
240
|
+
- `docs/clients/claude-code.md`
|
|
241
|
+
- `docs/clients/generic-mcp.md`
|
|
242
|
+
- Added tests proving `MCP_*` env vars override legacy aliases.
|
|
243
|
+
- Added `MCP_DETERMINISTIC_FALLBACK` hard no-network mode for deterministic local-only recall.
|
|
244
|
+
- Added `docs/privacy.md` covering local storage, data flow, and remote provider boundaries.
|
|
245
|
+
- Added provider guidance for Groq, Cerebras, and OpenRouter as optional external endpoints.
|
|
246
|
+
|
|
247
|
+
### Changed
|
|
248
|
+
- README now presents the project as **Dev MCP Suite** while keeping the npm package name `codex-dev-mcp-suite` for compatibility.
|
|
249
|
+
- Rerank and embedding helpers now describe any OpenAI-compatible endpoint, not 9Router only.
|
|
250
|
+
- `.env.example` now recommends `MCP_*` names for new installs.
|
|
251
|
+
- `memory_recall`, `journal_search`, and `memory_reindex` now explicitly respect deterministic no-network mode.
|
|
252
|
+
|
|
253
|
+
### Compatibility
|
|
254
|
+
- Legacy env names remain supported: `LLM_*`, `NINEROUTER_*`, `EMBED_*`, and `RERANK_*`.
|
|
255
|
+
- Offline keyword search remains the default if no model endpoint is configured.
|
|
256
|
+
|
|
257
|
+
## [1.7.0] - 2026-07-14 — Obsidian-grade vault (feat/obsidian-grade-vault)
|
|
258
|
+
### Added (project-memory)
|
|
259
|
+
- `memory_moc` — generate/refresh Obsidian-style Map of Content (`MOC.md`): all notes as wikilinks, `#tag` index, and backlink graph. Auto-refreshed on every save/delete.
|
|
260
|
+
- `memory_graph` — export note graph (nodes + directed edges from `[[wikilinks]]`) as JSON for external graph views.
|
|
261
|
+
- Auto-bootstrap `.obsidian/` workspace (`app.json` + `workspace.json`) on first save, so the vault opens directly in the Obsidian app with graph view + tag pages.
|
|
262
|
+
- MOC regenerates automatically after `memory_save` and `memory_delete`.
|
|
263
|
+
|
|
264
|
+
## [1.8.0] - 2026-07-14 — Vibecoder ergonomics (P1/P2, feat/obsidian-grade-vault)
|
|
265
|
+
### Added (project-memory)
|
|
266
|
+
- Auto-resolve `[[wikilinks]]` + backlinks immediately on `memory_save` (graph fresh without waiting for recall).
|
|
267
|
+
- Per-tag index pages: `tags/<tag>.md` emitted alongside MOC, pruned when tag empties.
|
|
268
|
+
- `aliases` field on notes (Obsidian-style); `[[alias]]` now resolves via `resolveLink`.
|
|
269
|
+
### Added (devjournal)
|
|
270
|
+
- `journal_daily` — Obsidian-style daily note (`daily/YYYY-MM-DD.md`); read or append mode.
|
|
271
|
+
- `journal_log` now auto-appends a line to today's daily note.
|
|
@@ -0,0 +1,297 @@
|
|
|
1
|
+
# Codex Dev MCP Suite — Solo Dev / Vibecoder Toolkit
|
|
2
|
+
|
|
3
|
+
Built for sessions that hit "input too long" / get compacted, so you can stop
|
|
4
|
+
copy-pasting context across sessions. All servers are local, file-based, and
|
|
5
|
+
split storage per-project (by directory path hash), so projects never mix.
|
|
6
|
+
|
|
7
|
+
Servers live in `~/.codex/mcp-servers/<name>/` and are registered in
|
|
8
|
+
`~/.codex/config.toml`. Restart/reload Codex to load them.
|
|
9
|
+
|
|
10
|
+
Shared storage root: `~/.codex/memories/`
|
|
11
|
+
- `memories/vault/` → project-memory notes
|
|
12
|
+
- `memories/checkpoints/` → checkpoint snapshots
|
|
13
|
+
- `memories/journal/` → devjournal logs + handoffs
|
|
14
|
+
|
|
15
|
+
`dir` argument defaults to the current working directory on every tool, so in
|
|
16
|
+
normal use you don't pass it — context auto-separates per project folder.
|
|
17
|
+
|
|
18
|
+
--------------------------------------------------------------------------------
|
|
19
|
+
## 1) project-memory — searchable Markdown knowledge vault
|
|
20
|
+
Obsidian-style `.md` notes + Context7-style on-demand recall (keyword index).
|
|
21
|
+
|
|
22
|
+
Tools:
|
|
23
|
+
- memory_save {title, content, tags?, kind?, dir?} → save + auto-index a note
|
|
24
|
+
- memory_recall {query, limit?, full?, dir?} → pull most relevant notes
|
|
25
|
+
- memory_list {limit?, dir?} → list notes (newest first)
|
|
26
|
+
- memory_get {id, dir?} → full Markdown of one note
|
|
27
|
+
- memory_delete {id, dir?} → remove a note
|
|
28
|
+
|
|
29
|
+
Use it for: durable knowledge — decisions, gotchas, API quirks, snippets.
|
|
30
|
+
Recall is keyword-based (fast, local, no embeddings).
|
|
31
|
+
|
|
32
|
+
Example flow:
|
|
33
|
+
1. After solving something: memory_save title="Fix CORS on /api" content="..." tags=["cors","api"]
|
|
34
|
+
2. Next session: memory_recall query="how did we fix cors" → returns that note.
|
|
35
|
+
|
|
36
|
+
--------------------------------------------------------------------------------
|
|
37
|
+
## 2) devjournal — session timeline + handoff/resume (anti-compaction)
|
|
38
|
+
The key tool for your "session penuh / limit" problem.
|
|
39
|
+
|
|
40
|
+
Tools:
|
|
41
|
+
- journal_log {title, body?, type?, dir?} type: note|decision|blocker|done|idea
|
|
42
|
+
- journal_handoff {summary, next_steps?, open_questions?, active_files?, dir?}
|
|
43
|
+
- journal_resume {recent?, dir?} → latest handoff + recent entries
|
|
44
|
+
- journal_timeline {limit?, type?, dir?}
|
|
45
|
+
- journal_search {query, limit?, dir?} → relevance search (rerank/keyword)
|
|
46
|
+
- journal_clear_handoff {dir?}
|
|
47
|
+
|
|
48
|
+
Use it for: never losing your place.
|
|
49
|
+
- BEFORE a session ends / before context compacts: journal_handoff with what you
|
|
50
|
+
did + next steps + active files.
|
|
51
|
+
- START of a new session: journal_resume → instantly rebuild context, no paste.
|
|
52
|
+
|
|
53
|
+
Storage is append-only `journal.jsonl` + human-readable `journal.md` mirror +
|
|
54
|
+
canonical `handoff.json`.
|
|
55
|
+
|
|
56
|
+
--------------------------------------------------------------------------------
|
|
57
|
+
## 3) checkpoint — git-independent file snapshots (safe vibecoding)
|
|
58
|
+
Snapshot/restore project text files so you can experiment freely and roll back.
|
|
59
|
+
|
|
60
|
+
Tools:
|
|
61
|
+
- checkpoint_create {label?, dir?} → snapshot all text files now
|
|
62
|
+
- checkpoint_list {dir?}
|
|
63
|
+
- checkpoint_diff {id, dir?} → added / modified / deleted vs now
|
|
64
|
+
- checkpoint_restore {id, clean?, dir?} → revert files (clean=true also removes new files)
|
|
65
|
+
- checkpoint_delete {id, dir?}
|
|
66
|
+
|
|
67
|
+
Use it for: "let me try a wild refactor" without committing to git.
|
|
68
|
+
- checkpoint_create label="before experiment"
|
|
69
|
+
- ...make changes...
|
|
70
|
+
- checkpoint_diff <id> to see what moved, checkpoint_restore <id> to undo.
|
|
71
|
+
|
|
72
|
+
Notes/limits: skips binary files and files >2MB; ignores node_modules/.git/
|
|
73
|
+
build dirs; caps at 4000 files. Content-addressed storage dedupes unchanged files.
|
|
74
|
+
|
|
75
|
+
--------------------------------------------------------------------------------
|
|
76
|
+
## 4) context-pack — token-efficient project briefing
|
|
77
|
+
Get oriented in a project without dumping files into context.
|
|
78
|
+
|
|
79
|
+
Tools:
|
|
80
|
+
- pack_overview {include_readme?, dir?} → stack, scripts, key files, top dirs, README excerpt
|
|
81
|
+
- pack_tree {max_depth?, max_entries?, dir?}
|
|
82
|
+
- pack_outline {file, dir?} → top-level functions/classes/exports only
|
|
83
|
+
- pack_search {query, limit?, dir?} → fast path/filename match
|
|
84
|
+
|
|
85
|
+
Use it for: session start in an unfamiliar/large repo. pack_overview first,
|
|
86
|
+
then pack_outline on the few files that matter — far cheaper than reading whole files.
|
|
87
|
+
Detects: Node/JS (+ Next/React/Vue/Svelte/Express/TS/Tailwind/Prisma/Vite),
|
|
88
|
+
Python, Rust, Go, Java/JVM, PHP, Ruby, Docker.
|
|
89
|
+
|
|
90
|
+
--------------------------------------------------------------------------------
|
|
91
|
+
## Recommended daily loop
|
|
92
|
+
1. Session start: context-pack.pack_overview + devjournal.journal_resume + memory_recall (topic)
|
|
93
|
+
2. Before risky change: checkpoint.checkpoint_create
|
|
94
|
+
3. While working: memory_save (durable facts), journal_log (events/blockers)
|
|
95
|
+
4. Session end / context about to compact: journal_handoff
|
|
96
|
+
|
|
97
|
+
## Maintenance
|
|
98
|
+
- All data is plain files under ~/.codex/memories/ — back up or inspect freely.
|
|
99
|
+
- To wipe one project's data, delete its slug folder under each store.
|
|
100
|
+
- Env overrides: MEMORY_VAULT_DIR, CHECKPOINT_DIR, JOURNAL_DIR.
|
|
101
|
+
|
|
102
|
+
================================================================================
|
|
103
|
+
## UPGRADE 1 — Semantic (embedding) recall in project-memory
|
|
104
|
+
project-memory now stores a semantic embedding per note and uses it for recall
|
|
105
|
+
when available. Hybrid scoring: 0.8 * cosine(semantic) + 0.2 * keyword.
|
|
106
|
+
|
|
107
|
+
- Embeddings via 9router (`/v1/embeddings`), model `bm/baai/bge-m3`.
|
|
108
|
+
- Configured in config.toml under [mcp_servers.project-memory.env]:
|
|
109
|
+
NINEROUTER_URL, NINEROUTER_KEY, EMBED_MODEL, EMBED_TIMEOUT_MS.
|
|
110
|
+
- GRACEFUL FALLBACK: if the embedding endpoint is unavailable (e.g. 503 "no
|
|
111
|
+
channel"), recall automatically falls back to keyword search. Nothing breaks.
|
|
112
|
+
- memory_recall output is tagged with the mode used: [semantic] or [keyword],
|
|
113
|
+
and per-note shows sim:0.xxx (semantic) or score:N (keyword).
|
|
114
|
+
|
|
115
|
+
New tool:
|
|
116
|
+
- memory_reindex {force?, dir?} → backfill embeddings for notes that don't have
|
|
117
|
+
one yet. Run it once the bge-m3 channel is live on your 9router so old notes
|
|
118
|
+
become semantically searchable. Safe to run repeatedly; force=true re-embeds all.
|
|
119
|
+
|
|
120
|
+
Status note: at build time the bge-m3 channel returned 503, so notes are saved
|
|
121
|
+
keyword-only and recall runs in [keyword] mode. The moment the channel is up,
|
|
122
|
+
new saves embed automatically and `memory_reindex` upgrades old ones — no code
|
|
123
|
+
changes needed.
|
|
124
|
+
|
|
125
|
+
To override the embedding model/endpoint: set EMBED_MODEL / NINEROUTER_URL /
|
|
126
|
+
NINEROUTER_KEY (or EMBED_URL / EMBED_KEY) in the env block.
|
|
127
|
+
|
|
128
|
+
================================================================================
|
|
129
|
+
## UPGRADE 2 — auto-capture plugin (hooks)
|
|
130
|
+
A Codex plugin that removes the manual step of pasting context across sessions.
|
|
131
|
+
|
|
132
|
+
Marketplace: `codex-dev-suite` (local) at
|
|
133
|
+
~/.codex/marketplaces/codex-dev-suite
|
|
134
|
+
Plugin: `auto-capture` (installed + enabled).
|
|
135
|
+
|
|
136
|
+
What it does:
|
|
137
|
+
- SessionStart (matcher: startup|clear|compact|resume): runs
|
|
138
|
+
scripts/session-start.sh, which finds the devjournal handoff + recent entries
|
|
139
|
+
for the CURRENT project (same slug algorithm as the MCP servers) and prints
|
|
140
|
+
them to stdout so Codex injects them as context. This is the anti-compaction
|
|
141
|
+
piece: after a compact/clear/resume, your handoff reappears automatically.
|
|
142
|
+
- PostToolUse (async, throttled): runs scripts/post-tool.sh, which counts tool
|
|
143
|
+
calls per project and, after >=25 calls and at most once per 30 min, emits a
|
|
144
|
+
short reminder to call journal_handoff / memory_save so work survives compaction.
|
|
145
|
+
|
|
146
|
+
Trust: Codex requires you to TRUST the hook the first time. On your next session
|
|
147
|
+
start in a trusted project, Codex will prompt to trust the auto-capture hook —
|
|
148
|
+
approve it once. (Advanced/automation only: `--dangerously-bypass-hook-trust`.)
|
|
149
|
+
|
|
150
|
+
Tuning (env, optional):
|
|
151
|
+
- AUTOCAP_THROTTLE seconds between nudges (default 1800)
|
|
152
|
+
- AUTOCAP_STATE_DIR where call counters live (default ~/.codex/memories/.autocap)
|
|
153
|
+
|
|
154
|
+
Manage:
|
|
155
|
+
- codex plugin list | grep auto-capture
|
|
156
|
+
- codex plugin remove auto-capture@codex-dev-suite
|
|
157
|
+
- Edit scripts under ~/.codex/marketplaces/codex-dev-suite/plugins/auto-capture/
|
|
158
|
+
then re-run `codex plugin marketplace add ~/.codex/marketplaces/codex-dev-suite`
|
|
159
|
+
and `codex plugin add auto-capture@codex-dev-suite` to refresh the cached copy.
|
|
160
|
+
|
|
161
|
+
How the pieces fit:
|
|
162
|
+
auto-capture (SessionStart) --reads--> devjournal handoff --so--> you resume instantly
|
|
163
|
+
auto-capture (PostToolUse) --reminds--> you to journal_handoff / memory_save
|
|
164
|
+
project-memory.memory_recall --semantic/keyword--> durable facts on demand
|
|
165
|
+
|
|
166
|
+
================================================================================
|
|
167
|
+
## Testing
|
|
168
|
+
A dependency-free test suite covers all four servers (26 tests).
|
|
169
|
+
|
|
170
|
+
Run everything:
|
|
171
|
+
cd ~/.codex/mcp-servers && node run-tests.mjs
|
|
172
|
+
|
|
173
|
+
Run one server:
|
|
174
|
+
cd ~/.codex/mcp-servers/<server> && npm test
|
|
175
|
+
|
|
176
|
+
Layout:
|
|
177
|
+
- _testkit/harness.mjs shared MCP stdio client + tiny assert/test runner
|
|
178
|
+
- <server>/test.mjs per-server tests (spawn server, call tools, assert)
|
|
179
|
+
- run-tests.mjs runs all suites, prints combined summary
|
|
180
|
+
|
|
181
|
+
Tests run fully offline (project-memory forces keyword mode by passing an empty
|
|
182
|
+
embedding key), use temp dirs, and clean up after themselves — safe to run anytime.
|
|
183
|
+
|
|
184
|
+
================================================================================
|
|
185
|
+
## Backfill — import past Codex sessions
|
|
186
|
+
Imports your existing Codex session history (~/.codex/sessions/*.jsonl) into
|
|
187
|
+
project-memory + devjournal, grouped by each session's cwd (project).
|
|
188
|
+
|
|
189
|
+
USE backfill-sessions-v2.mjs (see "Backfill v2" below). The original v1 script
|
|
190
|
+
and its state file (.backfill-state.json) have been removed in favor of v2,
|
|
191
|
+
which extracts deeper content (commands, plan, files, tool counts) and backdates
|
|
192
|
+
entries to the original session time.
|
|
193
|
+
|
|
194
|
+
Embeddings: backfill runs with embeddings OFF (keyword-only) for speed. Once the
|
|
195
|
+
bge-m3 channel on 9router is live, run memory_reindex per project to upgrade old
|
|
196
|
+
notes to semantic search. (LLM rerank still works in the meantime — see UPGRADE 3/4.)
|
|
197
|
+
|
|
198
|
+
================================================================================
|
|
199
|
+
## UPGRADE 3 — LLM rerank (Kiro) when embeddings are unavailable
|
|
200
|
+
Since the bge-m3 embedding channel is currently 503, project-memory now has a
|
|
201
|
+
middle tier between semantic and keyword: an LLM reranker using a 9router chat
|
|
202
|
+
model (default Kiro `kr/claude-haiku-4.5`).
|
|
203
|
+
|
|
204
|
+
Recall mode precedence (auto-selected, shown in output as [mode]):
|
|
205
|
+
1. [semantic] — if note embeddings + query embedding are available (bge-m3)
|
|
206
|
+
2. [rerank] — keyword prefilter (top ~20; falls back to most-recent if no
|
|
207
|
+
keyword hit) → chat model picks/orders the most relevant → ids
|
|
208
|
+
3. [keyword] — pure keyword scoring (always-available fallback)
|
|
209
|
+
|
|
210
|
+
Why this matters: rerank handles semantic queries with zero keyword overlap.
|
|
211
|
+
Example: query "how do users sign in securely with tokens" correctly returns a
|
|
212
|
+
note titled "JWT auth flow" — no shared words.
|
|
213
|
+
|
|
214
|
+
Config (config.toml, [mcp_servers.project-memory.env]):
|
|
215
|
+
RERANK_MODEL = "kr/claude-haiku-4.5" # any 9router chat model id
|
|
216
|
+
RERANK_TIMEOUT_MS = "30000"
|
|
217
|
+
RERANK_ENABLED = "1" # set "0" to force keyword-only
|
|
218
|
+
|
|
219
|
+
Files: rerank.js (chat client + parser), wired into server.js recall().
|
|
220
|
+
Graceful: any failure/timeout/non-200 falls back to keyword. Never throws.
|
|
221
|
+
|
|
222
|
+
Cost note: rerank makes ONE small chat call per recall (haiku, temp 0,
|
|
223
|
+
~200 max tokens). Cheap, but it does use your 9router quota. Disable with
|
|
224
|
+
RERANK_ENABLED=0 if you want zero-cost keyword-only recall.
|
|
225
|
+
|
|
226
|
+
Tests: project-memory/test.rerank.mjs (online; auto-skips if 9router is down).
|
|
227
|
+
|
|
228
|
+
================================================================================
|
|
229
|
+
## UPGRADE 4 — devjournal journal_search (rerank)
|
|
230
|
+
devjournal now has a relevance search tool, mirroring project-memory's rerank:
|
|
231
|
+
|
|
232
|
+
- journal_search {query, limit?, dir?}
|
|
233
|
+
Keyword prefilter over journal entries, then LLM rerank (9router Kiro
|
|
234
|
+
kr/claude-haiku-4.5) when available; else keyword scoring. Output tagged
|
|
235
|
+
[rerank] or [keyword]. Falls back to recent entries for semantic-style
|
|
236
|
+
queries with no keyword overlap.
|
|
237
|
+
|
|
238
|
+
journal_resume is intentionally unchanged — it returns the canonical latest
|
|
239
|
+
handoff + recent entries (no query). Use journal_search when you want to find
|
|
240
|
+
entries about a specific topic across past sessions.
|
|
241
|
+
|
|
242
|
+
Files: devjournal/rerank.js (same module as project-memory), wired into
|
|
243
|
+
devjournal/server.js. Same env knobs apply (RERANK_MODEL / RERANK_ENABLED /
|
|
244
|
+
RERANK_TIMEOUT_MS); they're already set in config.toml for project-memory, and
|
|
245
|
+
devjournal reads NINEROUTER_URL/KEY from its own env block — note: enable rerank
|
|
246
|
+
for devjournal by adding the RERANK_* + NINEROUTER_* vars to
|
|
247
|
+
[mcp_servers.devjournal.env] too (see below).
|
|
248
|
+
|
|
249
|
+
================================================================================
|
|
250
|
+
## Backfill v2 — deep extraction + original timestamps
|
|
251
|
+
backfill-sessions-v2.mjs supersedes v1. Per session it now extracts:
|
|
252
|
+
- all user prompts, the plan steps (update_plan), shell commands run, files
|
|
253
|
+
touched (apply_patch paths + cat/rm/cp/redirect heuristics), tool usage
|
|
254
|
+
counts, turn/command/reasoning counts, and the final assistant note.
|
|
255
|
+
- The note is BACKDATED to the session's original start time.
|
|
256
|
+
|
|
257
|
+
New tool args enabling this:
|
|
258
|
+
- memory_save ... created: "<ISO>" # backdate the note
|
|
259
|
+
- journal_log ... ts: "<ISO>" # backdate the entry
|
|
260
|
+
|
|
261
|
+
Usage:
|
|
262
|
+
cd ~/.codex/mcp-servers
|
|
263
|
+
node backfill-sessions-v2.mjs --dry --min-prompts 2 # preview deep extract
|
|
264
|
+
node backfill-sessions-v2.mjs --min-prompts 2 --wipe # replace old session
|
|
265
|
+
# entries, re-import deep
|
|
266
|
+
node backfill-sessions-v2.mjs --min-prompts 2 # incremental (new only)
|
|
267
|
+
|
|
268
|
+
--wipe removes existing kind/type=="session" entries (from any prior backfill)
|
|
269
|
+
before re-importing, so you don't get duplicates. Source of truth is always
|
|
270
|
+
~/.codex/sessions, so this is reversible.
|
|
271
|
+
|
|
272
|
+
State: ~/.codex/memories/.backfill-v2-state.json (separate from v1).
|
|
273
|
+
Result: 87 sessions re-imported with original timestamps (2026-03-16 .. 2026-06-13),
|
|
274
|
+
0 errors; timestamps verified 87/87 matching original session dates.
|
|
275
|
+
|
|
276
|
+
================================================================================
|
|
277
|
+
## UPGRADE 5 — project-memory resources (browsable notes)
|
|
278
|
+
project-memory now also exposes every saved note as a read-only MCP resource,
|
|
279
|
+
so notes can be browsed/opened without calling a tool.
|
|
280
|
+
|
|
281
|
+
- Capability: declares `resources` alongside `tools`.
|
|
282
|
+
- resources/list → one entry per note across ALL projects in the vault, with
|
|
283
|
+
name (title), description ([kind] tags — created), mimeType text/markdown.
|
|
284
|
+
- resources/read → full Markdown of a note.
|
|
285
|
+
- URI scheme: memory://<project-slug>/<noteId>
|
|
286
|
+
|
|
287
|
+
Note on naming: the MCP server id is `project-memory` (hyphen), as written in
|
|
288
|
+
config.toml. Some UIs show a tool namespace like `project_memory` (underscore) —
|
|
289
|
+
that label is NOT the server id. Resource/admin calls must target the real id
|
|
290
|
+
`project-memory`.
|
|
291
|
+
|
|
292
|
+
checkpoint / context-pack / devjournal remain tools-only by design (they're
|
|
293
|
+
actions, not browsable data). devjournal entries are best queried via
|
|
294
|
+
journal_search / journal_timeline.
|
|
295
|
+
|
|
296
|
+
Verified: resources/list returned all current notes; resources/read returned a
|
|
297
|
+
note's Markdown. Full test suite still 27/27.
|
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 maximalabs
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|