Skip to content

Guide

Reference

Concepts

.reyn/ — state directory

Per-project state. Default location: <project_root>/.reyn/. Override via reyn.yaml's state_dir key.

Layout

.reyn/
├── approvals.yaml                          # persistent permission approvals
├── events/                                 # all event JSONL logs
│   ├── direct/                             # skill runs from `reyn run`
│   │   └── skill_runs/<YYYY-MM>/
│   │       └── <ts>_<skill>.jsonl
│   └── agents/<name>/                      # skill runs + chat events from an agent
│       ├── skill_runs/<YYYY-MM>/
│       │   └── <ts>_<skill>.jsonl
│       └── chat/<YYYY-MM>/                 # chat session events (rotated by size/age)
│           └── <ts>.jsonl
├── agents/<name>/                          # per-agent workspace (one dir per agent)
│   ├── profile.yaml                        # agent name, role, allowed_skills
│   ├── history.jsonl                       # append-only conversation log
│   ├── memory/                             # agent-scoped memory
│   │   ├── MEMORY.md
│   │   └── <name>.md
│   └── state/                              # WAL skill-run snapshots
│       └── skills/<run_id>.snapshot.json
├── skill-versions/<name>/                  # skill version snapshots (FP-0006)
│   └── v<N>.md
├── eval-results/<skill>/                   # `reyn eval run` result files
│   └── <timestamp>.jsonl
├── state/                                  # process-global persistent state
│   └── budget_ledger.jsonl                 # daily/monthly token + USD ledger
└── memory/                                 # project-scope memory
    ├── MEMORY.md
    └── <name>.md

Note: .reyn/config.yaml was removed in ADR-0031 (3-layer config cascade). Personal config overrides now live in reyn.local.yaml (gitignored, project root). If you have an existing .reyn/config.yaml, move its contents to reyn.local.yaml and delete the old file. Reyn will print a warning until it is removed.

approvals.yaml

Persistent permission approvals from interactive prompts. Keyed by <skill>/<op>/<path> — see permissions.md.

my_skill/file.write//tmp/output: just_path
my_skill/shell: allow

Inspect with reyn permissions list. Remove with reyn permissions revoke <key>.

events/

All event JSONL logs. Organized by caller and log type:

  • direct/skill_runs/<YYYY-MM>/<ts>_<skill>.jsonl — events from reyn run (non-agent skill runs)
  • agents/<name>/skill_runs/<YYYY-MM>/<ts>_<skill>.jsonl — skill run events spawned by a named agent
  • agents/<name>/chat/<YYYY-MM>/<ts>.jsonl — chat-session events (rotated by events.max_bytes / events.max_age_seconds)

JSONL files are replayable with reyn events <file>. See events reference.

agents/<name>/

Per-agent workspace. One directory per named agent (created by reyn agent new). The default agent always exists.

  • profile.yaml — agent identity: name, role, optional allowed_skills. See profile-yaml reference.
  • history.jsonl — append-only conversation log (user + assistant turns; cross-agent messages include chain_id for tracing).
  • memory/ — agent-scoped memory (MEMORY.md index + body files). Recalled and written automatically during the router phase.
  • state/skills/<run_id>.snapshot.json — WAL snapshots for crash recovery of in-flight skill runs.

skill-versions/<name>/

Skill version snapshots written by skill_improver (FP-0006). Each v<N>.md is a timestamped snapshot of skill.md at the time a proposal was applied. Pruned to self_improvement.max_versions snapshots. Inspect with reyn skill versions <name>.

eval-results/<skill>/

One JSONL file per reyn eval run execution. Each line records a single case result: input, expected, actual final_output, score, passed flag, and skill_version_hash. Used by reyn eval report and reyn eval compare.

state/budget_ledger.jsonl

Persistent daily and monthly token + USD usage records. Append-only with fsync. Reset automatically at midnight (daily) or the 1st of the month (monthly). Inspect with /budget in reyn chat. Not affected by /budget reset (which only clears in-memory counters).

memory/

Project-scope memory — facts that should persist across runs but are project-specific. Global memory lives at ~/.reyn/memory/ instead.

MEMORY.md is the index; each <name>.md is one memory entry with frontmatter (type, name, description).

Global state (~/.reyn/)

Same shape as .reyn/ but lives in the home directory. Used for:

  • ~/.reyn/config.yaml — user-global defaults.
  • ~/.reyn/memory/ — global memory (facts about the user, not tied to a project).

recall_memory and write_memory consult both global and project scopes.

Gitignore

Recommended additions:

.reyn/
reyn.local.yaml

Memory (.reyn/memory/) — choose based on whether project memory is shared between collaborators.

See also

On this page