# `Nous.Plugins.Memory`
[🔗](https://github.com/nyo16/nous/blob/v0.17.1/lib/nous/plugins/memory.ex#L1)

Plugin for persistent agent memory with hybrid search.

Provides tools for agents to remember, recall, and forget information
across conversations. Supports text-based keyword search and optional
vector-based semantic search when an embedding provider is configured.

## Usage

`:deps` is passed to `Nous.run/3`, NOT `Nous.new/2` (the agent struct has no
`:deps` field, so config given to `new/2` is silently ignored).

    # Minimal — ETS store, keyword-only search
    agent = Agent.new("openai:gpt-4", plugins: [Nous.Plugins.Memory])
    deps = %{memory_config: %{store: Nous.Memory.Store.ETS}}
    {:ok, result} = Nous.run(agent, "Remember my name is Sam", deps: deps)

    # With embeddings for semantic search
    deps = %{
      memory_config: %{
        store: Nous.Memory.Store.ETS,
        embedding: Nous.Memory.Embedding.OpenAI,
        embedding_opts: %{api_key: "sk-..."}
      }
    }
    {:ok, result} = Nous.run(agent, "...", deps: deps)

## Configuration (via `deps[:memory_config]`)

**Required:**
  * `:store` - Store backend module (e.g. `Nous.Memory.Store.ETS`)

**Optional — store:**
  * `:store_opts` - Options passed to `store.init/1`

**Optional — embedding:**
  * `:embedding` - Embedding provider module (e.g. `Nous.Memory.Embedding.OpenAI`)
  * `:embedding_opts` - Options passed to embedding provider

**Optional — scoping:**
  * `:agent_id` - Tag memories with this agent ID
  * `:session_id` - Tag memories with this session ID
  * `:user_id` - Tag memories with this user ID
  * `:namespace` - Arbitrary namespace grouping
  * `:default_search_scope` - `:agent` (default), `:user`, `:session`, or `:global`

**Optional — auto-injection:**
  * `:auto_inject` - Auto-inject relevant memories before each request (default: true)
  * `:inject_strategy` - `:first_only` (default) or `:every_iteration`
  * `:inject_limit` - Max memories to inject (default: 5)
  * `:inject_min_score` - Minimum score for injection (default: 0.3)

**Optional — scoring:**
  * `:scoring_weights` - `[relevance: 0.5, importance: 0.3, recency: 0.2]`
  * `:decay_lambda` - Temporal decay rate (default: 0.001)

**Optional — auto-update (after_run reflection):**
  * `:auto_update_memory` - Automatically reflect on conversation and update memories after each run (default: `false`)
  * `:auto_update_every` - Run reflection every N runs (default: `1`)
  * `:reflection_model` - Model string for reflection LLM call (default: agent's own model). Use a cheaper model like `"openai:gpt-4o-mini"` to save costs.
  * `:reflection_max_tokens` - Max tokens for reflection response (default: `1000`)
  * `:reflection_max_messages` - Max recent messages to include in reflection context (default: `20`)
  * `:reflection_max_memories` - Max existing memories to include in reflection context (default: `50`)

## Auto-Update Memory

When `:auto_update_memory` is `true`, the plugin runs an `after_run/3` hook
after each agent run completes. It reflects on the conversation and outputs
a JSON array of memory operations (`remember`, `update`, `forget`) — similar
to Claude Code's "recalled/wrote memory" behavior.

    agent = Nous.new("openai:gpt-4o",
      plugins: [Nous.Plugins.Memory],
      deps: %{
        memory_config: %{
          store: Nous.Memory.Store.ETS,
          auto_update_memory: true,
          reflection_model: "openai:gpt-4o-mini"
        }
      }
    )

    {:ok, result} = Nous.run(agent, "My favorite color is blue")
    # Memory automatically stored after run completes

    {:ok, result2} = Nous.run(agent, "I changed my mind, it's green",
      context: result.context
    )
    # Memory automatically updated (not duplicated)

---

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