File layout

The files are the interface.

Checkpoint's project memory is designed to be opened in an editor, reviewed in a diff, and explained by its directory names.

Project memory

.contextos/
  context/
    constraints.md
    glossary.md
  tasks/
    active/
      TASK-004.md
    done/
  handoffs/
    latest.md
  decisions/
    0001-use-readable-memory.md
  state/
    events.jsonl

What each part is for

context/

Longer-lived notes: constraints, glossary, architecture hints, and product language.

tasks/

Active and completed work items that make the current thread explicit.

handoffs/

Session status, changed files, verification notes, blockers, and next actions.

decisions/

Small records of choices worth preserving across tool switches.

Generated agent files

Some commands can generate repo-level Markdown such as AGENTS.md or CLAUDE.md. Treat them as build artifacts you can read and refine, not as hidden instructions. 

checkpoint project AGENTS.md
checkpoint project CLAUDE.md

What to commit

Every project will choose its own boundary. A common starting point is to commit durable context and decisions, while keeping noisy local state out of review.

Use the repo's normal review habits.

If a file affects the next developer or the next AI session, it should be understandable in a pull request.