# The rescan cache

> Why a second scan of an unchanged tree is instant, what is stored, where, and how to bypass, inspect or clear it in the CLI and in the browser.

Source: https://keryn.dev/docs/guides/rescan-cache/

## Goal

Know when Keryn answers a scan from a stored report instead of scanning, what that store holds and where it lives, and how to bypass or empty it: with `--no-cache`, `KERYN_NO_CACHE=1`, `keryn cache clear|stats|path`, and the `keryn-rescan` database in the browser.

## Before you start

- The Keryn CLI ([install](https://keryn.dev/docs/start/install/)). The cache is on by default; there is nothing to enable.
- The cache holds **reports of code on this machine**, including the few lines of code each finding quotes. It never holds a token, and nothing in it is sent anywhere.

## 1. See a hit

Scan twice. The second run finds the same tree, the same rules and the same settings, and returns the stored report without scanning:

```sh
keryn scan . --quiet || true
keryn scan . 2>&1 | sed 's/since .* UTC/since <time>/' | sed -n '1,3p'
```

```text
keryn: unchanged since <time>, cached report (--no-cache rescans)
Keryn — Policy blocked (Hold); dependency advisories not checked (offline)
  1 violation(s)/finding(s) at or above 'error'
```

The first line is on standard error and says it was a hit. The numbers on the second line are those of the scan that produced the report, including its duration; a hit does not take that long. The cached report carries the same exit code the scan had.

## 2. See what changes the answer

The key is a digest of the engine (Keryn and engine versions, the packaged WebAssembly, the Deep and known-fix identities), the rule texts, the settings that change a report, and the tree (every path with a SHA-256 of its content). Change one file and the key changes:

```sh
echo "# edited" >> agent.py
keryn scan . 2>&1 | sed -n '1,1p'
```

```text
Keryn — Policy blocked (Hold); dependency advisories not checked (offline)
```

No `unchanged since` line: this is a real scan. It is cheaper than the first one in one way only. The pattern pass is file-local, so a file whose content, path, rules and engine are unchanged reuses its matches; **Deep, known-fix matching, the inventory and deduplication run again over the whole tree**, because they can depend on any file. A one-line edit saves the pattern pass, not Deep.

A report is also not reused in these cases, on purpose:

- a scan with `--base` (the comparison is the point; see [baselines](https://keryn.dev/docs/guides/baselines/)) or with observations (`--observed-browser`, `--observed-network`),
- a scan whose Deep or known-fix stage failed or was stopped, and files that hit a rule's time budget,
- a scan with an `expires` suppression or a policy waiver, across a UTC day boundary: the report could be wrong the next day.

## 3. Look at it

```sh
keryn cache stats | sed -E 's/ in .*//; s/[0-9.]+ MB/<size> MB/'
```

```text
3 entries, <size> MB
```

`keryn cache path` prints the directory, one file per stored scan, readable only by you. Defaults: macOS `~/Library/Caches/keryn/rescan`, Linux `$XDG_CACHE_HOME/keryn/rescan` or `~/.cache/keryn/rescan`, Windows `%LOCALAPPDATA%\keryn\Cache\rescan`. Set `KERYN_CACHE_DIR` to move it, for example onto the volume a CI job caches between runs. The cache is capped (512 MB for the CLI and the language server); the least recently used entries go first.

## 4. Bypass it, or empty it

```sh
KERYN_NO_CACHE=1 keryn scan . 2>&1 | sed -n '1,1p'
keryn scan . --no-cache --quiet
```

```text
Keryn — Policy blocked (Hold); dependency advisories not checked (offline)
```

`--no-cache` (on `scan` and `bundle`) and `KERYN_NO_CACHE=1` neither read nor write the cache for that run. Use them when you want a measured, from-scratch scan, when you are comparing two builds of Keryn, or in a job that must not leave files in a cache directory. If you are working on a checkout of Keryn itself, remember that the engine identity does not hash source you changed without bumping the version.

```sh
keryn cache clear | sed -E 's/ from .*//; s/\([0-9.]+ MB\)/(<size> MB)/'
```

```text
cleared 3 entries (<size> MB)
```

`keryn cache clear` deletes everything the cache holds. Clear it after a scan of code you must not leave traces of, because a stored report quotes lines of that code.

## 5. In the browser

[Keryn Web](https://keryn.dev/docs/guides/web-app/) (and its portfolio view, which uses the same scanner) keeps the same kind of cache in IndexedDB, in a database named **`keryn-rescan`**, capped at 256 MB with the same least-recently-used eviction. Entries are keyed by digests of file contents, rules and settings, or by the commit of a public GitHub repository, so scanning the same commit again answers without downloading it. If the browser blocks IndexedDB there is simply no cache.

To empty it, use **Settings, Clear cache** (or **Clear saved data**, which clears more). To look at it, open your browser's developer tools, Application (Storage in Firefox), IndexedDB, `keryn-rescan`. Two other databases sit next to it and are not part of this cache: `keryn-portfolio` (saved portfolios) and `keryn-gh-cache` (GitHub's answers, with their ETags, for seven days).

## What you just proved

The cache is a **local edge that you can see and cut**: a directory (or a browser database) of reports, keyed by content, that never leaves the machine, with one command to inspect it and one to remove it. The property it keeps is the one the rest of Keryn keeps: the same input gives the same answer. A cached report is returned only when every input to the key is identical, and a stale one cannot be returned, because a changed input is a different key.

## Next

- What else stays on the machine: [local by design](https://keryn.dev/docs/concepts/local-only/) and [privacy](https://keryn.dev/privacy/).
- Faster scans in CI: [CI](https://keryn.dev/docs/guides/ci/), and `KERYN_CACHE_DIR` on a cached volume.
- Read what a rule says offline: [explain and docs](https://keryn.dev/docs/guides/explain-and-docs/).
