---
title: "Read the Trace — Context Infrastructure"
description: "Most bad answers are retrieval or configuration problems wearing a model costume."
canonical: "https://press.getalchemystai.com/books/context-infrastructure-build-ai-that-understands-your-business/read-the-trace"
last_updated: "2018-10-20"
book: "Context Infrastructure"
label: "Chapter 13"
---

# Read the Trace

Most bad answers are retrieval or configuration problems wearing a model costume. Context Traces let you tell which in minutes: every trace lists the sources, scores and rules that assembled the window, available through `client.v1.context.traces.list()` or the trace viewer on the platform.

**Read the trace before you touch the prompt.** Wrong or generic answer → open its Context Trace → *what reached the window?*

| What the trace shows | Diagnosis | Where to look |
| --- | --- | --- |
| Nothing relevant | **Retrieval problem** | Confirm it was ingested (view); lower similarity thresholds; fewer groupName tags |
| Stale or out of scope | **Configuration problem** | Superseded or duplicate docs; groupName or scope mismatch; metadata filter too narrow |
| Evidence fine, answer wrong | **Model problem** | Prompt or steeringPrompt; model choice; require cited sources |

*Figure 13.1 · Triaging a bad answer with Context Traces*

Only the third branch is a reason to change the prompt or the model. Pairing traces with OpenAI's open-source conversation visualiser, Euphony, gives an end-to-end view of each turn; Alchemyst reports agent debugging around 20 times faster with traces than with raw logs.

## Symptoms and fixes

| Symptom | Likely cause | Fix |
| --- | --- | --- |
| No results | Thresholds too high, `groupName` sets that do not intersect, an over-specific query | Confirm the documents exist, drop the minimum threshold toward 0.5, remove tags, try a broader query |
| 50+ tiny fragments | Over-segmentation | Combine related content into 500 to 2,000-word documents |
| Search slower than 1 s | 7+ `groupName` tags, no minimum threshold, 10,000+ documents in scope | Cap tags at 3 to 5, set `minimum_similarity_threshold: 0.5`, shard with namespaces |
| Slow ingestion | Sequential adds, documents near 50 MB | Send arrays, use async ingestion, split large files |
| 409 Conflict | Same `fileName` already exists | Pick an update strategy (Chapter 8) |
| 413 Payload too large | Document over 50 MB or too many documents in one request | Split and resend in smaller batches |
| 422 Unprocessable | `fileType` does not match the bytes sent | Send the right type, for example PDF bytes as `application/pdf` |
| 429 Rate limit | More than 1,000 requests a minute | Exponential backoff (the SDK default) or ask for a higher limit |

## When to use Alchemyst, and when not to

Use it when context must be **reusable** across agents or sessions, when it is **larger than a model's effective context window**, when **latency** matters, and when **traceability and cost** are first-order requirements.

Do not use it as a replacement for a database. Structured data that is mostly IDs and numbers with little explanation (an inventory table of SKUs, for example), foreign-key relationships, and content with low semantic density belong in a traditional database. Store the document that explains the business logic connecting those IDs in the context layer, and denormalise relational data before ingesting it.

---

- Previous: [Chapter 12: Blueprints](https://press.getalchemystai.com/books/context-infrastructure-build-ai-that-understands-your-business/blueprints.md)
- Contents: [Context Infrastructure](https://press.getalchemystai.com/books/context-infrastructure-build-ai-that-understands-your-business.md)
- Next: [Chapter 14: In the Wild](https://press.getalchemystai.com/books/context-infrastructure-build-ai-that-understands-your-business/in-the-wild.md)
