Ragex.Agent.Memory (Ragex v0.11.0)

View Source

ETS-based conversation memory for agent sessions.

Manages multi-turn conversations with:

  • Session lifecycle management
  • Message history with role tracking
  • Context window management (truncation)
  • Tool result storage
  • Automatic session expiration

Usage

# Create a new session
{:ok, session} = Memory.new_session(%{project_path: "/path/to/project"})

# Add messages
:ok = Memory.add_message(session.id, :user, "Analyze this project")
:ok = Memory.add_message(session.id, :assistant, "I'll analyze...")

# Add tool result
:ok = Memory.add_tool_result(session.id, "call_123", %{status: "success"})

# Get conversation context for LLM
{:ok, messages} = Memory.get_context(session.id, max_tokens: 4000)

# End session
:ok = Memory.clear_session(session.id)

Summary

Functions

add_message(session_id, role, content, opts \\ [])

Add a message to a session.

add_tool_result(session_id, tool_call_id, result)

Add a tool result to the session.

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

clear_session(session_id)

Clear/delete a session.

get_context(session_id, opts \\ [])

Get conversation context suitable for LLM consumption.

get_messages(session_id, opts \\ [])

Get all messages from a session.

get_session(session_id)

Get a session by ID.

list_sessions(opts \\ [])

List all active sessions.

new_session(metadata \\ %{})

Create a new conversation session.

session_exists?(session_id)

Check if a session exists and is active.

start_link(opts \\ [])
stats()

Get session statistics.

update_metadata(session_id, metadata)

Update session metadata.

Functions

add_message(session_id, role, content, opts \\ [])

@spec add_message(String.t(), atom(), String.t(), keyword()) ::
  :ok | {:error, :not_found}

Add a message to a session.

Parameters

  • session_id - Session ID
  • role - Message role: :system, :user, :assistant, or :tool
  • content - Message content
  • opts - Optional:
    • :name - Function name for tool messages
    • :tool_call_id - Tool call ID for tool response messages
    • :tool_calls - Tool calls made by assistant

Returns

  • :ok - Message added
  • {:error, :not_found} - Session not found

add_tool_result(session_id, tool_call_id, result)

@spec add_tool_result(String.t(), String.t(), any()) :: :ok | {:error, :not_found}

Add a tool result to the session.

Tool results are stored separately and can be referenced by tool_call_id.

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

clear_session(session_id)

@spec clear_session(String.t()) :: :ok

Clear/delete a session.

get_context(session_id, opts \\ [])

@spec get_context(
  String.t(),
  keyword()
) :: {:ok, [map()]} | {:error, :not_found}

Get conversation context suitable for LLM consumption.

Applies truncation to fit within context window limits.

Options

  • :max_chars - Maximum total characters (default: 32,000)
  • :include_system - Include system messages (default: true)
  • :format - Output format: :openai (default) or :anthropic

get_messages(session_id, opts \\ [])

@spec get_messages(
  String.t(),
  keyword()
) :: {:ok, [map()]} | {:error, :not_found}

Get all messages from a session.

Options

  • :limit - Maximum number of messages to return (most recent)

get_session(session_id)

@spec get_session(String.t()) ::
  {:ok, Ragex.Agent.Memory.Session.t()} | {:error, :not_found}

Get a session by ID.

Returns

  • {:ok, session} - Session found
  • {:error, :not_found} - Session doesn't exist or expired

list_sessions(opts \\ [])

@spec list_sessions(keyword()) :: [Ragex.Agent.Memory.Session.t()]

List all active sessions.

Options

  • :limit - Maximum number of sessions to return

new_session(metadata \\ %{})

@spec new_session(map()) :: {:ok, Ragex.Agent.Memory.Session.t()}

Create a new conversation session.

Parameters

  • metadata - Optional metadata map (e.g., project_path, issues)

Returns

  • {:ok, session} - New session struct

session_exists?(session_id)

@spec session_exists?(String.t()) :: boolean()

Check if a session exists and is active.

start_link(opts \\ [])

stats()

@spec stats() :: map()

Get session statistics.

update_metadata(session_id, metadata)

@spec update_metadata(String.t(), map()) :: :ok | {:error, :not_found}

Update session metadata.