# `Agentic.Memory.MemoryManager`

Retrieves relevant context from the Knowledge store before LLM calls.

Sits between the agent session and LLM, querying knowledge entries with the
user's actual prompt to get relevant episodic context. Falls back gracefully
when knowledge store is unavailable.

Results are cached briefly to avoid redundant queries for the same prompt.

## Knowledge callbacks

Instead of a hardcoded data access layer, this module accepts optional knowledge
callbacks via the `:knowledge` option:

- `:search` — `(query, opts) -> {:ok, entries} | {:error, term}`
- `:get_edges` — `(id, direction) -> {:ok, edges} | {:error, term}`

If no knowledge callbacks are provided, only ContextKeeper context is used.

# `format_context`

```elixir
@spec format_context(map() | nil) :: String.t() | nil
```

Format knowledge entries into a context string suitable for system prompt injection.

# `optimize_context`

```elixir
@spec optimize_context(String.t(), String.t() | nil, integer(), function() | nil) ::
  String.t() | nil
```

Optimize context by summarizing it if it exceeds the budget.

Uses a fast LLM call to condense the context while preserving the most
relevant information for the user's prompt. Only triggers when context
is significantly over budget (2x+).

Accepts an optional `llm_chat` function as the 4th argument. If nil, just truncates.

Returns the original context if it fits, or a summarized version.

# `retrieve_context`

```elixir
@spec retrieve_context(String.t(), String.t(), keyword()) :: {:ok, String.t() | nil}
```

Retrieve relevant context from the Knowledge store for a user prompt.

Queries knowledge entries scoped to the workspace and optionally the user,
merging results and formatting as a context string.

Returns `{:ok, context_string}` or `{:ok, nil}` if nothing relevant found.
Never returns an error — failures are logged and return nil.

## Options

- `:user_id` — user ID for cross-workspace queries
- `:top_k` — max results (default 10)
- `:workspace_id` — workspace ID for ContextKeeper lookup
- `:last_retrieval_at` — timestamp for incremental retrieval
- `:cached_context` — previously cached context for incremental merge
- `:knowledge` — map with `:search` and `:get_edges` callback functions

---

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