tuskpoint-mcp 0.1.0

TuskPoint: a verifiable LangGraph checkpointer backed by Walrus decentralized storage, with semantic recall via MemWal. Drop-in MCP plugin: 'uvx tuskpoint-mcp'.

TuskPoint: Verifiable LangGraph checkpoints on Walrus

TuskPoint is a drop-in LangGraph checkpointer that saves every step of an agent run as a verifiable Walrus blob. When a process crashes, you resume from exactly where it stopped, not from the beginning. From there you can roll back to any earlier moment, hand a run off to another agent and have it verify the bytes by hash, fork a checkpoint into a new thread, and diff, search, and audit the whole history. It ships an all-in-one MCP server, so any agent (Claude, Cursor, Windsurf, and more) can do all of this with a tool call through 11 checkpoint tools.

Plain-English search is powered by MemWal.

• Docs: https://tuskpoint.xyz/docs
• Live run dashboard: https://tuskpoint.xyz/dashboard

What is TuskPoint?

• A checkpointer, not a database. WalrusSaver is a standard LangGraph BaseCheckpointSaver. Drop it into your graph and every checkpoint is serialized, gzipped, and stored as a content-addressed Walrus blob, the exact layer you rewind to.
• Crash-proof by construction. State lives on a decentralized network, not in your process. A fresh process rehydrates the latest checkpoint and continues. The only thing kept locally is a blob pointer.
• Git for agent runs. checkpoint_fork branches any checkpoint into a new thread so you can replay a different path without touching the original.
• Cryptographically tamper-evident. Every blob is SHA-256 hashed at write time; verify_trail re-fetches each blob, recomputes its hash, and compares, so a swapped or corrupted blob is a FAIL, not just a failed download.
• Durable rollback. checkpoint_rollback re-writes an earlier state as a new head of the same thread. Append-only: nothing is deleted, so the audit trail stays intact and still verifies.
• Cross-agent hand-off. handoff_checkpoint emits a tiny descriptor (blob id
  • SHA-256); adopt_checkpoint re-fetches the blob, verifies the hash, and adopts it as a new thread, so a tampered blob is rejected before it becomes state.
• Searchable in plain English. A core part of TuskPoint: the MemWal layer writes a one-line summary per checkpoint, so an agent can recall its own past in plain language, pointers it then loads exactly.
• All-in-one MCP server. Eleven tools over stdio, plus tuskpoint_info which returns ready-to-paste client config.

Summary of MCP tools

The server (tuskpoint-mcp) exposes these over stdio:

Tool	Category	What it does
checkpoint_save(thread_id, state_json)	Write	Persist agent state as a new Walrus blob.
checkpoint_fork(source_thread, source_id, new_thread)	Write	Branch a checkpoint into a new thread (replay a different path).
checkpoint_load(thread_id, checkpoint_id?)	Read	Load a specific checkpoint (or the latest) by ID.
checkpoint_list(thread_id)	Read	List a thread's checkpoints, newest first, with lineage.
checkpoint_resume(thread_id)	Read	Return the latest state so an agent can continue.
checkpoint_diff(thread_id, id_a, id_b)	Read	Human-readable diff between two checkpoints.
checkpoint_rollback(thread_id, checkpoint_id)	Write	Durable, append-only undo: re-write an earlier state as a new head.
handoff_checkpoint(thread_id, checkpoint_id, to_agent?)	Write	Emit a portable, hash-stamped descriptor for another agent.
adopt_checkpoint(handoff_json, new_thread_id)	Write	Re-fetch + hash-verify a handoff and adopt it as a new thread.
verify_trail(thread_id)	Read	Re-hash every blob and compare to the stored SHA-256 (PASS/FAIL/UNVERIFIED).
checkpoint_search(query)	Discover	Semantic recall over checkpoint summaries (MemWal).
tuskpoint_info()	Meta	Describe the server and emit copy-paste client config.

Quick Start

TuskPoint is a drop-in MCP plugin. One line wires it into any MCP client, no clone, no server to run, no paths to set: uvx fetches and launches it and all eleven tools appear in your agent.

Add it to your client

A ready-to-use .mcp.json is included, and the same block works for every client; only the file location changes.

{
  "mcpServers": {
    "tuskpoint": {
      "command": "uvx",
      "args": ["tuskpoint-mcp"],
      "env": {
        "WALRUS_AGGREGATOR_URL": "https://aggregator.walrus-testnet.walrus.space",
        "WALRUS_PUBLISHER_URL": "https://publisher.walrus-testnet.walrus.space"
      }
    }
  }
}

• Claude Code: claude mcp add tuskpoint -- uvx tuskpoint-mcp
• Claude Desktop: add the block to claude_desktop_config.json.
• Cursor: .cursor/mcp.json
• Windsurf: ~/.codeium/windsurf/mcp_config.json
• VS Code (Copilot): .vscode/mcp.json (uses a servers key).
• OpenAI Codex CLI: ~/.codex/config.toml (TOML).

Full per-client instructions: https://tuskpoint.xyz/docs/clients. Or, from any client, call the tuskpoint_info tool and let the agent emit the right snippet.

Prefer the terminal? The same setup is served as plain text at one URL:

curl -sL https://tuskpoint.xyz/skills/setup

Reads from Walrus are public and free, so the plugin works out of the box on testnet. Only writes need a publisher and semantic search needs MemWal credentials, set them in the env block above or a .env (see .env.example).

Note: checkpoint_search returns an explanatory message instead of failing when no MemWal credentials are present, so the server runs fine without them.

See it live

The fastest way to watch a crash-and-resume, a diff, a rollback, and plain-English search is the live dashboard: https://tuskpoint.xyz/dashboard.

Run from source (contributors)

git clone https://github.com/faithabiodun/tuskpoint.git
cd tuskpoint
python -m pip install -e ".[all]"
cp .env.example .env   # then fill in your keys

From a checkout the server also runs with python mcp_server/server.py (a thin shim around the packaged tuskpoint-mcp entry point), and python scripts/check_walrus.py proves a live Walrus round-trip.

Exact vs. semantic: why both?

• Exact lookups are by ID, never fuzzy. checkpoint_load resolves the manifest entry → blob ID → Walrus GET → de-gzip → de-serialize. The blob you read is byte-for-byte the blob you wrote. This is the part you rewind to.
• Semantic search is for discovery. checkpoint_search asks MemWal for the nearest summaries, pointers carrying checkpoint IDs you then load exactly. Vector recall indexes the exact store; it is never the source of truth.

MemWal is the semantic memory layer TuskPoint builds on. TuskPoint writes a one-line summary of each checkpoint to MemWal, and checkpoint_search uses MemWal's recall to find the right moment, then hands you a pointer you load exactly from Walrus. Semantic recall handles discovery; the content-addressed blob stays the source of truth.

Network: testnet by default, mainnet when you're ready

TuskPoint defaults to Walrus testnet, writes are free via a public publisher, so you can try everything with zero setup or funds. Reads are public and free on either network.

When you want durable, paid storage, switch to mainnet by setting both environment variables (these take precedence over the defaults):

export WALRUS_PUBLISHER_URL=https://walrus-mainnet-publisher-1.staketab.org:443
export WALRUS_AGGREGATOR_URL=https://aggregator.walrus-mainnet.walrus.space

Mainnet writes cost SUI (gas) + WAL (storage), so there is no public, unauthenticated mainnet publisher; use a community publisher, run your own, or use the upload relay with a funded key. See https://tuskpoint.xyz/docs/mainnet.

Tests

python -m pytest -m "not integration"   # fast unit tests, no network
python -m pytest -m integration         # live Walrus round-trip + resume

What's included

src/langgraph_checkpoint_walrus/
  walrus_client.py   BlobStore protocol, InMemoryWalrusClient, real WalrusClient
  manifest.py        ThreadManifest / CheckpointEntry (id -> blob_id, lineage, blob_sha256)
  saver.py           WalrusSaver: gzip envelope per checkpoint, fork/rollback/handoff/verify_trail
  memwal_layer.py    MemWalLayer: build_summary + summarize_and_remember + search
  mcp_server.py      All-in-one MCP server: 11 checkpoint tools + tuskpoint_info (FastMCP), exposed as the `tuskpoint-mcp` command
mcp_server/server.py Thin shim that runs the packaged server (for source checkouts)
demo/                researcher→writer agent + crash/resume/fork/audit/rollback/handoff/semantic demos
scripts/             check_walrus.py, check_memwal.py (standalone proofs)
web/                 Next.js site + docs (https://tuskpoint.xyz)
tests/               unit (no network) + integration (live Walrus) suites

License

MIT, see LICENSE.