Skip to main content
Contexity is distributed as a Rust workspace and built locally with Cargo. There is no binary download or cloud dependency — everything runs on your machine, and your project context never leaves it.

​
Requirements

Make sure you have the following installed before you build:
Contexity is written in stable Rust. Install or update the toolchain using rustup:
rustup update stable
Any recent stable release works. Nightly is not required.
Contexity reads Git metadata to establish project identity and detect changes. Git must be available on your PATH.
The ./bin/contexity wrapper script and local release smoke tests are written in Bash. Any POSIX-compatible shell environment works.
Node.js 22 is only required if you are running the repository’s release gate through npm. You do not need Node.js for normal development or to use the CLI.

​
Build from Source

Clone the repository, then build the full workspace from the repository root: 
cargo build --workspace
Once the build completes, run the CLI through the provided wrapper script: 
./bin/contexity --help
The wrapper automatically uses target/debug/contexity when that binary is present from a prior cargo build. If the binary is not present — for example, after a clean checkout — the wrapper falls back to cargo run so you are never blocked by a missing build artifact.
Run cargo build --workspace --release to produce an optimized binary at target/release/contexity for everyday use. The wrapper does not automatically prefer the release binary, so you may want to add target/release to your PATH or create a shell alias.

​
State Home

Contexity stores two distinct categories of data, and it is important to understand where each one lives. Project identity is written directly into the project directory: 
<project>/.cxcap/project.identity.json
This file is stable and should be committed to version control. It carries the project’s unique identity across machines and session boundaries. Durable state — run ledgers, memory entries, source captures, and freshness records — is stored in the Contexity state home. Contexity resolves the state home location in this order:
  1. CONTEXITY_HOME environment variable, if set
  2. XDG_STATE_HOME/contexity, if XDG_STATE_HOME is set
  3. ~/.local/state/contexity as the default fallback
To use an isolated state home for a test run or CI job — so it does not touch your real state — export the variable before invoking Contexity: 
export CONTEXITY_HOME="$(mktemp -d)/state"
Each project’s durable state is namespaced inside the state home by project identity, so multiple projects coexist safely in a shared state home without interfering with each other.

​
Upgrading

Before you upgrade to a newer version of Contexity, take the following steps to protect your existing project context. 1. Run the doctor check against every attached project to confirm they are in a healthy state before you change anything: 
contexity --project /path/to/project doctor
Resolve any issues the doctor reports before proceeding. 2. Back up your data. Copy the project’s .cxcap/ directory and the Contexity state home to a safe location: 
cp -r /path/to/project/.cxcap /path/to/project/.cxcap.bak
cp -r ~/.local/state/contexity ~/.local/state/contexity.bak
Adjust the state home path if you have customized CONTEXITY_HOME or XDG_STATE_HOME. 3. Build the new version following the same steps in the Build from Source section above. Contexity tracks schema compatibility through schema_version fields embedded in all persisted records. If a new version introduces a schema migration, the CLI will detect the version mismatch on first use and prompt you before making any changes to stored data.