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.
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:
-
Start HydraDB
The included script starts a local demo node with filesystem storage.
bashscripts/run_node.sh
-
Install and seed
Install dependencies, then seed the example context graph.
bashpip install -r requirements.txt python -m hydracontext.seed
-
Run the API
Serve the API and product site together.
bashuvicorn hydracontext.service:app --host 127.0.0.1 --port 8000
-
Plan a context pack
Send a task and inspect the returned skills, tools, and entities.
bashcurl -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.
# 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:
{
"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.
top_k defaults to 3, capped at 10.
POST
/v1/session
Open reference →
Record used tools and entity resolutions back to the graph.
GET
/v1/stats
Open reference →
Return graph counts by label.
GET
/health
Open reference →
Liveness and graph reachability.
GET
/ready
Open reference →
Readiness check; returns 503 when HydraDB is unreachable.
POST
/v1/pilot
Open reference →
Save a website pilot request to local JSONL storage.
API reference
Interactive OpenAPI explorer. Schemas and examples load from /openapi.json.