This repository is the comprehensive documentation source of truth for TraceDB and TraceField.
Start with the Docs Index.
The Fern source scaffold lives in fern/. It is configured for docs and API
reference publication from the TraceDB v1 OpenAPI contract, while SDK and CLI
generation lanes remain staged until Fern organization, package, and output
repository details are confirmed.
The canonical OpenAPI source remains
../tracedb-protocol/docs/api/v1-openapi.json. Do not commit a copied OpenAPI
artifact under fern/openapi/; remote CI should sync it into a temporary Fern
workspace before running Fern validation.
Remote validation entry points:
scripts/check_fern_scaffold.sh --require-fern
scripts/sync_fern_openapi.sh --writecheck_fern_scaffold.sh copies the canonical OpenAPI file into a temporary Fern
workspace and runs fern check only when requested. sync_fern_openapi.sh is
for remote publish/generation jobs that need fern/openapi/v1-openapi.json
materialized in the working tree before invoking Fern.
TraceDB is an AI-native transactional candidate-stream database. One logical record. One commit epoch. Many native views. No external sync drift. Explain every candidate.
TraceField is the memory/runtime research program that informs future runtime directions. It is not the current product and is not an implemented runtime in the core engine repo. Agent Memory Flight Recorder is a concrete local demo wedge built on TraceDB records, query/explain output, and replayable receipts.
| Section | Path | Contents |
|---|---|---|
| Overview | docs/01-overview/ |
Product vision, glossary, getting started, boundaries |
| Core Engine | docs/02-core-engine/ |
Architecture, crate map, algorithms, schematics |
| Storage & Durability | docs/03-storage-and-durability/ |
WAL, manifest, checkpoint, TDE, recovery semantics |
| Query Engine | docs/04-query-engine/ |
Hybrid query fusion, TraceQL, GraphQL, planner, provenance |
| SDKs | docs/05-sdks/ |
Rust, TypeScript, Python, Go SDK documentation |
| Protocol & API | docs/06-protocol-and-api/ |
HTTP /v1, OpenAPI, platform contract, conformance |
| TraceField Research | docs/07-tracefield-research/ |
Memory calculus, runtime theory, agent memory |
| Scientific Foundations | docs/08-scientific-foundations/ |
External research, citations, mathematical foundations |
| RFCs & Design | docs/09-rfcs-and-design/ |
Design proposals, ADRs, process documentation |
| Benchmarks & Performance | docs/10-benchmarks-and-performance/ |
Methodology, suites, evidence chains |
This is a living document. Updates should reference the canonical repos:
tracedb— core enginetracedb-protocol— wire contracttracedb-rust,tracedb-js,tracedb-python,tracedb-go— SDKstracedb-rfcs— design proposalstracedb-benchmarks— performance evidence
Apache-2.0