Raxol.Agent.Memory behaviour (Raxol Agent v2.6.0)

Copy Markdown View Source

Cross-session memory for Raxol agents.

Memory is a pluggable behaviour. A provider persists Raxol.Agent.Memory.Record entries and answers recall queries. The default provider, Raxol.Agent.Memory.Store.Ets, is a self-contained ETS+DETS store with pure-Elixir ranking (no external dependencies).

Reads are automatic: Raxol.Agent.Memory.Manager prefetches relevant memories before each turn and injects them into the system prompt. Writes are explicit: an agent calls the memory_remember action.

Memory is opt-in. With no provider configured, every hook is a no-op.

Provider lifecycle

  • prefetch/2 - records relevant to a query (defaults to search/2)
  • search/2 - ranked recall for a query
  • store/2 - persist a record
  • forget/2 - delete a record by id
  • build_system_prompt/1 - format records into a system-prompt block

Only search/2, store/2, and forget/2 are mandatory; prefetch/2 and build_system_prompt/1 have sensible defaults from use Raxol.Agent.Memory.

opts carry :server (provider instance), :agent_id (partition), :limit (default 5), :query, :query_tags, and :tags.

Summary

Callbacks

build_system_prompt(opts)
build_user_context(opts)

An optional per-user context block injected into the LAST user message rather than the system prompt, so a per-turn refresh does not invalidate the cacheable system prefix. Returns nil to inject nothing (the default).

forget(id, opts)
prefetch(query, opts)
search(query, opts)
store(t, opts)

Functions

default_provider()

The provider configured for this node, or nil when memory is disabled.

format_block(records)

Format memory records into a system-prompt block, or nil if empty.

provider_context(provider, agent_id, opts \\ [])

Build the normalized {provider, opts} tuple for context[:memory], scoping records to agent_id. Returns nil when provider is nil.

stack_context(providers, agent_id, opts \\ [])

Build the {module, opts} tuple for a stacked set of providers under context[:memory], scoping records to agent_id. Each entry is a bare module or a {module, opts} pair. Returns nil for an empty list.

Callbacks

build_system_prompt(opts)

@callback build_system_prompt(opts :: keyword()) :: String.t() | nil

build_user_context(opts)

(optional) 
@callback build_user_context(opts :: keyword()) :: String.t() | nil

An optional per-user context block injected into the LAST user message rather than the system prompt, so a per-turn refresh does not invalidate the cacheable system prefix. Returns nil to inject nothing (the default).

forget(id, opts)

@callback forget(id :: String.t(), opts :: keyword()) :: :ok

prefetch(query, opts)

@callback prefetch(query :: String.t(), opts :: keyword()) :: [
  Raxol.Agent.Memory.Record.t()
]

search(query, opts)

@callback search(query :: String.t(), opts :: keyword()) :: [
  Raxol.Agent.Memory.Record.t()
]

store(t, opts)

@callback store(Raxol.Agent.Memory.Record.t(), opts :: keyword()) ::
  {:ok, Raxol.Agent.Memory.Record.t()} | {:error, term()}

Functions

default_provider()

@spec default_provider() :: module() | nil

The provider configured for this node, or nil when memory is disabled.

format_block(records)

@spec format_block([Raxol.Agent.Memory.Record.t()]) :: String.t() | nil

Format memory records into a system-prompt block, or nil if empty.

provider_context(provider, agent_id, opts \\ [])

@spec provider_context(module() | nil, String.t() | nil, keyword()) ::
  {module(), keyword()} | nil

Build the normalized {provider, opts} tuple for context[:memory], scoping records to agent_id. Returns nil when provider is nil.

stack_context(providers, agent_id, opts \\ [])

@spec stack_context([module() | {module(), keyword()}], String.t() | nil, keyword()) ::
  {module(), keyword()} | nil

Build the {module, opts} tuple for a stacked set of providers under context[:memory], scoping records to agent_id. Each entry is a bare module or a {module, opts} pair. Returns nil for an empty list.