tuskpoint
faithabiodun/tuskpoint
Verifiable LangGraph agent checkpoints on Walrus — survive a crash, rewind to any moment, and search history in plain English via MemWal. Drop-in checkpointer + 6-tool MCP server + Next.js demo dashboard.
Instalação
npx convez-ai faithabiodun/tuskpoint1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
README
A tradução para o português deste README ainda está na fila.
TuskPoint — langgraph-checkpoint-walrus
Verifiable LangGraph agent state on Walrus, with semantic recall over checkpoint history via MemWal.
Built in small, testable increments.
What it is
Two layers:
-
WalrusSaver— a drop-in LangGraphBaseCheckpointSaver. Every checkpoint is serialized with LangGraph's own serde, gzipped, and stored as an immutable Walrus blob (the exact layer). A per-thread JSON manifest mapscheckpoint_id -> {blob_id, parent, timestamp, summary}. On every save it also writes a one-sentence natural-language summary to MemWal (the semantic layer), so an agent can later search its own past. -
mcp_server— an MCP server exposing six checkpoint tools (save / load / list / resume / diff / search) over stdio. It complements, and does not duplicate, MemWal's own MCP.
Architecture
┌─────────────────────────────────────────┐
LangGraph agent ──▶│ WalrusSaver │
(put / get_tuple) │ BaseCheckpointSaver[str] │
│ │
│ EXACT layer SEMANTIC layer │
│ ─────────── ────────────── │
│ serde→gzip→blob build_summary() │
│ │ │ │
└───────┼───────────────────────┼──────────┘
▼ ▼
┌──────────────────┐ ┌──────────────────┐
│ Walrus testnet │ │ MemWal │
│ publisher PUT / │ │ remember / recall │
│ aggregator GET │ │ (vector search) │
└──────────────────┘ └──────────────────┘
▲
│ latest manifest blob id cached in
│ .walrus_threads.json (only local state)
▼
┌──────────────────┐
│ mcp_server │ 6 tools over stdio:
│ (FastMCP) │ save load list resume diff search
└──────────────────┘
Exact vs. semantic — why both?
- Exact lookups are by ID, never fuzzy.
checkpoint_load(thread, id)resolves the manifest entry → blob ID → Walrus GET → de-gzip → de-serialize. This is deterministic and content-addressed: 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("when did the writer start?")asks MemWal for the nearest summaries. It returns pointers (summaries with thread/checkpoint IDs), which you then load exactly. Vector recall is never the source of truth — it's an index into the exact store.
How this differs from MemWal's own MCP
MemWal ships an MCP for free-form memories (remember / recall /
analyze / restore / login / logout). TuskPoint manages durable,
exactly-addressable checkpoints — agent state you can resume a graph from.
The only overlap, checkpoint_search, is deliberately scoped to our
checkpoint summaries, not general memories.
Quick start
python -m pip install -e ".[all]"
cp .env.example .env # then fill in your keys
All secrets come from environment variables (loaded from .env). See
.env.example for the full list. Never commit your real
.env — it is git-ignored.
Proofs and demos
Each build step has a runnable proof.
1. Walrus blob round-trip
python scripts/check_walrus.py
Writes a random blob to a testnet publisher, reads it back from an aggregator, and asserts the bytes are identical — printing the blob ID.
2. MemWal remember / recall
python scripts/check_memwal.py
Remembers a sentence, then recalls it semantically and prints the distance.
3–4. Crash / resume demo (the headline)
# In-memory fake backend (single process, interrupt then resume):
python demo/run_demo.py
# REAL Walrus testnet, surviving a genuine process kill:
python demo/run_demo.py --real --part1 # run to interrupt, persist, EXIT
python demo/run_demo.py --real --part2 # FRESH process rehydrates from Walrus
A researcher→writer agent is interrupted before the writer runs. --part2
starts a brand-new process that reads only the manifest blob ID from
.walrus_threads.json, pulls the checkpoint back from Walrus, and resumes the
writer to completion. That is the "survive a process kill" proof.
5. Semantic self-search
python demo/run_demo.py --semantic
Runs the agent on real Walrus + MemWal, then asks "when did the writer start?" and prints the nearest checkpoint summaries — the agent searching its own history.
MCP server
Six tools over stdio: checkpoint_save, checkpoint_load, checkpoint_list,
checkpoint_resume, checkpoint_diff, checkpoint_search.
Run it directly:
python mcp_server/server.py
Register with an MCP client
A ready-to-use .mcp.json is included. For Claude Desktop, add
the equivalent to claude_desktop_config.json:
{
"mcpServers": {
"tuskpoint-checkpoints": {
"command": "python",
"args": ["mcp_server/server.py"],
"cwd": "C:/Users/User/Documents/tuskpoint",
"env": {
"WALRUS_PUBLISHER_URL": "https://publisher.walrus-testnet.walrus.space",
"WALRUS_AGGREGATOR_URL": "https://aggregator.walrus-testnet.walrus.space",
"WALRUS_THREADS_CACHE": ".walrus_threads.json"
}
}
}
}
checkpoint_search returns an explanatory message instead of failing if no
MemWal credentials are present, so the server runs fine without them.
Tests
python -m pytest -m "not integration" # 16 fast unit tests, no network
python -m pytest -m integration # live Walrus round-trip + resume
Project layout
src/langgraph_checkpoint_walrus/
walrus_client.py BlobStore protocol, InMemoryWalrusClient, real WalrusClient
manifest.py ThreadManifest / CheckpointEntry (id -> blob_id, lineage)
saver.py WalrusSaver (BaseCheckpointSaver): gzip envelope per checkpoint
memwal_layer.py MemWalLayer: build_summary + summarize_and_remember + search
mcp_server/server.py 6 checkpoint tools over stdio (FastMCP)
demo/ researcher→writer agent + crash/resume/semantic demos
scripts/ check_walrus.py, check_memwal.py (standalone proofs)
tests/ unit (no network) + integration (live Walrus) suites
90-second video demo script
- (0:00) Show
check_walrus.py— "agent state lands on Walrus, byte-identical round-trip." - (0:15) Run
demo/run_demo.py --real --part1— agent interrupts before the writer, exits. - (0:35) Point at
.walrus_threads.json— "only a blob pointer survives locally; the state is on the network." - (0:45) Run
--real --part2in a fresh shell — "new process, resumes from Walrus, writer finishes." - (1:05) Run
--semantic— ask "when did the writer start?", show ranked summaries. - (1:20) Show the MCP server tools list — "any MCP agent can save/load/diff/search checkpoints."