Default root:
~/.ctx/
search/
lexical/
semantic/
usage.sqlite
config.toml
logs/CTX_DATA_ROOT or --data-root can point ctx somewhere else. The configured
root is used directly.
Self-contained Core
Provider transcript files and databases are read-only acquisition inputs. After a successful refresh, the committed Core generation is the authority for normalized history. It stores complete product-visible records, stable identities, content-policy state, repository bindings, citations, and the full meaningful text used for lexical search.
Search, show, locate, MCP, semantic indexing, and Local Pro read Core rather than reopening provider records. A temporary input failure preserves the last good Core data and is reported as refresh health; an incomplete refresh candidate is never published.
Core and derived products
The data root keeps Core alongside independent derived products:
search/lexical/contains immutable Tantivy Core generations. Each accepted event's complete normalized record is stored and its full meaningful text is indexed.search/semantic/contains optional generation-bound flat-F32 vectors, hashes, offsets, and policy metadata. It contains no plaintext transcript chunks, bodies, or previews.
Local Pro consumes bounded Core snapshots and deltas pinned to a committed generation. It stores derived graph facts and stable Core citations, not complete Core bodies.
Semantic and Pro bind exact Core-generation receipts and may trail Core independently. They rebuild from Core without requiring the original provider files.
Core/Tantivy is the sole public local architecture for normalized lexical
records and history queries. Typed provider-aware search, show, and locate
provide direct lookup. There is no ctx sql, MCP SQL tool, ctx-owned relational
history database, or replacement generic query engine.
Fresh v0.26 epoch
Version 0.26 does not adopt the pre-v0.26 history database. Before the first self-contained Core generation is verified and atomically active, setup, refresh, import, search, show, locate, MCP, and daemon maintenance do not open, query, repair, migrate, or use an old Store database family as fallback. After verified activation, ctx deletes that exact old Store database family.
There is no supported rollback, manual recovery, or v0.25 binary or daemon
path. Recovery fixes forward from currently available provider sources.
Current-format atomic install and publication crash recovery remain supported.
A fresh v0.26 data root does not create work.sqlite.
Other local state
usage.sqlite stores bounded daily local product-usage aggregates. It is
separate from provider history and contains no query, path, prompt, transcript,
session or event ID, or exact timestamp.
Official installer-managed binaries also have an ownership sidecar next to the
binary, such as ~/.local/bin/ctx.install.json. The sidecar is outside the ctx
data root because it describes the installed executable.
Local Pro keeps its encrypted graph and lifecycle state under pro/. Its
credentials and graph key remain in the operating-system credential store. Pro
state is separate from Core and cannot make Core unavailable.
Repository identity and local access
Core automatically certifies zero or more logical repository bindings from structured captured activity. It records a typed abstention when identity is missing, ambiguous, unsafe, or unsupported. Repository-scoped file and version-control observations never grant authority outside their binding.
Logical repository identity is separate from current local access. A moved or deleted worktree can retain its identity while losing an authorized local root. Pro reports repository, local-root, commit, and pull-request coverage separately from projection currentness, entitlement, and supported operations. Empty or abstained coverage is a valid terminal result, not blame readiness.
Network behavior
Discovery and refresh read provider inputs locally. Search, show, locate, and MCP read Core and its local derived products. None of these operations repeats the network activity that originally produced a provider transcript.
Semantic model or runtime acquisition and hosted Pro account actions are explicit, separately controlled network surfaces. Command-metadata privacy controls are covered in the Privacy Policy.