Caching

Overview

Axiomatic caches test results in a local SQLite database at .axiomatic/cache.db to avoid redundant LLM calls. This is the most effective cost control mechanism.

Cache Keys

Each cache entry is keyed on:

• A hash of the test condition and configuration (provider, model, severity)
• Content hashes of all files matching the on glob pattern

When any of these change, the cache is invalidated and the test re-runs.

Invalidation

The cache is automatically invalidated when:

• The condition text changes
• Any file matching the on glob is modified, added, or deleted
• The provider or model configuration changes

Tests Without on Cannot Be Cached

Tests that omit the on field have no file hashes to key against, so they run every time. Always add on patterns to enable caching. Use axm validate to identify tests missing on patterns.

Bypassing the Cache

axm run --no-cache

Agent Memory (Cross-Run Notes)

In addition to result caching, Axiomatic's agent maintains persistent notes about your codebase across runs.

First run: The agent thoroughly explores your codebase, reading files and documenting architectural patterns, package structure, conventions, and key file locations.

Subsequent runs (no changes): The agent retrieves cached notes before starting. Since relevant files have not changed, it bypasses exploration and focuses directly on evaluation. These runs are significantly cheaper.

Subsequent runs (some changes): When files change, notes that reference those files are automatically invalidated. The agent re-explores the affected areas and updates its notes, but reuses notes for unchanged areas.

What Gets Recorded

The agent stores two categories of notes:

1. Codebase-level observations -- architectural patterns, package structure, conventions, and key file locations
2. Per-test observations -- specific file contents, function signatures, and implementation details relevant to individual tests

Storage

Agent memory notes are stored alongside cached results in .axiomatic/. These files are:

• Auto-generated -- you never need to create or edit them manually
• Safe to gitignore -- they are machine-specific and rebuild automatically

Storage

The cache database is lightweight (typically under 1 MB) and should be added to .gitignore. The axm init command does this automatically.