API Reference

Complete reference for AgentDb's four public interfaces: the Elixir AgentDb module, the mix agent_db.* CLI, MCP tools over Streamable HTTP, and WebSocket v1.* events. Each section is written against its source of truth so it can be checked, not taken on faith:

The generated documentation is the API reference for the Elixir module — this guide maps entry points to it instead of copying signatures, which would go stale the moment the code moves. Generate it locally with mix docs.

1. Elixir API (AgentDb module)

Start the application once, then every call below is available: {:ok, _} = Application.ensure_all_started(:agent_db). Links go to the versioned generated docs; local mix docs output matches them.

Tree operations

Search

fields: selects which per-result fields are returned: :uri (always required — a result without its URI cannot be fetched), :content, :abstract, :overview, :score. Omitted returns all of them, so an existing caller sees the same result set as before. An unknown name, an empty list, or a selection without :uri is {:error, {:invalid_fields, value}} rather than a substituted answer, and the projection reaches the statement that reads the rows — a caller selecting :abstract does not pay to read document content it cannot receive.

# URIs and abstracts only, for deciding which documents to read
{:ok, results} = AgentDb.search("vector index", mode: :hybrid, fields: [:uri, :abstract, :score])

Memory

Sessions

Agent Skills

Data portability

Vector index

Status, observability, and subscriptions

Full signatures, option types with defaults, and every success/error return shape live in the generated docs (hexdocs link per row, or mix docs).

2. CLI (mix agent_db.*)

Every task takes --json (machine-readable stdout) and --no-compile (skips the app start). Without --json, output is human text. Failures write to stderr and exit non-zero; exit code 0 means success.

3. MCP tools (Streamable HTTP at POST /mcp)

The tool set is AgentDbWeb.Mcp.tools/0 — 19 tools. Requests are JSON-RPC 2.0 (tools/call with {"name": ..., "arguments": {...}}).

Success response — a JSON-RPC result whose content is the data as JSON:

{"jsonrpc":"2.0","id":1,"result":{"content":[{"type":"text","text":"{\"content\":\"...\"}"}]}}

Error response — a JSON-RPC error; the bounded code rides in data.reason. A model that is still loading is signalled distinctly as -32001; every other failure is -32000 with the classified code:

{"jsonrpc":"2.0","id":1,"error":{"code":-32000,"message":"...","data":{"reason":"model_loading"}}}

Confirm the live tool list with tools/list (what tools/install.sh --check asserts against context_read). With Bearer auth enabled, send the token as Authorization: Bearer <token>.

3.1 Local (sidecar) invocation

When AgentDb is embedded as a sidecar in a host Elixir application, the same tool inventory is reachable in-process through AgentDb.Mcp, without JSON-RPC or HTTP:

# Discover the inventory
tools = AgentDb.Mcp.tools()

# Invoke a tool directly
{:ok, %{"uri" => uri, "content" => content}} =
  AgentDb.Mcp.call_tool("context_read", %{"uri" => uri})

# Or speak JSON-RPC locally
AgentDb.Mcp.handle_request(%{"jsonrpc" => "2.0", "id" => 1, "method" => "tools/list"}, [])

AgentDb.Mcp.call_tool/3 returns {:ok, term()} or {:error, reason}. A tool deferred only because a model is still loading returns {:error, :model_loading}. AgentDbWeb.Mcp remains available as a compatibility shim delegating to AgentDb.Mcp.

4. WebSocket events (Phoenix Channel /api)

Events are {"event": "v1.*", "payload": {...}}. The reply is {:ok, <payload>} on success and {:error, %{reason: <message>, code: <classified code>}} on failure. :ok-only operations reply {:ok, %{status: "ok"}}.

Pushed events (server-to-client only): v1.append_message and v1.commit_session are responses to their matching operations, and v1.context_changed ({uri, kind, version}) is the subscription push.

Subscriptions are per-connection and do not survive a reconnect — re-subscribe after every reconnect.

Trace correlation: a traceparent is accepted as an HTTP header, at the payload's top level, or inside opts (W3C format).

5. Error code catalog

One bounded taxonomy classifies every failure on every transport. The source is AgentDb.Observability (classify_reason/1, the caller-error tags, and the http_status/1 mapping); each code also appears as the log reason and in transport error payloads.

Any tagged reason ({tag, detail}) classifies to its tag, so the set grows only by reusing or extending these codes — never free-form text.

Where the code appears per transport: Elixir — classify with Observability.error_code(reason); CLI — stderr message; MCP — error.data.reason (with -32001 for model_loading); WebSocket — error.code in the reply payload.

For the operational side (alerting, log interpretation, symptom-driven diagnosis) see MONITORING.md and TROUBLESHOOTING.md.