Building Waaris: An Agentic AI Inheritance Assistant with FalkorDB and Gemini
Team: Legacy Labs
Hackathon: Graph Hacks – Context for AI Agents
Technologies: FalkorDB, Google Gemini 2.5 Flash, Cypher, Agentic AI
1. The Problem: Navigating Inheritance Shouldn't Be This Difficult
When a loved one passes away, families may face a complicated administrative process to claim bank deposits, mutual fund investments, and other financial assets.
Each financial institution can have its own documentation procedures, verification requirements, and claim process. Families may need to understand nominee information, establish legal heirship where required, collect supporting documents, and follow up with multiple institutions.
The challenge is not simply finding information. It is understanding how people, assets, institutions, and documents relate to one another.
A document relevant to one claim might also help progress several other claims. However, identifying these relationships across multiple accounts and institutions can be difficult.
Traditional chatbots can explain general procedures, but they may struggle to answer structured questions that require traversing relationships, counting affected accounts, and comparing financial values.
What if an AI agent could connect these relationships and help families identify which documents may be most useful for progressing their claims?
That question inspired us to build Waaris, our project for the Graph Hacks – Context for AI Agents hackathon.
2. Introducing Waaris
Waaris is an agentic AI prototype designed to help users explore inheritance-related information and documentation dependencies through a connected knowledge graph.
Instead of treating every question as an isolated text-search problem, Waaris represents relevant information as interconnected entities and relationships.
Our approach combines three core technologies:
- Google Gemini 2.5 Flash: Understands natural-language questions and helps coordinate the reasoning workflow.
- FalkorDB: Stores and queries relationships between heirs, financial accounts, institutions, and documents.
- Cypher: Expresses graph traversals, filtering, counting, and aggregation as explicit database queries.
Together, these technologies provide a foundation for answering questions using structured graph context rather than relying exclusively on generated text.
3. Why FalkorDB?
The central design decision in Waaris is to model inheritance-related information as a graph.
Consider a simplified scenario.
A deceased person has several financial accounts across different institutions. Multiple documents may be associated with the requirements for progressing those claims. One document could be relevant to more than one account.
Representing this information in isolated records makes it harder to explore the relationships between all these entities.
A graph makes those connections explicit.
For example:
- A deceased person is connected to potential legal heirs.
- A financial account is connected to an institution.
- An account may be blocked by an outstanding requirement.
- A document may be associated with the requirements for progressing multiple accounts.
FalkorDB allows the application to traverse these relationships and perform structured queries over the connected data.
The graph is not merely a visual representation. It is a queryable source of context that supports the agent's answers.
4. Designing the Waaris Knowledge Graph
We designed Waaris around six main node types.
Nodes
Deceased
Represents the person whose financial assets may need to be claimed.
Heir
Represents a person who may have a family or legal relationship to the deceased. The relationship alone does not establish legal entitlement.
Account
Represents a bank account, mutual fund investment, or another financial asset included in the system.
Institution
Represents the bank or financial institution associated with an account.
Document
Represents a potentially relevant document, declaration, form, or legal record.
Requirement
Represents a documentation, verification, or procedural condition associated with a claim.
Relationships
Our graph uses relationships such as:
-
RELATED_TO— connects people through relevant relationships. -
HELD_AT— connects a financial account to its institution. -
BLOCKED_BY— represents a dependency preventing a claim from progressing. -
UNLOCKS— represents an association between a document and an account that may progress when the relevant requirements are satisfied.
These relationships allow the system to reason about dependencies across multiple connected entities.
The exact relationship semantics depend on the graph data and the rules used to populate it. In a production system, these rules must be validated against authoritative legal guidance and institution-specific documentation.
5. The Key Question: Which Document Could Help the Most Accounts?
One of the questions we designed Waaris to explore is:
"Which one document could help unblock the most accounts, and what is their combined value?"
This question requires more than retrieving a paragraph about succession documents.
The system needs to:
- Identify documents connected to relevant accounts.
- Filter accounts that are blocked or still in progress.
- Count the distinct accounts associated with each document.
- Calculate the associated financial value.
- Rank the documents according to the selected prioritization criteria.
This is where graph traversal and database-side aggregation become useful.
Rather than asking the language model to estimate the answer, we can express the calculation directly in Cypher.
6. The Cypher Query Behind the Insight
Here is the Cypher query for this example:
MATCH (d:Document)-[:UNLOCKS]->(a:Account)
WHERE a.status IN ['blocked', 'in_progress']
RETURN
d.name AS document,
count(DISTINCT a) AS accounts_unlocked,
sum(a.amount_inr) AS total_value
ORDER BY accounts_unlocked DESC
LIMIT 1;
How the query works
Step 1: Traverse the graph
MATCH (d:Document)-[:UNLOCKS]->(a:Account)
This finds document nodes connected to account nodes through the UNLOCKS relationship.
Step 2: Filter relevant accounts
WHERE a.status IN ['blocked', 'in_progress']
Only accounts with the specified statuses are considered.
Step 3: Aggregate the results
count(DISTINCT a) AS accounts_unlocked,
sum(a.amount_inr) AS total_value
The query counts distinct connected accounts and calculates their combined recorded value.
Step 4: Rank the documents
ORDER BY accounts_unlocked DESC
LIMIT 1
The query returns the document with the highest number of associated accounts.
This example prioritizes account count rather than total financial value. A different business objective could use a different ranking strategy.
The result is derived from the graph data and query logic, not invented by the language model.
An important implementation detail: The UNLOCKS relationship must be created using validated rules. It should not imply that submitting a document automatically guarantees claim approval. The summed value represents the accounts associated with the selected document, not necessarily the amount that will ultimately be recovered. If an account can be connected through multiple paths, aggregation must also be designed to avoid double-counting.
7. How the Agent Works
The intended workflow connects natural-language interaction with structured graph querying.
Architecture:
User question → Gemini 2.5 Flash agent → Cypher query execution → FalkorDB → Structured query results → Natural-language response
Step 1: The user asks a question
For example:
"Which document is associated with the highest number of blocked accounts?"
Step 2: The agent interprets the request
Gemini helps interpret the user's intent and identify the appropriate graph operation.
Step 3: The graph query executes
The application executes the relevant Cypher query against FalkorDB.
Step 4: FalkorDB returns structured results
The database returns the matching documents and the requested aggregate values.
Step 5: The agent explains the result
The agent converts the structured result into a readable explanation, ideally including the relevant account count, associated value, and supporting context.
This separation is important.
The language model handles natural-language interpretation and explanation, while the graph query performs the explicit traversal and aggregation.
The architecture makes it easier to inspect how a result was calculated and test the underlying query independently.
8. Graph Context Versus Vector RAG
Vector retrieval and graph databases solve different problems, and they can complement each other.
Vector search is useful for finding relevant passages in lengthy documents, such as official bank procedures, legal guidance, and claim instructions.
A graph database is particularly useful when the question depends on explicit relationships between entities.
For Waaris, consider the difference between these two questions.
Question A: "What documents does a bank's published guidance mention for a particular type of claim?"
This can benefit from document retrieval and source-grounded summarization.
Question B: "Which document is connected to the largest number of blocked accounts in our graph?"
This requires structured traversal and aggregation.
A vector similarity score alone does not answer Question B reliably.
By representing relationships explicitly and executing Cypher queries, Waaris can calculate the answer from the available graph records.
The broader lesson is not that vector RAG is unnecessary. It is that the retrieval and reasoning strategy should match the question being asked.
A more comprehensive system could combine document retrieval for evidence with graph queries for relationship-based analysis.
9. Reliability, Explainability, and Legal Boundaries
Inheritance-related applications require particular care because incorrect guidance can cause financial and legal harm.
Waaris is a prototype intended to explore how connected context can support administrative workflows. It should not be treated as a legal authority or a guarantee of financial recovery.
A production implementation would need several safeguards:
- Verified sources: Use current, authoritative legal guidance and institution-specific requirements.
- Evidence and citations: Link recommendations to the sources supporting them.
- Explicit uncertainty: Distinguish known information from missing or unverified information.
- Careful heirship reasoning: Do not infer legal entitlement from family relationships alone.
- Privacy protections: Protect personal, financial, and identity information.
- Query validation: Validate generated queries, enforce access controls, and restrict database operations.
- Human review: Require appropriate professional or institutional verification for consequential decisions.
Nomination, succession, and legal ownership are not interchangeable concepts. The applicable rules depend on the asset, the institution, the relevant law, and the circumstances of the claim.
Reliable assistance requires more than a convincing AI-generated answer. It requires trustworthy data, explicit rules, and results that can be checked.
10. Challenges and Lessons Learned
Building Waaris has highlighted an important architectural lesson: natural-language understanding and relational reasoning are different responsibilities.
A language model can interpret a question, but it should not be expected to perform every multi-entity calculation from memory.
A graph database can represent explicit relationships and execute repeatable queries, but it can only provide reliable results when the underlying data and relationships are correct.
Combining the two allows us to explore a more structured approach to agentic AI.
The most important design principle is simple:
Let the agent understand the question, let the database calculate the result, and make the evidence behind the answer inspectable.
This approach can be useful beyond inheritance-related workflows. Similar patterns may help in compliance analysis, document dependency management, financial operations, and other domains where relationships between entities matter as much as the entities themselves.
11. What's Next?
Our future development priorities include:
- Expanding the graph with verified institutional requirements.
- Improving how the application handles multiple heirs and accounts.
- Adding source citations and evidence to generated explanations.
- Testing more complex graph queries and edge cases.
- Improving privacy, security, and access control.
- Evaluating the system against realistic, carefully validated test scenarios.
- Exploring how document retrieval and graph reasoning can work together.
These improvements would help move Waaris toward a more reliable and transparent assistant for complex administrative processes.
12. Project Information
Project: Waaris — Agentic AI Inheritance Assistant
Team: Legacy Labs
Hackathon: Graph Hacks – Context for AI Agents
Graph database: FalkorDB
AI model: Google Gemini 2.5 Flash
Query language: Cypher
GitHub repository: Waaris — GitHub
Demo video: Watch the Waaris demo
Conclusion
Waaris explores how agentic AI can become more useful when it operates over explicit, connected context.
By combining Gemini's natural-language capabilities with FalkorDB's graph representation and Cypher's structured querying, we are exploring a way to answer relationship-heavy questions with results that can be inspected and tested.
The goal is not simply to generate an answer that sounds correct. It is to connect the relevant information, execute a verifiable operation, and explain the result clearly.
For us, that is the potential of graph-powered context for AI agents.
Built by Team Legacy Labs for Graph Hacks – Context for AI Agents.
