LlmCore.Memory.Hindsight.Cache (llm_core v0.3.0)

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}

Summary

Types

cache_entry()

stats()

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

clear()

Clears all cached entries.

get(key)

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

get_with_stale(key)

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

invalidate(key)

Invalidates a specific cache entry.

invalidate_pattern(pattern)

Invalidates entries matching a key prefix/pattern.

put(key, value, opts \\ [])

Stores a value in the cache with TTL.

recall_key(query, opts)

Generates a cache key for recall operations.

reflect_key(question, opts \\ [])

Generates a cache key for reflect operations.

start_link(opts \\ [])

Starts the cache GenServer.

stats()

Returns cache statistics.

Types

cache_entry()

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

stats()

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

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

clear()

@spec clear() :: :ok

Clears all cached entries.

get(key)

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

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

get_with_stale(key)

@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(key)

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

Invalidates a specific cache entry.

invalidate_pattern(pattern)

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

Invalidates entries matching a key prefix/pattern.

put(key, value, opts \\ [])

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

Stores a value in the cache with TTL.

recall_key(query, opts)

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

Generates a cache key for recall operations.

reflect_key(question, opts \\ [])

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

Generates a cache key for reflect operations.

start_link(opts \\ [])

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

Starts the cache GenServer.

stats()

@spec stats() :: stats()

Returns cache statistics.