Skip to main content
Copass retrieval has two flows over the same underlying knowledge graph:

Browse, then drill in

discover → interpretTwo calls. First a ranked menu of structural pointers, then a synthesized brief on the items the agent picks. Use when the agent needs to pick before going deep.

Direct answer

searchOne call. A synthesized natural-language answer over the graph. Use when the question is self-contained and the agent doesn’t need to pick.
Search composes Interpret which composes Discover — the three retrieval tools nested as a single surface. Same graph underneath. What varies is the resolution of what comes back — and the cost-quality tradeoff for this turn.

​
Flow 1 — Browse, then drill in

​
discover — the menu

Returns a ranked list of structural pointers (entity paths, with scores) that match the query. No prose. The cheapest way to see “what does the graph have on this topic?” 
copass discover "checkout flakiness" --json
Sample response (truncated): 
{
  "items": [
    { "path": "Checkout > Stripe Webhooks > retry policy",      "canonical_ids": ["..."], "score": 0.91 },
    { "path": "Checkout > Stripe Webhooks > dead-letter queue", "canonical_ids": ["..."], "score": 0.87 },
    { "path": "Logs > Payments > 5xx burst on 2026-04-12",      "canonical_ids": ["..."], "score": 0.82 },
    { "path": "Decisions > Move from polling to webhooks",      "canonical_ids": ["..."], "score": 0.79 }
  ]
}
When to use — first hit on an exploratory question, “show me more like this” follow-ups, anything where the agent needs to pick a sub-path before going deeper.

​
interpret — the brief

Takes one or more canonical_ids from a discover response and returns a 1–2 paragraph brief grounded in the actual underlying source. Use it when the agent has decided which items matter and wants the synthesized take on those specific ones. 
copass interpret '[["canonical_id_1"], ["canonical_id_2"]]' --json
Sample response (truncated): 
{
  "brief": "The Stripe webhook handler retries 5xx responses with exponential backoff up to 6 attempts; failures land in a dead-letter queue read by the on-call dashboard. The retry policy was set in PR #1432 after a Q3 incident…",
  "citations": ["...", "..."]
}
When to use — the agent committed to specific items from discover and needs the why/what, not the where.

​
Flow 2 — Direct answer

​
search — the answer

Synthesized natural-language answer over the graph. The heaviest call — but the right one when the question is self-contained and the agent doesn’t need to pick. 
copass search "why did checkout move from polling to webhooks?" --json
Sample response (truncated): 
{
  "answer": "We moved to Stripe webhooks in Q3 to eliminate the 90-second confirmation lag introduced by 30s polling…",
  "citations": ["...", "..."]
}
When to use — direct questions (“why”, “what does X do”, “how did we”), one-shot lookups, end-of-thread synthesis.

​
Picking the right flow

SituationFlowCalls
”What does the graph have on X?”Browsediscover
”Show me more like this”Browsediscover (window-aware skips what was already returned)
Agent picked 2–3 items and wants the synthesized takeBrowseinterpret
Hover cards, typeahead, live previewsBrowsediscover
User asked a self-contained questionDirectsearch
End-of-thread synthesis (“write this up”)Directsearch
Need to budget tokensBrowsestart with discover, escalate only if needed
Always the same document—skip retrieval, read the source directly

​
Composition pattern

A typical multi-turn flow looks like this: 
turn 1: user asks something exploratory
        → discover         → agent reads the menu, picks 2 paths
        → interpret(picks) → agent commits to the answer

turn 2: user follows up
        → discover         → window-aware: returns the next layer down
        → interpret(picks)

turn N: user asks "now write this up"
        → search           → synthesized narrative across the picks
You’re not locked into this shape. Skip steps. Mix calls. The point is that each call operates on the same graph — what varies is how much of it gets rendered into tokens. For the why behind the three-call shape, see Progressive Disclosure.

​
Memory across turns

Every call is window-aware. Pass conversation history and the system pushes down an exclusion: items the agent has already received don’t get redelivered. So discover on turn 2 reaches deeper than turn 1 — automatically. See Window-Aware Retrieval for the mechanics and the edge cases.

​
Where these calls live

Every call hits the same backend. You can invoke them from:
  • CLI — copass discover|interpret|search (with --json for scripting). See Copass CLI.
  • MCP — exposed as tools to any MCP client (Claude Code, Cursor, Claude Desktop). See MCP Server.
  • SDK — client.matrix.{discover,interpret,search} from @copass/core. See SDK.
  • Inside an agent — the Agent Router gives the agent these as tools automatically when a sandbox is attached.

​
Next steps