Skip to main content
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: 
<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:
ItemCommit?
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: 
cp -R /path/to/project/.cxcap /backup/project-cxcap
cp -R ~/.local/state/contexity /backup/contexity-state
Back up before upgrading. Contexity tracks schema compatibility with schema_version fields in persisted records, but a backup lets you roll back safely.