---
title: "Retrieval audit"
description: "The Agents → Audit section: what an agent searched for and opened, whether it found anything, and where its blind spots are — queries that come up empty."
---

# Retrieval audit

The context builder decides what gets loaded into an agent up front. The audit is its counterpart during the work itself: it shows what the agent actually searches for (`search` / `recall`) and opens (`get_note`), and whether it found anything. This matters because the dominant memory failure mode isn't "the fact is missing" — it's a retrieval failure: the note you need exists, but the query never reaches it. Without observability, grooming memory turns into guesswork.

The section lives under **Agents → Audit**.

## What goes into the log

Every call to a reading tool (`search`, `recall`, `get_note`) appends a line to the log: what was searched for (query, scope, class) and what was found (the top hits with `noteId`, `title`, `score`, `class`, plus the result count). Capture happens in the background — it affects neither latency nor the correctness of the answer returned to the agent.

Writing tools (`create_note`, `remember_*`, `edit_note`) are **not logged** to the retrieval audit — their provenance lives in the [revision log](/docs/concepts/versioning/). The audit is about reading.

Each line also remembers the **agent's name** — the friendly name of the token or app (for example, a CLI or Claude), captured while the token is alive. That way the line remembers forever which agent made the query.

## Blind spots

The audit's main signal is **recurring queries that come up empty**. A single empty search is normal (the agent tested a hypothesis). But a query that finds nothing **time after time** is a blind spot: the agent needs a fact that isn't in memory, or one that's filed under an unfortunate title. That's a direct pointer to what to add or how to rephrase.

The interface distills this into two panels:

- **Blind spots** — recurring empty queries (threshold: two or more with no result), highlighted in yellow/amber.
- **Frequent** — the most common queries.

Plus a history feed (newest on top) with a filter by tool (All / Search / Recall / Open): the tool icon, the query itself, the agent's name, the class/category label, the project (only when scoping is applied), the result count, and the time. Expanding a line reveals the hits it found — they're clickable and lead straight to the notes.

> [!note] Empty results
> The audit reliably catches exactly the empty-result case. The "something relevant exists but didn't make the top hits" case requires running the query against memory — that's a separate, subtler signal the audit doesn't surface.

## Privacy and reach

The log is visible only to the owner: you see retrieval by your own agents, tied to your username. Since the viewer is the owner, your agent's name is shown unredacted. The audit spans all of your spaces at once — a line has no single home space.

> [!info] When retrieval isn't logged
> The audit is stored in the metadata database. A host without a metadata database (for example, `none` mode with no database) doesn't log retrieval — the section simply stays empty, with no error.

## Next

- [Context sets and pins](/docs/agents/context-pins/) — what gets loaded up front; the audit shows what's pulled on demand.
- [Agent memory](/docs/agents/memory/) — what exactly `search` and `recall` look for.
- [Security and visibility](/docs/agents/security/) — why read logs are visible only to the owner.