BeamAgent.Memory (beam_agent_ex v0.1.0)

Canonical long-term memory for BeamAgent.

Memories are durable cross-session facts and notes that can be scoped to sessions, threads, or runs, linked to artifacts and other typed references, and recalled later using lexical search. This is the Elixir facade over the Erlang :beam_agent_memory public module.

Summary

Types

memory_filter()

Exact-match filter accepted by list/1, search/2, and expire/1.

memory_input()

Input accepted by remember/2,3.

memory_record()

Canonical memory record.

scope()

Scope passed to remember/2,3 and recall/2.

source_ref()

Typed source reference stored on a memory.

Functions

clear()

Clear all memories.

ensure_tables()

Ensure the memory store exists.

expire()

Expire all currently expired, unpinned memories.

expire(filter)

Expire currently expired, unpinned memories matching a filter.

forget(memory_id)

Forget a memory by id.

get(memory_id)

Fetch a memory by id.

list()

List all visible memories.

list(filter)

List memories with exact-match filters and visibility controls.

pin(memory_id)

Pin a memory.

recall(scope, query)

Recall memories for a scope using lexical search.

remember(scope, memory_input)

Remember content with embedded or explicit kind on a scope.

remember(scope, kind, memory_input)

Remember content with an explicit kind on a scope.

search(query)

Search memories across all scopes.

search(query, filter)

Search memories with a lexical query plus exact-match filters.

unpin(memory_id)

Unpin a memory.

Types

memory_filter()

@type memory_filter() :: %{
  optional(:memory_id) => binary(),
  optional(:kind) => atom() | binary(),
  optional(:session_id) => binary(),
  optional(:thread_id) => binary(),
  optional(:run_id) => binary(),
  optional(:pinned) => boolean(),
  optional(:source_ref_type) => atom() | binary(),
  optional(:source_ref_id) => binary(),
  optional(:limit) => pos_integer(),
  optional(:since) => integer(),
  optional(:include_expired) => boolean(),
  optional(:min_salience) => non_neg_integer(),
  optional(:before) => integer()
}

Exact-match filter accepted by list/1, search/2, and expire/1.

memory_input()

@type memory_input() ::
  binary()
  | %{
      optional(:memory_id) => binary(),
      optional(:kind) => atom() | binary(),
      optional(:content) => term(),
      optional(:attributes) => map(),
      optional(:source_refs) => [source_ref()],
      optional(:ttl) => non_neg_integer() | :infinity,
      optional(:pinned) => boolean(),
      optional(:salience) => non_neg_integer(),
      optional(:session_id) => binary(),
      optional(:thread_id) => binary(),
      optional(:run_id) => binary()
    }

Input accepted by remember/2,3.

memory_record()

@type memory_record() :: %{
  :memory_id => binary(),
  :kind => atom() | binary(),
  :content => term(),
  :attributes => map(),
  :source_refs => [source_ref()],
  :scope => map(),
  :pinned => boolean(),
  :salience => non_neg_integer(),
  :ttl => non_neg_integer() | :infinity,
  :created_at => integer(),
  :updated_at => integer(),
  optional(:expires_at) => integer()
}

Canonical memory record.

scope()

@type scope() ::
  binary()
  | %{
      optional(:session_id) => binary(),
      optional(:thread_id) => binary(),
      optional(:run_id) => binary()
    }

Scope passed to remember/2,3 and recall/2.

Use either a binary session id or a map containing any of :session_id, :thread_id, and :run_id.

source_ref()

@type source_ref() :: %{
  :type => atom() | binary(),
  :id => binary(),
  optional(:metadata) => map()
}

Typed source reference stored on a memory.

Functions

clear()

@spec clear() :: :ok

Clear all memories.

ensure_tables()

@spec ensure_tables() :: :ok

Ensure the memory store exists.

expire()

@spec expire() :: {:ok, non_neg_integer()}

Expire all currently expired, unpinned memories.

expire(filter)

@spec expire(memory_filter()) ::
  {:ok, non_neg_integer()}
  | {:error,
     {:invalid_filter,
      :before
      | :include_expired
      | :kind
      | :limit
      | :memory_id
      | :min_salience
      | :pinned
      | :run_id
      | :session_id
      | :since
      | :source_ref_id
      | :source_ref_type
      | :thread_id}
     | {:invalid_scope,
        :memory_id | :run_id | :session_id | :source_ref_id | :thread_id}}

Expire currently expired, unpinned memories matching a filter.

forget(memory_id)

@spec forget(binary()) :: :ok | {:error, :not_found}

Forget a memory by id.

get(memory_id)

@spec get(binary()) :: {:ok, memory_record()} | {:error, :not_found}

Fetch a memory by id.

list()

@spec list() :: {:ok, [memory_record()]}

List all visible memories.

list(filter)

@spec list(memory_filter()) :: {:ok, [memory_record()]} | {:error, term()}

List memories with exact-match filters and visibility controls.

pin(memory_id)

@spec pin(binary()) :: :ok | {:error, :not_found}

Pin a memory.

recall(scope, query)

@spec recall(scope(), binary()) :: {:ok, [memory_record()]} | {:error, term()}

Recall memories for a scope using lexical search.

remember(scope, memory_input)

@spec remember(scope(), memory_input()) :: {:ok, memory_record()} | {:error, term()}

Remember content with embedded or explicit kind on a scope.

remember(scope, kind, memory_input)

@spec remember(scope(), atom() | binary(), memory_input()) ::
  {:ok, memory_record()} | {:error, term()}

Remember content with an explicit kind on a scope.

search(query)

@spec search(binary()) :: {:ok, [memory_record()]} | {:error, term()}

Search memories across all scopes.

search(query, filter)

@spec search(binary(), memory_filter()) :: {:ok, [memory_record()]} | {:error, term()}

Search memories with a lexical query plus exact-match filters.

unpin(memory_id)

@spec unpin(binary()) :: :ok | {:error, :not_found}

Unpin a memory.