Skip to main content
Moss keeps an on-device index in sync with the cloud in two directions: hydration (loading existing data into memory when you open an index or session) and refresh (picking up cloud updates without reloading the service).
A cloud index hydrates a loaded index or session on device, auto-refreshes it, and receives push_index updatesA cloud index hydrates a loaded index or session on device, auto-refreshes it, and receives push_index updates

​
Hydration: cloud to device

When you open a session or load an index, Moss downloads the index binary and deserializes it into memory, so the agent starts warm instead of empty. No re-embedding happens; the prebuilt vectors are loaded directly.

​
Two layers of freshness

Once an index is live, freshness has two independent handles - one for getting changes into the index, and one for propagating those changes to running agents.

​
Layer 1: mutations

add_docs and delete_docs are the write API. They are asynchronous: you submit the change, and Moss rebuilds the index server-side without touching your live service. A mutation moves through statuses (pending_upload, uploading, building, completed); while building, it reports finer-grained phases such as generating_embeddings and building_index. Once completed, the new version is available in the cloud.

​
Layer 2: runtime hot-swap

Load an index with auto_refresh and Moss keeps the in-memory copy current automatically:
Periodically, Moss checks the cloud for a newer version. If one exists, it downloads in the background while the current version keeps serving queries; when the download finishes, the index is hot-swapped atomically. In-flight queries finish against the old version, new queries immediately see the updated one. No restart, no dropped requests, no coordination. The refresh path is:
  1. Content changes land through add_docs or delete_docs.
  2. Moss builds a new cloud version server-side.
  3. auto_refresh detects the new version, downloads it in the background, and atomically hot-swaps the loaded index.
  4. In-flight queries finish on the old version; new queries use the update.

​
Tuning the refresh interval

polling_interval_in_seconds controls how often Moss checks for a new version - not how fast a build completes. Match it to how quickly your data changes: To force an immediate update after a known critical change, reload the index explicitly. This is a blocking call that downloads and installs the latest version:

​
Independent per-index refresh

Each index manages its own refresh lifecycle on its own timer, so you can tune staleness tolerance per knowledge domain. A slow rebuild on one index never blocks queries or refreshes on another.

​
Persist: device to cloud

A session accumulates context locally during an interaction. push_index() syncs it back to the cloud - at the end, or at checkpoints - so it survives the session and any agent can resume it (see Cross-agent context & omni-channel handoff).

​
Convergence

With auto_refresh enabled, a loaded index converges to the latest version within at most one polling interval after the build completes. The hot-swap is atomic: in-flight queries complete against the previous version, and subsequent queries use the new one.

Live-call context

Short-term + long-term context during a call.

Sessions

The session lifecycle in depth.