Self-hosted web API · built on HydraDB

One API call. The right context for every agent task.

ContextMesh is a web API that plans context from a graph. Send a task to /v1/plan and get back only the skills, tool schemas, MCP servers, and resolved entities that task needs.

  • Plain HTTP/JSON — works with any agent runtime
  • 2 graph round-trips per plan, ~4–40 ms reads
  • Self-host behind your gateway; interactive docs at /docs
2 graph round-trips per /v1/plan
46% fewer prompt tokens vs. loading all tools
4/5 correct with the API pack, vs. 0/5 baseline
0 errors at 128 concurrent sessions

Every agent step pays for tools it never uses.

Stuffing every schema into the prompt is slow, expensive, and brittle. ContextMesh gives your agent a small, exact context pack per task through a single API call.

16→5

Tool tax

The model re-reads schemas it will not call. /v1/plan returns only the tools that match the task.

N→2

Resolver tax

Mentions like “checkout” or “prod” are resolved to canonical entities in the same plan response—no extra lookup calls.

1 reboot

Memory tax

Usage and learned aliases are written back via /v1/session to a graph that survives restarts.

The HydraDB graph: agent, skills, tools, MCP servers, and entities connected by edges.
6 skills, 15 tools, 5 MCP servers, 9 entities in the seeded graph. Queried by the API on every plan.

Call the API before the model sees anything.

Your agent posts a task, gets a context pack, binds only those tools, then reports what it used. The graph answers in two round-trips.

  1. 01

    POST /v1/plan with a task

    {"task": "why is checkout failing in prod"}

  2. 02

    API traverses skills → tools → servers

    incident-triage → 5 tools → github, k8s, grafana, pagerduty

  3. 03

    API resolves mentions to entities

    checkout → checkout-api · prod → prod-us

  4. 04

    POST /v1/session to write back

    usage counters and learned aliases improve the next plan

API reference · v0.2.0

Plain HTTP. JSON in, context pack out.

Run the ContextMesh service next to your HydraDB node and call it from any agent framework or language. Reads (/v1/plan) are concurrent; writes (/v1/session) are serialized per process to match single-writer storage.

Base http://localhost:8000 — self-hosted default; replace with your service URL. Auth optional API key — X-API-Key or Bearer; off by default, enable with CONTEXTSMESH_API_KEY. CORS for a separate frontend origin, allow it with CONTEXTSMESH_CORS_ORIGINS.
POST /v1/plan

Plan context for a task. Returns matched skills, tool schemas, MCP servers, resolved entities, and timing.

POST /v1/session

Record what was used. Updates usage counters and learns new aliases. Returns a session_id.

GET /v1/stats

Graph counts by label (skills, tools, servers, entities, aliases, sessions).

GET /health

Liveness plus graph reachability. /ready returns 503 when the graph is unreachable.

Request POST /v1/plan
curl -s http://localhost:8000/v1/plan \
  -H "Content-Type: application/json" \
  -d '{
    "task": "why is checkout failing in prod"
  }'
Response
{
  "skills": ["incident-triage"],
  "tools": [
    { "tool": "get_pod_status", "server": "k8s",
      "schema_json": "{...}" },
    { "tool": "get_events", "server": "k8s", ... },
    { "tool": "get_metric_series", "server": "grafana", ... }
  ],
  "mcp_servers": [
    { "name": "k8s", "command": "..." },
    { "name": "grafana", ... }
  ],
  "resolved_entities": {
    "checkout": { "name": "checkout-api", "kind": "service" },
    "prod":     { "name": "prod-us", "kind": "environment" }
  },
  "graph_round_trips": 2,
  "context_ms": 7.0
}
const base = "http://localhost:8000";
// Replace base with your self-hosted service URL.
// If API auth is enabled, set this header from a secure runtime config:
const headers = { "Content-Type": "application/json" };
// headers["X-API-Key"] = apiKey;
const task = "why is checkout failing in prod";

async function post(path, body) {
  const response = await fetch(`${base}${path}`, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
  });
  const data = await response.json();
  if (!response.ok) {
    throw new Error(data.error?.message || `HTTP ${response.status}`);
  }
  return data;
}

// 1. Plan: only the context this task needs.
const pack = await post("/v1/plan", { task });

// 2. Bind pack.tools, run your model, then record what was used.
await post("/v1/session", {
    task,
    used_tools: ["get_pod_status", "get_events"],
    resolutions: Object.fromEntries(
      Object.entries(pack.resolved_entities)
        .map(([mention, ent]) => [mention, ent.name])
    ),
});
import requests

base = "http://localhost:8000"
# Replace base with your self-hosted service URL.
# If API auth is enabled, set this from a secure runtime config:
headers = {}  # leave empty when auth is disabled
# headers["X-API-Key"] = api_key  # set from secure runtime config if enabled
task = "why is checkout failing in prod"

def post(path, body):
    response = requests.post(
        f"{base}{path}", json=body, headers=headers, timeout=10
    )
    data = response.json()
    if not response.ok:
        raise RuntimeError(data.get("error", {}).get("message", response.text))
    return data

# 1. Plan: only the context this task needs.
pack = post("/v1/plan", {"task": task})

# 2. Bind pack["tools"], run your model, then record what was used.
post("/v1/session", {
    "task": task,
    "used_tools": ["get_pod_status", "get_events"],
    "resolutions": {
        mention: ent["name"]
        for mention, ent in pack["resolved_entities"].items()
    },
})

Quickstart (self-host)

  1. 1
    Start HydraDB

    scripts/run_node.sh  # :7687 :8443 :9090

  2. 2
    Install & seed the graph

    pip install -r requirements.txt
    python -m hydracontext.seed

  3. 3
    Run the API

    uvicorn hydracontext.service:app --port 8000

  4. 4
    Call it from your agent

    POST /v1/plan → bind tools → run → POST /v1/session

Auth: off by default. Set CONTEXTSMESH_API_KEY to require X-API-Key or Authorization: Bearer, or terminate auth at your gateway. Writes are serialized per process; reads are concurrent. A Python store (HydraContextStore) is also available for in-process use.

Structured errors
// 401 when an API key is enabled and missing
{ "error": { "code": "http_error",
             "message": "Missing or invalid API key.",
             "request_id": "9f2c1a7b4e01" } }

// 422 invalid request
{ "error": { "code": "invalid_request",
             "message": "Request validation failed.",
             "request_id": "9f2c1a7b4e01",
             "details": [ ... ] } }

// 503 when HydraDB cannot serve a plan or write
{ "error": { "code": "graph_unavailable",
             "message": "Graph backend unavailable.",
             "request_id": "9f2c1a7b4e01" } }

// GET /ready when the graph is unreachable
{ "ok": false, "graph": "agent", "graph_reachable": false }

Behavior & limits

Reads

Concurrent. /v1/plan is safe to fan out across agents.

Writes

Serialized per process to match HydraDB's single-writer-per-cell model.

Plan shape

top_k defaults to 3, capped at 10; 2 graph round-trips on the demo graph.

Auth

Optional key on /v1/plan, /v1/session, /v1/stats; /health and /ready stay open.

CORS

Browser clients allowed by default; lock down origins with CONTEXTSMESH_CORS_ORIGINS.

Try the API

Send a task, inspect the context pack.

This calls POST /v1/plan on the live service and renders the JSON response below. Works with recorded packs if the API is offline.

Connecting to the API…
— round-trips
— ms context
— tools returned
— MCP servers

skills[]

waiting

tools[]

    resolved_entities{}

      Raw JSON response
      
                

      Same model. Same tasks. Smaller context.

      Five ops tasks, one local 1.5B model: every tool in the prompt versus the context pack returned by the API.

      Prompt tokens, lower is better

      baseline
      15,276
      via API
      8,195

      46% fewer tokens with the same model and the same expected answers.

      Tool and entity correctness

      4/5 ContextMesh API
      0/5 all tools in prompt

      The planned pack binds the right tools and resolves the right services. The baseline does not.

      7.8 ms/v1/plan p50 at 16-way concurrency
      23.5 ms/v1/plan p95 at 16-way concurrency
      128concurrent sessions, 0 errors
      0context lost across a reboot

      Measured against a live HydraDB node. Reads scale concurrently; session writes are serialized per process (single-writer-per-cell). Graph storage survives restarts because object storage is the source of truth.

      Pricing that follows the agents.

      Proposed pilot pricing for the hosted or managed API. Self-host the open stack on your own infra anytime.

      Free

      $0

      For a first agent

      • 1,000 plan resolutions / month
      • Up to 2 agents
      • Self-host or sandbox
      • Community support
      Read the API

      Enterprise

      Custom

      Self-hosted, your cloud

      • Your VPC / object storage
      • Gateway/token auth, TLS & audit logs
      • Multi-tenant namespaces
      • SLA and support

      API questions, answered.

      What exactly does the API return?

      POST /v1/plan returns a context pack: skills, tools (with schemas and server), mcp_servers, resolved_entities (mention → canonical name/kind), plus graph_round_trips and context_ms. Your agent binds only those tools.

      Does it work with my agent framework?

      Yes. It’s plain HTTP/JSON. Call /v1/plan before your model step and /v1/session after—LangGraph, custom loops, or any runtime in any language.

      Is there an SDK?

      The primary interface is the web API. For Python you can also use HydraContextStore in-process (same plan/record logic) if you prefer embedding over HTTP.

      How does write-back work?

      POST /v1/session takes the task, used_tools, and resolutions. It increments usage counters and learns new aliases. A conflict guard keeps one canonical entity per mention.

      Where does the data live?

      In a HydraDB graph (object-storage-backed). Query nodes are disposable caches, so a restart does not lose the graph. Reads are concurrent; writes are serialized per process.

      How do I secure the API (auth)?

      Two options. Set CONTEXTSMESH_API_KEY on the service to require X-API-Key or Authorization: Bearer on /v1/* (off by default). Or terminate auth at your API gateway or reverse proxy, where you can add TLS and network controls. The OpenAPI spec at /openapi.json and docs at /docs describe the surface to protect.

      Can I self-host it?

      Yes. One Docker image for the HydraDB node and one Python service for the API. Both run on a laptop in this repo; for production, deploy it behind your gateway with auth and TLS.

      Give every agent the right context. One call at a time.

      Pilot

      Start a pilot

      Tell us what you’re building. We’ll reply with access and help seed a context graph for your domain.