RAG Debugging (Chunk Retrieval Traces)

Last Updated: 2026-02-06
Content-Type: How-to
Audience: Developers, Admins

---

Overview

This guide explains how to inspect what the system retrieved for a user message (which chunks, scores, tiers) using the RAG trace feature.

RAG traces are optional and intended for debugging quality issues.

---

Enable RAG Traces

In backend/.env:

• RAG_TRACE=true

Then restart the backend.

---

View Traces in Admin Portal

1. Open Admin → User Management
2. Click Edit Context
3. Open the RAG Debug tab

You’ll see the latest retrieval traces:

• query text
• top chunks (tier, score, memoryId:chunkIndex)
• a short content preview

---

API Endpoint (Admin)

GET /api/admin/users/:id/rag-traces?limit=30

This returns:

• traces[] ordered by newest first
• each trace includes queryText, chunks, and optional meta

---

Notes / Safety

• Traces store snippets of retrieved content, so treat them as sensitive.
• Keep traces disabled unless you’re actively debugging retrieval.