LlmCore.Memory.Backend.HindsightREST (llm_core v0.6.0)

Copy Markdown View Source

Hindsight 0.4+ REST backend 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.toml (select this backend and set its options):

[memory]
backend = "hindsight_rest"

[memory.hindsight_rest]
enabled = true
url = "http://localhost:8888"
default_bank_id = "platform"
timeout_recall_ms = 4000
timeout_reflect_ms = 5000

[memory.hindsight] is accepted as a legacy alias for [memory.hindsight_rest]. This is the default backend, so it is active even when [memory].backend is unset.

Usage

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

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

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

# Store content (sync, for critical data)
{:ok, _} = LlmCore.Memory.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, 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, opts \\ [])

@spec reflect(
  String.t(),
  keyword()
) :: {:ok, String.t()} | {: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.