Skip to content

OPERATIONS.md

Latest commit

 

History

History
174 lines (126 loc) · 4.08 KB

OPERATIONS.md

File metadata and controls

174 lines (126 loc) · 4.08 KB
Raw

Operations Guide

This guide is the operator-facing companion to the README. It focuses on the runtime controls, safety features, and commands most useful for repeatable local automation.

./scripts/totalrecall --help prints usage text, and ./scripts/totalrecall --version prints the installed TotalRecall version and exits 0.

Core Commands

totalrecall fathom pull
totalrecall chat-export import
totalrecall slack import
totalrecall github-activity import
totalrecall config validate
totalrecall doctor
totalrecall state inspect
totalrecall state prune

High-Value Flags

Preview and automation

  • --dry-run: show what would happen without mutating a destination
  • --plan: plan-oriented alias for --dry-run
  • --output json: machine-readable command output
  • --report-json PATH: persist a machine-readable run report artifact
  • --verbose: print detailed execution steps

Safety and control

  • --force: re-sync an existing import
  • --max-failures N: stop a run after N item failures
  • --since YYYY-MM-DD: limit provider results by date
  • --before YYYY-MM-DD: state-prune cutoff date

Sync Semantics

Default behavior

  • first import creates destination artifacts and writes sync state
  • later runs skip duplicates based on provider/source identity
  • successful items checkpoint state incrementally

--force

--force is designed for repair and re-sync scenarios.

  • if the destination mapping still exists, TotalRecall updates it in place
  • if a Strata note mapping is stale and the note was deleted, TotalRecall creates a replacement note and repairs sync state automatically
  • for local destinations, update behavior uses the tracked destination artifact name or path

Runtime Controls

Reliability

TOTALRECALL_RETRY_MAX_ATTEMPTS=3
TOTALRECALL_RETRY_BACKOFF_MS=100
TOTALRECALL_RETRY_JITTER_MS=25

Fathom pacing and throughput

TOTALRECALL_FATHOM_REQUESTS_PER_SECOND=0
TOTALRECALL_FATHOM_TRANSCRIPT_WORKERS=1
TOTALRECALL_FATHOM_MEETINGS_RETRY_MAX_ATTEMPTS=3
TOTALRECALL_FATHOM_TRANSCRIPT_RETRY_MAX_ATTEMPTS=3
TOTALRECALL_FATHOM_MEETINGS_TIMEOUT_MS=30000
TOTALRECALL_FATHOM_TRANSCRIPT_TIMEOUT_MS=30000

Strata controls

TOTALRECALL_STRATA_HEALTH_RETRY_MAX_ATTEMPTS=3
TOTALRECALL_STRATA_NOTE_RETRY_MAX_ATTEMPTS=3
TOTALRECALL_STRATA_HEALTH_TIMEOUT_MS=5000
TOTALRECALL_STRATA_NOTE_TIMEOUT_MS=10000

Security and compliance

TOTALRECALL_USE_KEYCHAIN=1
TOTALRECALL_STATE_ENCRYPT=1
TOTALRECALL_AUDIT_LOG_PATH=~/Library/Logs/totalrecall/audit.jsonl

Import Policy Controls

Mapping and tagging

TOTALRECALL_MAPPING_TEMPLATE=default
TOTALRECALL_TAG_PROFILE=default
TOTALRECALL_TAG_FROM_PROJECTS=0
TOTALRECALL_TAG_FROM_PARTICIPANTS=0

Filtering and reconciliation

TOTALRECALL_FILTER_TITLE_PATTERNS=sprint,planning
TOTALRECALL_FILTER_PARTICIPANTS=robert,casey
TOTALRECALL_FILTER_PROJECTS=platform,openai/totalrecall
TOTALRECALL_FILTER_TAGS=engineering,udc
TOTALRECALL_DEDUP_TIME_WINDOW_DAYS=1
TOTALRECALL_RECONCILE_DESTINATIONS=1

Diagnostics

Validate configuration and reachability

./scripts/totalrecall config validate

Workstation-oriented health summary

./scripts/totalrecall doctor --output json

Inspect or prune state

./scripts/totalrecall state inspect --limit 20
./scripts/totalrecall state prune --before 2026-01-01 --dry-run

Exit Codes

Code Meaning
0 success
1 CLI usage error
2 configuration error
3 network or connectivity error
4 parse or response-shape error
5 write or state persistence error

Logs And Reports

Structured logs

./scripts/totalrecall fathom pull --log-format json

Report artifact

./scripts/totalrecall fathom pull --report-json artifacts/run-report.json

Quality Gate

The local validation path is:

scripts/quality_gate.sh

That gate runs:

  • Kujo tests
  • Python harness coverage enforcement
  • deterministic provider/destination harnesses
  • smoke checks
  • docs validation
  • changelog generation sanity checks