> 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.