tgms

# TGMS — Agent-Native Bi-Temporal Graph Management System

[![CI](https://github.com/zxf-work/tgms/actions/workflows/ci.yml/badge.svg)](../../actions)
[![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
[![Coverage: temporal/ 97%](https://img.shields.io/badge/coverage_(temporal)-97%25-brightgreen.svg)](#correctness)

**A temporal graph database whose query surface is built for LLM agents —
and whose answers can be audited claim by claim.**

**Project page & blog:** https://zxf-work.github.io/tgms/ · **Paper:** [paper/main.pdf](paper/main.pdf)

LLM agents are unreliable at exactly the things temporal graph analytics
requires: arithmetic, identifiers, and asserting only what the evidence
shows. TGMS's answer is architectural — give the model **no opportunity**
to do any of them:

- a **bi-temporal property graph** (valid time × transaction time) that
  distinguishes *evolution* ("the edge ended") from *correction* ("we were
  wrong"), so agents can answer *"what did we believe on March 1?"* — a
  question latest-state snapshots and the RAG configurations we evaluated
  cannot express. Bi-temporality itself is inherited, not invented here —
  it has a four-decade literature, a place in SQL:2011, and production
  databases built around it. We measure against the clearest of those,
  [XTDB](https://xtdb.com): fed the same operation stream, the two systems
  agree on believed state at 400 of 400 probe points, with TGMS 3.9–4.7×
  faster at correction-heavy ingest on 23–27× less disk
  ([the head-to-head](https://zxf-work.github.io/tgms/blog/the-competitor-agrees.html));
- **15 verified temporal operators** (reachability over time-respecting
  paths, δ-motifs, snapshot diffs, burst detection, interval joins, grouped
  aggregation over edge events, and the belief log itself) — typed,
  deterministic, bounded,
  cost-guarded, exposed as tools (MCP or in-process); identifiers must come
  from a resolver, arithmetic from a `compute` operator;
- a **Planner–Executor–Verifier** loop: the LLM only plans and reports;
  plans are statically validated (including a grounding rule that makes
  fabricated identifiers impossible and output-field contracts that reject
  invented result paths), executed deterministically with content-addressed
  traces, and every claim in the written answer is **machine-checked
  against the trace that produced it** — including truncation taint, so
  "correct arithmetic over incomplete evidence" is caught too;
- a **purpose-built native storage engine** (Rust, PyO3): bi-temporal
  columnar segments, a temporal-CSR traversal index, group commit, and a
  single-writer / many-reader concurrency mode — 24.6 bytes per edge
  version, versus 78.4 on ClickHouse and 549.7 on PostgreSQL for the same
  1M-event log.

## Quickstart

```bash
pip install tgms
tgms demo
```

No GPU, no API key, no dataset download. `tgms demo` builds a small store of
its own in a temp directory and runs the arc every TGMS answer follows: what
the graph currently believes, what it believed *before* a correction landed,
and the trace that backs both claims up. Clean environment to first temporal
result: under 5 minutes.

Once you want your own graph data, the native test suite, the MCP server, or
an agent wired to a real LLM, see [Full setup](#full-setup-from-source)
below — this quickstart is deliberately the smallest possible first step,
not a tour of the operator surface.

Next steps, in the order most people need them:
[bring your own temporal graph data](docs/tutorials/bring-your-own-data.md) ·
[give TGMS to an agent over MCP](docs/tutorials/agent-setup.md) ·
[audit an answer](docs/tutorials/audit-an-answer.md) ·
[what you can rely on across versions](docs/STABILITY.md) ·
[what's coming](docs/PUBLIC_ROADMAP.md)

## Does it work?

Three different questions, three different answers. All three are reported
because the third is the least flattering.

**1. Does the agent layer beat the alternatives?** Dev-split campaign
(CollegeMsg, open-source models served locally on one 24 GB GPU. "Answer
accuracy" is normalized typed-answer accuracy — counts and values scored
strictly, interval answers credited at IoU ≥ 0.5. Full receipts ship with
the paper and the eval records in `benchmarks/results-v1/`):

| pooled answer accuracy, Qwen2.5-14B | TGMS | vector-RAG | static-graph RAG | text-to-Cypher |
|---|---:|---:|---:|---:|
| all task families | **0.41** | 0.09 | 0.05 | 0.18 |
| correction probes ("as of tt…") | **0.67** | 0.00 | 0.00 | 0.00 |

- vs static-graph RAG: **+36 points**, paired-bootstrap 95% CI [0.18, 0.59]
- verifier fault injection: **500/500 injected false claims caught, 0 false
  positives**; on the frozen campaign, **0 of 199 emitted answers** contained
  an unsupported claim with gating (21 of 220 without it) — coverage is
  199/282, so some of that is bought by declining to answer
- accuracy tracks planner capability where baselines stay flat: **13.8% /
  34.0% / 62.8%** at Qwen2.5 7B / 14B / 32B fp16, correction probes
  saturating at 100% at 32B

**2. Is the engine competitive?** Six systems answer one 13-query registry
— TGMS native, TGMS-on-DuckDB, PostgreSQL, ClickHouse, Neo4j, Memgraph —
with **every cell hash-verified before it was timed**:

| query shape | TGMS native | best other |
|---|---:|---:|
| temporal reachability, 200k | **14.7 ms** | 3.9–7.3 s (Memgraph, Neo4j) |
| closed-triangle δ-motif, 200k | **28.7 ms** | 2.1–5.5 s (Memgraph, Neo4j) |
| grouped aggregation, 200k | **14.5 ms** | 32.6 ms (ClickHouse) |
| entity history by identity, 200k | **0.1 ms** | 0.3 ms (PostgreSQL) |
| whole-window bucketed count, 10M | 84.7 ms | **37.9 ms** (ClickHouse) |

The last row is the one we cannot close: ClickHouse keeps a factor of 2.2
on whole-window aggregation at both 1M and 10M, and it is a constant of the
shape rather than something that grows with scale. Three rounds of
profiling took that gap from 12× to 2.2× and each round found our own
implementation rather than the workload. Single latency cells reproduce to
about ±20% between days, which is stated everywhere they are quoted.

At 10M events the full query suite runs inside **1.76 GB** of peak RSS,
16 concurrent readers get **10.2×** the throughput of one, and a live
writer costs those readers **0–3%** of per-query latency.

**3. Can it answer the questions people actually ask?** This is the honest
one. 110 questions were written by people who saw a plain-language
description of two public datasets and **never saw the operator list**. Of
those, **94 are expressible today** — 10 were expressible when the study was
pre-registered. Of LDBC SNB's 41 read templates, **3**, and that number has
not moved in eight sessions because 35 of the 38 misses need labelled
multi-way pattern matching, which is a deliberately deferred design
decision rather than a missing operator.

The store is good and the surface is narrow. Both instruments live in the
repo (`scripts/independent_questions.py`, `scripts/ldbc_fit.py`), they
re-run in seconds, and each capability shipped since has been scored
against a forecast made *before* it was built — delivered/predicted has run
14/30, 4/7, 10/13, 14/16, 15/15, 4/8, 5/5 and 4/5. The last two were the
first forecasts made per question rather than in aggregate, and they were
right in every cell.

## What the operators can express

Fifteen operators — fourteen of them unchanged since D-044, because the
interesting growth since v0.4.0 happened *inside* them, driven question by question by the study above:

| capability | where it lives | what it answers |
|---|---|---|
| grouped aggregation | `aggregate_events` | counts and distinct counts by time bucket, rel_type, endpoint or endpoint label |
| arithmetic | `compute` | mean/median over rows; ratio/diff/percent over two scalars — never in the LLM |
| typed properties | `aggregate_events` | predicates and min/max/mean over an edge property, where a value participates only if its JSON type fits |
| set operations | `compute`, `aggregate_events` | intersect/difference/union over uid lists, a cohort pre-filter, undirected and reciprocal pair modes |
| row arithmetic and joins | `compute` | `derive` adds one computed column; `join` aligns two grouped results on a key unique on both sides |
| ordered sequences | `aggregate_events` | longest gap between consecutive events, busiest sliding window of a given span, longest run with no gap over a threshold |
| calendar units | `aggregate_events` | grouping by hour of day, day of week or month of year, at a fixed offset from UTC that is an argument rather than a default |
| the belief log | `version_history` | which beliefs were revised and when — the only operator that reads the correction record rather than a state derived from it |

Every one of these is verified against the same brute-force oracle as the
operators themselves, and every one is measured in the session that shipped
it. What is *not* there is written down too, question by question, in the
re-audit tables of `scripts/independent_questions.py` and
`scripts/ldbc_fit.py` — both of which print the current blocked-capability
board on `report`.

## Full setup (from source)

Everything below builds TGMS from a checkout instead of the PyPI wheel:
real dataset loaders, the native-engine test suite, the MCP server, and an
agent loop wired to an actual LLM.

```bash
# macOS note: if this repo sits in an iCloud-synced folder, keep the venv
# outside it (iCloud sets the hidden flag on .pth files and Python 3.12+
# silently skips them):  export UV_PROJECT_ENVIRONMENT=$HOME/.venvs/tgms
uv sync --extra agent
make test                     # 271 tests: property, oracle, metamorphic, e2e
```

```bash
# build a real store + task suite (downloads CollegeMsg from SNAP)
make data-collegemsg suite-collegemsg
```

```bash
# call one verified operator — no LLM needed
uv run tgms call temporal_reachability \
  '{"src": "n9", "window": {"t_a": 1082040961000000, "t_b": 108800