Introduction

tckg stores what an agent heard, what it believed, and why it changed its mind, with time and causality attached, and gives it back as of a point in time: only what was known then. You use it the way you use Zep or Mem0. One thing is different. Every read takes as_of. Anything learned after that instant is masked out of the answer, and the answer carries a certificate that says how much was masked. Backtests, post-mortems, and “what did we know when we decided” stop being guesswork.

Where to start

Quickstart

Write three blocks, read them as of two different dates, and watch the same data answer differently. Five minutes.

Concepts

The two clocks, spaces and tenants, backfill, the certificate, declared facts and resolve.

Migrate from Supabase

For teams that keep a knowledge graph in their own Postgres tables today. Field mapping, backfill, dual write, cutover.

API Reference

Eight endpoints. Every request and response field, every reason code.

What works today, and what does not yet

These docs describe only what is in the code. Everything that is not yet there is in this table.

	Status
Nine HTTP endpoints: write, read one, read many, search, resolve, why, facts, export, version and check_install	Works. Six smoke suites and the conformance gates run on every commit
Export as a FactBlock bundle: the ledger as files that validate and answer as-of reads without the server	Works
Structured writes (nodes and edges as JSON)	Works
`as_of` masking, `valid_at`, the certificate, backfill declarations	Works
Search: full text plus cosine over a caller-supplied embedding, then causal expansion	Works. The caller embeds. The engine calls no model
Delete	Absent, on purpose. 501 with a reason. Hiding (`invalidate`) is v1.x
API key to tenant	Works. Each key maps to one tenant; the hosted deployment hands out one key per app, so app.factagora.com and factagora.ai never see each other’s rows
Natural-language writes (`messages` plus `observed_at`, the engine extracts the blocks)	Works. Send `messages` to `POST /v1/memories`: statements become `claim`/`prediction` blocks, people and assets become `entity` nodes, and the causal links the speaker argued become edges. Gemini on Vertex AI does the extraction. Live on the hosted deployment since 2026-10-04
Hosted endpoint	Up, for internal preparation: `https://tckg.factagora.com`. One API key per app, handed out by Randy. Treat its data as disposable; it is wiped when the real cutover starts
MCP server	Works. `/mcp` on the same address and key; eight tools mirroring the HTTP operations. See Connect an agent
TypeScript and Python SDKs	Not yet. Plain HTTP, or MCP

Run it locally

You can also run the same API yourself, for example to test against an empty database. You need PostgreSQL 17 or newer and uv.

git clone https://github.com/factagora/tckg && cd tckg
schema/install.sh 5433                       # schema and roles into one empty PostgreSQL
psql -p 5433 -f schema/dev-login-roles.sql   # development logins (password: dev)
cd api && uv run uvicorn tckg_api.app:app --port 8765
curl localhost:8765/v1/version               # {"version":"0.3.1"}

GET /v1/check_install reports the installation item by item. Details are in INSTALL.md at the repository root.

Editing these docs

This site is built from docs/ in factagora/tckg. A push to main deploys; there is no staging. Edit docs/**/*.mdx there and run npx mint broken-links inside docs/ before pushing.

​Where to start