Locks Say No. The Graph Says Why: Giving AI Coding Agents a Shared Memory with FalkorDB

Good question, and the answer is the first one: the reason comes back with the denial. When a lock is refused, Relay adds what the holder is working on to the message the agent sees, something like: "File is locked by Claude Code. They're working on: 'switch the login flow to JWT tokens' (2 min ago)." So the blocked agent doesn't have to guess.

One detail on where it comes from. The lock check never queries the graph live, because it runs before every edit and can't afford a database round trip. The holder's intent sits in a small in-memory cache that's kept up to date as agent conversations are ingested into FalkorDB, and refilled from the graph when Relay restarts. If we're not confident about the holder's current task, the wording softens to "was last working on" instead of claiming too much.

Whether the agent then retries sensibly is partly up to the agent. The message tells it to pick a different task, and before touching unfamiliar files it can also ask Relay for a briefing, which pulls past blocks and decisions from the graph. In our own testing, the old behaviour was a retry storm (25 attempts in 10 seconds). With the reason attached, a blocked agent has what it needs to move on instead.