The faceted contract
One contract — discover, search, fetch, activity — over every source, and why it matters.
Every source in Echo — code, graph, docs, company docs, work items, commits, PRs, database — is queried through the same four operations. This is the faceted contract, and it is the architectural decision that keeps the API small and stable.
The four operations
| Operation | What it does | When to use it |
|---|---|---|
| Discover | Lists every source available for a project, its sync state, and what it contains | Before searching — know the shape of what you can query |
| Search | Runs a natural-language query across one or more sources, returns ranked hits | When you have a question and need answers |
| Fetch | Resolves a hit's opaque ref to its full content object and graph neighborhood | When you need the detail behind a search hit |
| Activity | Returns time-ordered events across the sources that carry a clock | When you need the timeline: what changed, when, by whom |
Why one contract
Most knowledge systems add an endpoint per source. A code search endpoint, a ticket search endpoint, a database query endpoint. Each has its own request shape, its own pagination, its own error model. The client knows what sources exist and changes when sources change.
Echo inverts this. The consumer calls search and optionally filters by source. Hits from all matching sources are fused into one ranked list. Adding a new source — say, a wiki connector — requires no client change: the new source appears in discover, its entities appear in search, and its refs resolve in fetch.
# Search across all sources
curl -X POST "$ECHO_URL/projects/$PROJECT_ID/knowledge/search" \
-H "X-API-Key: $SERVICE_KEY" \
-H "Content-Type: application/json" \
-d '{ "query": "session validation", "top_k": 10 }'
# Search only code and work items
curl -X POST "$ECHO_URL/projects/$PROJECT_ID/knowledge/search" \
-H "X-API-Key: $SERVICE_KEY" \
-H "Content-Type: application/json" \
-d '{ "query": "session validation", "sources": ["code", "work_items"], "top_k": 10 }'The MCP consequence
The MCP server exposes a fixed set of tools — echo_discover, echo_search, echo_fetch, echo_activity — that map directly to the four contract operations. When a new source is added, the same tools work. An agent integrated today does not need to be updated when Echo adds a source tomorrow.