> ## Documentation Index
> Fetch the complete documentation index at: https://cxity.kairaxis.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Install Contexity: Build from Source and Configure State

> Build Contexity from source with Cargo, configure the local state home, and learn how to upgrade safely while preserving project context.

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:

<AccordionGroup>
  <Accordion title="Rust stable toolchain with Cargo">
    Contexity is written in stable Rust. Install or update the toolchain using [rustup](https://rustup.rs):

    ```bash theme={null}
    rustup update stable
    ```

    Any recent stable release works. Nightly is not required.
  </Accordion>

  <Accordion title="Git">
    Contexity reads Git metadata to establish project identity and detect changes. Git must be available on your `PATH`.
  </Accordion>

  <Accordion title="Bash">
    The `./bin/contexity` wrapper script and local release smoke tests are written in Bash. Any POSIX-compatible shell environment works.
  </Accordion>

  <Accordion title="Node.js 22 (release gate only)">
    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.
  </Accordion>
</AccordionGroup>

## Build from Source

Clone the repository, then build the full workspace from the repository root:

```bash theme={null}
cargo build --workspace
```

Once the build completes, run the CLI through the provided wrapper script:

```bash theme={null}
./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.

<Tip>
  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.
</Tip>

## 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:

```text theme={null}
<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:

```bash theme={null}
export CONTEXITY_HOME="$(mktemp -d)/state"
```

<Note>
  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.
</Note>

## 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:

```bash theme={null}
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:

```bash theme={null}
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](#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.