{
  "markdown": "# @helm-protocol/ttt-mcp\n\n> Reference implementation of [draft-helmprotocol-tttps](https://datatracker.ietf.org/doc/draft-helmprotocol-tttps/) (IETF Experimental)\n\n**Proof-of-Time attestation — Ed25519-signed timestamps with multi-source corroboration and explicit error bounds. IETF draft-helmprotocol-tttps**\n\n---\n\n## EU AI Act Art. 50 — AI-Generated Content Transparency\n\nTTTPS provides cryptographic time-provenance for AI-generated content at the moment of creation. A `pot_generate` call anchors a tamper-evident timestamp to a cryptographic hash of the content record — independently of any embedded metadata.\n\n**C2PA complementarity**: C2PA metadata is stripped during recapture, transcoding, and format conversion. TTTPS survives as an external anchor independently verifiable without metadata chain continuity — allowing forensic reconstruction of content provenance even when embedded markers are absent.\n\n**GDPR-compatible by design**: PoT records contain no content and no personal identifiers. Each record binds a cryptographic hash (SHA-256 + HMAC-SHA256) to a multi-source time attestation. No plaintext content transits or is stored on Helm servers.\n\nIETF specification: [`draft-helmprotocol-tttps`](https://datatracker.ietf.org/doc/draft-helmprotocol-tttps/) (ISE track). Contact: peter@kenosian.com.\n\n---\n\n## The Problem: Workflow Amnesia\n\nEvery Claude Code long-horizon workflow hits the same wall: **context compression erases action history.**\n\nAgent B has no memory of what Agent A decided. Agent A resumes after compression with no record of its own prior steps. Duplicate work. Lost decisions. State corruption.\n\n**ttt-mcp is the external causal chain that survives context compression.**\n\nEvery workflow step is anchored to a cryptographic timestamp on an **external server** — physically separate from Claude's context window. When compression happens, agents call `pot_query(eventId)` for O(1) exact step recall and resume with full causal context.\n\n```\nClaude workflow → [context compressed] → agents call pot_query(eventId)\n                                         → external server returns full timeline\n                                         → workflow resumes, zero lost state\n```\n\n---\n\n## Mathematical Guarantees\n\n| Layer | Mechanism | Guarantee |\n|-------|-----------|-----------|\n| **Identity** | SHA-3 eventId (256-bit) | Collision probability 2⁻²⁵⁶ — practically zero |\n| **Lookup** | O(1) exact retrieval | No context consumed by history reconstruction |\n| **Ordering** | TTTPS causal timestamps | Total order on events — tamper-proof sequence proof |\n| **Causal chain** | prevEventId DAG | O(depth) traversal — depth ~100 for 1B-token workflows |\n| **Non-repudiation** | Ed25519 signature | Cryptographic proof of who acted when |\n| **Resilience** | Erasure-coded cryptographic shards | ≥97% recovery at BER=0.05, 99.88% at BER=0.02 (theoretical) |\n| **Persistence** | Redis AOF + 90-day TTL | Server survives context compression and restarts |\n\n---\n\n## Quick Start\n\n### Claude Code\n\n```bash\nclaude mcp add ttt -- npx -y @helm-protocol/ttt-mcp@0.3.3\n```\n\nWith an API key (raises the free limit to your plan's monthly quota):\n```bash\nclaude mcp add ttt -e TTT_API_KEY=your-key -- npx -y @helm-protocol/ttt-mcp@0.3.3\n```\n\n### Claude Desktop\n\nAdd to `claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"ttt\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@helm-protocol/ttt-mcp@0.3.3\"],\n      \"env\": { \"TTT_API_KEY\": \"your-key\" }\n    }\n  }\n}\n```\n\n### Cursor\n\n[![Add to Cursor](https://img.shields.io/badge/Add%20to%20Cursor-1a1a1a?style=flat&logo=cursor&logoColor=white)](https://cursor.com/install-mcp?name=ttt&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBoZWxtLXByb3RvY29sL3R0dC1tY3BAMC4zLjMiXX0=)\n\nOne-click install, or add the same `mcpServers` block above to `.cursor/mcp.json`.\n\nFree tier: 100 calls/day per IP — no signup needed.\n\n---\n\n## 5-Minute Test\n\nOnce connected, run this sequence in Claude:\n\n**Step 1 — Stamp a workflow step:**\n\nJust tell Claude naturally:\n> \"Stamp this step as my-first-step\"\n> \"Record what I just did as refactor-auth-step1\"\n\nClaude calls `pot_generate` automatically. Or call it directly:\n```\npot_generate(eventId: \"my-first-step\")\n```\n\n**Step 2 — Simulate context compression:** start a new Claude session\n\n**Step 3 — Recover in the new session:**\n\nTell Claude:\n> \"What did I do in my-first-step?\"\n> \"Recover my last workflow state\"\n\nOr call directly:\n```\npot_query(eventId: \"my-first-step\")\n```\n→ Returns exact record. Amnesia gone.\n\n**Step 4 — Build a causal chain:**\n```\npot_generate(eventId: \"step-2\", prevEventId: \"my-first-step\")\npot_graph(eventId: \"step-2\", depth: 5)\n```\n→ Full backward chain. Cryptographically ordered.\n\n---\n\n## 8 Tools\n\n| Tool | Purpose |\n|------|---------|\n| `pot_generate` | Stamp a workflow step with a cryptographic timestamp |\n| `pot_verify` | Verify a PoT signature |\n| `pot_verify_v08` | Verify a draft-08 §3 Payload Digest record |\n| `pot_query` | O(1) exact lookup by eventId — core amnesia recovery |\n| `pot_graph` | Traverse causal DAG (backward + forward chain) |\n| `pot_checkpoint` | Roll up events into a compressed summary — use every ~100 events or before long tasks |\n| `pot_stats` | Server statistics and mode status |\n| `pot_health` | Health check |\n\n---\n\n## Tool Parameters\n\n### pot_generate\n\nStamp a workflow step with a cryptographic timestamp. For Claude Code: use `eventId` + `prevEventId`. For DeFi: use `txHash` + `chainId` + `poolAddress`. To bind the attestation to a specific piece of content (draft-08 §3 Payload Digest), also supply `contentDigest`. One of `eventId`, `txHash`, or `contentDigest` is required.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| eventId | string | Either/or | Workflow step identifier. E.g. `\"refactor_auth_step1\"` |\n| prevEventId | string | No | Previous step's eventId — links steps into a causal chain |\n| txHash | string | Either/or | Transaction hash (DeFi, hex with 0x prefix) |\n| chainId | number | No | EVM chain ID (DeFi) |\n| poolAddress | string | No | DEX pool contract address (DeFi) |\n| contentDigest | string | Either/or | SHA-256 digest (lowercase hex, 64 chars) of the content this record attests to. Computed by the caller — the server never sees the content. When the local time synthesis meets draft-08's own requirements (≥3 independent sources, a representable error bound), the response includes a spec-conformant `potRecordV08` binary record (hex); otherwise `potRecordV08Error` explains why not. |\n| ctxId | string | No | draft-08 §3.3 context identifier (Commitment domain separator, max 255 octets). Defaults to a fixed server value; MAY be public. |\n\n### pot_verify_v08\n\nVerify a draft-08 §3 record produced by `pot_generate`'s `potRecordV08` field: recomputes the Commitment, checks the Ed25519 signature, and — if `content` is supplied — checks it against the record's Payload Digest.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| potRecordV08 | string | Yes | Hex-encoded 184 or 216-octet record |\n| ctxId | string | No | Must match what `pot_generate` used, or verification fails |\n| issuerPubKey | string | No | Hex-encoded 32-byte raw Ed25519 public key. Defaults to this server's own key. |\n| content | string | No | Payload to check against the record's Payload Digest field |\n\n### pot_query\n\nQuery Proof of Time records. Use `eventId` for O(1) exact lookup after context compression.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| eventId | string | No | Exact step lookup — collision probability 2⁻²⁵⁶ |\n| startTime | number | No | Start time (unix ms). Default: 24h ago |\n| endTime | number | No | End time (unix ms). Default: now |\n| limit | number | No | Max entries to return. Default: 100, max: 1000 |\n\n### pot_graph\n\nTraverse the causal chain from any step. Returns backward chain (ancestors) and forward chain (descendants).\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| eventId | string | Yes | Step to traverse from |\n| depth | number | No | Max backward depth. Default: 10, max: 100 |\n\n**Returns:**\n- `backwardChain` — ancestors in chronological order (depth-compressed for large chains)\n- `forwardChain` — steps that follow the given eventId\n- `chainBroken` — `true` if a gap is detected (ancestor was evicted from ring buffer, or the chain root references an unknown entry)\n- `brokenAt` — `\"server_restart\"` if the gap was caused by a server restart clearing in-memory state; otherwise the eventId at which the break occurred; `null` if chain is intact\n- `reachableDepth` — number of ancestors successfully traversed before the gap (or chain root)\n\n**Causal chain gap causes:**\n- **`server_restart`**: the server restarted and the in-memory DAG was cleared. If Redis is available and `REDIS_URL` is set, the DAG is rebuilt from Redis on startup — reducing restart gaps.\n- **Ring-buffer eviction**: the ring buffer holds the most recent 10,000 events in memory. Ancestors beyond that window show as `chainBroken: true` with `brokenAt` set to the oldest reachable eventId.\n\n**Recovering from a gap**: call `pot_checkpoint` before long tasks to compress and preserve the chain within the token budget, or use Redis persistence to survive restarts.\n\n### pot_verify\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| potHash | string | Yes | PoT hash to verify (hex with 0x prefix) |\n| grgShards | string[] | Yes | Array of hex-encoded cryptographic integrity shards |\n| chainId | number | Yes | EVM chain ID |\n| poolAddress | string | Yes | Uniswap V4 pool address |\n\n### pot_stats\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| period | `\"day\"` \\| `\"week\"` \\| `\"month\"` | Yes | Time period for statistics |\n\n### pot_health\n\nNo parameters.\n\n### pot_checkpoint\n\nCreates a compressed rollup checkpoint of workflow history.\n\n**Use when:** Approaching context limit, before long tasks, or every ~100 events.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| fromEventId | string | No | Start of range — first eventId in the causal chain to include |\n| toEventId | string | No | End of range — last eventId in the causal chain to include |\n| startTime | number | No | Unix ms. Default: 1 hour ago |\n| endTime | number | No | Unix ms. Default: now |\n| maxTokens | number | No | Approximate max tokens for rollup output. Default: 2000 |\n\n**Returns:**\n- `checkpointId` — unique checkpoint identifier\n- `rollup` — compressed event history (depth-adaptive: full/compact/minimal/rollup)\n- `summary` — human-readable one-line summary of the checkpoint\n- `chainIntact` — whether the causal chain is unbroken\n- `nextCheckpointHint` — recommended events before next checkpoint\n\n**Depth-adaptive compression:**\n\n| Depth | Format | ~Tokens |\n|-------|--------|---------|\n| 1–5 | Full entry | ~200/event |\n| 6–20 | Compact (id+hash+ts) | ~80/event |\n| 21–50 | Minimal (id+ts) | ~30/event |\n| 51+ | Rollup string | ~10/event |\n\n---\n\n## Use Cases\n\n### 1. Claude Code Workflow — Amnesia Prevention\n\n**Problem**: A 20-agent Dynamic Workflow refactors a 500K-line codebase over hours. After each context compression, agents have no memory of what they already processed. Duplicate work. State corruption.\n\n**Solution**: Each agent stamps its steps with `pot_generate(eventId, prevEventId)`. After compression, it calls `pot_query(eventId)` to recover its exact action history — what ran, when, in what order — from the external server. The server is outside Claude's context window; compression never touches it.\n\n```typescript\n// Agent starts a workflow step\nconst pot = await client.callTool({\n  name: \"pot_generate\",\n  arguments: {\n    eventId: \"refactor_auth_module_step3\",\n    prevEventId: \"refactor_auth_module_step2\"\n  }\n});\n// pot.potHash — cryptographic proof this step happened at this time\n\n// After context compression, agent recovers its history:\nconst history = await client.callTool({\n  name: \"pot_query\",\n  arguments: { eventId: \"refactor_auth_module_step3\" }\n});\n// history.local[0] — exact record: timestamp, prevEventId, potHash\n// history.found: true — O(1) lookup, collision probability 2⁻²⁵⁶\n\n// Traverse full causal chain:\nconst chain = await client.callTool({\n  name: \"pot_graph\",\n  arguments: { eventId: \"refactor_auth_module_step3\", depth: 20 }\n});\n// chain.backwardChain — all ancestor steps in chronological order\n// chain.forwardChain — steps that follow this one\n// chain.chainBroken — true if a gap was detected in the ancestor chain\n// chain.brokenAt    — \"server_restart\" if the server restarted and cleared\n//                     the in-memory DAG; otherwise the eventId of the oldest\n//                     reachable ancestor before the gap; null if chain intact\n// chain.reachableDepth — how many ancestors were recovered before the gap\n\n// Handle a server-restart gap:\nif (chain.chainBroken && chain.brokenAt === \"server_restart\") {\n  // Server cleared in-memory state; ancestors before the gap are gone unless\n  // Redis was configured (REDIS_URL) — in that case the DAG was rebuilt on\n  // restart and chainBroken will be false.\n  // Recover by querying the most recent checkpoint or restarting from a known step.\n}\n```\n\n**Before a long task or every ~100 events — create a checkpoint:**\n\n```typescript\n// Compress workflow history before context fills up — by causal range:\nconst checkpoint = await client.callTool({\n  name: \"pot_checkpoint\",\n  arguments: {\n    fromEventId: \"refactor_auth_module_step1\",\n    toEventId: \"refactor_auth_module_step3\"\n  }\n});\n// checkpoint.checkpointId — store this; resume from it after compression\n// checkpoint.rollup — depth-adaptive compressed history (10–200 tokens/event)\n// checkpoint.chainIntact: true — causal chain verified unbroken\n// checkpoint.nextCheckpointHint: 87 — suggested events before next checkpoint\n\n// Or compress by time window with a token budget:\nconst checkpoint = await client.callTool({\n  name: \"pot_checkpoint\",\n  arguments: {\n    startTime: Date.now() - 3_600_000,  // last 1 hour\n    maxTokens: 1500\n  }\n});\n\n// After context compression, restore from checkpoint instead of re-querying all events:\nconst history = await client.callTool({\n  name: \"pot_query\",\n  arguments: { eventId: checkpoint.checkpointId }\n});\n// Full causal context restored in a single call\n```\n\n**Outcome**: Zero duplicate work. Full workflow timeline recoverable even after complete context resets.\n\n---\n\n### 2. MEV Bot — Transaction Ordering Proof\n\n**Problem**: You got front-run. You can't prove it — mempool timestamps are per-node, unsigned, non-authoritative.\n\n**Solution**: Call `pot_generate` before every submission. The PoT receipt is cryptographically signed using three independent time sources (NIST, Google, Cloudflare). The on-chain hash can be anchored via a separate Base Sepolia TTT ERC-1155 contract. If front-running occurs, you have a timestamped record predating the attacker's block inclusion.\n\n```typescript\nconst pot = await client.callTool({\n  name: \"pot_generate\",\n  arguments: { txHash: pendingTxHash, chainId: 8453, poolAddress: \"0x...\" }\n});\n// pot.potHash — your evidence, timestamped by NIST+Google+Cloudflare\n```\n\n> **Note:** The DeFi path (`txHash` + `chainId` + `poolAddress`) requires a server-side build with the integrity-shard pipeline enabled. It is not available in the public `openttt` npm package; calls without it will throw. The Claude Code path (`eventId`) works out of the box.\n\n---\n\n### 3. DEX Protocol — Sandwich Deterrence\n\n**Solution**: Integrate `TTTHookSimple` (Uniswap V4 hook, Base Sepolia: `0x8C633b05b833a476925F7d9818da6E215760F2c7`). Honest builders get `turbo` mode. Tampered sequences get `full` mode (penalty delay). Economics, not governance.\n\n> **Note:** Shard-based verification (`pot_verify` with `grgShards`) requires a server-side build with the integrity-shard pipeline enabled — not available in the public `openttt` npm package.\n\n---\n\n### 4. Hedge Fund / Prop Desk — MiFIR Art.22c Compliance\n\n**Problem**: MiFIR Article 22c / RTS 25 requires microsecond-precision UTC-synchronized timestamps. Hardware PTP appliances cost $50K–$500K.\n\n**Solution**: `pot_generate` produces an Ed25519-signed timestamp with an uncertainty bound and multi-source attestation. Structurally compatible with the RTS 25 audit record format. One API call per trade.\n\n```typescript\nconst audit = await client.callTool({\n  name: \"pot_generate\",\n  arguments: { txHash: tradeHash, chainId: 8453 }\n});\n// audit.timestamp: high-resolution timestamp\n// audit.uncertainty: ± bound (RTS 25 uncertainty field)\n// audit.confidence: fraction of sources that agreed\n```\n\n> **Precision note:** The default network time sources (Roughtime / NTP) provide a few-millisecond uncertainty bound. The MiFIR Art. 22c / RTS 25 ±1ms (and tighter) requirement is met only with an added GEO time source (KTSat); this is a roadmap configuration, not the default deployment.\n\n**Outcome**: Structurally compatible audit trail. IETF specification: `draft-helmprotocol-tttps`.\n\n---\n\n### 5. Multi-Agent Coordination — Causal Order Proof\n\n**Problem**: When multiple AI agents interact in a pipeline, the causal order matters for debugging and audit. Agent logs are unverifiable.\n\n**Solution**: Each agent stamps its action with `pot_generate`. The potHash chain is independently verifiable. `pot_graph` reconstructs who did what and in what order.\n\n---\n\n## How It Differs — A Different Job, Not \"Better\"\n\n| Tool | Integration | What it recalls | Integrity | Hot-path cost |\n|------|-------------|-----------------|-----------|---------------|\n| Letta (MemGPT) | owns the agent loop | self-editing semantic memory | none | embedding + vector search per memory op |\n| LangGraph / LangMem | LangGraph only | graph state / semantic | none | checkpoint I/O (+ embeddings) |\n| RAG / vector DB | bolt-on | fuzzy similarity | none | embed + vector search per item |\n| **ttt-mcp** | **2-min MCP retrofit** | **exact causal step (by eventId)** | **Ed25519 + TTTPS timestamp** | **sign + hash + write — 0 embedding calls** |\n\n**The cost difference is structural, not incidental.**\n\nLetta and Mem0 treat agent memory as a semantic search problem — every recall forces an LLM embedding call and a vector search. ttt-mcp bypasses the LLM/embedding layer entirely: state recovery is an O(1) cryptographic hash lookup. Marginal cost is commodity CPU + storage, not API tokens.\n\n**Scope**: agents stamp the steps worth checkpointing — not every token, not every query. Volume tracks decisions, not total chat traffic.\n\nIf you need fuzzy semantic search over past conversations, use Letta or a vector DB. If you need a zero-embedding, deterministic state recovery layer for long-horizon workflows that survives context compaction, use ttt-mcp.\n\n---\n\n## Pricing\n\n| Tier | Price | Calls/month |\n|------|-------|-------------|\n| Free | $0 | 100/day per IP — no signup |\n| Dev | $29/mo | 100K |\n| Pro | $99/mo | 1M |\n| Team | $299/mo | 10M + $0.01/1K overage |\n| Enterprise | $999+/mo | 100M calls/mo · $0.001/1K overage · SLA 99.9% |\n| Platform License | Negotiated ($2M+/yr) | Volume cap negotiated · native integration |\n\n**Subscribe:**\n\nDev **$29/mo** · Pro **$99/mo** · Team **$299/mo** — to subscribe, email [peter@kenosian.com](mailto:peter@kenosian.com).\n\nEnterprise & Platform License: [peter@kenosian.com](mailto:peter@kenosian.com)\n\nContact: peter@kenosian.com\n\n**Quota mechanics — stdio vs HTTP:**\n\n- **HTTP mode** (Glama / Smithery container, `PORT` set): the per-IP free tier limit (100 calls/day) is enforced locally in the server process.\n- **stdio mode** (Claude Code `npx`, Claude Desktop): there is no per-IP counter. Tool calls are delegated to `api.kenosian.com` via `X-TTT-API-Key`; quota is enforced server-side against your plan's monthly allowance. Without `TTT_API_KEY` the local fallback runs with no daily cap, but plan features (server-side DAG persistence, multi-session causal chains) are unavailable.\n\n---\n\n## Requirements\n\n- Node.js >= 18\n- Network access for time synthesis (HTTPS to time.nist.gov, time.google.com, time.cloudflare.com)\n\n**Time source tiers (automatic fallback):**\n\n| Tier | Source | Stratum | Notes |\n|------|--------|---------|-------|\n| 1 (preferred) | PTP / hardware clock | 0–1 | Requires local PTP daemon |\n| 2 | Roughtime / NTP (NIST, Google, Cloudflare) | 2–4 | Default for most deployments |\n| 3 (offline fallback) | Local system clock | 16 | RFC 5905 unsynchronized stratum — used when all network sources are unreachable |\n\nThe server falls through to stratum 16 automatically; no manual configuration needed. The `stratum` field in every `pot_generate` response indicates which tier was used.\n\n**Redis persistence (optional):**\n\nRedis is not required. The in-memory DAG is authoritative at runtime. If `REDIS_URL` is set, events are written to Redis with a 90-day TTL and the DAG is rebuilt from Redis on server restart — reducing `server_restart` chain gaps. Without Redis, the in-memory DAG is cleared on restart.\n\n---\n\n## Production Tips\n\n**Cold Start warm-up** — On first startup, BatchSigner requires one request to initialize. Call `pot_health` or send a single dummy `pot_generate` before your load balancer health check goes live. Without this, the first request may see p99 ~500ms; subsequent requests stabilize to <10ms.\n\n```bash\n# Kubernetes / Docker: add to your startup script\ncurl -s http://your-server/pot/health > /dev/null\n```\n\n---\n\n## Learn More\n\n- [OpenTTT SDK](https://www.npmjs.com/package/openttt) — The underlying SDK\n- [IETF Draft: draft-helmprotocol-tttps](https://datatracker.ietf.org/doc/draft-helmprotocol-tttps/) — TTTPS Protocol Specification\n- [Helm Protocol](https://github.com/Helm-Protocol) — GitHub\n\n## License\n\nBSL-1.1 — free for non-commercial use.\n\n**Commercial use** (production bots, hedge funds, prop desks) requires a license.\n\nChange Date: 2029-05-28 → Apache 2.0\n",
  "bytes": 22071,
  "sha": "5f117037d3543d39015e8034a4ac32b32ea8b8c72135ae0defc3d2828c333199",
  "repo_slug": "helm-protocol/openttt-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_helm_protocol_openttt_pot_229f8978/readme"
}