> ## Documentation Index
> Fetch the complete documentation index at: https://docs.timepointai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Clockchain

> Persistent temporal causal graph — PostgreSQL-backed directed graph that grows autonomously.

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

<CardGroup cols={2}>
  <Card title="GitHub" icon="github" href="https://github.com/timepointai/timepoint-clockchain">
    `timepointai/timepoint-clockchain` — Apache-2.0, Python 3.11+, FastAPI
  </Card>

  <Card title="Detailed Docs" icon="book" href="https://github.com/timepointai/timepoint-clockchain">
    Full API reference, graph architecture, and deployment docs
  </Card>
</CardGroup>

## 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:

```bash theme={null}
# 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](https://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](/api-reference/clockchain#graph-traversal) (`X-Service-Key`) and the free `traverse_moments` / `find_path` [MCP tools](/api-reference/mcp#temporal-navigation-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.*