> For the complete documentation index, see [llms.txt](https://thesium.gitbook.io/thesium-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://thesium.gitbook.io/thesium-docs/mechanics/caching-polling-and-freshness.md).

# Caching, Polling, and Freshness

The freshness model is the bridge between "the data is correct" and "the data feels live." Several layers cooperate.

## Cache layers

| Layer                  | Storage              | Scope                                               | Eviction                |
| ---------------------- | -------------------- | --------------------------------------------------- | ----------------------- |
| In-memory snapshot     | service worker       | per (tabId) and (tabId, pageUrl)                    | worker shutdown         |
| Persistent snapshot    | chrome.storage.local | per (pageUrl)                                       | LRU over 200 entries    |
| Recently-viewed tokens | chrome.storage.local | per (source, chain, address)                        | per-source + global cap |
| Global token info      | service worker       | per (address, pool)                                 | worker shutdown         |
| Global AI artifacts    | service worker       | per (address) for lore, (address, pool) for summary | worker shutdown         |
| Audit cache            | service worker       | per (address)                                       | worker shutdown         |
| Negative cache         | service worker       | per (address, pool) for unknowns                    | short TTL               |

The persistent cache is what makes the experience feel stateful across browser restarts. When the trader closes their browser at end of day and reopens it tomorrow morning, the last tokens they looked at are still warm.

The recently-viewed list is what powers the "Recently Viewed" UI in the side panel, popup, and in-page card - a fast way back into tokens the trader recently researched, scoped per terminal so a binge on one terminal doesn't push out history from another.

## URL normalization for the cache

Some terminals append session-varying query parameters to their token URLs without changing the underlying token. To avoid cache-key fragmentation, the persistent cache normalizes those URLs to `origin + pathname` (dropping the query string) when constructing the cache key. Terminals that carry meaningful state in their query strings (e.g. `?chain=`) retain the full URL as the cache key.

## Polling loop

While a tab with a recognized token is open and a snapshot has resolved, the background polls all section services on a regular cadence. Polling uses `chrome.alarms` so that it survives service-worker shutdown.

The audit section runs on a faster sub-tick than the rest, so security-critical state (a contract just renounced ownership, a liquidity pool just got pulled) reflects faster than market data.

Polling is incremental in two ways:

* A successful response with an empty result set does not overwrite the existing populated view. The previous state is kept; the new state is treated as a stale read.
* A failed response (network error, timeout) does not overwrite the previous state. The snapshot is sticky on the last good value until a real change arrives.

This is deliberate. A flickering panel that bounces between "12 holders" and "0 holders" because one poll briefly failed is worse than a panel that reads slightly stale for one cycle.

## What is live, what is cached

| Section                          | Source freshness                     | Effective freshness |
| -------------------------------- | ------------------------------------ | ------------------- |
| Price, market cap, volume        | Backend indexers, sub-minute         | Standard poll tick  |
| Holder count, structural metrics | Backend indexers, near-real-time     | Standard poll tick  |
| Holders list                     | Backend indexers                     | Standard poll tick  |
| KOL positions                    | Backend indexers                     | Standard poll tick  |
| Feed                             | Ingestion pipeline, near-real-time   | Standard poll tick  |
| AI summary (Trenches Pulse)      | Generated on poll if inputs changed  | Standard poll tick  |
| Audit                            | Third-party simulation, cached short | Faster sub-tick     |
| Lore                             | Generated once, cached               | Cached              |

For traders coming from purely live-streaming tools: the polling cadence is a deliberate floor. The information in the panel is research-grade, not execution-grade. Position sizing and entry/exit decisions still happen against the live chart in the trader's terminal. Thesium tells the trader what they are looking at - not when to click.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://thesium.gitbook.io/thesium-docs/mechanics/caching-polling-and-freshness.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.