Project State Engine

State-first MCP engine for Claude Code and Codex. Keep project truth in files, generate tiny startup briefs, and stop replaying long chat history.

Minimal file-based state engine for agent workflows. Instead of replaying long chat history, it stores the current project state in structured JSON and generates a compact session brief.

Benchmarked on the bundled sample workspace: 5626 tokens for a full state replay vs 146 tokens for session startup with the compact brief. That is a measured 97.4% reduction in startup context size.

Release status: the repository is prepared for v1.0.0. Public npm publish and the first GitHub Release still need maintainer credentials and package-name availability.

Install In One Command

Current install path:

npm install -g github:dumancode/project-state-engine

That gives you two commands anywhere on your machine:

• project-state
• project-state-mcp

When the npm package is published, this becomes:

npm install -g project-state-engine

Try It In 60 Seconds

The repository ships with a committed demo-workspace/ so you can try the real CLI and MCP workflow immediately.

Generate the sample startup brief:

npm run demo:brief

Run the real MCP SDK client example against the bundled workspace:

npm run demo:mcp-workflow

This is the fastest way to answer the important question: "How would another agent or app actually use this?"

The MCP workflow example runs against a temporary working copy, so the committed demo-workspace/ stays clean.

Claude Code And Codex Setup

If you want to use the engine as an MCP server, the global install above makes setup copy-paste simple.

Claude Code:

claude mcp add project-state -- project-state-mcp

Codex:

codex mcp add project-state -- project-state-mcp

Initialize state in the project you actually work on:

project-state init --root /absolute/path/to/your-project --project your-project

Launch Kit

If you want to post this to Hacker News, Reddit, Product Hunt, or X, ready-to-edit launch copy lives here:

• docs/LAUNCH_COPY.md

30-Second Before / After

Without Project State Engine, a new session often starts like this:

We are building a Next.js app with a FastAPI backend.
JWT auth is active.
Refresh token work is still open.
Before merging we always run tests.
The current blocker is rate limiting.
Yesterday we changed the login flow...

That kind of handoff grows fast, and teams usually keep rewriting it.

With Project State Engine:

project-state session-brief --root /absolute/path/to/your-project

Or from your MCP client, use:

• prompt: start-session-from-state
• tool: session_brief

On the bundled sample workspace, that startup handoff drops from 5626 tokens to 146.

Why It Looks Different

Most memory tools are trying to remember everything the model touched.

This project is trying to keep only the current project truth small and sharp:

• what is active
• what changed
• what is risky
• what should happen next

That is why the README, dashboard, and MCP prompts all orbit the same thing: a tiny, deterministic startup handoff for Claude Code or Codex.

Who This Is For

• solo developers using Claude Code or Codex on the same repo for days or weeks
• vibe coders who keep re-explaining the same project state every morning
• freelancers and small teams who want project truth in Git instead of hidden chat history
• agent workflows that need a compact, deterministic startup brief

Who This Is Not For

• one-off scripts you finish in a single short session
• users who want a full autonomous memory graph of everything ever said
• teams that prefer opaque hosted memory over explicit file-based state
• workflows where replaying the whole chat is acceptable and token cost is irrelevant

Why This Exists

Most agent memory projects store too much conversation and then spend tokens searching through it. This project takes a different approach: treat the project as a small, structured state machine.

The goal is not "remember everything." The goal is "start the next session with the smallest useful brief."

Core Idea

• Source of truth is the filesystem
• State is explicit and typed
• Session startup reads current-state.json, not long chat history
• Retrieval is narrow and intentional

This is a better fit when you care about:

• lower token usage
• clearer project continuity
• team-readable state in Git
• fewer hidden side effects than automatic memory systems

Measured Results

The repo now ships a repeatable token benchmark. On the bundled sample workspace, replaying the full stored state and history costs 5626 tokens. The compact prompt surfaces are much smaller:

Scenario	Tokens	Reduction
Full state replay baseline	5626	0%
start-session-from-state prompt	146	97.4%
implementation-plan-from-state prompt	447	92.1%
release-checklist-from-state prompt	686	87.8%

This means the current sample benchmark shows roughly 97% lower startup context cost when using the brief instead of replaying the whole state dump.

Quick read:

• session startup drops from 5626 to 146 tokens
• implementation planning drops from 5626 to 447 tokens
• release checklist generation drops from 5626 to 686 tokens

Run the benchmark yourself:

npm run benchmark:tokens

Latest generated artifacts:

• benchmark-results/token-savings.json
• benchmark-results/token-savings.md

Method note: this is a bundled sample benchmark, not a universal guarantee. Real savings will vary by how much state you store and how aggressively you retrieve it.

What It Does

• Stores project state as JSON under .project-state/
• Tracks decision, rule, goal, task, risk, and session_summary
• Rebuilds current-state.json after every write
• Produces a compact session brief for token-efficient restarts
• Exposes the same engine as an MCP stdio server
• Validates structured writes before they hit disk
• Flags stale records and weak handoffs with state_doctor
• Adds lightweight search across stored state
• Adds append-only history tracking with changed-field diffs
• Exposes current state and records as MCP resources
• Ships reusable MCP prompts for session kickoff, planning, review, triage, refactors, and releases
• Adds markdown exports and an HTML state dashboard

Why State Instead of Memory

Classic "memory" systems often optimize for recall:

• what was said
• what was tried
• what the agent saw

This project optimizes for execution:

• what is currently true
• what matters right now
• what the next step should be

That makes the startup context smaller, more stable, and easier to version in Git.

Folder Layout

.project-state/
  decisions/
  rules/
  goals/
  tasks/
  risks/
  sessions/
  current-state.json
  index.json

Quick Start

If you prefer running from source instead of the one-command global install:

cd project-state-engine
npm install
npm run build

Run commands directly from the built output:

node dist/cli.js init --root ./demo-workspace --project demo-workspace

Or link the package locally once and use the short commands everywhere:

npm link

Initialize a project state directory in any target workspace:

project-state init --root ./demo-workspace --project demo-workspace

Capture a decision:

project-state state-capture \
  --root ./demo-workspace \
  --type decision \
  --title "Use JWT auth with rotating refresh tokens" \
  --summary "JWT was chosen over server-side sessions for portability and cleaner release rollbacks." \
  --tags auth,backend \
  --content '{"problem":"Choose an auth approach for the public API","decision":"JWT with rotating refresh tokens","reasoning":["Stateless API requests","Cleaner multi-client support"]}'

List open tasks:

project-state state-list --root ./demo-workspace --type task --status open

Search state:

project-state state-search --root ./demo-workspace --query "jwt auth"

Inspect recent history:

project-state history-list --root ./demo-workspace --limit 10

Generate a resource URI:

project-state resource-uri --root ./demo-workspace --kind current-state

Render a markdown brief:

project-state markdown-brief --root ./demo-workspace

Render a markdown history timeline:

project-state history-markdown --root ./demo-workspace

Export every markdown view in one shot:

project-state export-markdown-views --root ./demo-workspace

Run a state health check:

project-state state-doctor --root ./demo-workspace

Generate a dashboard:

project-state dashboard-html --root ./demo-workspace

Generate a brief:

project-state session-brief --root ./demo-workspace

Close a session:

project-state session-close \
  --root ./demo-workspace \
  --what-changed '["Captured the release handoff and open auth risk"]' \
  --open-loops '["Refresh token revoke behavior still needs staging verification"]' \
  --next-step "Generate the release checklist and capture rollback steps"

CLI Commands

• init
• state-capture
• state-list
• state-search
• history-list
• state-update
• session-brief
• session-close
• state-doctor
• doctor-markdown
• markdown-brief
• history-markdown
• export-markdown-views
• dashboard-html
• resource-uri
• mcp

Docs

• MCP setup and daily workflow: docs/MCP_GUIDE.md
• Example MCP config: docs/mcp-config.example.json
• Launch and marketing copy: docs/LAUNCH_COPY.md
• Release hygiene: docs/RELEASE.md
• Changelog: CHANGELOG.md
• Demo workspace: demo-workspace/

MCP Server

Run the stdio MCP server:

project-state-mcp

Or through the CLI:

project-state mcp

Suggested MCP config:

{
  "mcpServers": {
    "project-state": {
      "command": "project-state-mcp"
    }
  }
}

Available MCP tools:

• state_doctor
• state_init
• state_capture
• state_list
• state_search
• state_history
• state_update
• session_brief
• session_close

Available MCP resources:

• project-state://workspace/{workspace}/history
• project-state://workspace/{workspace}/history.md
• project-state://workspace/{workspace}/doctor
• project-state://workspace/{workspace}/doctor.md
• project-state://workspace/{workspace}/dashboard.html
• project-state://workspace/{workspace}/index
• project-state://workspace/{workspace}/current-state
• project-state://workspace/{workspace}/open-tasks
• project-state://workspace/{workspace}/session-brief
• project-state://workspace/{workspace}/session-brief.md
• project-state://workspace/{workspace}/records/{id}

Use URL-encoded absolute workspace paths in the {workspace} slot. The CLI can generate these URIs for you.

Available MCP prompts:

• start-session-from-state
• task-context-from-state
• implementation-plan-from-state
• refactor-plan-from-state
• sprint-planning-from-state
• code-review-from-state
• bugfix-from-state
• bug-triage-from-state
• release-checklist-from-state

Real MCP Client Workflow

A real SDK client example is included at src/examples/mcp-client-workflow.ts.

Run it against any workspace:

npm run example:mcp-workflow -- ./demo-workspace

The example does four things through the MCP protocol:

• connects to the local stdio server with the official MCP SDK client
• initializes project state and captures a couple of records
• calls the session_brief tool
• fetches the release-checklist-from-state prompt and the session-brief.md resource

This gives you a concrete end-to-end example of how another app or agent could use the server. The example copies the requested workspace into a temporary directory first, so it can safely create example records without mutating your checked-in files.

State Doctor

state_doctor inspects your project state for issues that make future sessions worse:

• stale active records
• open tasks without content.next_action
• in-progress goals without linked tasks
• duplicate active titles
• active risks without mitigation
• weak current-state.json handoff signals

Use it before releases, after long idle periods, or when the brief starts feeling unreliable.

Dashboard

dashboard-html generates a lightweight HTML dashboard that combines:

• current focus and next step
• record counts
• open tasks
• recent history
• state doctor findings

The same dashboard is also exposed as an MCP resource:

• project-state://workspace/{workspace}/dashboard.html

Quality Gates

Local maintenance scripts:

npm run lint
npm run check

CI runs on GitHub Actions and executes lint, typecheck, tests, and the bundled token benchmark on pushes and pull requests.

Benchmark Workflow

A token benchmark example is included at src/examples/token-benchmark.ts. It seeds a sample workspace, measures tokens with gpt-tokenizer, and writes the latest report into benchmark-results/.

Example Brief

{
  "brief": {
    "project": "demo-workspace",
    "active_decisions": ["Use JWT access tokens with rotating refresh tokens"],
    "current_focus": "Draft release notes",
    "next_step": "Generate the release checklist and capture rollback steps"
  },
  "brief_text": "Project: demo-workspace\nCurrent focus: Draft release notes\nNext step: Generate the release checklist and capture rollback steps\nActive decisions: Use JWT access tokens with rotating refresh tokens"
}

Notes

• Source of truth is the filesystem, not a database.
• current-state.json is the main artifact for session startup.
• content and patch arguments are JSON strings.
• events.jsonl stores append-only history with changed_fields and before/after values for updates.

Roadmap

• public npm release and the first tagged GitHub Release
• multi-workspace rollup views for people juggling several active repos
• richer dashboard UX beyond the static HTML export
• editor integrations such as a VS Code sidebar or companion extension
• optional hosted sync or team-sharing adapters that keep file-based state as the source of truth