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

POST /api/v1/{context_id}/query
API-KEY: <key>
Content-Type: application/json

{
  "query": "What role does Alice have?",
  "limit": 10,
  "scope": ["org=acme", "user=alice"]
}

Response fields:

Field	Meaning
`tier`	`direct`, `cache`, `hybrid`, or `full_context`
`hits`	Ranked facts and/or passages
`query_ms`	Server-side latency
`trace_id`	Correlates with `GET .../traces/{id}`

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

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?",
  "limit": 10,
  "scope": ["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.