@spec bulk_set_enabled([String.t()], boolean()) :: {:ok, map()} | {:error, term()}

Bulk enable/disable over an explicit URI list.

@spec bulk_set_group([String.t()], String.t()) :: {:ok, map()} | {:error, term()}

Bulk group assignment over an explicit URI list.

@spec cache_stats() :: map()

The size of the store's disposable read caches.

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

Removes the subtree at uri.

@spec error_message(term()) :: String.t()

Why a store operation failed, in words and from the shared taxonomy.

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

Removes a memory and its provenance.

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

A document's full content.

@spec get_layers(String.t()) :: %{l0: map(), l1: map(), l2: map()}

A document's LLM-facing layers, keyed the way the console labels them.

Returns %{l0: layer, l1: layer, l2: layer} where each layer is %{text: String.t(), source: :stored | :fallback | :unavailable, chars: non_neg_integer()}.

The store answers these layers under their own names (abstract, overview, content) because that is its vocabulary; the console's L0/L1/L2 labels are presentation, and translation at the transport edge is what that edge is for. One call to the facade, so a layer's meaning is the same wherever it is shown.

Reads several documents' layers in one store operation.

@spec get_session(String.t()) :: {:ok, [map()]} | {:error, term()}

A session's messages.

@spec health_check() :: %{
  status: String.t(),
  checks: %{db: boolean(), models: boolean()}
}

Whether the store is usable, per check.

A 200 or a 503 rather than an error: a store serving without a model is serving, and a monitor should be able to see which part is down.

@spec import_skills(String.t(), AgentDb.Skills.Source.source()) ::
  {:ok, map()} | {:error, term()}

Imports Agent Skills into a user's skills subtree. See AgentDb.import_skills/2.

@spec index_coverage() :: map()

How much of the store's content each index covers.

@spec job_stats() :: map()

How much background work is outstanding, by status.

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

Recursive paged document URIs under scope for operations listings.

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

A page of the document names under prefix.

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

Paged installed-skill inventory across users.

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

Memory statistics: counts per type and status, pending, never surfaced.

@spec model_status() :: map()

How the store's models are doing, including a load in progress.

@spec operation_stats() :: map()

Operation, job, and model counts by outcome.

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

Memories waiting for review.

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

Promotes a waiting memory candidate.

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

Writes a document, creating it or replacing it.

@spec queue_detail(pos_integer()) :: map()

How far behind the queue is, and which jobs are failing.

@spec recent_errors(pos_integer()) :: [map()]

Recent operational failures, newest first.

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

Rejects a waiting memory candidate.

@spec role(String.t()) :: :user | :assistant | :system | :unknown

Maps a wire role to the atom the store writes, or :unknown.

@spec runtime_snapshot() :: map()

A bounded, read-only view of the BEAM runtime.

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

Searches the store. See AgentDb.search/2 for the options.

@spec set_enabled(String.t(), boolean()) :: :ok | {:error, term()}

Enables or disables the subtree at uri.

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

Assigns the operator group tag for the subtree at uri. Empty clears.

@spec skill_import_error(term()) :: String.t()

Why a skill import was refused, in words.

@spec storage_stats() :: map()

What the store holds and how much room it takes on disk.

@spec transport_error(Plug.Conn.t(), term()) :: Plug.Conn.t()

Renders a store error on a controller connection.