
The Freeze Wasn’t the Answer: Building an AML Agent That Reasons Over FalkorDB
We built an AML investigation agent that follows money through transaction graphs, measures laundering capacity, and proves the smallest account freeze before acting. This article covers the graph design, failures, engineering lessons, and how we kept the AI honest with deterministic evidence.
Built by:
How we built an AML investigation agent that follows money through FalkorDB — and refuses to guess
At 10:30 on the fourth day, our agent gave us the answer every fraud console gives when it has been built too quickly:
Freeze all seven accounts.
It was not wrong in the ordinary sense. The seven accounts were connected. They shared phones and IP addresses. Money moved through them quickly. They looked suspicious.
It was just not the answer an analyst needed.
A47 and A52 were enough. Freezing those two accounts cut every route to the cash-out hub. Freezing only the alerted account left 74% of the capacity flowing. Freezing the obvious aggregator left 20% flowing through A77, an account that was not even part of the ring.
That difference — seven accounts versus two — became the reason we built Follow the Money.

The case board: four synthetic AML alerts, including two deliberately honest false alarms.
Live demo: graph-hacks-cyan.vercel.app
Source: github.com/anirudhsgh7/graph-hacks
Track: Agents That Act on Connected Data
Database: FalkorDB
This is the story of the decisions, failures, and graph operations behind it.
The problem was not finding suspicious accounts
Anomaly scores are easy to explain and difficult to trust.
A merchant can have a high score because hundreds of customers paid once. A household can look suspicious because four accounts share a tablet. A mule ring can look like an ordinary set of transfers if the investigator examines each account separately.
The questions an AML analyst actually asks are relational:
- Which accounts are connected through shared infrastructure?
- Does money move through those accounts, or do they merely share a device?
- Does a path in the transfer graph represent money moving in time, or only a coincidental relationship?
- How much money can reach the cash-out hub?
- What is the smallest set of accounts whose freeze cuts every route?
- What evidence supports each sentence in the conclusion?
None of those answers lives in one account record.
That made FalkorDB more than a storage choice. It became the context layer, the algorithm engine, the case store, and the place where the agent could prove what it was about to do.
Our design rule was simple:
If FalkorDB is removed, the product should lose its ring detection, trails, capacity calculation, freeze proof, and audit path.
If the graph were only behind a decorative network visualization, we would have failed the brief.
The world we built for the agent
The data is synthetic and reproducible.
backend/seed/generator.py uses seed 42 to generate:- 595 accounts
- 8,317 individual transfers
- 585 devices
- 581 IP addresses
- Customers, cases, investigations, proposals, and actions
The hidden ground truth is used only by
seed/verify.py to test whether the product rediscovers what was planted. No product query reads ring_id or is_laundering .The core graph is deliberately small enough to understand and rich enough to make the easy answer wrong.
(:Customer)-[:OWNS]->(:Account)(:Account)-[:TRANSFER]->(:Account)(:Account)-[:FLOWS_TO]->(:Account)(:Account)-[:USED_DEVICE]->(:Device)(:Account)-[:USED_IP]->(:IPAddress)The
TRANSFER relationship preserves individual payments: amount, timestamp, channel, and transfer id. The FLOWS_TO relationship is an aggregated projection with one edge per ordered account pair.That second relationship type exists for a very practical reason: max-flow needs a relationship type without parallel edges, while real accounts can transfer money to one another many times.
FLOWS_TO.capacity is the total observed value for the pair.The case graph also stores its own memory and audit trail:
(:Case)-[:HAS_INVESTIGATION]->(:Investigation)(:Investigation)-[:PROPOSES]->(:Proposal)(:Case)-[:HAS_ACTION]->(:Action)-[:TARGETS]->(:Account)(:Investigation)-[:ABOUT]->(:Account)The last relationship was added after we asked ourselves whether the agent could remember what it had learned about an account in another case. The answer should not be a hidden conversation transcript. It should be another graph relationship that can be queried, cited, and inspected.
The agent never writes Cypher
The obvious architecture was to give the model the schema and ask it to generate queries. We rejected it immediately.
A generated query can be subtly wrong, expensive, hard to explain, or impossible to reproduce after the model has moved on. It also makes the database boundary harder to audit.
Instead, the model chooses from 11 fixed tools in
backend/agent/tools.py . Each tool has:- a human-written, named query in
queries/*.cypher;
- a typed parameter schema;
- input validation against FalkorDB;
- a compact result digest for the model;
- an evidence record for the analyst;
- query receipts containing the named query, parameters, and Cypher.
The model can ask for
detect_ring . It cannot write the MATCH or choose an arbitrary procedure. It can ask for money_trail with a source and destination. It cannot change the traversal into a query that returns the entire database.The tool catalogue is the interface between reasoning and the graph.
That made the agent easier to test too. The rule-based investigator calls the same tools in a fixed playbook. If the LLM is unavailable, the database operations do not disappear and the API contract does not change. The model is replaceable; the graph operations are not.
First failure: community detection found almost everyone
Our first ring-detection idea was to use community detection over the transfer graph. It sounded right: money-laundering rings are communities, so let the algorithm find the communities.
On our realistic background traffic, label propagation merged 585 of 595 accounts into one community. It was also not deterministic enough for a product that needed to show the same answer every time.
The problem was not that the algorithm was broken. The graph projection was wrong for the question.
We were asking a transfer network to answer an infrastructure question.
The product's ring signal is not merely “these accounts transfer money.” It is “these accounts share devices or IP addresses, and their money behaves like pass-through money.” So we projected the infrastructure graph instead:
CALL algo.WCC({ nodeLabels: ['Account', 'Device', 'IPAddress'], relationshipTypes: ['USED_DEVICE', 'USED_IP']})YIELD node, componentIdWITH componentId, collect(node.id) AS membersWHERE any(m IN members WHERE m IN $ids)RETURN componentId, membersalgo.WCC gave us deterministic connected components. Then Python measured the behaviour of each component:- pass-through ratio;
- median minutes between receiving and forwarding money;
- number of shared devices and IPs;
- entry points and cash-out candidates.
The ring decision is a measurement, not a visual impression:
mule_ring when: accounts >= 3 pass_through >= 85% median_forward_minutes <= 60That distinction is what keeps the family cluster honest. A95–A98 share a tablet and an IP, but only 34% of the money passes through over days. They are connected. They are not a mule ring.
Second failure: a shortest path is not necessarily a money trail
algo.SPpaths gives us candidate routes through FLOWS_TO . That is useful, but a graph path alone can be misleading.Two accounts can be connected by transfers that happened in the wrong order. A route can exist structurally while money could not have followed it. A legitimate payment can create a path through an ordinary account.
So
money_trail uses algo.SPpaths as a proposal, then reads the individual TRANSFER records behind each pair:MATCH (s:Account {id: $src}), (t:Account {id: $dst})CALL algo.SPpaths({ sourceNode: s, targetNode: t, relTypes: ['FLOWS_TO'], relDirection: 'outgoing', maxLen: $max_len, pathCount: $path_count})YIELD path, pathWeightRETURN [n IN nodes(path) | n.id] AS nodes, pathWeight AS hopsFor every hop, the tool then checks real transfers in timestamp order. It keeps the route as a strong trail only when:
- the transfers happen in sequence;
- the amount does not grow between hops;
- the gaps fit the configured time window.
Otherwise the evidence is labelled
structural rather than presented as laundering.That extra read is important. The shortest path is a graph operation. Calling it a money trail is an evidence decision.
The question that changed the product: what should we freeze?
Ring detection produces a finding. It does not produce an action.
For action, the analyst needs to know how much money can still reach a hub and what intervention has the least collateral damage.
For case-001, the entry accounts are A17, A63, and A68. The destination is H3.
algo.maxFlow over FLOWS_TO measures the observed laundering capacity:MATCH (s:Account) WHERE s.id IN $sourcesWITH collect(s) AS sourcesMATCH (t:Account) WHERE t.id IN $sinksWITH sources, collect(t) AS sinksCALL algo.maxFlow({ sourceNodes: sources, targetNodes: sinks, relationshipTypes: ['FLOWS_TO'], capacityProperty: 'capacity'})YIELD edges, edgeFlows, maxFlowRETURN maxFlow AS max_flow, [e IN edges | [startNode(e).id, endNode(e).id]] AS pairs, edgeFlows AS flowsThe result is $30,100.
But max-flow does not answer the smallest account set to remove. We implemented a minimum vertex cut using node splitting over the
FLOWS_TO edges. The cut cost is not just one account equals one unit: busy legitimate accounts carry a higher collateral cost based on the share of their counterparties outside the suspicious network.The planner recommends A47 and A52.
Then comes the part we cared about most: we do not trust the planner's number by itself.
The backend copies the graph with
GRAPH.COPY , removes the proposed accounts on the disposable fork, and re-runs the capacity and path operations. The fork must show:capacity before: $30,100capacity after: $0remaining paths: 0The live graph is untouched until the analyst confirms the action. This is a what-if simulation that is also a proof.

The console puts the verdict and measured numbers before the graph: capacity, ring size, freeze count, and time for the money to cross.
The graph is also the explanation
Every tool result registers an evidence item such as
ev-3 or ev-8 . An evidence item carries:- the evidence type;
- the producing tool;
- graph node ids;
- transfer edge ids;
- structured result facts;
- named query receipts.
A finding cannot cite an evidence id that does not exist. A proposed action cannot exist without evidence references. The graph sent to the frontend is bounded to a case subgraph, but the evidence still points back to the operations that produced it.
The UI makes this visible instead of hiding it in logs. Selecting a finding lights its nodes and edges. Selecting an evidence chip opens the structured excerpt and the exact Cypher receipt.

The evidence panel shows the producing tool, graph ids, structured facts, and replayable query receipts; the trace shows every tool call, rows, duration, and arguments.
This is a different standard from asking the model to explain itself after the fact. The path is returned by the operation that found it. The model may narrate it, but it does not get to invent the route afterward.
Third failure: the model stopped before the important part
Switching from Groq to OpenRouter solved our token-per-minute failure mode, but introduced a new one: free models were slower and less consistent about the playbook.
A model could correctly find the ring, then stop before calling capacity and minimum freeze. In one run it suggested freezing all seven accounts. In another, it wandered through repeated profile calls until the tool-turn budget ended.
The deterministic fallback protected correctness, but it changed the result from an LLM investigation to a rule-based one. We wanted the model to have a chance to finish, without trusting it to finish.
We added two bounded guards:
- The prompt says that a confirmed mule ring is incomplete until
laundering_capacityandplan_minimum_freezerun.
- If the model stops early, the loop gets one nudge. If it still ends without the plan, the deterministic planner completes only the missing graph steps — with no extra model calls.
The result is not “make the model smarter.” It is “make the system safe when the model is variable.”
The tests cover both cases: early stop → nudge → plan, and turn exhaustion → planner completion. In the real local run, the model stopped early, the nudge fired, and the final plan still produced A47+A52 with
$30,100 → $0 on a fork.The model is useful. The graph and the guards are responsible.
Fourth failure: a fluent sentence can still be false
Evidence references protect findings, but summaries are free text. A model can cite a real evidence id and still mention an account or amount that was not in the graph result.
We added
backend/agent/factcheck.py for that boundary. Before the response leaves the backend, it extracts account ids and dollar amounts from the model's summary and findings and compares them with the facts returned by the tools. If a claim is unsupported, deterministic text replaces the model's prose and meta.notes explains why.Unknown names are handled even earlier. If the analyst asks about
A999 , the backend resolves the account against FalkorDB before selecting seeds, running tools, or calling the model. It returns NOT_IN_GRAPH with a 404 and no model call.That is a small check with a large effect. A case should not silently investigate A17 because the question named an account that does not exist.

The proof strip turns the trace into a readable sequence: each tool, its FalkorDB algorithm, its headline, and its measured duration.
What fought back
The failures were more useful than the first successful demo.
The graph algorithm was right, but the projection was wrong
Label propagation over transfers merged almost the whole synthetic world. We stopped treating “community detection” as a magic answer and chose the projection that represented the relationship we actually cared about.
Result sets can be silently bounded
FalkorDB can cap result sets through
RESULTSET_SIZE . Our flow reader counts the total edges first and pages through FLOWS_TO until it has all of them. A silent truncation is worse than a query failure because it produces a plausible but incomplete capacity.Free-tier model limits are product behavior
OpenRouter's free pool is request-counted: local, hosted, and rehearsal calls share the daily budget. Free models can take 30–130 seconds per investigation. We added provider fallback, retry handling, a 120-second local budget, a 90-second hosted budget, and deterministic completion. When the pool was exhausted during rehearsal, the system fell back to the rule-based investigator and still returned the correct false-alarm decision.
That was not a failure of the fallback. It was a reminder that a demo plan must budget inference requests like any other dependency.
A freeze must not mutate the graph during simulation
The obvious implementation would remove candidate accounts and then try to restore them. We never do that. What-if operations use
GRAPH.COPY ; confirmed actions are the only path that writes statuses to the live graph.A visual graph is not evidence
A glowing node is not proof. The graph canvas is a view over evidence, not the source of truth. Every highlight has node or edge ids behind it, every finding has evidence refs, and every receipt can be replayed.
What the agent receives — and what it does not
The runtime model receives:
- the AML system prompt and a case context;
- the analyst's question;
- 11 fixed tool schemas;
- assistant tool calls from the conversation;
- compact digests of tool results;
- an evidence ledger for final narration.
It does not receive raw FalkorDB rows, Cypher text, the whole graph, hidden ground truth, or a write tool.
The backend keeps full evidence server-side. The model sees enough to select the next operation and write a narrative, while the application retains the data needed to verify it.
This separation also keeps the system useful without an LLM. The deterministic investigator calls the same tools and returns the same typed response shape. In a fraud workflow, graceful degradation is more important than preserving the appearance of intelligence.
Two suspicious cases and two honest false alarms
A demo that always finds fraud teaches the wrong lesson.
Case-001 contains the ring and the freeze proof. Case-002 follows an unauthorized
$9,800 through C42 → A91 → A33 → A75 → H1 in 26 minutes and proposes freezing A75.Case-003 is M8, a merchant that tops the legacy anomaly score. The account has 320 one-time customers and ordinary settlements. It has no ring evidence and no meaningful pass-through pattern. The agent recommends closing the alert.
Case-004 is a household cluster around A95. Four accounts share a tablet and IP, but the transfers happen over days and the pass-through ratio is low. Shared infrastructure alone is not enough.
The negative cases are not filler. They are the integrity test for the product's central claim: connected data should make the decision more precise, not merely more alarming.
What I would tell myself on day one
Model the question before the data
The useful schema fell out of the questions: ring membership, trails, capacity, cut sets, and evidence paths. If we had started with “accounts and transfers” without the freeze question, we would have missed
FLOWS_TO , GRAPH.COPY , and the collateral cost model.A fixed tool catalogue beats generated queries
Human-written Cypher is easier to review, parameterise, test, and replay. Let the model choose among safe operations. Do not make it responsible for composing the database layer it is supposed to explain.
A shortest path needs a semantic check
Graph reachability and money movement are not synonyms. Read the underlying events and validate time and amount before naming a path.
Prove actions before executing them
The most useful agent output was not a confidence score. It was “these two accounts stop every route, verified on a copy.” Simulation is the difference between a recommendation and an action an analyst can defend.
Honest no-evidence answers are a feature
M8 and A95 make the product more credible than another suspicious alert would. The agent should be allowed to say the graph does not support the accusation.
What this project claims — and what it does not
Follow the Money is a synthetic AML investigation demo, not a production banking system. The thresholds are tuned to the generated world. Capacity is measured over observed transfers in the data window, not a daily rate. The LLM is optional and its prose is not the authority. The live deployment uses a small shared synthetic graph and a single analyst persona.
Those limitations are visible in the UI and documentation because hiding them would undermine the product's point.
The claim we can support is narrower and more useful:
Given a connected transaction graph, the agent can follow relationships, use graph algorithms, propose an evidence-linked action, and prove the action's graph impact before changing the live graph.
That is what FalkorDB makes possible here.
Try it
- Open the live case board .
- Open case-001 and watch the agent investigate the burst from A17.
- Select the ring finding and inspect its evidence.
- Compare the simulated freeze plans.
- Confirm A47+A52, then ask: “Is there any way around this freeze?”
- Try case-003 and watch the agent close the honest false alarm instead of forcing a fraud verdict.
The repository includes the seed, named Cypher, API contract, frontend, backend tests, and local setup instructions. The project runs against recorded fixtures without a database, or against FalkorDB locally and in the hosted deployment.
Follow the money. Then prove the freeze.
Follow the Money was built during Graph Hacks: Context for AI Agents by WeMakeDevs and FalkorDB. The dataset is synthetic; it contains no real persons, accounts, or financial records. AI coding assistants were used during development and are disclosed in the repository. All opinions are those of the project team.
Enjoyed reading this content? Let the author know!
Your likes, comments, shares, and saves help creators reach more builders.
Loading recommendations
Loading article