Execution Traces

ContextOS provides first-class observability through Execution Traces. When you call build_context(), the orchestrator meticulously records every stage of the retrieval, ranking, and planning process.

The ExecutionTrace Object

The ContextResult returned by ContextOS includes a trace property. This object contains:

• Execution Steps: A chronological log of every major pipeline stage (Embedding, Retrieval, Planner, Prompt Builder).
• Latency Metrics: Microsecond-level timings for embedding generation, hybrid retrieval, fusion, reranking, and database I/O.
• Token Metrics: The exact number of tokens consumed by the constructed prompt.
• Candidate Pool: The full pool of merged candidate memories before planning.

Example Trace Output

You can inspect a trace to understand exactly how ContextOS reached its final state:

Query
 ↓
Embedding (bge-small-en-v1.5)
 ↓
Retrieval (Dense + BM25)
 ↓
RRF Fusion
 ↓
Planner
 ↓
Prompt Builder
 ↓
ContextResult

Explainable Decisions

The most powerful feature of the trace is the decisions list. For every candidate that enters the Memory Planner, ContextOS records whether it was selected or rejected, and why.

Available fields for each decision:

• semantic_score: The final semantic relevance score.
• recency_score: The chronological recency score.
• final_score: The blended score used for final sorting.
• rank: The candidate's rank in the final planned list.
• selected: Boolean indicating if it made it into the context window.
• reason: An enum explaining the decision (e.g., BUDGET_EXHAUSTED, HIGH_SEMANTIC_SCORE, SYSTEM_PROMPT).

Observability Integrations

By passing a TraceStore implementation to the ContextOrchestrator, you can automatically stream these traces to PostgreSQL, Datadog, LangSmith, or any custom observability platform.