# `Gralkor.Client.HTTP`
[🔗](https://github.com/elimydlarz/gralkor/blob/main/lib/gralkor/client/http.ex#L1)

Real `Gralkor.Client` implementation over HTTP using `Req`.

Reads config from `Application.get_env(:gralkor_ex, :client_http)`:

  * `:url` — required. Base URL of the Gralkor server (e.g.
    `"http://127.0.0.1:4000"`).
  * `:plug` — optional `Req.Test` plug tuple for stubbing in tests.
    Unset in production so Req hits the network directly.

No auth: Gralkor is expected to run under the consumer app's
supervision tree, bound to loopback. The consumer owns the trust
boundary.

Per-endpoint `receive_timeout`s, calibrated to the workload:

  * `/health` (2 s) — cheap liveness check; tight so `Gralkor.Connection`
    doesn't flap when the server is under LLM load.
  * `/recall` (5 s) — fast graph search (`graphiti.search()` — RRF,
    edges only) plus one small LLM interpretation call. Typical ~1–2 s;
    5 s means something's actually wrong.
  * `/tools/memory_search` (10 s) — *slow* graph search
    (`graphiti.search_()` with `COMBINED_HYBRID_SEARCH_CROSS_ENCODER`
    — cross-encoder reranking + BFS, facts + entity summaries) plus
    LLM interpretation. The cross-encoder dominates; 5 s drops
    legitimate results and the LLM hallucinates "no memory found".
    10 s is the working ceiling.
  * `/capture` (5 s) — server returns 204 immediately after buffering.
  * `/session_end` (5 s) — server returns 204 immediately after
    scheduling the flush.
  * `/tools/memory_add` (60 s) — Graphiti entity/edge extraction is
    slow; only reached from a background `Task` in the consumer, so
    the agent never waits.
  * `/build-indices`, `/build-communities` (`:infinity`) — admin
    operations that scan the whole graph; can run for minutes to
    hours on a populated database. The operator invokes them
    explicitly, so blocking the caller is fine.

Returns `{:error, reason}` on non-2xx or transport failure; raises on
missing config or blank session_id. Callers let those surface.

---

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