Guides

Cache

Mostly Right is local-first. Historical reads reuse a cache owned by your process; volatile periods are fetched again so an incomplete month or year is not mistaken for final data.

Python layout

The default root is ~/.mostlyright/cache/:

~/.mostlyright/cache/
├── v1/
│   ├── observations/KNYC/2025/01.parquet
│   ├── climate/KLAX/2024.parquet
│   ├── forecasts/...
│   ├── economy/...
│   └── sources/...
└── provenance/
    └── iem.jsonl

The v1 directory is a cache schema version, not the installed SDK major version. Version 2.0 continues to use it until the cache wire shape itself changes.

Writes use a file lock and atomic rename. Move the root with:

export MOSTLYRIGHT_CACHE_DIR="/path/to/mostlyright-cache"

MOSTLYRIGHT_CACHE_DIR is the only supported cache-root environment variable in 2.0.

Routing is automatic

from mostlyright import weather

reports = weather.observations(
    "KNYC",
    "2025-01-06",
    "2025-01-12",
)

Python weather.observations() chooses its ingest tactic internally. strategy= is not a public Python keyword in 2.0.

The router considers the window, existing cache coverage, an optional source= pin, and the configured hosted weather URL:

source-pinned reads use a source-isolated exact-window path
short cold windows can fetch only the requested range
repeated or large fused-source reads can warm and reuse year/month partitions
a configured hosted weather URL selects hosted delivery for methods that support it

This policy may change without changing the stable observations() call.

Mutable periods

Incomplete data is not trusted as final:

Data	Volatile period
Observations	Current station-local-standard-time month
Climate	Current station-local-standard-time year
Forecasts	Current station-local-standard-time month

Current-period cache entries are skipped or re-fetched. Closed partitions can be reused.

Targeted invalidation

Use the public weather cache helpers when a specific partition is suspect:

from mostlyright.weather import cache

cache.invalidate("KNYC", 2025, 1)
cache.invalidate_climate("KNYC", 2024)
cache.invalidate_forecast(...)
cache.invalidate_satellite(...)

Each helper returns True when it removed an entry and False when the entry was absent.

Cache files carry a schema stamp. When the stored shape is incompatible with the reader, the next call treats it as a miss and fetches again.

Provenance ledger

Re-fetchable cache writes append a small JSONL record under $MOSTLYRIGHT_CACHE_DIR/provenance/. It records the source, station, requested window, fetch time, row count, and a stable window hash.

Ledger writes are best-effort and never turn a successful data read into a failure.

TypeScript

The TypeScript SDK uses runtime-appropriate stores:

Runtime	Default
Browser, Service Worker, MV3	IndexedDB (`mostlyright-cache-v1`)
Node 20+	Filesystem under `$HOME/.mostlyright/cache-ts/`
Cloudflare Worker / storage-less edge	In-memory

Python and TypeScript caches are separate formats and directories. Do not share their files directly.

Advanced cache classes are available under @mostlyrightmd/core/internal/cache, but trainingTable() remains capped and does not accept a cache option. Domain reads may expose their own documented options.