# `Mojentic.Agents.BaseLLMAgentWithMemory`
[🔗](https://github.com/svetzal/mojentic-ex/blob/v1.5.0/lib/mojentic/agents/base_llm_agent_with_memory.ex#L1)

An LLM agent that uses SharedWorkingMemory to remember information.

This agent extends BaseLLMAgent with memory capabilities, allowing it to:
- Access shared working memory in its system context
- Learn new information from conversations
- Merge learned information back into shared memory

The agent automatically includes memory context in its prompts and extracts
memory updates from LLM responses using structured output.

## Usage

    alias Mojentic.Context.SharedWorkingMemory
    alias Mojentic.Agents.BaseLLMAgentWithMemory
    alias Mojentic.LLM.Broker

    # Create shared memory
    memory = SharedWorkingMemory.new(%{
      "User" => %{"name" => "Alice"}
    })

    # Create broker
    broker = Broker.new("qwen2.5:7b", Ollama)

    # Create agent with memory
    agent = BaseLLMAgentWithMemory.new(
      broker: broker,
      memory: memory,
      behaviour: "You are a helpful assistant.",
      instructions: "Answer questions and remember new facts.",
      response_model: %{
        "type" => "object",
        "required" => ["text"],
        "properties" => %{
          "text" => %{"type" => "string", "description" => "Your response"}
        }
      }
    )

    # Generate response - memory is automatically included
    {:ok, response, updated_memory} =
      BaseLLMAgentWithMemory.generate_response_with_memory(agent, "What's my name?")

## Examples

    # Create agent that remembers user preferences
    memory = SharedWorkingMemory.new(%{})
    broker = Broker.new("qwen2.5:7b", Ollama)

    agent = BaseLLMAgentWithMemory.new(
      broker: broker,
      memory: memory,
      behaviour: "You are a personal assistant.",
      instructions: "Help the user and remember their preferences.",
      response_model: %{
        "type" => "object",
        "required" => ["response"],
        "properties" => %{
          "response" => %{"type" => "string"}
        }
      }
    )

    {:ok, response, memory} =
      BaseLLMAgentWithMemory.generate_response_with_memory(
        agent,
        "I prefer dark mode and vim keybindings"
      )

    # Memory now contains user preferences

# `t`

```elixir
@type t() :: %Mojentic.Agents.BaseLLMAgentWithMemory{
  behaviour: String.t(),
  broker: Mojentic.LLM.Broker.t(),
  instructions: String.t(),
  memory: Mojentic.Context.SharedWorkingMemory.t(),
  response_model: map(),
  tools: [module()] | nil
}
```

# `create_initial_messages`

Creates initial messages with behaviour, memory, and instructions.

The messages include:
1. System message with agent behaviour
2. Memory context (what the agent remembers)
3. User message with instructions

## Parameters

- `agent` - The BaseLLMAgentWithMemory instance

## Returns

List of Message structs.

## Examples

    messages = BaseLLMAgentWithMemory.create_initial_messages(agent)
    #=> [
    #     %Message{role: :system, content: "You are..."},
    #     %Message{role: :user, content: "This is what you remember:..."},
    #     %Message{role: :user, content: "Answer questions..."}
    #   ]

# `generate_response_with_memory`

Generates a response with memory context and updates.

This function:
1. Creates initial messages with current memory
2. Adds the user's content
3. Requests structured output with memory field
4. Merges memory updates back into SharedWorkingMemory
5. Returns the response and updated memory

## Parameters

- `agent` - The BaseLLMAgentWithMemory instance
- `content` - The user's input string

## Returns

- `{:ok, response_data, updated_memory}` on success
- `{:error, reason}` on failure

## Examples

    {:ok, response, memory} =
      BaseLLMAgentWithMemory.generate_response_with_memory(
        agent,
        "My favorite color is blue"
      )

    # response contains the structured response (without memory field)
    # memory is updated SharedWorkingMemory with new information

# `new`

Creates a new BaseLLMAgentWithMemory.

## Parameters

- `opts`: Keyword list with:
  - `:broker` - LLM broker instance (required)
  - `:memory` - SharedWorkingMemory instance (required)
  - `:behaviour` - System message defining agent personality (required)
  - `:instructions` - Instructions for processing events (required)
  - `:response_model` - JSON schema for structured output (required)
  - `:tools` - List of tool modules (optional)

## Examples

    agent = BaseLLMAgentWithMemory.new(
      broker: broker,
      memory: memory,
      behaviour: "You are a helpful assistant.",
      instructions: "Answer questions and learn new facts.",
      response_model: %{
        "type" => "object",
        "required" => ["answer"],
        "properties" => %{
          "answer" => %{"type" => "string"}
        }
      }
    )

# `update_memory`

Updates an agent's memory reference.

Returns a new agent struct with the updated memory.

## Parameters

- `agent` - The BaseLLMAgentWithMemory instance
- `memory` - The new SharedWorkingMemory instance

## Examples

    agent = BaseLLMAgentWithMemory.update_memory(agent, new_memory)

---

*Consult [api-reference.md](api-reference.md) for complete listing*