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 (Navigation Plans)

In addition to result caching, Axiomatic's agent maintains navigation plans — persistent memory of which files matter and how to verify each condition.

First run: The agent thoroughly explores your codebase, discovering which files are relevant to each condition and developing a verification strategy.

Subsequent runs: The agent retrieves its navigation plan and goes directly to the relevant files, skipping cold-start exploration. This significantly reduces token usage and cost.

What Gets Recorded

Each navigation plan stores:

1. Relevant files — the key files the agent needs to read for a specific condition
2. Verification strategy — how the agent approached verification
3. Key findings — important observations from the investigation

Shared Agent Memory

When you're authenticated (axm login or AXM_TOKEN env var), navigation plans are automatically synced to the cloud and shared across your team. This means:

• A teammate running the same test on a fresh clone skips cold-start exploration
• CI runners benefit from navigation plans built during local development
• The more your team runs, the smarter everyone's agent gets

Shared agent memory is available on both Free and Cloud tiers. Plans are matched by model — a navigation plan created with Claude Sonnet is shared with all team members using Claude Sonnet.

Storage

Agent memory is stored locally in .axiomatic/cache.db and synced to the cloud when authenticated. Local 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.