Reasonix stores global state in ~/.reasonix/, project state inside the project, and the runtime in two more places. Knowing which directory holds what makes backup scripts trivial. The trickiest file is .env — it is excluded from MCP child environments but you still want it under version control, just redacted.

Reasonix files and directories at a glance

How a Reasonix turn flows from input to provider to tools

Reasonix version timeline: 0.x TS legacy, 1.0 Go rewrite, current 1.17.x

A backup script

Bash
#!/usr/bin/env bash
# Back up Reasonix state for archival or migration.
# Assumes REASONIX_HOME=~/.reasonix (default on Linux/macOS).
set -euo pipefail
STAMP=$(date -u +%Y%m%dT%H%M%SZ)
BACKUP_DIR="${REASONIX_BACKUP_DIR:-$HOME/Documents/reasonix-backup-$STAMP}"
mkdir -p "$BACKUP_DIR"

# 1. global config (TOML, safe to archive as-is)
cp -a "$HOME/.reasonix/config.toml" "$BACKUP_DIR/config.toml"

# 2. global .env — keep, but redact before sharing
cp -a "$HOME/.reasonix/.env" "$BACKUP_DIR/env.raw"
# produce a redacted copy for sync to git
sed -E 's/=.*$/=<REDACTED>/' "$BACKUP_DIR/env.raw" > "$BACKUP_DIR/env.example"

# 3. skills, commands, hooks
for d in skills commands; do
  [ -d "$HOME/.reasonix/$d" ] && cp -a "$HOME/.reasonix/$d" "$BACKUP_DIR/$d"
done
[ -f "$HOME/.reasonix/settings.json" ] && cp -a "$HOME/.reasonix/settings.json" "$BACKUP_DIR/settings.json"

# 4. sessions + checkpoints (largest part, optional)
STATE_ROOT="${REASONIX_STATE_HOME:-$HOME/.reasonix}"
if [ -d "$STATE_ROOT/sessions" ]; then
  tar czf "$BACKUP_DIR/sessions.tgz" -C "$STATE_ROOT" sessions
fi

# 5. memory
if [ -d "$STATE_ROOT/memory" ]; then
  tar czf "$BACKUP_DIR/memory.tgz" -C "$STATE_ROOT" memory
fi

echo "wrote $BACKUP_DIR"

Restoring from a backup

Bash
#!/usr/bin/env bash
# Restore a backup produced by the script above.
set -euo pipefail
BACKUP_DIR="${1:?usage: reasonix-restore.sh <backup-dir>}"

# 1. global config
mkdir -p "$HOME/.reasonix"
cp -a "$BACKUP_DIR/config.toml" "$HOME/.reasonix/config.toml"

# 2. .env — only restore if missing
if [ ! -f "$HOME/.reasonix/.env" ]; then
  cp -a "$BACKUP_DIR/env.raw" "$HOME/.reasonix/.env"
  chmod 600 "$HOME/.reasonix/.env"
else
  echo "warning: ~/.reasonix/.env exists; leaving in place"
fi

# 3. skills / commands / hooks
for d in skills commands; do
  [ -d "$BACKUP_DIR/$d" ] && cp -an "$BACKUP_DIR/$d" "$HOME/.reasonix/$d"
done
[ -f "$BACKUP_DIR/settings.json" ] && cp -an "$BACKUP_DIR/settings.json" "$HOME/.reasonix/settings.json"

# 4. sessions / memory
STATE_ROOT="${REASONIX_STATE_HOME:-$HOME/.reasonix}"
[ -f "$BACKUP_DIR/sessions.tgz" ] && tar xzf "$BACKUP_DIR/sessions.tgz" -C "$STATE_ROOT"
[ -f "$BACKUP_DIR/memory.tgz" ]   && tar xzf "$BACKUP_DIR/memory.tgz"   -C "$STATE_ROOT"

# 5. sanity check
reasonix doctor capabilities

What lives where

Purpose Path Note
Global config ~/.reasonix/config.toml TOML, safe to commit after secret redaction.
Global API keys ~/.reasonix/.env Key values. NEVER commit unredacted. Add .env to your ignore list and keep a redacted .env.example.
Project config ./reasonix.toml TOML, project-scoped providers, permissions, MCP.
Project .env ./.env Non-provider ${VAR} for MCP/plugin settings. Does not contain Reasonix control variables.
Sessions and history /sessions/ JSONL transcripts plus <id>.ckpt/ directories for checkpoints.
Skills ~/.reasonix/skills/ and /.reasonix/skills/ Markdown playbooks you authored.
Slash commands ~/.reasonix/commands/ and /.reasonix/commands/ Custom command files.
Hooks ~/.reasonix/settings.json Hook definitions. Stored as JSON, not TOML.
Memory /memory/ Pinned facts and project memory.
Cache $XDG_CACHE_HOME/reasonix/ Re-derivable; no need to back up unless disk pressure matters.

Common failure modes

  • /rewind rewind snapshots live under <state root>/sessions/<id>.ckpt/ next to the session JSONL. Back up the whole sessions/ directory, not just the JSONL files, or you lose rewind history.
  • Reasonix enforces chmod 600 on .env because provider keys are sensitive. Preserve that mode when restoring; do not let a backup pipeline silently flip it to 644.
  • A full session archive plus memory archive is the largest part of a backup. Drop the sessions/ tarball from the daily backup if your retention policy is shorter than 30 days — Reasonix prunes after ~30 days by default.
  • REASONIX_HOME and REASONIX_STATE_HOME let you split config from sessions. On CI runners, point REASONIX_STATE_HOME at ephemeral storage and keep REASONIX_HOME in the image.
  • Restoring an old config.toml over a newer one can drop providers the user has since added. Diff before you overwrite.

Sources

Last modified: 2026年7月23日

Author

Comments

Write a Reply or Comment

Your email address will not be published.