Tracing as graph-resident memory
Spectron stores three trace kinds as first-class nodes in the substrate, linked by real edges to entities, attributes, passages, and model calls. Traces are inputs to future ranking and consolidation – not only external telemetry.
| Trace | Emitted by | Holds (conceptually) | Typical edges |
|---|---|---|---|
retrieval_trace | Every /query and ranked read | Query text, candidate sets per index, fused scores, returned subset, model metadata | considered, returned, parent_trace |
decision_trace | Every reconciliation | Input extraction, confidence, trust, per-record outcome (created, updated, superseded, flagged), plus the acting principal, any on-behalf-of delegation target, and the session scope under which the write ran | considered, created, superseded, flagged, parent_trace |
response_trace | /chat and /reflect | User message, assembled prompt, model response, tokens, cost, latency | used_retrieval, produced_decision, wrote, parent_session |
Traces are queryable (for example GET /api/v1/{ctx}/traces and GET /api/v1/{ctx}/traces/{id}) and inspectable from the CLI (spectron inspect trace:…). Trace listing respects the same access model as memory: holders of manage can see every trace in a Context; other callers see only traces whose session scope falls within their read grant. See Surface, models, and security for HTTP and CLI detail.
Feedback loops (examples):
The ranker uses aggregated
retrieval_trace.returnedsimilarity – entities that helped similar queries get boosted; records tied to corrections get demoted.Elaboration uses
decision_trace.consideredco-occurrence to propose links between entities that were examined together but never connected.Consolidation reinforces facts that
response_traceshows were actually used in successful answers; untouched records can age out.Calibration uses repeated
decision_trace.supersededlineage as a negative trust signal on the original source.
That is the difference between “we logged what happened” and “we remember what happened – and it changes what we do next.”
Reflection, elaboration, and consolidation
Three mechanisms create new memory; they answer different questions and run at different times.
| Mechanism | Trigger | When | Output |
|---|---|---|---|
| Reflection | Caller asks a synthesis question | On-demand (POST /reflect) | Answer plus optional new facts (source.kind = "reflect") |
| Elaboration | Background sweep (default); also ingest-time or targeted | Async / periodic | New relations and attributes (source.kind = "elaboration") linking previously disconnected material |
| Consolidation | Async job; sometimes every few hundred writes | Cron-style and triggered | Observation records (source.kind = "consolidation") with history, derived_from, proof_count |
Reflection is the active path: it runs when something asks.
Elaboration and consolidation are passive: they evolve memory between user interactions.
All write through the same reconciler as turns and documents, so supersession and uncertainty rules stay identical.
Semantic response reuse (tier 2)
Prior response_trace records can answer new questions when:
The new question is the same or very similar (embedding similarity) within the same Context and scope, and
Every entity and attribute cited via
used_retrieval → retrieval_trace.returnedis still current (no superseding writes, no new contradictinguncertainty).
Then Spectron can return the stored answer and link a fresh response_trace with reused_from pointing at the original trace.
This is semantic response caching with entity-aware invalidation – the cache key is not a raw string hash; it is the query plus the set of facts the prior answer depended on. When any cited fact moves, dependent responses invalidate automatically.
Operational notes:
Reuse is conservative by default; similarity, freshness, and trust thresholds are tuneable per Context.
A reuse still emits a new
response_traceso the graph distinguishes “answered from cache” from “fresh LLM call”, and reinforcement continues to attribute to the original.
The REST API and MCP tools reference exercise these paths.