Recalling memories

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.

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 10

Pass 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)
`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.

CLI flags: --limit (maps to k), --mode hybrid|vector|bm25|graph, --include facts,passages, tri-temporal --as-of, --at-instant, --valid-from, --valid-until.

Note

--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}/context

Returns 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/query

spectron documents query "return policy"

Chat (composed recall + synthesis)

POST /api/v1/{context_id}/chat

spectron 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}/state

profile 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.