AxAgent Memory And Skills Rules (@ax-llm/ax)

AxAgent Memory And Skills Rules (@ax-llm/ax)

Use this skill when an agent needs a persistent context map, task-relevant memory retrieval, or skill guides loaded into the executor prompt on demand. For ordinary agent setup use ax-agent. For RLM runtime policy use ax-agent-rlm. For callbacks and telemetry use ax-agent-observability.

Use These Defaults

• Use a static skillsCatalog / memoriesCatalog when the skill guides or memories fit in a plain array — Ax then backs discover({ skills }) / recall(...) with a built-in deterministic local search and no host search code is needed.
• Use onSkillsSearch / onMemoriesSearch when retrieval needs a real backend (vector DB, BM25 service, KV). A host callback always takes precedence over the catalog's built-in search.
• Use contextMap when repeated runs inspect the same long external context and should accumulate a small orientation cache automatically.
• recall(...) is available to distiller and executor stages when onMemoriesSearch or a non-empty memoriesCatalog is set.
• discover({ skills }) is available to the executor when onSkillsSearch or a non-empty skillsCatalog is set.
• With skillsCatalog, the executor prompt also gains a static ### Available Skills index (id + name + description), so skill discovery is targeted instead of blind.
• Both recall(...) and discover({ skills }) return void. The loaded content appears on the next turn.
• Use onLoadedMemories / onLoadedSkills to observe what got loaded.
• Use onUsedMemories / onUsedSkills to track what the actor says it actually relied on.
• Child agents do not inherit memory or skills search callbacks; wire them explicitly on every agent that needs the capability.

Context Map

Use contextMap when repeated runs ask different questions over the same long context, document set, or repository. The map is prompt-resident orientation knowledge: structure, concepts, constants, parsing schema, reusable aggregate results, and concrete error patterns. It is not a task-specific answer cache.

Runnable example: src/examples/rlm-context-map-live.ts demonstrates a provider-backed context-map update, onUpdate snapshot persistence, finite evolve, and frozen map reuse.

When contextMap is configured:

• Ax injects the current map into the distiller prompt.
• Ax updates the map once after each successful completed forward(...).
• By default the map evolves forever. For a finite warmup, create the map with { infiniteEvolve: false, evolveSteps: N }; after N successful updates it is still injected but no longer updated.
• Failed runs, aborts, and clarification requests do not update the map.
• Use onUpdate to persist result.map.snapshot() outside the agent.

import { agent, AxAgentContextMap } from '@ax-llm/ax';

const map = new AxAgentContextMap(savedSnapshot, {
  maxChars: 4000,
  infiniteEvolve: false,
  evolveSteps: 10,
});