# `Mojentic.Context.SharedWorkingMemory`
[🔗](https://github.com/svetzal/mojentic-ex/blob/v1.5.0/lib/mojentic/context/shared_working_memory.ex#L1)

A shared working memory context for agents.

SharedWorkingMemory provides a simple key-value store that multiple agents
can read from and write to, enabling knowledge sharing and persistence
across agent interactions.

## Features

- **Shared Context** - Multiple agents can access the same memory
- **Merge Updates** - New information is merged into existing memory
- **Simple API** - Get and merge operations for easy use

## Immutability and Concurrency Safety

This struct is immutable — every mutating operation (`merge_to_working_memory/2`)
returns a **new** struct rather than modifying the original. This immutability is
what makes `Mojentic.AsyncDispatcher`'s concurrent (per-subscriber `Task`) dispatch
safe: each agent receives its own snapshot of memory and cannot race with other agents
over a shared mutable reference.

**Important:** If a future change introduces genuinely shared mutable state (an ETS
table, an `Agent` process, or a stateful GenServer that multiple agents call), revisit
the dispatcher's concurrency model — concurrent dispatch may no longer be safe.

## Usage

    # Initialize with user data
    memory = SharedWorkingMemory.new(%{
      "User" => %{
        "name" => "Alice",
        "age" => 30
      }
    })

    # Retrieve current memory
    current = SharedWorkingMemory.get_working_memory(memory)

    # Merge new information
    memory = SharedWorkingMemory.merge_to_working_memory(memory, %{
      "User" => %{
        "pets" => ["dog", "cat"]
      }
    })

## Examples

    # Create memory with initial data
    memory = SharedWorkingMemory.new(%{
      "preferences" => %{"theme" => "dark"}
    })

    # Add new information
    memory = SharedWorkingMemory.merge_to_working_memory(memory, %{
      "preferences" => %{"language" => "elixir"},
      "history" => []
    })

    # Retrieve all memory
    all_data = SharedWorkingMemory.get_working_memory(memory)
    #=> %{
    #     "preferences" => %{"theme" => "dark", "language" => "elixir"},
    #     "history" => []
    #   }

# `t`

```elixir
@type t() :: %Mojentic.Context.SharedWorkingMemory{working_memory: map()}
```

# `get_working_memory`

Retrieves the current working memory.

## Parameters

- `memory` - The SharedWorkingMemory instance

## Returns

The current working memory map.

## Examples

    iex> memory = SharedWorkingMemory.new(%{"key" => "value"})
    iex> SharedWorkingMemory.get_working_memory(memory)
    %{"key" => "value"}

# `merge_to_working_memory`

Merges new data into the working memory.

Performs a deep merge where nested maps are merged recursively.
Non-map values at the same key are overwritten by the new value.

## Parameters

- `memory` - The SharedWorkingMemory instance
- `new_data` - Map of new data to merge

## Returns

Updated SharedWorkingMemory instance.

## Examples

    iex> memory = SharedWorkingMemory.new(%{"a" => %{"b" => 1}})
    iex> memory = SharedWorkingMemory.merge_to_working_memory(memory, %{"a" => %{"c" => 2}})
    iex> SharedWorkingMemory.get_working_memory(memory)
    %{"a" => %{"b" => 1, "c" => 2}}

    iex> memory = SharedWorkingMemory.new(%{"count" => 1})
    iex> memory = SharedWorkingMemory.merge_to_working_memory(memory, %{"count" => 2})
    iex> SharedWorkingMemory.get_working_memory(memory)
    %{"count" => 2}

# `new`

Creates a new SharedWorkingMemory with optional initial memory.

## Parameters

- `initial_memory` - Map of initial working memory (default: %{})

## Examples

    iex> SharedWorkingMemory.new()
    %SharedWorkingMemory{working_memory: %{}}

    iex> SharedWorkingMemory.new(%{"user" => "Alice"})
    %SharedWorkingMemory{working_memory: %{"user" => "Alice"}}

---

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