LlmCore.Memory.Hindsight (llm_core v0.3.0)

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:

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")

Summary

Functions

available?()

Checks if Hindsight API is available and enabled.

bank_stats(bank_id, opts \\ [])

Returns stats for a specific bank.

create_bank(bank_id, opts \\ [])

Creates or updates a memory bank.

delete_bank(bank_id, opts \\ [])

Deletes a memory bank and all its contents.

health_check()

Performs a health check on the Hindsight API.

list_banks(opts \\ [])

Lists available Hindsight memory banks.

recall(query, opts \\ [])

Semantic search for similar content with caching.

reflect(question_or_type, opts \\ [])

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

retain(content, metadata \\ %{}, opts \\ [])

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

retain_sync(content, metadata \\ %{}, opts \\ [])

Stores content synchronously, bypassing the write buffer.

url()

Returns the effective Hindsight base URL.

Functions

available?()

@spec available?() :: boolean()

Checks if Hindsight API is available and enabled.

bank_stats(bank_id, opts \\ [])

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

Returns stats for a specific bank.

create_bank(bank_id, opts \\ [])

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

Creates or updates a memory bank.

delete_bank(bank_id, opts \\ [])

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

Deletes a memory bank and all its contents.

health_check()

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

Performs a health check on the Hindsight API.

list_banks(opts \\ [])

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

Lists available Hindsight memory banks.

recall(query, opts \\ [])

@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(question_or_type, opts \\ [])

@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(content, metadata \\ %{}, opts \\ [])

@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(content, metadata \\ %{}, opts \\ [])

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

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

Returns the effective Hindsight base URL.