The retrieval structure is not the interface

Tags: rag, search, restraint

Deciding what is relevant is the system's job. A node map, a similarity slider or a list of chunks hands that job to a person who did not ask for it, cannot do it well, and came for the content rather than the apparatus.

Why this keeps happening

Not because anybody thinks the graph is a good interface. Because of two pressures that both point the same way.

The machinery is the interesting part of the build. It is where the difficulty was, it is legible to the team, and it is genuinely impressive. Surfacing it feels like showing the work.

It looks like the differentiator. Every competitor has a search box; not every competitor has the graph. So the graph goes in the demo, and what is in the demo ends up in the product.

Both are reasonable instincts about the team's experience and wrong about the user's. The user's experience of the graph is a screen of nodes they have to untangle before they get what they came for.

The test

Would the user have wanted this view if they did not know how the system was built?

It is a blunt question and it settles most cases. Nobody who has not seen the architecture diagram asks for a force-directed layout of their documents. Nobody wants to set a cosine-similarity threshold. Nobody has an opinion about chunk size, and a person shown chunk boundaries in their results experiences them as the product being broken.

A similarity score is the sharpest version. It is a number the user cannot check, cannot act on, and has no basis for believing — so "relevance: 0.87" asks them to do arithmetic on the system's confidence in place of reading the result.

When structure does belong on screen

The first two branches are real and worth taking seriously — an investigator mapping connections between entities is doing a task for which the graph is the answer, and a codebase's call graph is not an implementation detail, it is the thing. The distinction is whether the person is navigating relationships or just wants what they asked for.

The third branch is the one products get wrong in the other direction. When default retrieval misses often enough that users need to steer, the answer is a control in their vocabulary — filter by source, by date, by document type — not a parameter from yours. "Only the 2024 filings" is steering. "Top-k = 12" is delegation of your tuning problem.

And exposing the apparatus behind a disclosure, for the handful of people debugging why something was retrieved, is entirely fine. The failure is making it the primary surface.

Grounded in

Edvo runs on a graph database, and the users get content and a search box.

The premise of the product was that scattered tabs, files, docs and notes should be findable faster than you could remember where you put them — and the graph is the reason that works across sources that have no common schema. It is load-bearing. It is also, deliberately, not something anyone is asked to look at: restraint over spectacle was the call, and a node map to untangle would have reintroduced exactly the work the product existed to remove.

The honest reading is that the graph earned its place by being invisible. A person who has to understand the index in order to search it is doing the system's job, and the system was the thing they were paying for.

A note on the neighbouring pattern

This sits next to model output as structure, not prose, and the two can look contradictory — one says surface structure, this one says hide it.

The resolving question is whose vocabulary the structure is in. A facet the user would recognise is an interface. An artifact only the system recognises is machinery. The colour of a mineral is a property of the mineral; a cosine distance is a property of the index. Promote the first, keep the second underneath.

Anti-patterns

• A node graph as the main view. Impressive in a demo, work in a product.
• Similarity scores shown to end users. An uncheckable number presented as a reason.
• Chunk boundaries visible in results. Fragments where documents were expected; reads as a bug.
• Retrieval parameters in the UI. Top-k, temperature, thresholds. Your tuning problem, reassigned.
• "Advanced search" that requires understanding the index. Advanced for whom.
• An empty result that blames the query. When retrieval finds nothing, the useful thing to say is what was searched — see answer within the boundary — not "try different keywords".

The smallest version worth building

Ship the content and one way to ask for it. Put every number the retrieval layer produces behind a debug view that only you open.

Then watch where people actually fail. If default retrieval misses often, add one steering control phrased in their terms — and resist the version phrased in yours, because that one is cheaper to build and it moves the problem rather than fixing it.

Related patterns

• Model output as structure, not prose — the other side of the line, and the case where extraction genuinely belongs in front of people.
• Wizard or conversation — the same restraint one level up: the machinery being conversational does not mean the interface should be.
• Answer within the boundary, and show its shape — what to say when retrieval legitimately could not see something.