Provides local-first version control for AI sessions, allowing users to save project states and resume them in new chats with full file integrity.
Also known as Askrion/stateark
- Stars
- 2
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- 0.5.3
- Last commit
- Aug 25, 2026
- License
- —
What is StateArk MCP?
StateArk provides local-first version control for AI sessions, allowing users to save project states and resume them in new chats with full file integrity.
Summary generated from the project's README
About StateArk MCP server
StateArk provides a local-first version control system designed specifically for AI chat sessions. It allows developers to transform a working conversation into a portable, versioned project state that can be resumed in new chats without losing context or file integrity. By using commands like Savepoint and Resume, users can capture decisions, constraints, and actual files into organized directories containing Markdown and JSON files.
The system runs as a local MCP server, making it compatible with Claude Desktop, Claude Code, and other local hosts like Codex or Hermes. It operates by default on your local machine, storing data in a ~/StateArk directory, which ensures your files remain accessible even if the tool is removed. For those requiring remote backups, an optional Supabase mirror can be configured to sync artifacts and state data to the cloud.
What distinguishes this tool is its focus on integrity. It uses SHA-256 hashes to track artifacts and performs checks to detect if an AI has truncated code or failed to provide a file it mentioned in text. This prevents the common issue of models silently losing project details during long sessions.
What you can do with it
- 1Resume a project in a new chatLoad the latest project state, including all files and previous decisions, into a fresh AI conversation.
- 2Create a versioned project snapshotConsolidate your current chat session into a new, organized version of your project.
- 3Compare changes between versionsIdentify exactly what changed between two different project savepoints using text and hash comparisons.
Written from the project's README. Every use case is checked against a quote from it.
How to install StateArk MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall StateArk MCP in Claude Code
$ claude mcp add stateark -- npx -y statearkInstall StateArk MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"stateark": {
"command": "npx",
"args": [
"-y",
"stateark"
]
}
}
}Install StateArk MCP in VS Code
.vscode/mcp.json
{
"servers": {
"stateark": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"stateark"
]
}
}
}Install StateArk MCP in VS Code CLI
$ code --add-mcp '{"name":"stateark","type":"stdio","command":"npx","args":["-y","stateark"]}'Install StateArk MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"stateark": {
"command": "npx",
"args": [
"-y",
"stateark"
]
}
}
}Install StateArk MCP in Codex
$ codex mcp add stateark -- npx -y statearkInstall StateArk MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.stateark] command = "npx" args = ["-y", "stateark"]
Install StateArk MCP in Gemini CLI
$ gemini mcp add -s user stateark npx -- -y statearkInstall StateArk MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"stateark": {
"command": "npx",
"args": [
"-y",
"stateark"
]
}
}
}Automated checks
Ran Nov 15, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work · What to fix for more points
- Source repository linked and reachableaskrion/stateark is public and reachablegithub.com/askrion/stateark ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)No build attestation published for this releaseNot checked
- Open source license (OSI)No licenseFinding
- Commit or release in the last yearLast commit or release 2026-08-25github.com/askrion/stateark ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from statearkPass
- No critical advisory in the package or its dependencies115 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubStateArk
Never explain your project to an AI twice.
Your chat is a workspace, not an archive. StateArk turns a working session into a versioned, portable project state that any new chat can pick up. Open terminal and write:
npx stateark
Then quit Claude Desktop completely (Cmd+Q) and reopen it. That is the whole install.
(Prefer to install from source? npm install && npm run build && npm run setup —
see INSTALL.md. Undo any time with npx stateark remove.)
Here what we had in mind developing stateark - we address a problem millions of users have...
You: ...three hours of work...
You: Savepoint
-> my-project v0.3 written to ~/StateArk
(next day, new chat, empty context)
You: Resume my-project
-> decisions, constraints, rejected approaches, open questions,
and the actual files - all current, none of the detours
Local by default. Savepoints are ordinary folders of Markdown, JSON and your real files. Nothing is uploaded. If StateArk disappears tomorrow, you still have everything.
~/StateArk/projects/my-project/v0.3/
state.md <- the canonical state, readable in any editor
state.json
manifest.json <- every artifact with its SHA-256
artifacts/
app.py
schema.sql
Commands
| In the chat | What happens |
|---|---|
Savepoint |
consolidate the session into a new version |
Resume <project> |
load the latest state into a fresh chat |
History <project> |
list the versions |
Diff <project> |
what actually changed between two savepoints |
| In the terminal | |
|---|---|
npx stateark |
register with Claude Desktop |
npx stateark report |
anonymised local usage summary, printed for you only |
npx stateark remove |
unregister; savepoints are kept |
What makes it more than a summary
- Carry-forward. Files you do not re-submit are copied into the new version with their original hash, so a forgetful model cannot silently lose your schema.
- Integrity checks. StateArk cannot see your chat - so it checks what it can:
truncation markers (
// ... rest unchanged), files that collapsed in size, files the state describes but never handed over, savepoints identical to their predecessor. It warns, it never blocks: the savepoint is always written. - Journal. Between savepoints the model quietly records turning points, so a Savepoint at the end of a long session does not depend on a degraded context. Only for projects you already saved once - scratch conversations are never touched.
Requirements
Node 20+. Claude Desktop, or Claude Code (claude mcp add --transport http ...).
It also runs under other local MCP hosts — users have it working with Codex and
Hermes against the same store.
Hosted clients that dial your server from the vendor's cloud (Claude web,
ChatGPT web) cannot reach localhost. See INSTALL.md.
Several agents at once
Supported, and worth saying plainly because it is the setup that broke first. Writes to a project are serialised across processes, so two agents cannot claim the same version number. If a savepoint reports that another process is busy, repeat it in a moment — nothing is lost. A process that dies mid-write releases its lock automatically.
If your store lives in Dropbox, OneDrive or iCloud Drive: several agents on one machine are fine. Two machines writing the same store simultaneously is a sync conflict, which the sync client resolves and StateArk cannot.
| Variable | Default | |
|---|---|---|
STATEARK_LOCK_WAIT_MS |
60000 |
how long to wait for another process before giving up |
STATEARK_LOCK_STALE_MS |
120000 |
when a lock is assumed to belong to a dead process |
STATEARK_FS_RETRIES |
6 |
retries when a sync client holds a file open |
Licence
Elastic License 2.0. Use it for anything including commercially, read and modify the source, share the package. You may not offer it to third parties as a hosted or managed service. Your savepoints are yours and are not covered by this licence.
Architecture
ChatGPT / Claude / Gemini-capable MCP client
|
v
StateArk Local Agent <- 127.0.0.1 only, by default
|
v
~/StateArk/projects <- SOURCE OF TRUTH
|
| optional
v
Supabase <- mirror / backup / transport
A Savepoint is an ordinary directory, not a proprietary database:
StateArk/projects/my-project/
journal.ndjson # entries recorded since the last savepoint
project.json # index (self-healing: rebuilt from disk if corrupt)
v0.3/
state.md # human- and LLM-readable canonical state + integrity warnings
state.json # the same state, structured
meta.json # version, lineage, platform, sync status, warnings
manifest.json # artifacts with SHA-256, stored/pending, carried_forward_from
journal.ndjson # the entries this savepoint consolidated
artifacts/
app.py
schema.sql
prototype.zip
If StateArk disappears, those files remain usable.
Install
Requires Node 20+.
npm install
npm run typecheck
npm test # 97 checks against a throwaway store — run this first
npm start
No .env is needed for local-only mode. Copy .env.example to .env only if you want
to change the port, the store location, or enable the Supabase mirror.
On first run StateArk generates a random access key and stores it in
~/StateArk/.access-key (mode 0600). The startup banner prints your endpoints:
MCP: http://localhost:8787/mcp/<key>
Upload page: http://localhost:8787/upload/<key>
Health: http://localhost:8787/health
Security model
The HTTP entrypoint is a local server on your own machine, so StateArk assumes any web page you visit is hostile:
| Control | Default |
|---|---|
| Bind address | 127.0.0.1 (STATEARK_BIND to change) |
| Access key | random per install, in <root>/.access-key, constant-time compared |
Origin header |
loopback only, plus STATEARK_ALLOWED_ORIGINS |
Host header |
loopback only, plus STATEARK_ALLOWED_HOSTS (DNS-rebinding guard) |
| CORS | echoes the validated origin, never * |
| Upload form | single-use CSRF token, capped body size |
| Non-loopback bind | refuses to start unless the access key is ≥ 24 chars |
Before exposing the agent over HTTPS: set a long STATEARK_ACCESS_KEY, set
STATEARK_ALLOWED_HOSTS to your tunnel hostname, and put a real reverse proxy in front.
Platform reality
Local-first and hosted LLMs are different networking environments. Claude Desktop/Code and
other local MCP clients can talk to the local agent directly. A hosted ChatGPT/Gemini
client generally cannot reach localhost on your computer. For those you would need a
secure HTTPS route to your running local agent — remote access is on the roadmap and does
not exist yet.
If you are setting this up, in this order:
- run StateArk locally;
- test Savepoint and Resume from a local MCP client;
- enable Supabase sync only if you actually want a mirror;
- expose the agent over HTTPS only after the three steps above work.
Local-only mode — the default
Leave SUPABASE_URL, SUPABASE_SECRET_KEY and STATEARK_OWNER_ID unset. Cloud sync stays
off and files never leave the machine. Default store: ~/StateArk
(override with STATEARK_LOCAL_ROOT).
This is what you get out of the box. The Supabase section below is opt-in.
Local + Supabase sync
Run the migrations in the Supabase SQL editor, in order:
supabase/migrations/001_stateark.sqlsupabase/migrations/002_artifacts.sqlsupabase/migrations/003_hardening.sql
Then set SUPABASE_URL, SUPABASE_SECRET_KEY (server-side Secret key, never a
publishable key), STATEARK_OWNER_ID, and STATEARK_STORAGE_BUCKET.
Cloud is a mirror, not the master:
- the local savepoint is committed first and a cloud failure cannot invalidate it;
- cloud deletion does not delete local data;
- sync status lives in
meta.json(disabled/pending/synced/failed); - retry a failed push with the
sync_savepointtool.
Text/code artifacts up to 2 MB are mirrored inline in Postgres; everything else goes to the private Storage bucket. The mirror is not end-to-end encrypted — the Supabase project can read what it stores. Sync is off by default for exactly that reason; turn it on only for a project you would be comfortable putting in any hosted database.
Savepoint behaviour
When you say Savepoint, the host LLM should:
- reconstruct the latest valid state rather than summarise chronology;
- retain governing decisions, requirements and constraints;
- keep rejected approaches only when the reason matters;
- send exact text/code as
transfer=text; - send binary bytes as
transfer=base64only when truly available; - otherwise mark the artifact
transfer=pendinginstead of fabricating it; - omit files that have not changed — they are carried forward automatically;
- never abbreviate a file with
... rest unchanged.
Local creation is atomic: StateArk writes a temporary bundle and renames it only when
complete. Artifact names are sanitised; if a name had to be changed, manifest.json
records the original under original_name.
Integrity checks
Every savepoint is compared against its predecessor. Findings are returned in the tool
result and rendered at the top of state.md. The savepoint is always written — a
check never costs you work, it only tells the model to come clean.
| Code | Meaning |
|---|---|
artifact_carried_forward |
file was not re-submitted and not declared deleted, so it was copied from the previous version |
artifact_became_pending |
content that was stored is now only pending |
artifact_shrank |
file collapsed to under 50% of its previous size |
truncation_marker |
stored text contains ... rest unchanged, [...], … gekürzt and similar |
no_change |
this savepoint is identical to the previous one |
journal_not_reflected |
decisions were journalled but the submitted state lists none |
artifacts_mentioned_but_missing |
the state text names a file (schema.sql, app.py, …) that was never handed over as an artifact |
The last one is the check that matters most in practice. StateArk cannot read your chat, so a filename appearing in the prose is the only available clue that the model described a file instead of preserving it. The warning is phrased as a question, because a named file may legitimately be planned or live outside the conversation.
Journal
note_event records one short line per turning point, silently, and only for projects
that already exist in StateArk. Untracked projects return tracked: false and nothing is
written — that is the filter that keeps scratch conversations out.
At the next Savepoint the journal is consolidated into the new version and cleared. It is never cleared before the savepoint is durably on disk.
Inspect pending entries with the journal tool. Nudging is based on entry count
(STATEARK_JOURNAL_NUDGE_AT, default 20), never on a timer.
Diff
diff_savepoints with no version arguments compares the latest savepoint against its
predecessor: LCS line diff on the text fields, set diff on the lists, SHA-256 comparison on
the artifacts, plus an attention block for anything that looks like silent loss.
Artifacts
Every stored artifact has a SHA-256. Pending files are explicit in manifest.json and in
the resume_project output, so the LLM cannot quietly pretend a file exists.
If a binary cannot travel through MCP, open the local upload page printed at startup and attach it to the existing project/version. This resolves the pending manifest entry.
Resume
Resume My Project returns state.md plus the artifact manifest. The LLM calls
get_artifact for exact text only when needed. For binaries it gets the verified local
path and hash rather than invented content.
MCP clients
- Claude Desktop —
npx statearkregisters the stdio entrypoint for you. - Claude Code — point it at the local Streamable HTTP endpoint:
claude mcp add --transport http ... - Codex, Hermes and other local MCP hosts — point them at the same store root and
they share your savepoints. Each client is configured separately; there is no shared
setting. StateArk writes a
README.mdinto the store explaining the layout, which most coding agents will read on their own. - ChatGPT web/mobile, Gemini, and other hosted clients — these dial your server from
the vendor's cloud and cannot reach
localhoston your machine. That is a networking fact, not a missing feature. Reaching your savepoints from a hosted client needs an authenticated HTTPS route to your own machine; it is on the roadmap and does not exist yet.
Roadmap
Nothing here exists yet. In roughly this order:
- Optional cloud storage — your savepoints mirrored so a dead laptop is not a dead project. Off by default, and only ever a copy: your disk stays the original.
- Remote access — reaching your state from web and mobile clients, not just the desktop app on the one machine that holds it.
- Branching — two chats working the same project currently produce one linear chain of versions. Documented, not solved.
- State pruning — over many savepoints
state.mdgrows without limit. It needs a size ceiling and a rule for what ages out.
StateArk is free to use, including commercially. See the licence above for the one thing it does not allow.
StateArk MCP questions
How do I add StateArk MCP to Claude Code?
Run claude mcp add stateark -- npx -y stateark in your terminal. Add --scope user to make it available in every project.
How do I add StateArk MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
Is my data uploaded to the cloud?
No, it is local by default. Savepoints are stored in ordinary folders on your machine and nothing is uploaded unless you opt-in to Supabase sync.
Can multiple AI agents use the same project?
Yes, writes are serialized across processes to prevent version conflicts, though simultaneous writing from two different machines may cause sync conflicts.