@helm-protocol/ttt-mcp

Reference implementation of draft-helmprotocol-tttps-00 (IETF Experimental)

MCP Server for OpenTTT — Proof of Time tools for AI agents

The Problem: Workflow Amnesia

Every Claude Code long-horizon workflow hits the same wall: context compression erases action history.

Agent 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.

ttt-mcp is the external causal chain that survives context compression.

Every 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.

Claude workflow → [context compressed] → agents call pot_query(eventId)
                                         → external server returns full timeline
                                         → workflow resumes, zero lost state

Mathematical Guarantees

Quick Start

Claude Code

claude mcp add ttt -- npx -y @helm-protocol/ttt-mcp@0.3.0

With an API key (raises the free limit to your plan's monthly quota):

claude mcp add ttt -e TTT_API_KEY=your-key -- npx -y @helm-protocol/ttt-mcp@0.3.0

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "ttt": {
      "command": "npx",
      "args": ["-y", "@helm-protocol/ttt-mcp@0.3.0"],
      "env": { "TTT_API_KEY": "your-key" }
    }
  }
}

Cursor

One-click install, or add the same mcpServers block above to .cursor/mcp.json.

Free tier: 100 calls/day per IP — no signup needed.

5-Minute Test

Once connected, run this sequence in Claude:

Step 1 — Stamp a workflow step:

Just tell Claude naturally:

"Stamp this step as my-first-step" "Record what I just did as refactor-auth-step1"

Claude calls pot_generate automatically. Or call it directly:

pot_generate(eventId: "my-first-step")

Step 2 — Simulate context compression: start a new Claude session

Step 3 — Recover in the new session:

Tell Claude:

"What did I do in my-first-step?" "Recover my last workflow state"

Or call directly:

pot_query(eventId: "my-first-step")

→ Returns exact record. Amnesia gone.

Step 4 — Build a causal chain:

pot_generate(eventId: "step-2", prevEventId: "my-first-step")
pot_graph(eventId: "step-2", depth: 5)

→ Full backward chain. Cryptographically ordered.

7 Tools

Tool Parameters

pot_generate

Stamp a workflow step with a cryptographic timestamp. For Claude Code: use eventId + prevEventId. For DeFi: use txHash + chainId + poolAddress. One of eventId or txHash is required.

pot_query

Query Proof of Time records. Use eventId for O(1) exact lookup after context compression.

pot_graph

Traverse the causal chain from any step. Returns backward chain (ancestors) and forward chain (descendants).

Returns:

• backwardChain — ancestors in chronological order (depth-compressed for large chains)
• forwardChain — steps that follow the given eventId
• chainBroken — true if a gap is detected (ancestor was evicted from ring buffer, or the chain root references an unknown entry)
• 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
• reachableDepth — number of ancestors successfully traversed before the gap (or chain root)

Causal chain gap causes:

• 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.
• 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.

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.

pot_verify

pot_stats

pot_health

No parameters.

pot_checkpoint

Creates a compressed rollup checkpoint of workflow history.

Use when: Approaching context limit, before long tasks, or every ~100 events.

Returns:

• checkpointId — unique checkpoint identifier
• rollup — compressed event history (depth-adaptive: full/compact/minimal/rollup)
• summary — human-readable one-line summary of the checkpoint
• chainIntact — whether the causal chain is unbroken
• nextCheckpointHint — recommended events before next checkpoint

Depth-adaptive compression:

Use Cases

1. Claude Code Workflow — Amnesia Prevention

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.

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.

// Agent starts a workflow step
const pot = await client.callTool({
  name: "pot_generate",
  arguments: {
    eventId: "refactor_auth_module_step3",
    prevEventId: "refactor_auth_module_step2"
  }
});
// pot.potHash — cryptographic proof this step happened at this time

// After context compression, agent recovers its history:
const history = await client.callTool({
  name: "pot_query",
  arguments: { eventId: "refactor_auth_module_step3" }
});
// history.local[0] — exact record: timestamp, prevEventId, potHash
// history.found: true — O(1) lookup, collision probability 2⁻²⁵⁶

// Traverse full causal chain:
const chain = await client.callTool({
  name: "pot_graph",
  arguments: { eventId: "refactor_auth_module_step3", depth: 20 }
});
// chain.backwardChain — all ancestor steps in chronological order
// chain.forwardChain — steps that follow this one
// chain.chainBroken — true if a gap was detected in the ancestor chain
// chain.brokenAt    — "server_restart" if the server restarted and cleared
//                     the in-memory DAG; otherwise the eventId of the oldest
//                     reachable ancestor before the gap; null if chain intact
// chain.reachableDepth — how many ancestors were recovered before the gap

// Handle a server-restart gap:
if (chain.chainBroken && chain.brokenAt === "server_restart") {
  // Server cleared in-memory state; ancestors before the gap are gone unless
  // Redis was configured (REDIS_URL) — in that case the DAG was rebuilt on
  // restart and chainBroken will be false.
  // Recover by querying the most recent checkpoint or restarting from a known step.
}

Before a long task or every ~100 events — create a checkpoint:

// Compress workflow history before context fills up — by causal range:
const checkpoint = await client.callTool({
  name: "pot_checkpoint",
  arguments: {
    fromEventId: "refactor_auth_module_step1",
    toEventId: "refactor_auth_module_step3"
  }
});
// checkpoint.checkpointId — store this; resume from it after compression
// checkpoint.rollup — depth-adaptive compressed history (10–200 tokens/event)
// checkpoint.chainIntact: true — causal chain verified unbroken
// checkpoint.nextCheckpointHint: 87 — suggested events before next checkpoint

// Or compress by time window with a token budget:
const checkpoint = await client.callTool({
  name: "pot_checkpoint",
  arguments: {
    startTime: Date.now() - 3_600_000,  // last 1 hour
    maxTokens: 1500
  }
});

// After context compression, restore from checkpoint instead of re-querying all events:
const history = await client.callTool({
  name: "pot_query",
  arguments: { eventId: checkpoint.checkpointId }
});
// Full causal context restored in a single call

Outcome: Zero duplicate work. Full workflow timeline recoverable even after complete context resets.

2. MEV Bot — Transaction Ordering Proof

Problem: You got front-run. You can't prove it — mempool timestamps are per-node, unsigned, non-authoritative.

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.

const pot = await client.callTool({
  name: "pot_generate",
  arguments: { txHash: pendingTxHash, chainId: 8453, poolAddress: "0x..." }
});
// pot.potHash — your evidence, timestamped by NIST+Google+Cloudflare

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.

3. DEX Protocol — Sandwich Deterrence

Solution: Integrate TTTHookSimple (Uniswap V4 hook, Base Sepolia: 0x8C633b05b833a476925F7d9818da6E215760F2c7). Honest builders get turbo mode. Tampered sequences get full mode (penalty delay). Economics, not governance.

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.

4. Hedge Fund / Prop Desk — MiFIR Art.22c Compliance

Problem: MiFIR Article 22c / RTS 25 requires microsecond-precision UTC-synchronized timestamps. Hardware PTP appliances cost $50K–$500K.

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.

const audit = await client.callTool({
  name: "pot_generate",
  arguments: { txHash: tradeHash, chainId: 8453 }
});
// audit.timestamp: high-resolution timestamp
// audit.uncertainty: ± bound (RTS 25 uncertainty field)
// audit.confidence: fraction of sources that agreed

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.

Outcome: Structurally compatible audit trail. IETF specification: draft-helmprotocol-tttps-00.

5. Multi-Agent Coordination — Causal Order Proof

Problem: When multiple AI agents interact in a pipeline, the causal order matters for debugging and audit. Agent logs are unverifiable.

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.

How It Differs — A Different Job, Not "Better"

The cost difference is structural, not incidental.

Letta 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.

Scope: agents stamp the steps worth checkpointing — not every token, not every query. Volume tracks decisions, not total chat traffic.

If 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.

Pricing

Subscribe:

Dev $29/mo · Pro $99/mo · Team $299/mo — to subscribe, email peter@kenosian.com.

Enterprise & Platform License: peter@kenosian.com

Contact: peter@kenosian.com

Quota mechanics — stdio vs HTTP:

• HTTP mode (Glama / Smithery container, PORT set): the per-IP free tier limit (100 calls/day) is enforced locally in the server process.
• 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.

Requirements

• Node.js >= 18
• Network access for time synthesis (HTTPS to time.nist.gov, time.google.com, time.cloudflare.com)

Time source tiers (automatic fallback):

The server falls through to stratum 16 automatically; no manual configuration needed. The stratum field in every pot_generate response indicates which tier was used.

Redis persistence (optional):

Redis 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.

Production Tips

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.

# Kubernetes / Docker: add to your startup script
curl -s http://your-server/pot/health > /dev/null

Learn More

• OpenTTT SDK — The underlying SDK
• IETF Draft: draft-helmprotocol-tttps-00 — TTTPS Protocol Specification
• Helm Protocol — GitHub

License

BSL-1.1 — free for non-commercial use.

Commercial use (production bots, hedge funds, prop desks) requires a license.

Change Date: 2029-05-28 → Apache 2.0