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

# Project cognition and memory

> How Voss persists project-local instructions, sessions, plans, and recallable memory.

Project cognition is the project-local state Voss uses to avoid starting from zero every session.

## Durable state

Human-readable project context lives in `VOSS.md`. Machine-managed durable state lives under `.voss/`:

```text theme={"theme":"github-dark"}
VOSS.md
.voss/
  permissions.yml
  validation.yml
  memory/
  plans/
  sessions/
  decisions/
```

`VOSS.md` can include human prose plus machine-managed fenced sections such as architecture notes. Legacy `.voss/architecture.md` content is migrated into the `VOSS.md` architecture fence.

## Rebuildable state

Machine-generated indexes and cache files live under `.voss-cache/`:

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

This state should be safe to delete and rebuild.

`code/` is the rebuildable code recall cache. Voss uses it to answer concept-level
questions through `voss recall` and the `code_recall` tool, while project memory remains the
curated durable store under `.voss/memory/`.

## What Voss records

Agent runs can record:

* Task goal
* Plan
* Inspected files
* Changed files
* Avoided files
* Assumptions
* Decisions
* Risks
* Validation
* Failures
* Diff summary
* Follow-ups

## Memory commands

Inside a harness session:

```text theme={"theme":"github-dark"}
/recall <query>
/memory
/save <note>
/forget <pattern> --yes
```

From the CLI:

```bash theme={"theme":"github-dark"}
voss recall "where is retry backoff handled?"
voss recall "permission gate" --json
voss memory size
voss memory vacuum
voss memory adopt --id <fence-id>
```

Recall results are labeled by source, such as `[code]` and `[memory]`. Vector search is an
optional acceleration path; Voss can still return lexical results when that backend is
unavailable.