{
  "markdown": "# StateArk\n\n**Never explain your project to an AI twice.**\n\nYour chat is a workspace, not an archive. StateArk turns a working session into a\nversioned, portable project state that any new chat can pick up. Open terminal and write:\n\n```bash\nnpx stateark\n```\n\nThen quit Claude Desktop completely (Cmd+Q) and reopen it. That is the whole install.\n\n*(Prefer to install from source? `npm install && npm run build && npm run setup` —\nsee `INSTALL.md`. Undo any time with `npx stateark remove`.)*\n\nHere what we had in mind developing stateark - we address a problem millions of users have...\n\n```\nYou:  ...three hours of work...\nYou:  Savepoint\n      -> my-project v0.3 written to ~/StateArk\n\n      (next day, new chat, empty context)\n\nYou:  Resume my-project\n      -> decisions, constraints, rejected approaches, open questions,\n         and the actual files - all current, none of the detours\n```\n\n**Local by default.** Savepoints are ordinary folders of Markdown, JSON and your real\nfiles. Nothing is uploaded. If StateArk disappears tomorrow, you still have everything.\n\n```text\n~/StateArk/projects/my-project/v0.3/\n  state.md        <- the canonical state, readable in any editor\n  state.json\n  manifest.json   <- every artifact with its SHA-256\n  artifacts/\n    app.py\n    schema.sql\n```\n\n## Commands\n\n| In the chat | What happens |\n| --- | --- |\n| `Savepoint` | consolidate the session into a new version |\n| `Resume <project>` | load the latest state into a fresh chat |\n| `History <project>` | list the versions |\n| `Diff <project>` | what actually changed between two savepoints |\n\n| In the terminal | |\n| --- | --- |\n| `npx stateark` | register with Claude Desktop |\n| `npx stateark report` | anonymised local usage summary, printed for you only |\n| `npx stateark remove` | unregister; savepoints are kept |\n\n## What makes it more than a summary\n\n- **Carry-forward.** Files you do not re-submit are copied into the new version with\n  their original hash, so a forgetful model cannot silently lose your schema.\n- **Integrity checks.** StateArk cannot see your chat - so it checks what it *can*:\n  truncation markers (`// ... rest unchanged`), files that collapsed in size, files the\n  state describes but never handed over, savepoints identical to their predecessor.\n  It warns, it never blocks: the savepoint is always written.\n- **Journal.** Between savepoints the model quietly records turning points, so a\n  Savepoint at the end of a long session does not depend on a degraded context.\n  Only for projects you already saved once - scratch conversations are never touched.\n\n## Requirements\n\nNode 20+. Claude Desktop, or Claude Code (`claude mcp add --transport http ...`).\nIt also runs under other local MCP hosts — users have it working with Codex and\nHermes against the same store.\n\nHosted clients that dial your server from the vendor's cloud (Claude web,\nChatGPT web) cannot reach `localhost`. See `INSTALL.md`.\n\n## Several agents at once\n\nSupported, and worth saying plainly because it is the setup that broke first.\nWrites to a project are serialised across processes, so two agents cannot claim\nthe same version number. If a savepoint reports that another process is busy,\nrepeat it in a moment — nothing is lost. A process that dies mid-write releases\nits lock automatically.\n\nIf your store lives in Dropbox, OneDrive or iCloud Drive: several agents on **one**\nmachine are fine. Two **machines** writing the same store simultaneously is a sync\nconflict, which the sync client resolves and StateArk cannot.\n\n| Variable | Default | |\n| --- | --- | --- |\n| `STATEARK_LOCK_WAIT_MS` | `60000` | how long to wait for another process before giving up |\n| `STATEARK_LOCK_STALE_MS` | `120000` | when a lock is assumed to belong to a dead process |\n| `STATEARK_FS_RETRIES` | `6` | retries when a sync client holds a file open |\n\n## Licence\n\n[Elastic License 2.0](https://www.elastic.co/licensing/elastic-license). Use it for\nanything including commercially, read and modify the source, share the package. You may\nnot offer it to third parties as a hosted or managed service. Your savepoints are yours\nand are not covered by this licence.\n\n---\n\n## Architecture\n\n```text\nChatGPT / Claude / Gemini-capable MCP client\n                 |\n                 v\n          StateArk Local Agent      <- 127.0.0.1 only, by default\n                 |\n                 v\n        ~/StateArk/projects         <- SOURCE OF TRUTH\n                 |\n                 | optional\n                 v\n             Supabase               <- mirror / backup / transport\n```\n\nA Savepoint is an ordinary directory, not a proprietary database:\n\n```text\nStateArk/projects/my-project/\n  journal.ndjson      # entries recorded since the last savepoint\n  project.json        # index (self-healing: rebuilt from disk if corrupt)\n  v0.3/\n    state.md          # human- and LLM-readable canonical state + integrity warnings\n    state.json        # the same state, structured\n    meta.json         # version, lineage, platform, sync status, warnings\n    manifest.json     # artifacts with SHA-256, stored/pending, carried_forward_from\n    journal.ndjson    # the entries this savepoint consolidated\n    artifacts/\n      app.py\n      schema.sql\n      prototype.zip\n```\n\nIf StateArk disappears, those files remain usable.\n\n## Install\n\nRequires Node 20+.\n\n```bash\nnpm install\nnpm run typecheck\nnpm test          # 97 checks against a throwaway store — run this first\nnpm start\n```\n\nNo `.env` is needed for local-only mode. Copy `.env.example` to `.env` only if you want\nto change the port, the store location, or enable the Supabase mirror.\n\nOn first run StateArk generates a random access key and stores it in\n`~/StateArk/.access-key` (mode 0600). The startup banner prints your endpoints:\n\n```\nMCP:         http://localhost:8787/mcp/<key>\nUpload page: http://localhost:8787/upload/<key>\nHealth:      http://localhost:8787/health\n```\n\n## Security model\n\nThe HTTP entrypoint is a local server on your own machine, so StateArk assumes any web page\nyou visit is hostile:\n\n| Control | Default |\n| --- | --- |\n| Bind address | `127.0.0.1` (`STATEARK_BIND` to change) |\n| Access key | random per install, in `<root>/.access-key`, constant-time compared |\n| `Origin` header | loopback only, plus `STATEARK_ALLOWED_ORIGINS` |\n| `Host` header | loopback only, plus `STATEARK_ALLOWED_HOSTS` (DNS-rebinding guard) |\n| CORS | echoes the validated origin, never `*` |\n| Upload form | single-use CSRF token, capped body size |\n| Non-loopback bind | refuses to start unless the access key is ≥ 24 chars |\n\nBefore exposing the agent over HTTPS: set a long `STATEARK_ACCESS_KEY`, set\n`STATEARK_ALLOWED_HOSTS` to your tunnel hostname, and put a real reverse proxy in front.\n\n## Platform reality\n\nLocal-first and hosted LLMs are different networking environments. Claude Desktop/Code and\nother local MCP clients can talk to the local agent directly. A hosted ChatGPT/Gemini\nclient generally cannot reach `localhost` on your computer. For those you would need a\nsecure HTTPS route to your running local agent — remote access is on the roadmap and does\nnot exist yet.\n\nIf you are setting this up, in this order:\n\n1. run StateArk locally;\n2. test Savepoint and Resume from a local MCP client;\n3. enable Supabase sync only if you actually want a mirror;\n4. expose the agent over HTTPS only after the three steps above work.\n\n## Local-only mode — the default\n\nLeave `SUPABASE_URL`, `SUPABASE_SECRET_KEY` and `STATEARK_OWNER_ID` unset. Cloud sync stays\noff and files never leave the machine. Default store: `~/StateArk`\n(override with `STATEARK_LOCAL_ROOT`).\n\nThis is what you get out of the box. The Supabase section below is opt-in.\n\n## Local + Supabase sync\n\nRun the migrations in the Supabase SQL editor, in order:\n\n1. `supabase/migrations/001_stateark.sql`\n2. `supabase/migrations/002_artifacts.sql`\n3. `supabase/migrations/003_hardening.sql`\n\nThen set `SUPABASE_URL`, `SUPABASE_SECRET_KEY` (server-side **Secret** key, never a\npublishable key), `STATEARK_OWNER_ID`, and `STATEARK_STORAGE_BUCKET`.\n\nCloud is a mirror, not the master:\n\n- the local savepoint is committed first and a cloud failure cannot invalidate it;\n- cloud deletion does not delete local data;\n- sync status lives in `meta.json` (`disabled` / `pending` / `synced` / `failed`);\n- retry a failed push with the `sync_savepoint` tool.\n\nText/code artifacts up to 2 MB are mirrored inline in Postgres; everything else goes to the\nprivate Storage bucket. **The mirror is not end-to-end encrypted** — the Supabase project\ncan read what it stores. Sync is off by default for exactly that reason; turn it on only\nfor a project you would be comfortable putting in any hosted database.\n\n## Savepoint behaviour\n\nWhen you say `Savepoint`, the host LLM should:\n\n- reconstruct the latest valid state rather than summarise chronology;\n- retain governing decisions, requirements and constraints;\n- keep rejected approaches only when the reason matters;\n- send exact text/code as `transfer=text`;\n- send binary bytes as `transfer=base64` only when truly available;\n- otherwise mark the artifact `transfer=pending` instead of fabricating it;\n- **omit** files that have not changed — they are carried forward automatically;\n- **never** abbreviate a file with `... rest unchanged`.\n\nLocal creation is atomic: StateArk writes a temporary bundle and renames it only when\ncomplete. Artifact names are sanitised; if a name had to be changed, `manifest.json`\nrecords the original under `original_name`.\n\n## Integrity checks\n\nEvery savepoint is compared against its predecessor. Findings are returned in the tool\nresult and rendered at the top of `state.md`. **The savepoint is always written** — a\ncheck never costs you work, it only tells the model to come clean.\n\n| Code | Meaning |\n| --- | --- |\n| `artifact_carried_forward` | file was not re-submitted and not declared deleted, so it was copied from the previous version |\n| `artifact_became_pending` | content that was stored is now only pending |\n| `artifact_shrank` | file collapsed to under 50% of its previous size |\n| `truncation_marker` | stored text contains `... rest unchanged`, `[...]`, `… gekürzt` and similar |\n| `no_change` | this savepoint is identical to the previous one |\n| `journal_not_reflected` | decisions were journalled but the submitted state lists none |\n| `artifacts_mentioned_but_missing` | the state text names a file (`schema.sql`, `app.py`, …) that was never handed over as an artifact |\n\nThe last one is the check that matters most in practice. StateArk cannot read your chat,\nso a filename appearing in the prose is the only available clue that the model *described*\na file instead of preserving it. The warning is phrased as a question, because a named file\nmay legitimately be planned or live outside the conversation.\n\n## Journal\n\n`note_event` records one short line per turning point, silently, and only for projects\nthat already exist in StateArk. Untracked projects return `tracked: false` and nothing is\nwritten — that is the filter that keeps scratch conversations out.\n\nAt the next Savepoint the journal is consolidated into the new version and cleared. It is\nnever cleared before the savepoint is durably on disk.\n\nInspect pending entries with the `journal` tool. Nudging is based on entry count\n(`STATEARK_JOURNAL_NUDGE_AT`, default 20), never on a timer.\n\n## Diff\n\n`diff_savepoints` with no version arguments compares the latest savepoint against its\npredecessor: LCS line diff on the text fields, set diff on the lists, SHA-256 comparison on\nthe artifacts, plus an `attention` block for anything that looks like silent loss.\n\n## Artifacts\n\nEvery stored artifact has a SHA-256. Pending files are explicit in `manifest.json` and in\nthe `resume_project` output, so the LLM cannot quietly pretend a file exists.\n\nIf a binary cannot travel through MCP, open the local upload page printed at startup and\nattach it to the existing project/version. This resolves the pending manifest entry.\n\n## Resume\n\n`Resume My Project` returns `state.md` plus the artifact manifest. The LLM calls\n`get_artifact` for exact text only when needed. For binaries it gets the verified local\npath and hash rather than invented content.\n\n## MCP clients\n\n- **Claude Desktop** — `npx stateark` registers the stdio entrypoint for you.\n- **Claude Code** — point it at the local Streamable HTTP endpoint:\n  `claude mcp add --transport http ...`\n- **Codex, Hermes and other local MCP hosts** — point them at the same store root and\n  they share your savepoints. Each client is configured separately; there is no shared\n  setting. StateArk writes a `README.md` into the store explaining the layout, which most\n  coding agents will read on their own.\n- **ChatGPT web/mobile, Gemini, and other hosted clients** — these dial your server from\n  the vendor's cloud and cannot reach `localhost` on your machine. That is a networking\n  fact, not a missing feature. Reaching your savepoints from a hosted client needs an\n  authenticated HTTPS route to your own machine; it is on the roadmap and does not exist\n  yet.\n\n## Roadmap\n\nNothing here exists yet. In roughly this order:\n\n- **Optional cloud storage** — your savepoints mirrored so a dead laptop is not a dead\n  project. Off by default, and only ever a copy: your disk stays the original.\n- **Remote access** — reaching your state from web and mobile clients, not just the\n  desktop app on the one machine that holds it.\n- **Branching** — two chats working the same project currently produce one linear chain\n  of versions. Documented, not solved.\n- **State pruning** — over many savepoints `state.md` grows without limit. It needs a\n  size ceiling and a rule for what ages out.\n\nStateArk is free to use, including commercially. See the licence above for the one thing\nit does not allow.\n",
  "bytes": 13788,
  "sha": "d57732addfff18083d79d4082445a8051b3e0b0fb36d6180264de975aae74c6a",
  "repo_slug": "askrion/stateark",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_askrion_stateark_4a9967a3/readme"
}