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

# Config and state reference

> Where Voss stores user config, durable project cognition, sessions, and rebuildable cache.

## User config

Harness config lives under the user's config directory:

```text theme={"theme":"github-dark"}
~/.config/voss/config.toml
```

Use:

```bash theme={"theme":"github-dark"}
voss config
voss config --show
```

## Project state

Durable project state is split between human-readable `VOSS.md` and machine-managed `.voss/` directories:

```text theme={"theme":"github-dark"}
VOSS.md
.voss/
  constraints.yml
  permissions.yml
  validation.yml
  principles.yml      # project engineering principles (orchestration)
  team.voss           # declared role roster (orchestration)
  memory/
  plans/
  sessions/
  decisions/
```

`VOSS.md` is injected into harness context at session start. Machine fences inside it let Voss update architecture notes without overwriting surrounding human prose.

`principles.yml` and `team.voss` drive the [orchestration layer](/orchestration/overview): `principles.yml` extends or overrides the six default [principles](/orchestration/principles), and `team.voss` declares the [role roster](/orchestration/team-config) validated by `voss team check`.

## Cache state

Rebuildable state belongs under `.voss-cache/`:

```text theme={"theme":"github-dark"}
.voss-cache/
  repo.idx
  harness/
  code/
```

You should be able to delete cache state and rebuild it. The `code/` directory holds the
derived code recall index used by `voss recall` and the `code_recall` tool; it is not the
curated project memory store.

## Session state

Current project sessions live under `.voss/sessions/`. Legacy sessions in the old user-state directory are read-only via `voss sessions --all`.

A team run also persists its [session tree](/orchestration/session-tree) here, one file per agent node, plus per-card review sidecars:

```text theme={"theme":"github-dark"}
.voss/sessions/
  <session_id>.json                 # harness session
  <session_id>/
    token-savings.jsonl             # estimated original vs packed context tokens
  <root_id>/
    <node_id>.json                  # session-tree node (budget, scope, status)
    <node_id>.review.json           # Reviewer-A + Reviewer-B sidecar
```

Node and review files are written with `0o600` permissions.

`token-savings.jsonl` contains estimated counts only. It does not store prompt text, tool
arguments, or tool output.

<Note>
  Do not commit secrets to `VOSS.md`, `.voss/`, or `.voss-cache/`. Voss avoids storing provider credentials, but prompt text and project notes are still local files.
</Note>