Setting Up ADR Sensor with XDG_CACHE_HOME for Session Storage

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 (lines 78-86). This method implements the XDG cache resolution logic:

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 (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:

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.

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:

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.
• 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}