Document Metadata

• title: Chronicle Archive Runbook
• description: Emergency and scheduled preservation commands for Chronicle screen recordings and written context.
• status: active
• lastUpdated: "2026-06-04 14:05 ET (America/New_York)"
• owner: Product/Engineering

Chronicle Archive Runbook Chronicle screen recordings are a rolling buffer.

Chronicle Archive Runbook

Chronicle screen recordings are a rolling buffer. Treat $TMPDIR/chronicle/screen_recording/ as volatile and copy captures out before they roll off.

The archive also preserves written context from ~/.codex/memories, including:

• MEMORY.md
• memory_summary.md
• raw_memories.md
• extensions/chronicle/instructions.md
• extensions/chronicle/resources/*.md
• rollout_summaries/*.md

The internal .git folder under ~/.codex/memories is intentionally excluded.

Current Emergency Archive

• Active archive root: /Users/maggielerman/ChronicleArchiveEmergency
• LaunchAgent: /Users/maggielerman/Library/LaunchAgents/com.maggielerman.chronicle-visualizer.archive.plist
• Interval: every 600 seconds
• Script: scripts/archive/chronicle-incremental.mjs
• Logs:
  • /Users/maggielerman/ChronicleArchiveEmergency/logs/launch-agent.out.log
  • /Users/maggielerman/ChronicleArchiveEmergency/logs/launch-agent.err.log

The Google Drive CloudStorage path timed out during directory creation on 2026-06-04 13:12 ET. Durable storage now uses private AWS S3 with client-side GPG encryption before upload.

Durable Private Storage

• Provider: AWS S3
• AWS profile: default
• AWS account guardrail: 528049652889
• Region: us-east-1
• Bucket: chronicle-visualizer-raw-private-528049652889-us-east-1
• Client encryption: GPG symmetric AES256
• Local passphrase file: ~/.config/chronicle-visualizer/archive-passphrase
• Passphrase permissions: 0600
• Local retention: 72 hours after successful upload receipt
• Local logs/receipts retention: 30 days by default

Do not commit the passphrase file, generated bundles, encrypted bundles, receipts, restore outputs, or raw captures to git.

Commands

Dry-run the compressed snapshot:

npm run archive:chronicle:dry-run

Create a compressed raw snapshot:

npm run archive:chronicle

Run the incremental preservation pass once:

CHRONICLE_ARCHIVE_ROOT="$HOME/ChronicleArchiveEmergency" npm run archive:chronicle:incremental

Run the incremental pass without remote upload:

CHRONICLE_ARCHIVE_ROOT="$HOME/ChronicleArchiveEmergency" npm run archive:chronicle:incremental:local

Install or refresh the 10-minute LaunchAgent:

CHRONICLE_ARCHIVE_ROOT="$HOME/ChronicleArchiveEmergency" npm run archive:chronicle:install-agent

Inspect the LaunchAgent:

launchctl print gui/$(id -u)/com.maggielerman.chronicle-visualizer.archive

Create or verify the private S3 bucket:

npm run archive:remote:setup:dry-run
npm run archive:remote:setup

Upload the latest snapshot:

CHRONICLE_ARCHIVE_ROOT="$HOME/ChronicleArchiveEmergency" npm run archive:remote:upload-snapshot

Verify recent remote objects and local upload receipts:

CHRONICLE_ARCHIVE_ROOT="$HOME/ChronicleArchiveEmergency" npm run archive:remote:verify

Dry-run restore of the latest written-context bundle:

CHRONICLE_ARCHIVE_ROOT="$HOME/ChronicleArchiveEmergency" npm run archive:restore:dry-run

Dry-run local pruning:

CHRONICLE_ARCHIVE_ROOT="$HOME/ChronicleArchiveEmergency" npm run archive:prune-local

Apply local pruning only after reviewing dry-run output:

CHRONICLE_ARCHIVE_ROOT="$HOME/ChronicleArchiveEmergency" npm run archive:prune-local:apply

Archive Layout

Compressed snapshots:

/Users/maggielerman/ChronicleArchiveEmergency/raw/YYYY/MM/DD/
  <timestamp>-screen-recording.tar.zst
  <timestamp>-screen-recording.manifest.json
  <timestamp>-written-context.tar.zst
  <timestamp>-written-context.manifest.json

Encrypted snapshot uploads:

s3://chronicle-visualizer-raw-private-528049652889-us-east-1/raw/snapshots/YYYY/MM/DD/
  <timestamp>-screen-recording.tar.zst.gpg
  <timestamp>-screen-recording.manifest.json.gpg
  <timestamp>-written-context.tar.zst.gpg
  <timestamp>-written-context.manifest.json.gpg

Incremental copies:

/Users/maggielerman/ChronicleArchiveEmergency/incremental/
  screen_recording/
  latest/YYYY/MM/DD/
  written-context/
  runs/YYYY/MM/DD/<timestamp>-incremental.json

Encrypted delta uploads:

s3://chronicle-visualizer-raw-private-528049652889-us-east-1/raw/deltas/YYYY/MM/DD/
  <timestamp>-delta.tar.zst.gpg
  <timestamp>-delta.manifest.json.gpg

Upload receipts:

/Users/maggielerman/ChronicleArchiveEmergency/receipts/YYYY/MM/DD/
s3://chronicle-visualizer-raw-private-528049652889-us-east-1/receipts/YYYY/MM/DD/

Remote receipts are plaintext and intentionally minimal. Bundle contents and manifests are client-encrypted before upload.

Policy

• Do not commit archive outputs to git.
• Do not rely on private git as the raw-capture archive for this repo.
• Keep the emergency archive local for 72 hours after successful remote upload receipts.
• Delete local raw/delta files only through archive:prune-local:apply.
• Keep public derivatives separate from raw private captures.
• Preserve written context and images together so visual history is not detached from durable work context.
• Treat OCR as noisy search metadata only.
• Treat project labels as inferred unless confirmed by git, docs, or artifacts.

Restore Notes

The restore dry-run downloads an encrypted S3 object, decrypts it locally with the passphrase file, lists the tar contents, and does not restore files into active source locations.

Current written-context restore checks require:

• MEMORY.md
• memory_summary.md
• rollout_summaries/
• extensions/chronicle/resources/
• .git excluded

If the passphrase file is lost, existing client-encrypted archives cannot be decrypted. Back up the passphrase through a separate private secret-management path before relying on S3 as the only copy.

Provenance

• Source file: DOCS/development/archive-runbook.md
• Source URL: https://github.com/maggielerman/chronicle-visualizer/blob/main/DOCS/development/archive-runbook.md