> ## Documentation Index
> Fetch the complete documentation index at: https://claw-lens.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Data Storage

> How Claw Lens stores and handles your agent data — all local, no external calls, no telemetry.

Claw Lens is designed to run entirely on your machine. No data leaves your computer — not to the Claw Lens project, not to any analytics service, not to any third party.

## What data Claw Lens reads

Claw Lens reads the session files that OpenClaw writes when your agents run. These files are stored in your OpenClaw home directory (by default `~/.openclaw`) and follow the path pattern:

```text theme={null}
~/.openclaw/agents/<agent-name>/sessions/<session-id>.jsonl
```

Each `.jsonl` file contains the message and tool-call history for a single agent session. Claw Lens parses these files to populate its dashboard views.

## Where Claw Lens stores data

All parsed data is stored in a local [SQLite](https://sqlite.org) database on your machine. The database file is created at:

```text theme={null}
~/.openclaw/claw-lens.db
```

If you have set the `OPENCLAW_HOME` environment variable, the database lives at:

```text theme={null}
$OPENCLAW_HOME/claw-lens.db
```

The database holds all session data, tool call history, and security audit findings. It is a standard SQLite file — you can inspect it with any SQLite client if needed.

<Note>
  The security audit data (flagged findings, risk scores, agent baselines) is stored in the same database file, not in a separate location.
</Note>

## Network access

The dashboard server binds exclusively to `127.0.0.1`. It is never reachable from another machine on your network — even if you configure a custom port or open it in your firewall.

Claw Lens makes no outbound network calls of its own. There is no telemetry, no analytics, no crash reporting, and no update pings sent anywhere.

## Clearing all stored data

To wipe everything Claw Lens has stored, delete the database file:

```bash theme={null}
rm ~/.openclaw/claw-lens.db
```

If you set `OPENCLAW_HOME`:

```bash theme={null}
rm "$OPENCLAW_HOME/claw-lens.db"
```

The next time you start `claw-lens`, it creates a fresh database and re-reads your agent session files from scratch.

<Warning>
  Deleting the database also removes all security audit findings, dismissed false positives, and computed risk scores. This cannot be undone.
</Warning>

## Refreshing agent data

If you want to reload agent data without deleting the database, use the **Refresh Data** button on the **Settings** page. This forces Claw Lens to re-read all session files and update its stored data.

You can also trigger a refresh via the API:

```bash theme={null}
curl -X POST http://localhost:4242/api/refresh
```

Claw Lens tracks each file by its modification time and size. On a normal startup it only processes files that have changed since the last run. A forced refresh re-reads every file regardless.

## Data retention

Claw Lens can only show data that still exists on disk. OpenClaw manages the lifecycle of session files — when OpenClaw deletes a file, that data disappears from Claw Lens on the next refresh. Understanding these retention settings helps you control how much history is available in the dashboard.

### Session file lifecycle

Session files are not deleted immediately. Instead, OpenClaw renames them with a suffix before eventually removing them:

* **`.deleted`** — when a session is archived, the file is renamed from `.jsonl` to `.jsonl.deleted.<timestamp>`
* **`.reset`** — when context is compacted mid-session, the old transcript is renamed to `.jsonl.reset.<timestamp>` and a fresh `.jsonl` is created

Both suffixed files still count toward token usage in Claw Lens. They are only physically deleted when the retention period expires.

### Session retention

By default, OpenClaw removes archived session files after **30 days**. You can change this in `~/.openclaw/openclaw.json`:

```json theme={null}
{
  "session": {
    "maintenance": {
      "pruneAfter": "90d",
      "resetArchiveRetention": "90d"
    }
  }
}
```

<ParamField path="pruneAfter" type="string">
  How long `.deleted` files are kept before being physically removed. Default: `"30d"`.
</ParamField>

<ParamField path="resetArchiveRetention" type="string">
  How long `.reset` files are kept. Defaults to the value of `pruneAfter` if not set.
</ParamField>

Accepted values: `"30d"`, `"720h"`, or `false` (never prune).

<Note>
  Restart the OpenClaw gateway after changing retention settings.
</Note>

### Cron session retention

Cron run metadata is stored separately from session transcripts:

| File               | Path                                                      | Retention                     |
| ------------------ | --------------------------------------------------------- | ----------------------------- |
| Run log (metadata) | `~/.openclaw/cron/runs/<jobId>.jsonl`                     | Kept permanently              |
| Session transcript | `~/.openclaw/agents/<agentId>/sessions/<sessionId>.jsonl` | Pruned after retention period |

By default, OpenClaw prunes cron session transcripts after **24 hours**. Once the session file is deleted, the run record still appears in the Cron page, but the "See in Sessions" link disappears.

To extend the retention window, add this to `~/.openclaw/openclaw.json`:

```json theme={null}
{
  "cron": {
    "sessionRetention": "48h"
  }
}
```

Accepted values: `"24h"`, `"7d"`, or `false` (never prune).

<Note>
  Restart the OpenClaw gateway after changing retention settings.
</Note>

### Cache trace retention

The cache trace file powers the **Context Breakdown** and **Cache Trace** pages. It is not enabled by default.

**Two ways to enable it:**

**Option 1** — add to `~/.openclaw/openclaw.json`:

```json theme={null}
{
  "diagnostics": {
    "cacheTrace": {
      "enabled": true,
      "includeMessages": true,
      "includePrompt": true,
      "includeSystem": true
    }
  }
}
```

**Option 2** — send the keyword `OPENCLAW_CACHE_TRACE` to OpenClaw and let it enable the setting for you.

<Warning>
  The cache trace file grows quickly. Set up a cron job to clean it periodically, or it will consume significant disk space over time.
</Warning>

## Summary

| What                | Where                                                                            |
| ------------------- | -------------------------------------------------------------------------------- |
| Agent session files | `~/.openclaw/agents/*/sessions/*.jsonl` (written by OpenClaw, read by Claw Lens) |
| Cron run logs       | `~/.openclaw/cron/runs/<jobId>.jsonl` (metadata, kept permanently)               |
| Cache trace file    | `~/.openclaw/` (requires manual cleanup)                                         |
| Claw Lens database  | `~/.openclaw/claw-lens.db`                                                       |
| External data sent  | None                                                                             |
| Telemetry           | None                                                                             |