Using the cache

Fetching bars from an adapter (which may be reading a large data lake and building bars from ticks) dominates a backtest’s wall clock, and it repeats identically run after run. algo run therefore caches fetch results on disk at ~/algolang/cache (override with --cache-dir or ALGO_CACHE_DIR) and serves repeat fetches from there. The cache is shared safely by every workspace and process on the machine, and it is invisible in results: off, cold, and warm runs produce byte-identical fills, reports, manifests, and audit records – only the BENCH timing/byte diagnostics differ. A corrupt or half-written cache file is treated as a miss, never an error.

The cache engages only for backtests whose --end does not extend past today 00:00 UTC (the window must be fully historical – note the default --end is 2100-01-01, so pass a real end date to benefit; the run tells you when caching was skipped and why). Entries are keyed on everything that determines the bars: the adapter identity (its description, which for the marketfeed adapter carries the build stamp make marketfeed-adapter writes from scripts/build-id.sh: both checkouts as git describes them, plus a fingerprint of any uncommitted content, so no two adapter builds share entries; GLE-354) and its inputs, the negotiated wire protocol, the symbol, the full bar spec, the exact range and, for a continuous run’s composite, the served snapshot token and the adjustment anchor the fetch pinned (GLE-324). A continuous run caches its composite bars under that token; the roll schedule itself is fetched fresh, and a new schedule generation from the feed changes the token, so it misses the cache and takes effect without a refresh. The cache has one level: the Level-2 continuous build cache of earlier builds is gone (the engine builds nothing since GLE-323), and a continuous/ directory left by an older cache is removed by a pattern-less algo cache flush, its files counted as removed entries.

Two behaviors worth knowing:

• Same-end reuse. A request that narrows only the start of an existing entry (same everything else, same end) is served by slicing that entry – running 2015-2024 after 2010-2024 reads no data from the adapter. Time bars only; activity bars (volume/tick/dollar/…) are construction-order dependent and always match exact ranges.
• Invalidation is manual. There is no freshness check against the lake. If the lake is rebuilt or history revised, run once with --cache refresh (bypass reads, rewrite entries) or clear entries with algo cache flush. A composite entry is no exception: the token names the feed’s lineage state, not the tape, so a nightly bar re-derive under one state is served from the warm entry until the refresh or the flush.

algo cache                  # stats: directory, entry count, total size
algo cache list  [glob...]  # entries by level/symbol/range
algo cache flush [glob...]  # remove matching entries (none = all)

--cache off disables for a run; ALGO_CACHE=off disables wherever the flag was not given explicitly. Trading-day containers participate in cache identity. Intraday session-window filtering (hours/days) remains unsupported; it is a separate feature. See the cache reference.