Codex Dev Suite

CI npm version npm downloads license node

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. 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, Gemini-compatible launchers, Hermes, or any stdio MCP host).

Quickstart

Try it in 10 seconds (no clone, no config):

npx -y -p codex-dev-mcp-suite project-memory-mcp --help

Local-first by default: no hosted backend, no telemetry. Works offline with keyword recall; model/provider config is optional. For strict no-network mode, set MCP_DETERMINISTIC_FALLBACK=true.

Register all four servers with an MCP client (Codex CLI shown):

# ~/.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"]

Inspect any server without starting it:

project-memory-mcp --version
project-memory-mcp --doctor   # config diagnostics; API keys redacted

Other clients (Claude Code, Cursor, Cline, ...): see docs/clients/. Full env reference: docs/configuration.md. Data flow: docs/privacy.md.

The four servers

Server	What it does	Key tools
project-memory	Searchable Markdown knowledge vault (Obsidian-style notes + on-demand recall). Notes are also exposed as MCP resources.	memory_save, memory_recall, memory_list, memory_get, memory_delete, memory_reindex, memory_link, memory_global_recall, memory_dedup
devjournal	Per-project session timeline + handoff/resume (anti-compaction).	journal_log, journal_handoff, journal_resume, journal_timeline, journal_search, journal_clear_handoff
checkpoint	Git-independent file snapshots for safe experimentation.	checkpoint_create, checkpoint_list, checkpoint_diff, checkpoint_restore, checkpoint_delete
context-pack	Token-efficient project briefing (stack, tree, symbols, search).	pack_overview, pack_tree, pack_outline, pack_search

Recall quality (project-memory & devjournal)

Recall auto-selects the best available mode:

1. semantic — if an embeddings endpoint is configured (any OpenAI-compatible /v1/embeddings: OpenAI, Ollama, LM Studio, OpenRouter, vLLM, LiteLLM, 9router, ...)
2. rerank — keyword prefilter then an LLM reranker (any OpenAI-compatible chat model)
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.

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:

# 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

git clone https://github.com/<you>/codex-dev-mcp-suite.git
cd codex-dev-mcp-suite
# install the MCP SDK in each server
for s in project-memory checkpoint context-pack devjournal; do (cd "$s" && npm install); done

Register with your MCP client

Client-specific examples:

• Codex CLI
• Claude Code
• Generic MCP JSON

Codex CLI (~/.codex/config.toml):

[mcp_servers.project-memory]
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 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"
args = ["/abs/path/codex-dev-mcp-suite/checkpoint/server.js"]

[mcp_servers.context-pack]
command = "node"
args = ["/abs/path/codex-dev-mcp-suite/context-pack/server.js"]

[mcp_servers.devjournal]
command = "node"
args = ["/abs/path/codex-dev-mcp-suite/devjournal/server.js"]
[mcp_servers.devjournal.env]
JOURNAL_DIR = "~/.codex/memories/journal"

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.

Memory Recall Modes

memory_recall supports a mode arg (default "auto") that controls fallback behavior:

Mode	Behavior
auto (default)	Smart: try semantic → keyword → LLM rerank
semantic	Require embedding. Returns isError: true if no embed key configured
keyword	Skip embedding entirely (faster, pure keyword scoring)

The recall output annotates the active mode for transparency:

Recall for "how do users sign in" in my-project [semantic+rerank]:
### JWT login flow (id:..., sim:0.603, ...)

The +rerank suffix is appended when LLM rerank is active (MCP_RERANK_ENABLED + key). Without embeddings, recall falls back to [keyword] or [keyword+rerank]. With MCP_DETERMINISTIC_FALLBACK=true, the mode is always [deterministic].

This means you can run codex-dev-mcp-suite with zero API keys configured — memory_recall still works via keyword scoring, just no semantic similarity.

New in v1.5.0

project-memory now adds a lightweight knowledge-graph layer:

• memory_link resolves wiki-style links like [[id]], [[title]], and [[project:title]], and shows backlinks
• memory_global_recall searches across projects with same-project bias and graceful keyword fallback
• memory_dedup suggests duplicate-note merges without deleting anything

Link resolution always prefers the active project first, then falls back globally when appropriate.

Daily workflow

• Session start: pack_overview + journal_resume + memory_recall "<topic>"
• Before a risky change: checkpoint_create
• While working: memory_save (durable facts), journal_log (events/blockers)
• Session end / before compaction: journal_handoff

Optional: import your existing Codex history

backfill-sessions-v2.mjs reads ~/.codex/sessions/*.jsonl and imports each session (prompts, plan, commands, files touched) into project-memory + devjournal, grouped by project, backdated to the original session time.

node backfill-sessions-v2.mjs --dry --min-prompts 2     # preview
node backfill-sessions-v2.mjs --min-prompts 2           # import

Stats CLI

A read-only summary of your local memory storage — totals, top projects, recent activity, and temp-slug cleanup candidates.

npx -y -p codex-dev-mcp-suite stats             # human-readable
npx -y -p codex-dev-mcp-suite stats --json      # machine-readable
npx -y -p codex-dev-mcp-suite stats --root /tmp/mem   # different root
npx -y -p codex-dev-mcp-suite stats --top 5     # trim top lists

Example output:

Dev MCP Suite — stats
======================
Storage root: /home/you/.codex/memories

Totals
------
  Notes:           89
  Journal projects:19
  Checkpoints:     1
  Distinct projects: 25

Top projects by notes (top 10)
------------------------
    24  mrtrickster99-fd1ff0fa
    14  Coding-17e063ef
    ...

Temp/cleanup candidates (2)
------------------------
  tmp.itbtDn9eB3-b62798fd
  tmp.iHqM2Uh5K2-8d3660a2

The CLI is a thin wrapper around lib/stats.js, which is also importable directly from your own scripts. The default storage root is ~/.codex/memories, but --root (or the existing MEMORY_VAULT_DIR / JOURNAL_DIR / CHECKPOINT_DIR env vars) override it.

Provider Smoke CLI

Verify every configured LLM provider (chat + embeddings) with one command. Useful after adding a new API key, or when comparing provider latency.

npx -y -p codex-dev-mcp-suite provider-smoke                          # uses process.env
npx -y -p codex-dev-mcp-suite provider-smoke --env-file ~/secrets.env  # separate secrets file
npx -y -p codex-dev-mcp-suite provider-smoke --markdown --save-md docs/providers.md

Auto-detects providers from these env vars (highest precedence first):

• Numbered slots: MCP_PROVIDER_PRIMARY / _CHAIN2 / _CHAIN3 / ...
• Named env: GROQ_*, CEREBRAS_*, MISTRAL_*, OPENROUTER_*, OPENAI_*, GEMINI_*, COHERE_*, VOYAGE_*, OLLAMA_*, ANTHROPIC_*
• Catch-all: MCP_LLM_BASE_URL / MCP_RERANK_BASE_URL / MCP_EMBED_BASE_URL / NINEROUTER_URL / LLM_BASE_URL (any OpenAI-compatible endpoint)

For each detected provider, runs:

• chat probe (/v1/chat/completions) — if the provider supports it
• embed probe (/v1/embeddings) — if the provider supports it

Inference-only providers (Groq, Cerebras, Anthropic) skip the embed probe automatically. Non-OpenAI-compatible providers (Cloudflare Workers AI) require a custom code path in project-memory/embedding.js — see docs/providers.md.

No provider assumption is baked in: the tool only probes what's in your env. Zero-config users get an empty matrix; pass --env-file to point at a secrets file.

Chat-only providers (Groq, Cerebras) skip the embeddings probe automatically — they don't expose /v1/embeddings. Embedding-capable providers (Mistral, OpenRouter, OpenAI, Ollama, Gemini, Cohere) run both probes.

Example output (Groq + Cerebras, both configured):

[groq]
  ✓ chat       200 310ms  "OK"

[cerebras]
  ✓ chat       200 476ms

See docs/providers.md for a saved smoke matrix.

Prune CLI

Remove temp project slugs (prefix tmp.) from vault / journal / checkpoints. Default is DRY-RUN — nothing is deleted without --yes.

npx -y -p codex-dev-mcp-suite prune           # dry-run report
npx -y -p codex-dev-mcp-suite prune --yes     # actually delete
npx -y -p codex-dev-mcp-suite prune --json    # machine-readable
npx -y -p codex-dev-mcp-suite prune --root /tmp/mem   # different root

Safety: refuses to delete any slug that does not start with tmp.. Useful right after heavy refactors or after imports that left tmp scratch dirs.

For in-session use from an MCP client, the project-memory server exposes a memory_stats tool that returns the same summary text (or JSON) as the stats CLI above.

Tests

node run-tests.mjs          # all servers (offline, ~27 tests)
cd project-memory && npm test

Privacy

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. Your personal vault/journal/checkpoints are gitignored.

License

MIT — see LICENSE.