Skip to main content
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/:
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/:
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:
From the CLI:
Pinned memories are always injected into agent context. voss memory promote copies a project memory into the global store, tagged with the project it came from, so it can be used across repositories. 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. Projects that opt into Jev judgments can rerank pre-turn code recall; see Config and auth.

​
Instructions files

Voss also reads AGENTS.md and CLAUDE.md from the project root down to the working directory and injects them into every native run within a token budget. Inspect the bundle with voss instructions show, and fail CI on import cycles or budget overflow with voss instructions check. See [instructions].

​
Retained memory backend

By default retained memory lives in .voss/memory/. A project can opt into a Laravel memory service instead:
The service is reached through VOSS_MEMORY_API_URL and VOSS_MEMORY_API_TOKEN. Session history stays in the local store. With this backend, /forget needs an exact memory:<project>:<id> locator.