AxContextCacheOptions

TypeScript

type AxContextCacheOptions = object;

Defined in: https://github.com/ax-llm/ax/blob/7965c876f6a5b641e0cf166e8942e540cfde65e1/src/ax/ai/types.ts#L848

Options for explicit context caching (e.g., Gemini/Vertex context caching). Allows caching large prompt prefixes for cost savings and lower latency.

When this option is present, caching is enabled. The system will:

Automatically cache the system prompt and any content marked with cache: true
Reuse existing caches when content hash matches
Create new caches when content changes
Auto-refresh TTL when cache is near expiration
Recreate or fall back uncached when an automatic refresh fails
Retry a provider-rejected automatically managed cache once without it

Properties

cacheBreakpoint?

TypeScript

optional cacheBreakpoint: "system" | "after-functions" | "after-examples";

Defined in: https://github.com/ax-llm/ax/blob/7965c876f6a5b641e0cf166e8942e540cfde65e1/src/ax/ai/types.ts#L892

Controls where the cache breakpoint is set in the prompt prefix. Prefix order: System → Functions → Examples → User Input

‘after-examples’ (default): Cache includes system + functions + examples
‘after-functions’: Cache includes system + functions only (use when examples are dynamic)
‘system’: Cache includes only system prompt (use when functions are dynamic)

minTokens?

TypeScript

optional minTokens: number;

Defined in: https://github.com/ax-llm/ax/blob/7965c876f6a5b641e0cf166e8942e540cfde65e1/src/ax/ai/types.ts#L868

Minimum token threshold for creating explicit caches. Content below this threshold won’t create explicit caches (implicit caching still applies). Default: 2048 (Gemini minimum requirement)

name?

TypeScript

optional name: string;

Defined in: https://github.com/ax-llm/ax/blob/7965c876f6a5b641e0cf166e8942e540cfde65e1/src/ax/ai/types.ts#L855

Explicit cache resource name/ID. If provided, this cache will be used directly (bypasses auto-creation). Explicit names are not automatically invalidated or retried without cache. If omitted, a cache will be created/looked up automatically.

refreshWindowSeconds?

TypeScript

optional refreshWindowSeconds: number;

Defined in: https://github.com/ax-llm/ax/blob/7965c876f6a5b641e0cf166e8942e540cfde65e1/src/ax/ai/types.ts#L874

Window in seconds before expiration to trigger automatic TTL refresh. Default: 300 (5 minutes)

registry?

TypeScript

optional registry: AxContextCacheRegistry;

Defined in: https://github.com/ax-llm/ax/blob/7965c876f6a5b641e0cf166e8942e540cfde65e1/src/ax/ai/types.ts#L882

External registry for persisting cache metadata. If provided, cache lookups and storage will use this registry instead of in-memory storage. Useful for serverless/short-lived processes. Namespace registry operations by tenant/account when caches must not be shared.

ttlSeconds?

TypeScript

optional ttlSeconds: number;

Defined in: https://github.com/ax-llm/ax/blob/7965c876f6a5b641e0cf166e8942e540cfde65e1/src/ax/ai/types.ts#L861

TTL (Time To Live) in seconds for the cache. Default: 3600 (1 hour). Maximum varies by provider.