
ShadowChain AI: Building Security Investigations That Remember
A practical look at using FalkorDB to connect security evidence, preserve agent memory, and recover investigation progress after restarts—with an interactive graph explorer and Groq-powered explanations.
Security investigations need context that lasts
A security alert usually starts a longer conversation.
What changed? Which identities and resources are connected? Has someone investigated this before? What evidence supports the finding, and what still needs verification?
We built ShadowChain AI to keep those questions connected.
Our goal was to create an investigation system where evidence, agent observations, decisions, and unfinished tasks remain available across sessions. An agent should be able to continue earlier work without reconstructing the entire investigation from scratch.
That led us to FalkorDB as the persistent foundation.
Why we chose a graph
Security investigations involve relationships: identities connect to resources, findings depend on evidence, and agents hand work to other agents.
We wanted to preserve those connections directly.
In ShadowChain AI, FalkorDB stores application relationships alongside investigation context:
- Entities and their connections.
- Source observations and supporting evidence.
- Agent memories, tasks, and handoffs.
- Investigation records and previous decisions.
- Simulation proposals and human reviews.
The database also performs actual Cypher traversals. The application retrieves connected evidence and bounded paths from the graph before producing an explanation.
Removing FalkorDB makes core investigation operations unavailable. We do not replace it with an authoritative in-memory copy.
What the live application does today
The hosted application imports evidence from an approved public GitHub repository.
That includes repository metadata, contributor references, selected configuration-file references, and bounded dependency declarations. Each observation retains its source context.
For example, a visitor can inspect a relationship chain such as:
Contributor → Repository → Dependency manifest → Declared dependencyThis helps explain how entities are connected. A dependency declaration alone does not establish that a package is vulnerable, and a contributor reference does not establish access permissions.
The interface, called GraphVerse, lets visitors search entities, inspect evidence, and follow relationship paths in an interactive 3D view. Browsers without WebGL can use the same graph through a 2D fallback.
Source refreshes are currently triggered by an operator. The hosted application is not a continuous security monitoring service.
How the system fits together
The project has two backend components with distinct responsibilities:
GraphVerse browser interface | vExpress explorer API ──────→ Groq | Optional explanations v FalkorDB ^ |FastAPI investigation backend | vLangGraph security workflowsThe hosted explorer uses the Express API for its public GitHub investigation flow.
The separate Python backend implements security investigation and memory workflows using FastAPI and LangGraph. These workflows have been tested with labeled synthetic security scenarios. They use a separate graph schema and should not be confused with the hosted repository pipeline.
Both components persist their authoritative investigation data in FalkorDB.
Memory is part of the investigation
We organized the Python memory system around three types of context:
Episodic memory records what happened during an investigation: observations, hypotheses, evidence, and conclusions.
Semantic memory captures established knowledge about entities, relationships, and verified attributes.
Procedural memory preserves investigation procedures, useful checks, and lessons from earlier approaches.
Memories retain provenance, confidence, verification status, and version history. Corrections supersede earlier records while preserving the audit trail.
Conflicting observations remain connected to their evidence so an investigator can examine why they disagree.
Coordination that survives a restart
The project defines six logical agent roles:
Agent | Responsibility |
|---|---|
Cloud Sentinel | Processes configuration observations and evidence. |
Identity Guardian | Reviews identity and permission relationships. |
Risk Oracle | Runs graph traversals and deterministic checks. |
Memory Keeper | Retrieves context and preserves conflicting observations. |
Coordinator | Tracks tasks, dependencies, and handoffs. |
Response Architect | Evaluates possible responses through simulations. |
The live repository pipeline uses six bounded, deterministic stages. The separate Python workflows use LangGraph.
Progress is persisted in FalkorDB. Recovery reads completed tasks, pending work, and handoff context from the graph rather than depending on a running process’s memory.
Our integration tests exercise recovery across processes and check that completed work is not duplicated.
Where Groq fits
Groq provides optional explanations over retrieved graph facts. The deployed assistant has been verified with
openai/gpt-oss-20b .The graph determines the relationships and paths. The model receives bounded facts and evidence references, and its response is validated before display.
It cannot execute commands, change permissions, or approve remediation.
If generation fails or the public allowance is exhausted, the application preserves the deterministic graph answer and explains the fallback.
Visitors do not need database credentials or their own model key. Those credentials remain in server environment variables. Administrative actions and private saved investigations require operator access.
Testing a change before recommending it
The what-if simulator lets an operator exclude a modeled relationship from a reachability query.
It compares paths before and after the hypothetical removal, checks for remaining routes, and preserves the proposal and review decision in FalkorDB.
The original inventory remains unchanged. Approval records agreement with a recommendation; it does not execute an external change.
For security scenarios, we describe findings as potential attack paths. A connected graph path alone does not prove effective authorization or exploitability.
What we verified—and what remains
Recent verification covered real FalkorDB persistence, temporal relationships, tenant boundaries, memory retrieval, restart recovery, simulation behavior, and credential-free public browsing. We also verified an actual anonymous Groq response on the hosted application.
External provider failures are tested with mocked transports; those tests are distinct from live generation checks.
There is still work ahead: broader authorization modeling, automatic source updates, individual user authentication, and verified backup restoration. We have not benchmarked Groq against Gemini or measured a performance improvement from this provider change.
The most useful lesson from this project has been straightforward: persistent, traceable context makes agent coordination easier to inspect and trust.
Try ShadowChain AI
Open the application, search for an entity, and trace its connection to another node. Inspect the supporting evidence and ask the assistant to explain the retrieved path.
Built together by Devesh Singhal, Mayank Gupta, and Devesh Raj.
ShadowChain AI reflects our shared work on the application, graph-based investigations, agent memory, and testing.

- Live application: shadowchain-ai.vercel.app
- Source code: deveshsinghal09/shadowchain-ai
- License: MIT
I would welcome feedback on the investigation flow, graph readability, and how the system presents uncertainty.
Enjoyed reading this content? Let the author know!
Your likes, comments, shares, and saves help creators reach more builders.
Loading recommendations
Loading article