@helm-protocol/ttt-mcp 0.2.2 → 0.3.1

package/README.md

@@ -1,305 +1,461 @@
 # @helm-protocol/ttt-mcp
 
-> Reference implementation of [draft-helmprotocol-tttps-00](https://datatracker.ietf.org/doc/draft-helmprotocol-tttps/) (IETF Experimental)
+> Reference implementation of [draft-helmprotocol-tttps](https://datatracker.ietf.org/doc/draft-helmprotocol-tttps/) (IETF Experimental)
 
 **MCP Server for OpenTTT — Proof of Time tools for AI agents**
 
-> AI Agent A and Agent B both trigger a payment at the same time.
-> Who was first?
->
-> OpenTTT answers this with cryptographic Proof of Time — synthesized from
-> multiple independent time sources, verified through GRG integrity shards,
-> and signed with Ed25519 for non-repudiation.
+---
+
+## 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
+
+| Layer | Mechanism | Guarantee |
+|-------|-----------|-----------|
+| **Identity** | SHA-3 eventId (256-bit) | Collision probability 2⁻²⁵⁶ — practically zero |
+| **Lookup** | O(1) exact retrieval | No context consumed by history reconstruction |
+| **Ordering** | TTTPS causal timestamps | Total order on events — tamper-proof sequence proof |
+| **Causal chain** | prevEventId DAG | O(depth) traversal — depth ~100 for 1B-token workflows |
+| **Non-repudiation** | Ed25519 signature | Cryptographic proof of who acted when |
+| **Resilience** | Erasure-coded cryptographic shards | ≥97% recovery at BER=0.05, 99.88% at BER=0.02 (theoretical) |
+| **Persistence** | Redis AOF + 90-day TTL | Server survives context compression and restarts |
+
+---
 
 ## Quick Start
 
+### Claude Code
+
 ```bash
-npm install @helm-protocol/ttt-mcp
+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):
+```bash
+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`:
+
 ```json
-// claude_desktop_config.json
 {
   "mcpServers": {
     "ttt": {
       "command": "npx",
-      "args": ["@helm-protocol/ttt-mcp"]
+      "args": ["-y", "@helm-protocol/ttt-mcp@0.3.0"],
+      "env": { "TTT_API_KEY": "your-key" }
     }
   }
 }
 ```
 
-That's it. Your AI agent now has access to 5 Proof of Time tools.
+### Cursor
 
-## Tools
+[![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=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBoZWxtLXByb3RvY29sL3R0dC1tY3BAMC4zLjAiXX0=)
 
-| Tool | Description |
-|------|-------------|
-| `pot_generate` | Generate a Proof of Time for a transaction |
-| `pot_verify` | Verify a Proof of Time using its hash and GRG shards |
-| `pot_query` | Query PoT history from local log and on-chain subgraph |
-| `pot_stats` | Get turbo/full mode statistics for a time period |
-| `pot_health` | Check system health: time sources, subgraph sync, uptime |
+One-click install, or add the same `mcpServers` block above to `.cursor/mcp.json`.
 
-## Tool Parameters
+Free tier: 100 calls/day per IP — no signup needed.
 
-### pot_generate
+---
 
-Generate a Proof of Time for a transaction. Returns potHash, timestamp, stratum, and GRG integrity shards.
+## 5-Minute Test
 
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| txHash | string | Yes | Transaction hash (hex with 0x prefix) |
-| chainId | number | Yes | Chain ID (e.g. 8453 for Base, 84532 for Base Sepolia) |
-| poolAddress | string | Yes | DEX pool contract address |
+Once connected, run this sequence in Claude:
 
-### pot_verify
+**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 | Purpose |
+|------|---------|
+| `pot_generate` | Stamp a workflow step with a cryptographic timestamp |
+| `pot_verify` | Verify a PoT signature |
+| `pot_query` | O(1) exact lookup by eventId — core amnesia recovery |
+| `pot_graph` | Traverse causal DAG (backward + forward chain) |
+| `pot_checkpoint` | Roll up events into a compressed summary — use every ~100 events or before long tasks |
+| `pot_stats` | Server statistics and mode status |
+| `pot_health` | Health check |
 
-Verify a Proof of Time using its hash and GRG shards. Returns validity, mode (turbo/full), and timestamp.
+---
+
+## 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.
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
-| potHash | string | Yes | PoT hash to verify (hex with 0x prefix) |
-| grgShards | string[] | Yes | Array of hex-encoded GRG integrity shards |
-| chainId | number | Yes | EVM chain ID (e.g. 84532 for Base Sepolia) |
-| poolAddress | string | Yes | Uniswap V4 pool address (0x-prefixed) |
+| eventId | string | Either/or | Workflow step identifier. E.g. `"refactor_auth_step1"` |
+| prevEventId | string | No | Previous step's eventId — links steps into a causal chain |
+| txHash | string | Either/or | Transaction hash (DeFi, hex with 0x prefix) |
+| chainId | number | No | EVM chain ID (DeFi) |
+| poolAddress | string | No | DEX pool contract address (DeFi) |
 
 ### pot_query
 
-Query Proof of Time history from local log and on-chain subgraph.
+Query Proof of Time records. Use `eventId` for O(1) exact lookup after context compression.
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
+| eventId | string | No | Exact step lookup — collision probability 2⁻²⁵⁶ |
 | startTime | number | No | Start time (unix ms). Default: 24h ago |
 | endTime | number | No | End time (unix ms). Default: now |
 | limit | number | No | Max entries to return. Default: 100, max: 1000 |
 
-### pot_stats
+### pot_graph
 
-Get PoT statistics: total swaps, turbo/full counts, and turbo ratio for a given period.
+Traverse the causal chain from any step. Returns backward chain (ancestors) and forward chain (descendants).
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
-| period | `"day"` \| `"week"` \| `"month"` | Yes | Time period for statistics |
+| eventId | string | Yes | Step to traverse from |
+| depth | number | No | Max backward depth. Default: 10, max: 100 |
 
-### pot_health
+**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.
 
-Check PoT system health: time source status, subgraph sync, server uptime, and current mode.
+**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
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
-| *(none)* | — | — | This tool takes no parameters |
+| potHash | string | Yes | PoT hash to verify (hex with 0x prefix) |
+| grgShards | string[] | Yes | Array of hex-encoded cryptographic integrity shards |
+| chainId | number | Yes | EVM chain ID |
+| poolAddress | string | Yes | Uniswap V4 pool address |
 
-## Example: Generate and Verify a PoT
+### pot_stats
 
-```typescript
-// In your AI agent's tool call:
-const pot = await pot_generate({
-  txHash: "0xabc123...",
-  chainId: 84532,
-  poolAddress: "0xdef456..."
-});
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| period | `"day"` \| `"week"` \| `"month"` | Yes | Time period for statistics |
 
-// pot.potHash — unique Proof of Time hash
-// pot.grgShards — GRG integrity shards for verification
-// pot.timestamp — synthesized nanosecond timestamp
-// pot.mode — "turbo" (honest) or "full" (requires full verification)
+### pot_health
 
-const verification = await pot_verify({
-  potHash: pot.potHash,
-  grgShards: pot.grgShards
-});
-// verification.valid — true if integrity shards reconstruct correctly
-```
+No parameters.
 
-## How It Works
+### pot_checkpoint
 
-1. **Time Synthesis** — Queries multiple independent time sources (NIST, Google, Cloudflare) via HTTPS/NTP and synthesizes a median timestamp with uncertainty bounds
-2. **GRG Pipeline** — Encodes transaction data through a multi-layer integrity pipeline, producing verifiable shards
-3. **Ed25519 Signing** — Signs the PoT hash for non-repudiation
-4. **Adaptive Mode** — Honest builders get `turbo` mode (fast, profitable); tampered sequences get `full` mode (slow, costly) — natural economic selection
+Creates a compressed rollup checkpoint of workflow history.
 
-## Claude Desktop Configuration
+**Use when:** Approaching context limit, before long tasks, or every ~100 events.
 
-Add to your `claude_desktop_config.json`:
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| fromEventId | string | No | Start of range — first eventId in the causal chain to include |
+| toEventId | string | No | End of range — last eventId in the causal chain to include |
+| startTime | number | No | Unix ms. Default: 1 hour ago |
+| endTime | number | No | Unix ms. Default: now |
+| maxTokens | number | No | Approximate max tokens for rollup output. Default: 2000 |
+
+**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:**
+
+| Depth | Format | ~Tokens |
+|-------|--------|---------|
+| 1–5 | Full entry | ~200/event |
+| 6–20 | Compact (id+hash+ts) | ~80/event |
+| 21–50 | Minimal (id+ts) | ~30/event |
+| 51+ | Rollup string | ~10/event |
 
-```json
-{
-  "mcpServers": {
-    "ttt": {
-      "command": "npx",
-      "args": ["@helm-protocol/ttt-mcp"]
-    }
-  }
-}
-```
+---
 
-Config file locations:
-- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
-- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
-- **Linux**: `~/.config/Claude/claude_desktop_config.json`
+## Use Cases
 
-## Requirements
+### 1. Claude Code Workflow — Amnesia Prevention
 
-- Node.js >= 18
-- Network access for time synthesis (HTTPS to time.nist.gov, time.google.com, time.cloudflare.com)
+**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.
 
-## Use Cases
+```typescript
+// 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
 
-### 1. MEV Bot — Transaction Ordering Proof
+// 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⁻²⁵⁶
 
-**Problem**: You got front-run. You know it happened. You can't prove it — mempool timestamps are per-node, unsigned, and non-authoritative. No evidence, no recourse.
+// 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.
+}
+```
 
-**Solution**: Call `pot_generate` before submitting every transaction. The PoT receipt is cryptographically signed by three independent time sources (NIST, Google, Cloudflare), hashed on-chain to Base Sepolia TTT ERC-1155. If front-running occurs, you have a timestamped, on-chain-anchored record of your original submission that predates the attacker's block inclusion.
+**Before a long task or every ~100 events — create a checkpoint:**
 
 ```typescript
-// Before tx submission
-const pot = await client.callTool({ name: "pot_generate", arguments: { txHash: pendingTxHash, chainId: 8453 } });
-// Store pot.potHash alongside your trade log
-// If front-run: pot.potHash is your evidence, timestamped by NIST+Google+Cloudflare
+// 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
 ```
 
-**V2 path**: When builder staking goes live, `S(V) ≥ V − c₀` makes reordering economically irrational for any V. Not just evidence — prevention.
+**Outcome**: Zero duplicate work. Full workflow timeline recoverable even after complete context resets.
 
 ---
 
-### 2. DEX Protocol — AdaptiveSwitch Sandwich Deterrence
+### 2. MEV Bot — Transaction Ordering Proof
 
-**Problem**: Small-to-mid value sandwich attacks (V < ~$87) are constant background noise on any AMM. Each one is individually too small to litigate, collectively significant. No governance mechanism moves fast enough to respond.
+**Problem**: You got front-run. You can't prove it — mempool timestamps are per-node, unsigned, non-authoritative.
 
-**Solution**: Integrate `TTTHookSimple` (Uniswap V4 hook, Base Sepolia: `0x8C633b05b833a476925F7d9818da6E215760F2c7`). Honest builders who preserve PoT-verified ordering get `turbo` mode (~50ms path). Builders who tamper are flagged to `full` mode (~127ms + exponential backoff up to 320 blocks). The 77ms throughput differential makes reordering cost exceed opportunity value for the V* range. No vote. No committee. Economics.
+**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.
 
 ```typescript
-// Query current switch state for a pool
-const status = await client.callTool({ name: "pot_stats", arguments: { poolAddress: "0x..." } });
-// status.adaptiveMode: "turbo" | "full"
-// status.currentV_star: estimated MEV threshold being deterred
+const pot = await client.callTool({
+  name: "pot_generate",
+  arguments: { txHash: pendingTxHash, chainId: 8453, poolAddress: "0x..." }
+});
+// pot.potHash — your evidence, timestamped by NIST+Google+Cloudflare
 ```
 
-**Outcome**: ~80% reduction in sub-threshold sandwich attacks. Provable per-block audit trail.
+> **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.
 
 ---
 
-### 3. Hedge Fund / Prop Desk — MiFIR Art.22c Compliance
+### 4. Hedge Fund / Prop Desk — MiFIR Art.22c Compliance
 
-**Problem**: MiFIR Article 22c / RTS 25 requires microsecond-precision UTC-synchronized timestamps for every trade on regulated venues. The standard hardware solution (PTP/IEEE 1588 appliances) costs $50K–$500K and requires dedicated ops. Most DeFi-adjacent funds run manual reconciliation between two separate timestamp systems.
+**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 uncertainty bound, confidence score, and multi-source attestation. The output is structurally compatible with RTS 25 audit record requirements. No hardware appliance. No dedicated ops. One API call per trade.
+**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.
 
 ```typescript
 const audit = await client.callTool({
   name: "pot_generate",
-  arguments: { txHash: tradeHash, chainId: 8453, metadata: { desk: "MACRO-1", trader: "algo-07" } }
+  arguments: { txHash: tradeHash, chainId: 8453 }
 });
-// audit.timestamp: nanosecond precision
-// audit.uncertainty: +/- ms bound (required field in RTS 25 record)
+// audit.timestamp: high-resolution timestamp
+// audit.uncertainty: ± bound (RTS 25 uncertainty field)
 // audit.confidence: fraction of sources that agreed
-// audit.ed25519_sig: non-repudiation signature
-// Export to your compliance system — same format, every trade
 ```
 
-**Outcome**: MiFIR-grade audit trail at ~$0.04/1K calls (DEX tier). Replaces $50K+ hardware setup. IETF standardized via `draft-helmprotocol-tttps-00`.
+> **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`.
 
 ---
 
-### 4. Liquidity Provider — Position Timeline for Dispute Resolution
+### 5. Multi-Agent Coordination — Causal Order Proof
 
-**Problem**: LP enters and exits positions based on market conditions. When impermanent loss occurs due to a suspected protocol exploit or ordering manipulation, proving the sequence of events (position entry → exploit event → position exit) requires timestamped evidence that the current stack doesn't provide.
+**Problem**: When multiple AI agents interact in a pipeline, the causal order matters for debugging and audit. Agent logs are unverifiable.
 
-**Solution**: Stamp every LP action (add liquidity, remove liquidity, fee harvest) with a PoT receipt. The receipt chain creates an unforgeable causal timeline: each action's potHash references the previous, anchored on Base Sepolia. Legally defensible for tax documentation, insurance claims, and protocol dispute resolution.
+**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.
 
-```typescript
-// On liquidity add
-const entryPot = await client.callTool({ name: "pot_generate", arguments: { txHash: addLiqTx, chainId: 8453 } });
+---
 
-// On liquidity remove
-const exitPot = await client.callTool({ name: "pot_generate", arguments: { txHash: removeLiqTx, chainId: 8453 } });
+## How It Differs — A Different Job, Not "Better"
 
-// Verify the causal chain
-const chain = await client.callTool({ name: "pot_verify", arguments: { potHash: exitPot.potHash, precedingHash: entryPot.potHash } });
-// chain.valid: true means exit cryptographically followed entry
-```
+| Tool | Integration | What it recalls | Integrity | Hot-path cost |
+|------|-------------|-----------------|-----------|---------------|
+| Letta (MemGPT) | owns the agent loop | self-editing semantic memory | none | embedding + vector search per memory op |
+| LangGraph / LangMem | LangGraph only | graph state / semantic | none | checkpoint I/O (+ embeddings) |
+| RAG / vector DB | bolt-on | fuzzy similarity | none | embed + vector search per item |
+| **ttt-mcp** | **2-min MCP retrofit** | **exact causal step (by eventId)** | **Ed25519 + TTTPS timestamp** | **sign + hash + write — 0 embedding calls** |
+
+**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.
 
 ---
 
-### 5. AI Agent Coordination — Multi-Agent Causal Ordering
+## Pricing
 
-**Problem**: When multiple AI agents interact in a pipeline (Agent A signals → Agent B acts → Agent C settles), the causal order matters for debugging, auditing, and liability. Agent logs are unverifiable—any agent can claim any timestamp.
+| Tier | Price | Calls/month |
+|------|-------|-------------|
+| Free | $0 | 100/day per IP — no signup |
+| Dev | $29/mo | 100K |
+| Pro | $99/mo | 1M |
+| Team | $299/mo | 10M + $0.01/1K overage |
+| Enterprise | $999+/mo | 100M calls/mo · $0.001/1K overage · SLA 99.9% |
+| Platform License | Negotiated ($2M+/yr) | Volume cap negotiated · native integration |
 
-**Solution**: Each agent calls `pot_generate` before acting. The resulting potHash chain is independently verifiable: "Agent A's signal at T₁ preceded Agent B's action at T₂" can be proven without trusting either agent's self-reported logs. The on-chain anchor makes the ordering dispute-proof.
+**Subscribe:**
 
-```typescript
-// Agent A (signal generator)
-const signalPot = await client.callTool({ name: "pot_generate", arguments: { txHash: signalId } });
+Dev **$29/mo** · Pro **$99/mo** · Team **$299/mo** — to subscribe, email [peter@kenosian.com](mailto:peter@kenosian.com).
 
-// Agent B (executor) — references Agent A's pot
-const execPot = await client.callTool({
-  name: "pot_generate",
-  arguments: { txHash: execId, precedingPotHash: signalPot.potHash }
-});
+Enterprise & Platform License: [peter@kenosian.com](mailto:peter@kenosian.com)
 
-// Any third party can verify the causal chain
-const verified = await client.callTool({ name: "pot_verify", arguments: { potHash: execPot.potHash, precedingHash: signalPot.potHash } });
-```
+Contact: peter@kenosian.com
 
-**Outcome**: Unforgeable causal chain across autonomous agents. Useful for multi-agent DeFi strategies, audit compliance, and cross-agent dispute resolution.
+**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.
 
 ---
 
-## TypeScript: MEV Bot Integration
+## Requirements
 
-```typescript
-import { McpClient } from "@modelcontextprotocol/sdk/client/mcp.js";
+- Node.js >= 18
+- Network access for time synthesis (HTTPS to time.nist.gov, time.google.com, time.cloudflare.com)
 
-// Generate a Proof of Time for a transaction
-const result = await client.callTool({
-  name: "pot_generate",
-  arguments: {
-    txHash: "0xabc123...",
-    chainId: 8453,
-    poolAddress: "0xdef456..."
-  }
-});
-// Returns: { potHash, timestamp, stratum, grg_shards }
-```
+**Time source tiers (automatic fallback):**
 
-## Python: Hedge Fund Audit
+| Tier | Source | Stratum | Notes |
+|------|--------|---------|-------|
+| 1 (preferred) | PTP / hardware clock | 0–1 | Requires local PTP daemon |
+| 2 | Roughtime / NTP (NIST, Google, Cloudflare) | 2–4 | Default for most deployments |
+| 3 (offline fallback) | Local system clock | 16 | RFC 5905 unsynchronized stratum — used when all network sources are unreachable |
 
-```python
-import subprocess, json
+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.
 
-result = subprocess.run(
-    ["npx", "-y", "@helm-protocol/ttt-mcp"],
-    input=json.dumps({
-        "tool": "pot_verify",
-        "potHash": "0x...",
-        "expectedChainId": 8453
-    }),
-    capture_output=True, text=True
-)
-```
+**Redis persistence (optional):**
 
-## Rate Limits & Pricing
+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.
+
+```bash
+# Kubernetes / Docker: add to your startup script
+curl -s http://your-server/pot/health > /dev/null
 ```
-Free Tier:   100 calls/day per IP — no API key needed
-Paid Tier:   Set TTT_API_KEY env var — unlimited
-Commercial:  peter@kenosian.com (hedge funds, DEX protocols, OTC desks)
-```
+
+---
 
 ## Learn More
 
 - [OpenTTT SDK](https://www.npmjs.com/package/openttt) — The underlying SDK
-- [IETF Draft: draft-helmprotocol-tttps-00](https://datatracker.ietf.org/doc/draft-helmprotocol-tttps/) — TTTPS Protocol Specification
+- [IETF Draft: draft-helmprotocol-tttps](https://datatracker.ietf.org/doc/draft-helmprotocol-tttps/) — TTTPS Protocol Specification
 - [Helm Protocol](https://github.com/Helm-Protocol) — GitHub
 
 ## License
 
 BSL-1.1 — free for non-commercial use.
 
-**Commercial use** (production bots, hedge funds, prop desks) requires a license.  
-→ [kenosian.com/pricing](https://kenosian.com/pricing)
+**Commercial use** (production bots, hedge funds, prop desks) requires a license.
 
 Change Date: 2029-05-28 → Apache 2.0

package/dist/auth.js

@@ -66,7 +66,7 @@ function writeUsageFile(entry) {
 }
 function checkRateLimit(apiKey, clientIp) {
   if (apiKey && apiKey.trim().length > 0) {
-    return { allowed: true, remaining: -1, tier: "paid" };
+    return { allowed: true, remaining: -1, tier: "paid", serverDelegated: true };
   }
   const now = Date.now();
   if (clientIp === "stdio") {