ContextMesh Docs

Developer documentation

ContextMesh API

Plan a compact context pack for each agent task — skills, tool schemas, MCP servers, and resolved entities — then write usage back to the graph.

v0.2.0 OpenAPI 3.1 Base localhost:8000

Overview

ContextMesh is a self-hosted web API backed by a HydraDB graph. Before your agent calls a model, POST /v1/plan returns only the tools and entities that task needs. After the run, POST /v1/session records usage and learned aliases.

Reads are concurrent. Session writes are serialized per process because HydraDB admits one writer per cell.

Task
  └─ plan ─► HydraDB graph
               ├─ keywords → Skill → NEEDS → Tool → SERVED_BY → MCPServer
               └─ mentions → Alias → RESOLVES_TO → Entity
                    ↓
              task-specific context pack
                    ↓
              agent binds tools and runs
                    ↓
              session write-back updates usage and aliases

Quickstart

Prerequisites: Python 3.10+, Docker, and a running HydraDB node. From the repository root:

  1. Start HydraDB

    The included script starts a local demo node with filesystem storage.

    bash
    scripts/run_node.sh
  2. Install and seed

    Install dependencies, then seed the example context graph.

    bash
    pip install -r requirements.txt
    python -m hydracontext.seed
  3. Run the API

    Serve the API and product site together.

    bash
    uvicorn hydracontext.service:app --host 127.0.0.1 --port 8000
  4. Plan a context pack

    Send a task and inspect the returned skills, tools, and entities.

    bash
    curl -sS http://localhost:8000/v1/plan \
      -H 'Content-Type: application/json' \
      -d '{"task":"why is checkout failing in prod","top_k":3}'

Authentication

Authentication is optional and disabled by default. Set CONTEXTSMESH_API_KEY to require X-API-Key or Authorization: Bearer on /v1/plan, /v1/session, and /v1/stats.

/health, /ready, and /v1/pilot stay public. CORS defaults to * for the local demo; set CONTEXTSMESH_CORS_ORIGINS for a deployed browser client.

http
# Either header works when CONTEXTSMESH_API_KEY is set
X-API-Key: your-key
Authorization: Bearer your-key

Errors

Every response includes an X-Request-ID header. API errors use a consistent envelope:

json
{
  "error": {
    "code": "graph_unavailable",
    "message": "Graph backend unavailable.",
    "request_id": "9f2c1a7b4e01"
  }
}
Status Code When
422 invalid_request Request body or query failed validation
401 unauthorized Missing or invalid API key (when auth is enabled)
503 graph_unavailable HydraDB unreachable for a graph operation
500 internal_error Unexpected server failure

Endpoints

Replace http://localhost:8000 with your deployment URL when calling remotely.

API reference

Interactive OpenAPI explorer. Schemas and examples load from /openapi.json.

OpenAPI http://localhost:8000