AWS Builder Center
The Freeze Wasn’t the Answer: Building an AML Agent That Reasons Over FalkorDB

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.
Follow the Money case board

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, componentId
WITH componentId, collect(node.id) AS members
WHERE any(m IN members WHERE m IN $ids)
RETURN componentId, members
 algo.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 <= 60
That 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, pathWeight
RETURN [n IN nodes(path) | n.id] AS nodes, pathWeight AS hops
For every hop, the tool then checks real transfers in timestamp order. It keeps the route as a strong trail only when:
  1. the transfers happen in sequence;
  1. the amount does not grow between hops;
  1. 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 $sources
WITH collect(s) AS sources
MATCH (t:Account) WHERE t.id IN $sinks
WITH sources, collect(t) AS sinks
CALL algo.maxFlow({
sourceNodes: sources,
targetNodes: sinks,
relationshipTypes: ['FLOWS_TO'],
capacityProperty: 'capacity'
})
YIELD edges, edgeFlows, maxFlow
RETURN maxFlow AS max_flow,
[e IN edges | [startNode(e).id, endNode(e).id]] AS pairs,
edgeFlows AS flows
The 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,100
capacity after: $0
remaining paths: 0
The live graph is untouched until the analyst confirms the action. This is a what-if simulation that is also a proof.
Investigation console with the network and measured verdict

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.
Evidence details and the agent trace

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:
  1. The prompt says that a confirmed mule ring is incomplete until  laundering_capacity  and  plan_minimum_freeze  run.
  1. 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 with tool steps and graph algorithms

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

  1. Open the  live case board .
  1. Open case-001 and watch the agent investigate the burst from A17.
  1. Select the ring finding and inspect its evidence.
  1. Compare the simulated freeze plans.
  1. Confirm A47+A52, then ask: “Is there any way around this freeze?”
  1. 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.
Any opinions in this article are those of the individual author and may not reflect the opinions of AWS.
Enjoyed reading this content? Let the author know!

Your likes, comments, shares, and saves help creators reach more builders.

Loading recommendations

Loading article