# Setting Up ADR Sensor with XDG_CACHE_HOME for Session Storage

> Learn how to set up ADR Sensor with XDG_CACHE_HOME to easily redirect AI-agent session storage to your preferred custom location. Configure ADR Sensor efficiently.

- Repository: [Uber Open Source/ADR](https://github.com/uber/ADR)
- Tags: how-to-guide
- Published: 2026-08-07

---

**The ADR Sensor writes AI-agent session files to `~/.cache/adr_sensor` by default, but you can redirect storage to any custom location by setting the `XDG_CACHE_HOME` environment variable before launching the sensor.**

The Uber ADR (AI Data Recorder) Sensor captures and persists AI-agent interactions for observability and debugging purposes. According to the `uber/ADR` source code, the sensor adheres to the XDG Base Directory Specification to determine its cache location, falling back to `~/.cache` only when the environment variable is unset. This guide explains how session storage resolution works and demonstrates how to configure custom paths via environment variables for both the CLI tool and Python API.

## How ADR Sensor Resolves the Cache Directory

When you instantiate an `AgentObserver`, the sensor immediately calls the private helper `_get_default_session_dir()` defined in [`Sensor/adr_sensor/observer.py`](https://github.com/uber/ADR/blob/main/Sensor/adr_sensor/observer.py) (lines 78-86). This method implements the XDG cache resolution logic:

```python
xdg_cache_home = os.getenv("XDG_CACHE_HOME")
if xdg_cache_home:
    cache_dir = Path(xdg_cache_home)
else:
    cache_dir = Path.home() / ".cache"
return cache_dir / "adr_sensor"

```

If `XDG_CACHE_HOME` is present in the environment, the sensor writes session files to `<XDG_CACHE_HOME>/adr_sensor`. Otherwise, it falls back to the standard `~/.cache/adr_sensor` path. The CLI entry point in [`Sensor/adr_sensor/cli.py`](https://github.com/uber/ADR/blob/main/Sensor/adr_sensor/cli.py) (line 176) accesses this same path through `observer._get_default_session_dir()` when handling the `--save-sessions` flag.

## Configuring Session Storage via Environment Variable

You can override the default cache location by exporting `XDG_CACHE_HOME` before invoking the sensor. This approach works for both containerized environments and local development workflows where you need session data written to a specific volume or temporary directory.

Set the variable in your shell and run the sensor:

```bash
export XDG_CACHE_HOME="/tmp/adr_cache"
adr-sensor --save-sessions

```

After execution, session files appear under `/tmp/adr_cache/adr_sensor/` instead of the default location. This configuration persists only for the current shell session unless added to your shell profile.

## Programmatic Configuration with the Python API

When using the `AgentObserver` class directly, set `XDG_CACHE_HOME` in `os.environ` before instantiating the observer. The sensor checks this variable during initialization and automatically creates session files in the specified directory.

```python
import os
from pathlib import Path
from adr_sensor import AgentObserver

os.environ["XDG_CACHE_HOME"] = str(Path("/var/tmp/adr_cache"))

observer = AgentObserver()
events, configs = observer.ingest_all()

observer.save_to_file(events, configs, output_format="json")

```

In this example, the observer writes session data to `/var/tmp/adr_cache/adr_sensor/` because the environment variable was defined prior to instantiation.

## Verifying the Session Directory Location

To confirm where the sensor will persist data before running ingestion, you can invoke the `_get_default_session_dir()` method directly on an `AgentObserver` instance:

```python
from adr_sensor.observer import AgentObserver

obs = AgentObserver()
default_dir = obs._get_default_session_dir()
print(f"ADR Sensor will store sessions in: {default_dir}")

```

This technique is useful for debugging path resolution issues in CI/CD pipelines or verifying that environment variables are being read correctly.

## Summary

- **Default location**: Without configuration, ADR Sensor stores sessions in `~/.cache/adr_sensor` as implemented in [`Sensor/adr_sensor/observer.py`](https://github.com/uber/ADR/blob/main/Sensor/adr_sensor/observer.py).
- **XDG compliance**: The sensor respects the `XDG_CACHE_HOME` environment variable, following the XDG Base Directory Specification.
- **Universal application**: Both the CLI (`adr-sensor`) and the Python `AgentObserver` class rely on `_get_default_session_dir()` to resolve paths, ensuring consistent behavior across interfaces.
- **Pre-instantiation requirement**: Set `XDG_CACHE_HOME` before creating the `AgentObserver` instance or running the CLI to ensure the custom path is recognized.

## Frequently Asked Questions

### What is the default session storage path for ADR Sensor?

By default, ADR Sensor stores session files in `~/.cache/adr_sensor`. This path is constructed by appending `adr_sensor` to the user's home cache directory when the `XDG_CACHE_HOME` environment variable is undefined.

### How does the CLI determine where to save sessions?

The CLI entry point in [`Sensor/adr_sensor/cli.py`](https://github.com/uber/ADR/blob/main/Sensor/adr_sensor/cli.py) retrieves the session directory by calling `observer._get_default_session_dir()` (line 176), which applies the same XDG cache resolution logic used by the Python API. Setting `XDG_CACHE_HOME` before running `adr-sensor --save-sessions` redirects output to your custom location.

### Can I use a relative path for XDG_CACHE_HOME?

While the sensor will resolve the path using Python's `Path` constructor, it is recommended to use absolute paths for `XDG_CACHE_HOME` to avoid ambiguity. Relative paths may resolve relative to the current working directory at runtime, which can lead to inconsistent behavior depending on where the sensor is launched from.

### Does ADR Sensor create missing cache directories automatically?

The source implementation implies that the sensor writes session files to the resolved path, though you should ensure the parent directory exists and is writable. Setting `XDG_CACHE_HOME` to a non-existent path may require creating the directory manually or ensuring your deployment process provisions the volume before the sensor starts.