See why your agent answered from the wrong paragraph

Your agent sounds certain. It quotes a policy, names a number, and moves on. A week later a customer tells you the number was wrong, and now you are reading retrieval logs at 11pm trying to work out which of forty chunks it pulled and why. If that is a familiar evening, this post is for you.

The problem is not that your agent is dumb. It is that flat vector search hands back a pile of similar-looking passages with no record of how they connect. You can see what was retrieved. You cannot see why that was the route to the answer. So a wrong answer looks exactly like a right one until someone complains.

Why "read the retrieved chunks" stops working

The usual fix is to log the top-k chunks and read them by hand, or to add "cite your sources" to the prompt. Both help a little and neither scales. Reading chunks tells you what matched a query embedding; it does not tell you that the agent connected a refund policy to a dollar limit to an approver role. When the answer is wrong, the chunks often look reasonable in isolation. The mistake lives in the join, and the join is invisible.

Re-chunking, re-ranking and metadata filters all push the same lump around. They change which passages surface, not whether you can audit the path. You end up trusting a system you cannot inspect, in front of users who will find the one case you did not test.

What a checkable answer looks like

FastMemory takes a different starting point. Instead of storing your documents as one flat cloud of vectors, it builds a map with six plain layers:

1. What it's made of — the pieces in your domain.
2. How it's organized — how those pieces group together.
3. What it does — the actions and rules.
4. What data it uses — the sources each rule touches.
5. Who is allowed — the access and roles.
6. What happens when — the events that fire.

When your agent asks a question, the answer comes back with the route it walked through those layers. Not a similarity score. An actual trail: this rule, in this section, tied to this limit, gated by this role. You read the trail and you know in seconds whether it went where a human would have looked. A wrong answer shows up as a wrong turn on the map, not as a plausible paragraph you have to fact-check by hand.

The map is built from ATF Markdown, a plain format you write or generate. A minimal entry looks like this:

## [ID: refund_policy]
**Action:** Approve or decline a refund request
**Data_Connections:** orders_table, refund_limits
**Access:** support_agent, finance_lead
**Events:** refund_approved, refund_declined

Those headers are the six layers. FastMemory reads them directly. There is no LLM call at ingest, which matters for the next thing every team asks about: cost and speed. Building the map does not send your documents to a model and bill you per token.

Try it on one real question

The fastest way to judge this is to point it at something you already know the answer to. The command-line tool installs from Cargo:

cargo install fastmemory
fastmemory build data/input.md
fastmemory query data/input.md "who approves a refund over $5,000?"

The query output includes the trail. If the trail matches where you would have looked, that is the signal FastMemory is built to give you. If it does not, you can browse what was indexed instead of guessing:

fastmemory serve data/input.md --port 16743

One note so you do not lose ten minutes: pip install fastmemory gives you the Python module (fastmemory.process_markdown(...)), not the command-line binary. For the CLI above, use cargo install.

When the trail becomes the audit

For a solo builder, the trail saves a late night. For a team in a regulated industry, it is the difference between shipping an agent and not. If an auditor can ask "where did this answer come from?" and you can show the exact route, the same question gives the same trail tomorrow, because the map is deterministic by design rather than re-sampled on every call. That is the property FastMemory Enterprise extends by keeping the map inside your own graph database, so the audit trail lives where your compliance team already looks.

Where to start

You do not have to believe a benchmark to check this. Write one ATF Markdown file for a corner of your domain, pick a question you already know the answer to, and read the trail. That is the whole test.

• Read how the map is built, layer by layer, on the FastMemory architecture page.
• Get the code and the worked example on GitHub.
• Install and run the folder-to-answer workflow in under five minutes.

If your agent has ever answered confidently from the wrong paragraph, the fix is not another re-ranker. It is being able to see the route it took.