# `LlmCore.Memory.Hindsight`
[🔗](https://github.com/fosferon/llm_core/blob/v0.3.0/lib/llm_core/memory/hindsight.ex#L1)

Hindsight 0.4+ integration for semantic memory capabilities.

Uses the Hindsight REST API (not MCP). Server runs at localhost:8888,
REST endpoints at `/v1/default/banks/{bank_id}/...`.

Provides:
- Semantic search (recall) with intelligent caching
- Insight queries (reflect) with longer TTL caching
- Content retention with write-behind buffering
- Auto-discovery, retry logic, and circuit breaker

## Configuration

Configure in `~/.llm_core/config.yml`:

```yaml
memory:
  hindsight:
    url: http://localhost:8888
    enabled: true
    default_bank_id: platform
    cache_ttl_ms: 300000
```

## Usage

    # Semantic search
    {:ok, results} = Hindsight.recall("authentication patterns", bank_id: "my-bank")

    # Insights
    {:ok, insight} = Hindsight.reflect("What patterns work best?", bank_id: "my-bank")

    # Store content (async)
    :ok = Hindsight.retain("New pattern discovered", %{}, bank_id: "my-bank")

    # Store content (sync, for critical data)
    {:ok, _} = Hindsight.retain_sync("Critical execution", %{}, bank_id: "my-bank")

# `available?`

```elixir
@spec available?() :: boolean()
```

Checks if Hindsight API is available and enabled.

# `bank_stats`

```elixir
@spec bank_stats(
  String.t(),
  keyword()
) :: {:ok, map()} | {:error, term()}
```

Returns stats for a specific bank.

# `create_bank`

```elixir
@spec create_bank(
  String.t(),
  keyword()
) :: {:ok, map()} | {:error, term()}
```

Creates or updates a memory bank.

# `delete_bank`

```elixir
@spec delete_bank(
  String.t(),
  keyword()
) :: :ok | {:error, term()}
```

Deletes a memory bank and all its contents.

# `health_check`

```elixir
@spec health_check() :: {:ok, map()} | {:error, term()}
```

Performs a health check on the Hindsight API.

# `list_banks`

```elixir
@spec list_banks(keyword()) :: {:ok, [map()]} | {:error, term()}
```

Lists available Hindsight memory banks.

# `recall`

```elixir
@spec recall(
  String.t(),
  keyword()
) :: {:ok, [map()]} | {:error, term()}
```

Semantic search for similar content with caching.

## Options
- `:limit` - max results (default 10)
- `:bank_id` / `:target_bank` - Memory bank to query (defaults to config)
- `:budget` - `"low"` | `"mid"` | `"high"` (impacts recall cost)
- `:max_tokens` - maximum tokens for result summarization
- `:bypass_cache` - force fresh query

# `reflect`

```elixir
@spec reflect(
  String.t(),
  keyword()
) :: {:ok, String.t()} | {:error, term()}
@spec reflect(
  atom(),
  keyword()
) :: {:ok, map()} | {:error, term()}
```

Natural language reflection/synthesis over a bank's memories.

## Options
  * `:bank_id` / `:target_bank` - Memory bank to reflect on
  * `:budget` - `"low"` | `"mid"` | `"high"`
  * `:context` - Additional context for the reflection

# `retain`

```elixir
@spec retain(String.t(), map(), keyword()) :: :ok
```

Stores content in Hindsight for semantic indexing (async, buffered).

## Options
  * `:bank_id` / `:target_bank` - Memory bank to write to
  * `:context` - Short descriptor for the memory

# `retain_sync`

```elixir
@spec retain_sync(String.t(), map(), keyword()) :: {:ok, map()} | {:error, term()}
```

Stores content synchronously, bypassing the write buffer.

Use for critical data that must be persisted immediately.

# `url`

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

Returns the effective Hindsight base URL.

---

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