Clockchain

Temporal causal graph for AI agents. PostgreSQL-backed directed graph of historical moments — canonical spatiotemporal URLs, typed causal edges, autonomous expansion, and browse/search/discovery APIs. Holds tens of thousands of moments connected by hundreds of thousands of typed causal edges, spanning 700 BCE to 2026 and growing autonomously 24/7. For current totals (nodes, edges, image coverage), query the live GET /api/v1/stats endpoint.

GitHub

timepointai/timepoint-clockchain — Apache-2.0, Python 3.11+, FastAPI

Detailed Docs

Full API reference, graph architecture, and deployment docs

MCP Endpoint

The Clockchain exposes a Model Context Protocol (MCP) interface for AI agents and tools:

Property	Value
URL	`https://clockchain.timepointai.com/mcp/`
Version	v1.26.0
Transport	Streamable HTTP
Auth	Public reads (no auth required)

Any MCP-compatible client (Claude Desktop, Cursor, etc.) can connect directly to browse and search the temporal graph.

Why This Exists

AI agents that reason about causality across time currently rely on web search (noisy, unstructured), knowledge graphs (no temporal dimension), or hallucination. The Clockchain is a structured alternative: every node carries dialog, entity states, provenance, and confidence, addressed by a canonical spatiotemporal URL, in a format (TDF) designed for machine consumption.

Graph Architecture

Two PostgreSQL tables: nodes (canonical spatiotemporal URLs as PKs) and edges (source, target, type, weight).

Canonical URL Format

/-44/march/15/1030/italy/lazio/rome/assassination-of-julius-caesar

8 segments: year (negative = BCE), month, day, time (24hr), country, region, city, slug.

Content Layers

Layer	Content	Source
0	URL path + event name	Auto-generated
1	Metadata: figures, tags, description	Expander (LLM)
2	Full Flash scene with dialog, characters, image, CDN-hosted image_url	Flash renderer

Edge Types

Type	Meaning	Auto-linked?
`causes`	Direct causal relationship	No — expander or manual
`contemporaneous`	Same year (+/- 1)	Yes, weight 0.5
`same_location`	Matching geography	Yes, weight 0.5
`thematic`	Overlapping tags	Yes, weight 0.3

Background Workers

Worker	Role
Renderer	Calls Flash to upgrade layer-1 nodes to layer-2 (full scenes)
Expander	LLM-driven graph growth — discovers related moments, renders each through Flash
Judge	Content moderation
Daily	”Today in History” cron — adds new nodes for the current date

Public API

No authentication required for read access:

# Graph statistics
GET /api/v1/stats

# List moments (paginated, filterable)
GET /api/v1/moments?limit=10&offset=0&q=rome&year_from=-500&year_to=500

# Get a specific moment
GET /api/v1/moments/{canonical-path}

Rate Limits

Tier	Limit
Public (unauthenticated)	60/min
Authenticated reads	300/min
Authenticated writes	30/min

Temporal Navigator

The Temporal Navigator at app.timepointai.com/navigator is an interactive explorer for the causal graph. Pick an anchor moment and walk its causes and consequences on a WebGL canvas — direction toggle (Past | Both | Future), depth slider (1–4 hops), and edge-type filters — or select any two moments and render the shortest chain of historical connections between them. The same traversal is available programmatically via the graph traversal endpoints (X-Service-Key) and the free traverse_moments / find_path MCP tools.

The Bayesian Flywheel

Each new event with causal edges tightens the Bayesian prior — fewer plausible things could have happened in the gaps — approaching asymptotic coverage of any historical period. Flash scenes feed into the Clockchain graph, which builds a stronger Bayesian prior. That prior drives the Expander (LLM) to discover gaps, which feeds back into more Flash renders.

Flash scenes ──► Clockchain Graph ──► Stronger Prior
                          │               │
                          ▼               │
                    Expander (LLM) ◄──────┘
                    discovers gaps

The name is conceptual. This is PostgreSQL, not a blockchain.

Getting Started

Products

API Reference

Clockchain

Clockchain

GitHub

Detailed Docs

MCP Endpoint

Why This Exists

Graph Architecture

Canonical URL Format

Content Layers

Edge Types

Background Workers

Public API

Rate Limits

Temporal Navigator

The Bayesian Flywheel

​Clockchain

GitHub

Detailed Docs

​MCP Endpoint

​Why This Exists

​Graph Architecture

​Canonical URL Format

​Content Layers

​Edge Types

​Background Workers

​Public API

​Rate Limits

​Temporal Navigator

​The Bayesian Flywheel

Clockchain

MCP Endpoint

Why This Exists

Graph Architecture

Canonical URL Format

Content Layers

Edge Types

Background Workers

Public API

Rate Limits

Temporal Navigator

The Bayesian Flywheel