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

# State and Files: Where Contexity Stores Data

> Contexity separates project identity in .cxcap/ from the local state home. Learn what to commit, what to back up, and how state home resolution works.

Contexity separates project identity (per-checkout) from durable local state (machine-wide). Understanding this split helps you know what to commit, what to back up, and how to share project context across machines.

## Project Identity

Each attached project has a small identity file inside its own directory:

```text theme={null}
<project>/.cxcap/project.identity.json
```

This file anchors the checkout to a Contexity project ID. Without it, Contexity cannot associate local state — context packs, checkpoints, run ledgers — with the correct project. Keep it wherever you need Contexity to recognize the project.

## Local State Home

All durable state lives in a single directory on your machine, resolved in this order:

1. The `CONTEXITY_HOME` environment variable, if set
2. `XDG_STATE_HOME/contexity`, if `XDG_STATE_HOME` is set
3. `~/.local/state/contexity` (the default)

The state home stores:

* **Context items** — captured decisions, notes, and facts
* **External references** — Slack threads, issues, docs, and other captured sources
* **External signals** — extracted signals from external references
* **Checkpoints** — session closeout records
* **Run ledgers** — structured logs of agent runs
* **Project settings** — per-project Contexity configuration
* **Project intelligence sidecar data** — graph and analysis outputs
* **Metrics counters** — token and time savings estimates

Because the state home is machine-local, it is not shared automatically when you clone a project on another machine. Use `contexity export` and `contexity import` to move a context capsule across machines.

## What to Commit

Use the following as a guide when deciding what belongs in version control:

| Item                                                    | Commit?                                                      |
| ------------------------------------------------------- | ------------------------------------------------------------ |
| Source code                                             | ✅ Yes                                                        |
| Documentation                                           | ✅ Yes                                                        |
| `.cxcap/project.identity.json`                          | ✅ Yes — when your team intentionally shares project identity |
| Local state home contents (`~/.local/state/contexity/`) | ❌ No — machine-local only                                    |
| Rust `target/` directory                                | ❌ No                                                         |
| Generated benchmark output                              | ❌ No — unless it is part of a reviewed fixture               |

If your team wants all members to share the same Contexity project ID (so context packs and checkpoints are associated with the same project), commit `.cxcap/project.identity.json`. If each developer maintains independent project identity, add `.cxcap/` to your `.gitignore`.

## Backup

Back up both the per-project identity directory and the machine-wide state home before major changes or upgrades:

```bash theme={null}
cp -R /path/to/project/.cxcap /backup/project-cxcap
cp -R ~/.local/state/contexity /backup/contexity-state
```

<Tip>
  Back up before upgrading. Contexity tracks schema compatibility with `schema_version` fields in persisted records, but a backup lets you roll back safely.
</Tip>