# A Retrieval Receipt Is the JSON the Query Wrote

> I keep the public RAGFS query JSON as a retrieval receipt: query, file, score, content, and line range. I do not invent a quality benchmark.

Published: 2026-10-04
Canonical: https://gianlucamazza.it/en/blog/ragfs-retrieval-receipts
Tags: RAG, FUSE, Linux, Retrieval

## Why this matters

A retrieval step that I cannot re-read later is a story, not a record. I want the query, the files it returned, the scores, the snippets, and the line ranges sitting in one JSON object I can keep.

That object is already public. [RAGFS](https://github.com/Venere-Labs/ragfs) documents the query output in the [User Guide](https://github.com/Venere-Labs/ragfs/blob/main/docs/USER_GUIDE.md). The [ragfs card](/en/projects#ragfs) points at the repository and the [documentation](https://venere-labs.github.io/ragfs/). I am reading those pages. I am not adding a client, a company, or a benchmark.

The interface decision lives in [Why I Gave Agents a Filesystem Instead of Another API](/en/blog/agent-filesystem). This page is the receipt cut: what a query writes, and what that writing is not.

## What the public receipt records

The User Guide shows the query command and the JSON shape it prints:

```plaintext
ragfs query ./src "error handling implementation" -f json
```

```json
{
  "query": "error handling implementation",
  "results": [
    {
      "file": "src/lib.rs",
      "score": 0.847,
      "content": "Handle errors gracefully by...",
      "lines": "45:52"
    }
  ]
}
```

Five fields, and only those five, are what I treat as the retrieval receipt:

1. **query**: the string I asked.
2. **file**: the path of a hit.
3. **score**: the score the command printed for that hit.
4. **content**: the snippet it returned.
5. **lines**: the line range it named.

The same guide prints a text form with the same facts: query, file, score, lines, snippet. JSON is the form I keep because a script can read it. The [documentation site](https://venere-labs.github.io/ragfs/) lists `query` next to `index`, `mount`, and `status`. Hybrid search is the documented default. I do not turn that default into a quality claim.

Search on the mount still runs a local embedding model and stores vectors in LanceDB. The first run downloads `thenlper/gte-small`. Later queries use that local model. I already wrote that path in the filesystem article. The receipt here is the JSON, not the mount.

## What the example numbers are not

The `0.847` in the guide is the guide's example. So is the second text-form score `0.812`. They show the field. They are not a measured run I published, and they are not a retrieval-quality benchmark.

I have not published a retrieval-quality or scale benchmark for this setup. The filesystem article already says that. I will not invent one here.

`ragfs status --format json` is a different object: path, file count, chunk count, index size, last update. The User Guide shows an example of that object too. Those example counts are also documentation wording. They are not a corpus I measured for this page.

## What I do not claim

A receipt says what the command returned. It does not say the hit was the right passage. [RAG in Production](/en/blog/rag-systems-production) is still the diagnostic order when retrieval is weak: measure, then inspect chunking and ranking before changing the embedding model.

I do not claim a client used this JSON. I do not claim a company adopted RAGFS. I do not quote a private score. If a sentence is not in the public project, the User Guide, the documentation site, or a receipt already on this site, I leave it out.

"Trust me, the context was relevant" is not a receipt. The query JSON is.

## FAQ

### What counts as a RAGFS retrieval receipt?

The query JSON: the query string, and each hit's file, score, content, and line range. The User Guide documents that shape.

### Are the 0.847 and 0.812 scores a published benchmark?

No. They are the User Guide's example numbers. I have not published a retrieval-quality or scale benchmark for this setup.

### Does keeping the JSON prove the hit was relevant?

No. The JSON records what the command returned. Relevance still needs an evaluation. I use the diagnostic order in RAG in Production when retrieval is weak.

### Where is the public receipt?

The [User Guide query format](https://github.com/Venere-Labs/ragfs/blob/main/docs/USER_GUIDE.md), the [repository](https://github.com/Venere-Labs/ragfs), and the [documentation](https://venere-labs.github.io/ragfs/). The [ragfs card](/en/projects#ragfs) is the public index.