Spectron exposes one fused read path over the unified substrate: structured facts from turns and passages from documents. Use POST /api/v1/{context_id}/query for ranked hits and POST /api/v1/{context_id}/context for a pre-formatted LLM block.
Register scope paths before use (spectron scopes create org/acme/user/alice). See Contexts and scope.
Ranked hits — /query
spectron recall "What role does Alice have?" --json \
--url "$SPECTRON_URL" \
--api-key "$SPECTRON_API_KEY" \
--context-id "$SPECTRON_CONTEXT_ID" \
--limit 10Pass lens on the REST body (the CLI does not expose a --scope flag on recall today):
POST /api/v1/{context_id}/query
Authorization: Bearer <key>
Content-Type: application/json
{
"query": "What role does Alice have?",
"k": 10,
"lens": [["org/acme/user/alice"]]
}Response fields:
| Field | Meaning |
|---|---|
tier | direct, cache, hybrid, or full_context — relational questions may resolve at tier 1 when the classifier routes to a structured relation read |
hits | Ranked results; each hit includes source (entity, attribute, memory_chunk, chunk, or section) and optional occurredAt (known time of the row — use to resolve relative dates in source text) |
contextHits | Same-section sibling passages pulled by section expansion — separate from hits, not counted against k. Empty when expansion is off or found nothing to add. Useful for UIs that show “expanded context” beside the ranked answer set |
queryMs | Server-side latency in milliseconds |
trace.traceId | Correlates with GET .../traces/{traceId} |
Optional read modifiers: labels (descriptor filter only), lens (DNF scope filter by involvement), asOf (known-time playback — hide facts and relations from later chapters or episodes; see spoiler-safe narrative memory), scope_view (strict, crossTeam, merged — the latter two resolve like strict; see Contexts and scope), include (facts, passages, or both — narrows the response only; retrieval considers all families), includeDuplicates (default false — excludes near-duplicate passage chunks from fused recall; set true for parity with /documents/query).
k defaults to 10 and is capped at 50 per deployment (SPECTRON_MAX_QUERY_K). The internal retrieval pool is independent of k — see Hybrid search.
Section expansion
When a ranked hit lands on a section heading or other “pointer” chunk, Spectron can pull the same-section siblings into contextHits so synthesis (and /chat citations) see the section body, not only the heading. Expansion is on by default (SPECTRON_RETRIEVAL_SECTION_EXPANSION); set it to 0 to opt out. It is read-path only, capped, scope-gated, and does not change the ranked hits list — so eval and ranker baselines that read only hits stay stable. MCP recall returns the ranked hits path; /chat and /context fold expanded passages into synthesis.
CLI flags: --limit (maps to k), --mode hybrid|vector|bm25|graph, --include facts,passages, tri-temporal --as-of, --at-instant, --valid-from, --valid-until.
--min-trust is not supported yet — the /query response does not expose per-hit trust scores, so the CLI rejects the flag rather than silently returning unfiltered results.
Formatted context — /context
Use when you want a single string for system-prompt injection:
POST /api/v1/{context_id}/context
Content-Type: application/json
{
"query": "What role does Alice have?",
"k": 10,
"lens": [["org/acme/user/alice"]]
}spectron context "What role does Alice have?"Session-scoped context
GET /api/v1/{context_id}/sessions/{session_id}/contextReturns recall formatted for the session’s scope and recent turns.
Document-only query
For retrieval limited to uploaded files:
POST /api/v1/{context_id}/documents/queryspectron documents query "return policy"Chat (composed recall + synthesis)
POST /api/v1/{context_id}/chatspectron chat "Summarise what you know about Alice"Spectron runs recall internally, then calls the configured response model. Use --stream for SSE.
Profile and state
GET /api/v1/{context_id}/profile
POST /api/v1/{context_id}/stateprofile returns category-grouped attributes (identity, knowledge, context, instructions) for prompt assembly.
Four-tier router
See Coherence, retrieval, and cost tiers. Tiers progress from cheap structured lookup through response cache, hybrid vector + BM25 + graph, to full-context synthesis. Mode details: Hybrid search, Keywords and BM25, Graph traversal.