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

Smart caching layer for Hindsight operations.

Features:
- TTL-based expiry
- LRU eviction when max entries exceeded
- Stale-while-revalidate for fast responses
- Background refresh before TTL expiry
- Manual invalidation

## Cache Keys

- Recall: `{:recall, query_hash, opts_hash}`
- Reflect: `{:reflect, question_hash}`

# `cache_entry`

```elixir
@type cache_entry() :: %{
  value: term(),
  inserted_at: integer(),
  ttl_ms: pos_integer(),
  last_access: integer()
}
```

# `stats`

```elixir
@type stats() :: %{
  hits: non_neg_integer(),
  misses: non_neg_integer(),
  size: non_neg_integer()
}
```

# `child_spec`

Returns a specification to start this module under a supervisor.

See `Supervisor`.

# `clear`

```elixir
@spec clear() :: :ok
```

Clears all cached entries.

# `get`

```elixir
@spec get(term()) :: {:hit, term()} | :miss
```

Gets a cached value by key, returning `{:hit, value}` or `:miss`.

# `get_with_stale`

```elixir
@spec get_with_stale(term()) :: {:hit, term()} | {:stale, term()} | :miss
```

Gets a cached value, allowing stale data within grace period.
Returns `{:hit, value}` or `{:stale, value}` or `:miss`.

# `invalidate`

```elixir
@spec invalidate(term()) :: :ok
```

Invalidates a specific cache entry.

# `invalidate_pattern`

```elixir
@spec invalidate_pattern(term()) :: :ok
```

Invalidates entries matching a key prefix/pattern.

# `put`

```elixir
@spec put(term(), term(), keyword()) :: :ok
```

Stores a value in the cache with TTL.

# `recall_key`

```elixir
@spec recall_key(
  String.t(),
  keyword()
) :: term()
```

Generates a cache key for recall operations.

# `reflect_key`

```elixir
@spec reflect_key(
  String.t() | atom(),
  keyword()
) :: term()
```

Generates a cache key for reflect operations.

# `start_link`

```elixir
@spec start_link(keyword()) :: GenServer.on_start()
```

Starts the cache GenServer.

# `stats`

```elixir
@spec stats() :: stats()
```

Returns cache statistics.

---

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