DEV Community: Abhishek.M. Shivanagoudar

"KindRed: when a kidney swap breaks, the graph finds another way (built on FalkorDB)"

Abhishek.M. Shivanagoudar — Sun, 18 Oct 2026 08:20:33 +0000

Sunita is 48 and lives in Hyderabad. Her kidneys are failing, and her husband wants to give her one of his. He can't: she carries antibodies against his tissue type, so her body would reject the kidney. Worse, she's highly sensitised. Her antibodies react to most donors, so only a handful of people in any pool could ever give to her.

Somewhere in another city there's a family with the mirror-image problem. If Sunita's husband gives to their patient and their donor gives to Sunita, two people get a transplant. That's a paired exchange, a swap. With three families it becomes a ring: A's donor gives to B, B's to C, C's back to A.

We built KindRed, a paired exchange for kidney and liver across hospitals in India, on FalkorDB. This post walks through one swap breaking and the graph repairing it, the agent that runs a patient's case week by week, and the things FalkorDB taught us along the way.

Live demo: https://3o3ntcusu2.execute-api.ap-south-1.amazonaws.com (no sign-up)
Code: https://github.com/abhishiv17/Graph-hacks
Video: see below

Built for Graph Hacks 2026 (WeMakeDevs × FalkorDB), Tracks 1 and 2.

Everything in KindRed is synthetic. Sunita and Rajesh are demo personas with generated lab histories. No real patient or hospital record has been near this system. It's a software prototype, not a clinical tool, and nothing here is medical advice.

Why India needs this

India meets about 7% of its kidney transplant need and about 1.5% of its liver need (Lancet Regional Health - Southeast Asia, 2026). In 24 years the country has done 1,839 kidney exchange transplants across 65 centres, and 259 liver exchanges across 7 (Kute et al., 2025). Most of those swaps happened inside one hospital's small pool.

A bigger, shared pool finds more swaps. But finding the swap is only half of it. Each planned donation still has to pass a real lab test, a crossmatch, where the patient's blood is mixed with the donor's cells. If one test in a 3-way ring comes back positive, the whole ring fails and somebody starts again by phone.

KindRed is built around that moment: one failed match, and what happens next.

What our year-long simulation says a shared, failure-aware pool could change. Simulation numbers, not clinical ones.

Swaps are cycles

"Which donors are blood group O?" is a table question. "Who can swap with whom?" is a path question:

A 2-way swap is a cycle of length 2: A can give to B, and B can give back to A.
A 3-way swap is a cycle of length 3: A → B → C → A.
"Why can't this donor give to this patient?" is a 3-hop path: donor → tissue type ← antibody ← patient.
"Who could replace the family that just dropped out?" is a search over a neighbourhood whose size you don't know ahead of time.

In SQL each of those is another self-join. In a graph they're patterns you write down directly. So the model came out small:

Thing	In the graph
A family (patient + willing donor)	`Pair` node
"This donor could give to that patient"	`CAN_GIVE_TO` edge, with its reasons stored on it
A swap	A cycle of `CAN_GIVE_TO` edges, plus a `Loop` node
A failed lab test	A `FAILED` edge, kept forever
A repair	A local search a couple of hops around the break

One FalkorDB server, many graphs

FalkorDB is the only database in KindRed. One server holds many graphs, and we use them as tenants:

Graph	What's in it
`exchange`	The shared pool: families, blood groups, tissue types, antibodies, `CAN_GIVE_TO` links, swaps, offers, crossmatches, failures, decisions, tasks
`hosp_<city>` (11 of them)	Each hospital's private data: names, documents, full tissue typing, lab results. Only de-identified facts reach `exchange`
`mem_sunita`, `mem_rajesh`	Each demo patient's memory: findings, beliefs, playbooks, sessions
`chat_<id>`	Each family's conversation
`<copy>__exchange`, …	A visitor's private copy of all of the above

The shared exchange graph as the How it works page draws it. The matching rules live in the graph too: antibodies REACTS_WITH the tissue types they attack, and a failed test is a FAILED edge that is never proposed again.

When a family joins, a named query (Q02 for kidney, Q21 for liver) builds its CAN_GIVE_TO edges and writes the reasons onto each one. Here's a real edge from our run:

P-0211 → P-0388   p_success 0.56   status: failed
  "B → B · same blood group"
  "virtual test clear: no antibody at or above 2000 MFI against this donor"
  "donor DQ not typed: higher risk of a positive lab test"

Look at the third reason. Bengaluru's donor was never typed for DQ, so the virtual check couldn't see a DQ clash, and the success estimate dropped to 56% before any lab test was run. This is the edge that fails later in the story.

All the Cypher lives in 59 numbered files in backend/queries/ (Q00 to Q59). Any query without a write clause runs through GRAPH.RO_QUERY, so FalkorDB itself refuses a write from it, whoever calls it.

The multi-hop queries

The virtual crossmatch is three hops: does the patient have an antibody, at or above 2,000 MFI, against any of the donor's tissue types?

// Q03 Virtual crossmatch: donor antigen <- antibody <- patient, at or above the MFI threshold.
MATCH (:Pair {pair_id: $donor_pair})-[:HAS_DONOR]->(d:Donor),
      (:Pair {pair_id: $patient_pair})-[:HAS_PATIENT]->(r:Patient)
OPTIONAL MATCH (d)-[:HAS_ANTIGEN]->(h:HLAAntigen)<-[:REACTS_WITH]-(:Antibody)<-[k:HAS_ANTIBODY]-(r)
WHERE k.mfi >= $mfi
RETURN collect({antigen: h.name, mfi: k.mfi}) AS clashes, d.untyped_loci AS untyped_loci

The family explorer draws exactly that path. On Kolkata's P-0388, the red links show why the family's own donor can't give: the patient has antibodies against DQ8 (MFI 8,800), A1 (9,800) and B8 (11,200), all carried by that donor.

Hovering one red link: "Anti-DQ8 → DQ8. This antibody attacks that tissue marker."

A 3-way swap is a 3-hop cycle over live edges, all in one program:

// Q05 All 3-way loops a -> b -> c -> a, each listed once (a has the smallest id).
MATCH (a:Pair)-[e1:CAN_GIVE_TO]->(b:Pair)-[e2:CAN_GIVE_TO]->(c:Pair)-[e3:CAN_GIVE_TO]->(a)
WHERE id(a) < id(b) AND id(a) < id(c) AND b <> c
  AND a.organ = b.organ AND b.organ = c.organ AND ($organ IS NULL OR a.organ = $organ)
  AND a.status = 'waiting' AND b.status = 'waiting' AND c.status = 'waiting'
  AND e1.status = 'live' AND e2.status = 'live' AND e3.status = 'live'
  AND ($ids IS NULL OR a.pair_id IN $ids OR b.pair_id IN $ids OR c.pair_id IN $ids)
RETURN [a.pair_id, b.pair_id, c.pair_id] AS pairs, [e1.p_success, e2.p_success, e3.p_success] AS probs

The organ check on every node is why a kidney family and a liver family can never land in the same ring. Each edge's success estimate comes back with the loop, and the optimiser multiplies them into the chance the whole swap holds.

Why bother with 3-way swaps at all? Ask KindRed answers "how far can this family's donor reach?" at any depth up to 3. For Kolkata's P-1015, the donor reached 3 waiting families in one donation and 82 within three (3 at one hop, 69 at two, 10 at three). For a hard-to-match patient, that difference is the whole case for 3-way swaps.

Answered live by gpt-oss-120b in 2.1 s, with the graph paths behind the answer and every id checked.

FalkorDB's built-in algorithms are tools the agents call: algo.WCC splits the pool into parts that can be matched independently (Q07), algo.betweenness finds bridge families whose withdrawal would break the most swaps (Q19), and algo.pageRank ranks how easy each family is to place, so the matching agent can put the hardest first (Q59).

One failed match, end to end

We ran this live in a private copy. Every number below came back from the API in that run.

The plan. The pool holds 198 synthetic families (154 kidney, 44 liver) across 11 hospitals. The matching agent finds candidate loops in the graph, and a CP-SAT optimiser (OR-Tools) picks the set with the most expected transplants. This week's plan has 32 swaps, 85 donations and 64.1 expected transplants. One of them is S-0076: Hyderabad → Bengaluru → Kolkata, with a 46% chance every link holds.

A test fails. A new family registers in Chennai, and the graph builds its compatibility links. Then the crossmatch coordinator runs S-0076's lab tests:

Hyderabad → Bengaluru   negative
Bengaluru → Kolkata     positive   (DQ7 antibody, MFI 9000)
Kolkata → Hyderabad     cancelled  (the loop broke first)

That's the risky edge from earlier. The failure is written to the graph as a Failure node that BROKE the loop and a FAILED edge between the two families, so that donation is never proposed again. No rule engine needed: every future search simply doesn't walk that edge.

The FAILED edge between Bengaluru's and Kolkata's families, both IN_LOOP of S-0076, and the Failure node that BROKE it.

Repair locally. The matching agent doesn't re-plan the whole country. It reads the failure memory first (Q54), then searches only 2 hops around the three released families (Q11), keeps the swap's stored 2-way fallback in play (Q12), and ranks options with the same optimiser. In our run it searched 33 candidate loops in 55 ms and left the other 31 swaps alone.

Option	Expected transplants	Every link holds
Hyderabad → Bengaluru → Chennai (recommended)	2.29 of 3	56%
Stored 2-way fallback (S-0076-FB)	1.46 of 2	73%
Hyderabad ⇄ Bengaluru	1.46 of 2	73%
Bengaluru → Chennai → Ahmedabad	1.85 of 3	46%

The new Chennai family closes the ring.

"Nothing changes for any family until you decide." Each link's reasons are read from the graph.

A person approves. Nothing changes for any family until the exchange coordinator, a human, says yes. The repaired swap becomes S-0078, and the Hyderabad → Bengaluru test that already passed carries over instead of being run again. The decision is stored as Decision -[:APPROVED_BY]-> Agent {name: 'Exchange coordinator (person)'}. Approving the same task twice returns a 409, and so does asking for more tests on the broken loop.

Liver fails differently. A liver donor gives part of their liver, and the graft has to be at least 0.8% of the patient's body weight. Until a CT scan measures the lobe, the exchange only has an estimate. In L-0034 (Delhi → Chennai → Kochi), the Chennai → Kochi link looked fine on paper at 0.84%. The CT measured the right lobe at 780 ml, 0.74% of the patient's 105 kg. That link failed, and the repair (28 ms) proposed the stored 2-way fallback, Delhi ⇄ Chennai. The graph had flagged it in advance: "Liver size is only estimated and close to the limit; the CT scan will decide."

An agent that runs the case, over MCP

Two demo patients are followed week by week. Sunita's eGFR (kidney function) is falling; Rajesh's MELD score (how ill a liver patient is) is rising. Press Next week and a new lab result arrives, the health watch assesses it, and the coordinator agent decides what to do about the patient's swap.

The coordinator is the one place where a language model drives an action. Each week it reads the patient's state and memory from the graph and picks one step: search for swaps (2-way first, then 3-way), form a swap, run tests, request papers, book surgery, or wait. It's a real MCP client. KindRed runs its own MCP server (37 tools) as a child process over stdio, and the coordinator lists and calls its case tools through the protocol. The model is Groq's openai/gpt-oss-120b, falling back to gpt-oss-20b when the first one is rate limited.

We ran both patients from week 0 to transplant on the live deployment, in a fresh private copy, with Groq answering. Every tool call went over MCP.

Sunita (kidney)

Week	Health watch saw	Coordinator did
1	eGFR 19, stage → Prepare	`find_swaps(2)` → 4 found; `form_swap` → S-0078, Chennai → Hyderabad → Mumbai
2	eGFR 18	`run_tests` → every lab crossmatch passed
3	eGFR 17	`request_papers` → consent, ID proof and relationship proof from P-0377
4	eGFR 16, stage → Act now	`book_surgery` → 22 Nov
5		Transplant done

Rajesh (liver)

Week	Health watch saw	Coordinator did
1	MELD 20, stage → Prepare	`find_swaps(2)` → 0, `find_swaps(3)` → 0, then the model's call failed and the rules ran the step: wait
2	MELD 22	`find_swaps(2)` → 0, `find_swaps(3)` → 2; `form_swap` → L-0037, Kochi → Bengaluru → Mumbai
3	MELD 25	`run_tests(L-0037)` → donor work-ups
4	MELD 26	`request_papers` → consent from P-5014, ID proof from P-0903
5		`book_surgery` → 29 Nov
6	MELD 27	Transplant done, 29 Nov

The presses of Next week we timed came back in about 2 seconds or less, model turns included.

Rajesh's week 2 is the one we like most. The 2-way search found nothing. One family further, the 3-way search found two swaps, and the coordinator formed L-0037. A 2-way-only matcher would have left him waiting.

The guardrails are code

The model never writes Cypher and never sees the raw pool. What keeps it honest is plain code:

One action per week, enforced by the MCP server. Calls in the same week share a session, so the rule holds for any MCP client, not only ours.
Every tool checks the graph before it acts. find_swaps refuses if the patient isn't waiting; run_tests refuses a loop that isn't this patient's.
The reason check. The model writes a one-line reason for the care team. Every id in it must appear in that week's tool result, or the reason is replaced with the result itself.
The rules as a safety net. If no model is configured, or the model fails, the rules run the same tools and the trace says so.

allowed = set(ask.ID.findall(json.dumps(did["result"] if did else {}, default=str))) | {p["pair_id"]}
stray = sorted(set(ask.ID.findall(reason.upper().replace("‑", "-"))) - allowed) if reason else []
if stray:
    note = f"The model's reason named {', '.join(stray)}, which this week's result doesn't show, so it was replaced by the result."
    reason = ""

We didn't stage any failures, and the run hit two anyway. In Rajesh's week 1, Groq returned an HTTP error after the two searches, and the rules ran the step instead (nothing was found, so: wait). In Sunita's week 1, the reason check fired. The search found four 2-way swaps, but form_swap hands the final choice to the optimiser, which picked a 3-way swap with Chennai and Mumbai. The model's sentence named P-1046, which wasn't in that week's result, so the page shows the result instead of the model's words. We'll take a strict check that sometimes throws away a sentence over one that lets an invented id through.

"The model's reason named P-1046, which this week's result doesn't show, so it was replaced by the result."

Ask KindRed: tools, not generated Cypher

Coordinators can ask questions in plain words: "What breaks if Bengaluru's P-0211 withdraws?" or "Which waiting families are hardest to match?". A model picks from 15 read-only graph tools, each a wrapper around named queries. Ids are resolved against the graph first, every answer shows its tool trace and the graph paths it rests on, and if the draft names an id no query returned, the raw results replace it.

Asking about a family that doesn't exist gets the honest answer instead of "no impact":

The model picked withdrawal_impact; the id lookup (Q36) found no such family, so nothing else ran.

Testing it live also turned up a bug. The model sometimes writes ids with a non-breaking hyphen, P‑0433 (U+2011) instead of P-0433. Ask KindRed's id pattern only matched the ASCII hyphen, so for that answer nothing got checked. The coordinator already normalised that character; Ask KindRed didn't. Our checks had only been tested with friendly input.

Memory is more nodes

Agent memory in KindRed isn't a separate store. It's more nodes and edges in the same FalkorDB server, one graph per patient:

What happened: each week the health watch writes a Finding linked BASED_ON the readings it used. In the exchange, failed tests are Failure nodes and FAILED edges.
What the agents believe: stage, trend and swap are Fact nodes. A new belief doesn't overwrite the old one. It SUPERSEDES it, and the old one stays with its date.
How to act: each stage has a Playbook of ordered Step nodes, which the health watch reads from the graph before handing work out.

// Q46 Replace one belief. The old fact stays, marked not current, behind a SUPERSEDES edge.
MATCH (me:Person {persona_id: $persona_id})
OPTIONAL MATCH (me)-[:KNOWS]->(old:Fact {key: $key, current: true})
WITH me, old
WHERE old IS NULL OR old.value <> $value
CREATE (me)-[:KNOWS]->(f:Fact {fact_id: $fact_id, key: $key, value: $value, text: $text, at: $at, current: true})
FOREACH (x IN CASE WHEN old IS NULL THEN [] ELSE [old] END | SET x.current = false CREATE (f)-[:SUPERSEDES]->(x))
RETURN f.fact_id AS fact_id

Sunita's beliefs in mem_sunita: each newer Fact is linked to the one it replaced by a SUPERSEDES edge.

Agents never call each other. When the health watch sees a more urgent stage, it writes one Task per playbook step, ASSIGNED_TO the scheduler, the committee clerk or the patient liaison, and they pick the tasks up on their next turn. Every agent step also stores what it read first and who wrote it. Before searching, the matching agent read one failed-link memory ("P-0211 → P-0388 (positive_xm)") and skipped that link. The Agents page draws all of this live from FalkorDB, and no line on it joins two agents directly.

Each box is an agent and each cylinder is a FalkorDB graph. Lines are writes, reads and Task hand-offs.

Many judges, one demo

During judging, two people might press Next week on the same patient. So "Make my own copy" rebuilds the whole demo in the visitor's own graphs (<copy>__exchange, <copy>__mem_sunita, …). The copy id travels in a header, and a context variable routes every query to that copy's graphs:

_world: contextvars.ContextVar[str] = contextvars.ContextVar("world", default="")

def real(graph: str) -> str:
    """The real FalkorDB graph name for a logical one ("exchange", "hosp_hyd", "mem_sunita") in the current world."""
    w = _world.get()
    return f"{w}__{graph}" if w else graph

Isolation doesn't depend on remembering a filter in every query. The query just runs against a different graph.

We also load tested it. Every family write is version-checked (Q01). With 16 agents updating one family at the same moment (160 updates), the check refused 1,498 stale writes, which were retried, and lost 0 updates. The same run without the check lost 138.

Through the whole API, using Artillery on one laptop, our first run managed 28 requests a second with a p95 of 25.6 s, and 575 of 1,590 visitors timed out. Profiling showed most of the time going to parsing FalkorDB replies in pure Python, and every visitor re-running the same whole-pool traversals. Adding hiredis and a small read cache that any write to the exchange graph clears fixed both:

Run	Requests/s	p95	Visitors timed out
First	28	25.6 s	575 of 1,590
With hiredis + cache	51.6	3.7 s	0

Afterwards, all 1,046 chat messages were in the graph exactly once. When 20 people pressed Next week on one patient in the same second, 1 moved the journey and 19 were refused.

We stopped FalkorDB to check it's doing the work

"The graph does the work" is a claim, so we stopped only the FalkorDB container and called the API. Health, pool, agents, patients, the family explorer and Ask KindRed all returned 500. No stale answers, and no model answering without the graph. The web app falls back to a clearly labelled recording of a real run, and its buttons say nothing can be rebuilt.

When we started FalkorDB again, the API recovered by itself in about 16 seconds. All 57 graphs were still there, including the private copy and its two FAILED edges, because FalkorDB wrote its snapshot on shutdown.

Things FalkorDB taught us the hard way

None of these threw an error, which is what made them expensive.

Results are capped at 10,000 rows by default. A big pool has more 3-way loops than that, and the extras just weren't returned. One line in schema setup fixes it: db().config_set("RESULTSET_SIZE", -1).
A variable-length path can't take a parameter. [:CAN_GIVE_TO*1..$hops] isn't accepted, so Q33 uses *1..3 and filters with WHERE length(path) <= $hops.
shortestPath only works in RETURN or WITH. Q34 computes the route inside the return expression.
An edge alias you never reference didn't get the constraints we expected. In cycle patterns, Q57 now references every edge alias in WHERE.
A MATCH straight after a WHERE could drop that filter. The liver integrity checks put a WITH after every filtered MATCH.
Chained OPTIONAL MATCH aggregations miscounted rows. We split link counts into their own query and gather antibodies before the other optional matches.

The lesson: test graph queries against answers you already know, not just for "no exception".

What we'd tell another team

Store the reason on the edge. Putting "why this donation works" on CAN_GIVE_TO gave us the hover explanations, the step-by-step walkthroughs, the decision trail and the risk flag that predicted the DQ7 failure.
Remember failures as structure. A FAILED edge is cheaper than any rule engine.
Search locally. A 2-hop repair took 55 ms and left 31 swaps alone. Re-planning the pool would have reshuffled families who were fine.
Constrain the action space, not just the prompt. One action per week on the server, preconditions in every tool and an id check on the model's reason caught real failures. Prompt wording didn't.

Limits

Synthetic data only. The generator reproduces published match rates (Saidman et al., 2006), but this isn't a clinical tool.
One backend process. The load test shows where that ends.
Free Groq keys hit rate limits quickly. KindRed falls back to a second model, then to the rules.
In our yearly simulation, failure-aware matching places fewer highly sensitised patients than a failure-blind matcher (39% vs 43%), because their links fail more often. Sunita is exactly that patient, and we haven't solved it.

Try it

Open the live demo and press Make my own copy in the top bar first, so your Next week presses don't move anyone else's patient. Then open Demo patients and walk Sunita or Rajesh to transplant, or open the Live map for the failed-swap story.

To run it yourself you need Docker Desktop:

git clone https://github.com/abhishiv17/Graph-hacks.git kindred
cd kindred
docker compose up --build -d

The app is on http://localhost:3001, FalkorDB Browser on http://localhost:3000 (try MATCH (a:Pair)-[f:FAILED]->(b:Pair) RETURN a, f, b on the exchange graph), and the API docs on http://localhost:8000/docs. The coordinator and Ask KindRed need a model: set GROQ_API_KEY and KINDRED_ASK_PROVIDER=groq in .env, or point it at a local Ollama model. Everything else runs without a key.

Stack: FalkorDB · Python 3.11 + FastAPI · OR-Tools CP-SAT · MCP Python SDK · Groq (gpt-oss-120b, gpt-oss-20b) · Sarvam for voice · Next.js + Tailwind · Docker Compose · AWS (EC2, API Gateway, VPC link) · Artillery · 79 pytest tests

Built by Team KindRed: Abhishek M Shivanagoudar, Afreen Hossain and Akshay R, for Graph Hacks 2026 by WeMakeDevs and FalkorDB.

Mergetober part 2: my plan was wrong twice, and a free trial caught it before the code did

Abhishek.M. Shivanagoudar — Wed, 14 Oct 2026 23:23:14 +0000

After my BambooHR connector, I picked up a second Mergetober issue: a Customer.io connector for cognee. Last time the lesson was "read the API before writing code". This time it was "test your plan before writing code", because my plan was wrong in public, twice.

The issue

cognee turns your data into a knowledge graph that AI agents can search. Issue #4786 asked for a connector for Customer.io, a marketing messaging platform. The idea: if your team's emails, push notifications and in-app messages live in Customer.io, your agent should be able to answer "what does our French welcome email say?"

I posted a plan on the issue: merge + tombstones like BambooHR, with a doc id of "action id + language" so translations wouldn't overwrite each other.

Honestly, I didn't expect to get it. I'd asked a maintainer on Discord whether we could comment on several issues at once, since a lot of people were doing it. The answer was yes, but issues go to the best proposal, and people who already have an issue assigned are lower priority so everyone gets a chance. I already had BambooHR. A few other people had posted plans on this issue too.

So I didn't comment on every issue I could find. I only commented on two in total, and I took my time on both plans.

Yesterday I checked my mail as soon as I woke up: "Issue assigned to @abhishiv17". That felt really good. 😄

A trial workspace before any code

I signed up for a free Customer.io trial and built a small test automation: one email in Default, English and French, plus a newsletter. Then I wrote a throwaway script that:

saved every API response as raw JSON (snapshot NAME),
printed what appeared, disappeared or changed between two snapshots (diff A B).

Keeping the raw responses turned out to matter. Fields I wasn't even looking at showed up in the diffs, and that's how most of the surprises below got caught.

A small tip if you try this: my trial account was "on hold" until verified. That only blocks sending. The App API worked fine.

Wrong #1: translations

My plan assumed one message comes back once per language. In reality, each language is its own action with its own id, linked by a multi_language_branch_action_id. The default language is "", not en. Adding "English" created a brand new action.

So the action id alone was already unique, and my "id + language" key wasn't needed. But then I found a collision I hadn't planned for: a newsletter's content and a campaign message were both id 5. They use separate counters. Doc ids got a type prefix: action:5, newsletter_content:5.

Wrong #2: `deduplicate_id`

My plan said deduplicate_id "looks like id + timestamp" and proposed using it to detect changes. Then action 5 came back as 4:1792011300. The prefix was the branch id, not its own id.

It got worse:

Publishing an edit to one language bumped updated on every language, even ones I didn't touch.
Adding a push step to the campaign bumped updated on all the existing emails, with nothing else changed.

Neither field could tell me "this content changed".

The open question, and changing one thing at a time

The issue suggested using the campaign's updated timestamp as the sync cursor. I wasn't sure editing a message actually moves it, so I'd said I'd check.

My first test was useless: in the same publish I edited a body and added a language. The campaign's updated moved, but I couldn't tell which change did it. I reran with a body-only edit. Result: the campaign's updated doesn't move when you edit a message. It only tracks structure (steps added or removed).

Lesson: change one thing per test, or the test can't answer anything.

Changing the design (again)

I first posted a fix on the issue: hash the message fields and re-ingest only when the hash changes. Then, while coding, it clicked.

I had copied my own BambooHR design (merge + tombstones), but the reason it fit BambooHR was its change feed. Customer.io doesn't have one. And since editing a message doesn't move the campaign timestamp, I have to list every message on every run anyway.

So the connector became a full snapshot, like cognee's Notion connector:

Every run lists everything, with replace. Anything that disappeared upstream is forgotten by cognee's cleanup.
Rows hold only the message text, no updated and no deduplicate_id. cognee already hashes each row, so an untouched message keeps the same hash and isn't processed again, even when Customer.io bumps its timestamp.
It works with cognee's default settings. No write_disposition="merge" for users to forget.

The one rule this brings: if a listing fails, the run must abort. A partial snapshot would make cognee forget messages that still exist.

The half-built SMS that broke everything

Then that rule bit me. I added a push step and an SMS step but left them unfinished, since both needed a provider set up.

Suddenly the campaign's actions list returned 500, every time. But each message still loaded fine on its own by id, except the empty SMS. Deleting the SMS step made the list work again.

With "abort on a failed listing", one half-finished draft would have blocked syncing the whole workspace. So now, on a 5xx, the connector fetches that campaign's messages one by one, and skips only the one that keeps failing. If nothing at all loads, the run aborts.

Cleaning up the text

body_plain comes back empty, so the connector converts the HTML body to text and strips the head, style and script tags, plus the unsubscribe footer Customer.io adds to every email. Otherwise every document in the graph would end with "Unsubscribe" (or "Se désabonner").

A few more things the trial showed: unpublished edits never reach the API (good, only published content goes in), a deleted newsletter just disappears and returns 404, and webhooks are refused because their bodies can carry tokens.

Testing

36 unit tests with a mocked API that copies the real response shapes, including a real load into SQLite.
I broke the code on purpose: the footer stripping, the 5xx fallback and the abort guard, one at a time. The tests caught each one. A test suite that passes on the first try proves nothing until you've seen it fail.
I also ran my own code over my saved snapshots. That caught a wrong claim in my own notes about which text had been published.
A live run against the trial made 3 API calls and staged exactly what I'd typed in the UI. The empty push was skipped, and there was no "Unsubscribe" anywhere.

id	channel	language	subject	text
`action:2`	email	default	hello	English version four
`action:3`	email	fr	bonjour	Version française une
`action:5`	email	en	hello	English version one
`action:9`	in-app	default		In-app body one

Then end to end on local Ollama (llama3.1:8b + nomic-embed-text, CPU only): the first sync took about 141s, and the second sync with nothing changed took 7s, because nothing was re-processed.

Windows gotchas (again)

Git Bash rewrote my API path. Passing /v1/... as an argument turned it into C:/Program Files/Git/v1/.... PowerShell didn't do that.
"Version franÃ§aise" in my output looked like an encoding bug in cognee. Printing the stored text with ascii() showed \xe7, a correct ç. It was just PowerShell decoding the output with the wrong code page. Check the bytes at each step before blaming the code.
And yes, I ran git init in the wrong folder again. 😅

Using it

await cognee.remember(customerio_source(), dataset_name="customerio")

You need an App API key (not the Track API keys). Setup steps are in the package README.

What I learned

Your plan is a guess until you test it. Correcting it in public with evidence is better than quietly changing the design in the PR.
Don't copy a design without its reason. Merge fit BambooHR because of the change feed. No feed here meant a snapshot was simpler.
Change one thing per test.
One broken item shouldn't stop everything.
Only claim what you've run. I removed two claims from the README that I hadn't actually tested.

What's next

The PR is up and waiting for review: cognee-community#388. Hoping it gets merged! 🤞

Thank you @dexters1 for assigning me the issue, and to the WeMakeDevs community for Mergetober. On to the next one.

Links

PR: https://github.com/topoteretes/cognee-community/pull/388
Issue: https://github.com/topoteretes/cognee/issues/4786
Part 1 (BambooHR): https://dev.to/abhishekm_shivanagoudar/my-mergetober-story-building-a-bamboohr-connector-for-cognee-4d1n
cognee: https://github.com/topoteretes/cognee

"My Mergetober story: building a BambooHR connector for cognee"

Abhishek.M. Shivanagoudar — Wed, 07 Oct 2026 22:27:58 +0000

This Mergetober I wanted to do more than fix a typo. I wanted to build something real, get it reviewed, and actually understand every line of it. I ended up building a BambooHR connector for cognee, and this post is the story of how it went, mistakes included.

Finding the issue

cognee is an open source project that turns your data into a knowledge graph AI agents can search, basically long-term memory for agents. It uses "connectors" to pull data in from tools like Notion, Gmail and Google Drive.

While browsing the issues I found #4795: add a connector for BambooHR, an HR platform. The idea was simple: if your company's employee directory and handbooks are in BambooHR, your AI agent should be able to answer "who works in Sales?" or "how many days of leave do we get?"

The issue suggested copying the existing Notion connector. Before commenting, I read through BambooHR's API docs and noticed something important: BambooHR has a change feed, an endpoint that tells you exactly which employees were added, updated or deleted since a given time.

The Notion connector re-downloads everything every run and replaces the old data, because Notion has no such feed. If I copied that approach but only fetched changes, every employee who didn't change would get wiped from memory. So in my comment I proposed using the change feed with a merge strategy instead, like the Gmail and Google Drive connectors do. I also asked what should happen to employees who leave the company.

That comment got me assigned. 🎉

Setting up (and immediately messing up)

My first hour was mostly Git mistakes:

I forked cognee instead of cognee-community. The issue lives in the main repo, but connectors actually go in the community repo.
I ran git init in the parent folder instead of inside the cloned repo.

Not my proudest moment, but it's the kind of thing you only do once.

Making a BambooHR trial account

I didn't have access to a real company's BambooHR (and wouldn't want to test on one anyway), so I signed up for a free BambooHR trial. It comes preloaded with around 118 fake employees and about 20 company files like handbooks and policies, which turned out to be perfect for testing.

I spent a while just calling the API by hand to see what it actually returns. That's where I learned two things that shaped the whole design:

The first sync doesn't need a separate endpoint. If you ask the change feed for everything since 1970-01-01, every employee comes back as "Inserted". One code path handles both the first sync and every sync after it.
BambooHR returns only the employee id unless you ask for specific fields. That meant I could make the connector private by default: it only ever requests safe fields like name, job title and department. Salary, SSN, date of birth and home address are never even fetched.

Building it

The connector syncs two things: the employee directory and company files (PDF, TXT, MD, CSV).

For employees, it uses the change feed and stores BambooHR's own timestamp as a cursor for the next run. That cursor is only saved once the whole run succeeds, so a crash halfway doesn't skip anything. Deleted employees are removed, and terminated employees (which BambooHR marks as Inactive) are forgotten by default too.

Files were trickier because BambooHR has no change feed for them. So each run lists all files, compares them with the previous run to spot deletions, and lets cognee skip files whose content hasn't changed.

Testing with Ollama on Windows

I didn't want to pay for API calls while experimenting, so I ran everything locally with Ollama, using llama3.1:8b as the LLM and nomic-embed-text for embeddings. This is where most of my debugging time went.

Ollama models "downloaded" but didn't exist. ollama pull said success, yet ollama list was empty. It turned out Ollama 0.40.0 stores model manifests as symlinks, and Windows 11 refused to follow them. Replacing the two symlinks with real copies of the files fixed it.

Windows' 260-character path limit. cognee's vector store creates deeply nested folders, and my long project path pushed it over the limit. Moving the data to a short folder fixed it.

The model returned the schema instead of the data. cognee asks the LLM for JSON in a fixed shape, and the small 8B model sometimes replied with the description of the shape instead. Adding this to .env solved it:

LLM_INSTRUCTOR_MODE="json_schema_mode"

Once it all worked, I loaded a few mock employees and a leave policy and asked:

"Who works in the Sales department?" → it named the right person.
"How many days of paid leave do employees get?" → "every employee gets 24 days of paid leave per year."

Then I deleted that Sales employee upstream, synced again, and watched cognee's document count drop from 4 to 3. Seeing it forget someone was honestly the most satisfying moment of the project.

Testing against the real trial

Next I ran the connector against my BambooHR trial four times, making changes in between:

Run	Employees fetched	What happened	Stored
1 (first sync)	108	Deleted and inactive sample employees skipped	88
2	20	Picked up my edits	88
3	5	One deleted, one terminated	87
4	2	Caught an employee I terminated while run 3 was still running	86

Run 4 was a nice confirmation that saving the cursor only at the end really works: nothing slipped through.

The trial also surprised me. One of the sample files was a Benefits CSV with per-employee data in it. My field allowlist protects the employee directory, but it can't protect against a file like that. So I added a file_categories option to let you choose exactly which file folders get synced. Another sample PDF turned out to be genuinely corrupt, so I made sure broken files are skipped with a warning instead of crashing the run.

Alongside the live tests I wrote 33 unit tests with a mocked API, so reviewers can run them without a BambooHR account.

Opening the PR

I opened the PR… and CI failed immediately. The repo requires a DCO sign-off on every commit, which I'd never heard of. The fix:

git rebase --signoff upstream/main
git push --force-with-lease

How to use it

If your team uses BambooHR, here's all it takes:

cd packages/connector/bamboohr && uv sync
export BAMBOOHR_COMPANY_DOMAIN=acme   # from https://acme.bamboohr.com
export BAMBOOHR_API_KEY=...           # BambooHR → your name → API Keys

import asyncio
import cognee
from cognee_community_connector_bamboohr import bamboohr_source

async def main():
    await cognee.remember(
        bamboohr_source(),
        dataset_name="bamboohr",
        primary_key="id",
        write_disposition="merge",  # important: cognee's default is replace
    )

    answer = await cognee.search(
        query_text="Who works in the Sales department?",
        query_type=cognee.SearchType.GRAPH_COMPLETION,
        datasets=["bamboohr"],
    )
    print(answer)

asyncio.run(main())

Run remember again anytime and only the changes are synced. You can also pass include_inactive=True to keep former employees, or file_categories=["Company Files"] to limit which files are synced.

What I learned

Read the API before writing code. One look at BambooHR's change feed changed the whole design, and it's what got me the issue.
A trial account beats mocks. The broken PDF, the Benefits CSV and the inclusive timestamps only showed up with real-ish data.
Local LLMs are great for learning, as long as you're ready to debug your OS along the way.
Privacy is easier to design in than to bolt on. Never requesting sensitive fields is safer than filtering them out later.

Thanks to the cognee maintainers for the guidance on the issue, and to the WeMakeDevs community for Mergetober pushing me to ship something real.

Links

Mergetober #WeMakeDevs #OpenSource

Building CampusEvac | How We Won Best UI at First Commit

Abhishek.M. Shivanagoudar — Thu, 01 Oct 2026 10:07:30 +0000

Two perspectives, one shared emergency, and the engineering behind a real-time evacuation simulation.

A fire evacuation is not just a problem of finding the nearest exit. It is also a problem of understanding what is happening across a building, communicating information, and coordinating people who see the same emergency from different perspectives.

We wanted to explore that problem through a browser-based simulation.

CampusEvac was our attempt to turn an evacuation drill into an interactive, real-time experience. One participant navigates the building as an evacuee, while another observes the scenario as a warden. Both interact with the same simulation, but neither sees it in quite the same way.

We built CampusEvac during First Commit, a WeMakeDevs hackathon, and our project was recognised in the Best UI track.

This is a look at the problem we chose, the architecture behind the application, the design decisions that shaped the experience, and what building a real-time product taught us.

Why Build an Evacuation Simulator?

Emergency preparedness involves more than documenting procedures. People need opportunities to understand their environment, practice decisions, and become familiar with how an evacuation might unfold.

Physical drills serve an important purpose, but organising them requires coordination and a suitable environment. We wanted to explore how a browser-based simulation could provide another way to practise and understand evacuation scenarios.

That led us to a question:

What if two people could participate in the same evacuation drill from completely different roles, directly in their browsers?

The answer became CampusEvac.

Instead of creating a static building map or a conventional monitoring dashboard, we designed a two-player experience with a shared environment and role-specific interfaces.

The project had three central requirements:

A navigable building environment for the evacuee.
An overhead monitoring interface for the warden.
Real-time communication so that both participants could interact with the same evolving simulation.

These requirements shaped both our interface design and our technical architecture.

Two Roles, Two Different Interfaces

One of the most important decisions was to avoid treating the evacuee and warden as two versions of the same user.

They have different responsibilities, different information needs, and different ways of understanding the building.

The evacuee: navigating the situation

The evacuee interacts with the environment from a first-person perspective.

The interface needs to keep the building and navigation experience central, allowing the participant to understand their surroundings and make decisions without unnecessary interface clutter.

The warden: understanding the bigger picture

The warden sees the building from an overhead perspective.

Rather than navigating from ground level, the warden needs to understand the broader scenario and observe what is happening across the environment.

That calls for a different information hierarchy, a different layout, and controls designed around monitoring rather than first-person movement.

Why the distinction matters

A role-based application should not simply change a heading or swap a few buttons when the user changes roles.

The interface should reflect what that person needs to accomplish.

For CampusEvac, we treated the two perspectives as complementary parts of the same experience. The evacuee focuses on navigating the environment; the warden focuses on observing the wider situation.

This principle extends to many other applications, from collaborative tools to logistics dashboards and real-time monitoring systems.

The Real-Time Problem

Two browser windows showing the same building do not automatically create a shared simulation.

When participants interact independently, the application needs a way to communicate changes, manage connections, and keep the experience coherent.

For CampusEvac, we used AWS AppSync Events for real-time communication and Amazon DynamoDB for application state.

At a high level, the architecture consists of three main parts:

Component	Responsibility
Browser application	Provides the evacuee and warden interfaces
AWS AppSync Events	Enables real-time communication between connected participants
Amazon DynamoDB	Stores application state persistently

The distinction between real-time communication and persistent state is important.

A message can communicate that something has changed, but a message and a durable record of application state are not the same thing. A robust implementation needs to define which information is persisted, how updates are propagated, and what happens when a participant disconnects and returns.

These questions become especially relevant in collaborative applications, where the experience depends on multiple clients interacting with shared state.

Our architecture gave us a foundation for combining a browser-based simulation with AWS-managed real-time communication and persistence.

Why UI Was More Than Visual Polish

The Best UI track gave us a reason to look closely at what makes an interface effective in the first place.

It is tempting to equate good UI with gradients, animations, typography, and polished components. Those elements can contribute to the experience, but they do not replace clear interaction design.

CampusEvac has an additional challenge: the interface needs to communicate a situation that changes over time.

The evacuee needs an interface that supports navigation. The warden needs an interface that supports observation. Both need to understand that they are participating in the same simulation.

That makes several design considerations particularly important:

Role clarity. Participants should be able to understand their responsibilities from the interface they are using.

Information hierarchy. The most relevant information should be easy to distinguish from secondary controls and status indicators.

Contextual feedback. Changes in a shared environment need to be communicated clearly enough that participants can understand what has happened.

Functional consistency. The interface should remain understandable while the application is running, not merely in a static screenshot.

The central idea is that UI quality depends on how effectively an interface supports its intended task.

A visually polished interface is useful. A visually polished interface that also communicates the system's behaviour is more useful still.

Building Under Hackathon Constraints

Hackathons require teams to make decisions quickly. There is limited time to explore a problem, choose a stack, implement the main experience, integrate services, test the application, and prepare a demonstration.

For CampusEvac, we concentrated on the core interaction: two roles, two perspectives, and one shared simulation.

We also incorporated AI coding agents into our development workflow.

These tools helped accelerate implementation, but generating code was only one part of the process. The application still needed architectural decisions, integration work, and testing across its different components.

A component can render correctly on its own while the complete application behaves incorrectly when two participants interact simultaneously.

That distinction matters particularly in real-time systems. Testing an individual interface is not a substitute for testing the relationship between connected clients.

Our experience reinforced a useful principle: AI-assisted development can reduce implementation effort, but it does not remove the need to understand the system being built.

The quality of the result still depends on defining the problem clearly, making sound decisions, and verifying that the pieces work together.

What We Would Improve Next

CampusEvac gave us a working foundation, but a simulation of this kind has several areas worth exploring further.

Some possible directions include:

Larger building scenarios: More detailed environments that allow for varied evacuation routes and layouts.
Clearer monitoring interfaces: Better ways to communicate the overall state of a drill without overwhelming the warden with information.
Reconnection handling: More robust behaviour when a participant leaves a session and later returns.
More extensive real-time testing: Testing concurrent interactions, changing connection states, and the consistency of shared information.

These are potential improvements, not claims that every feature is already implemented.

The broader challenge is to make the simulation useful beyond a successful demonstration: predictable behaviour, understandable interfaces, and a system that remains coherent when real users interact with it.

The Result: Best UI at First Commit

CampusEvac was recognised in the Best UI track at WeMakeDevs' First Commit hackathon.

For us, the project brought together several areas of engineering: interface design, browser-based interaction, real-time communication, persistent state, and AI-assisted development.

The recognition was a milestone, but the process was equally valuable. It gave us an opportunity to think about how design decisions affect a product's functionality and how architectural choices influence the experience users ultimately see.

I'm grateful to WeMakeDevs for the opportunity to participate, and to my teammates Afreen and Akshay for building CampusEvac with me.

Try CampusEvac

The best way to understand the project is to explore the two perspectives and see how they fit together.

Live demo: Explore CampusEvac
Demo video: Watch the walkthrough
wemakedevs: showcase

CampusEvac started with a simple idea: make an evacuation drill interactive and shared. Building it taught us how much work goes into connecting the interface, the underlying system, and the experience of the people using it.

That is what made this project worth building.

Built by Abhishek M. Shivanagoudar, Afreen, and Akshay for WeMakeDevs First Commit.

DEV Community: Abhishek.M. Shivanagoudar

"KindRed: when a kidney swap breaks, the graph finds another way (built on FalkorDB)"

Why India needs this

Swaps are cycles

One FalkorDB server, many graphs

The multi-hop queries

One failed match, end to end

An agent that runs the case, over MCP

The guardrails are code

Ask KindRed: tools, not generated Cypher

Memory is more nodes

Many judges, one demo

We stopped FalkorDB to check it's doing the work

Things FalkorDB taught us the hard way

What we'd tell another team

Limits

Try it

Mergetober part 2: my plan was wrong twice, and a free trial caught it before the code did

The issue

A trial workspace before any code

Wrong #1: translations

Wrong #2: deduplicate_id

The open question, and changing one thing at a time

Changing the design (again)

The half-built SMS that broke everything

Cleaning up the text

Testing

Windows gotchas (again)

Using it

What I learned

What's next

"My Mergetober story: building a BambooHR connector for cognee"

Finding the issue

Setting up (and immediately messing up)

Making a BambooHR trial account

Building it

Testing with Ollama on Windows

Testing against the real trial

Opening the PR

How to use it

What I learned

Mergetober #WeMakeDevs #OpenSource

Building CampusEvac | How We Won Best UI at First Commit

Why Build an Evacuation Simulator?

Two Roles, Two Different Interfaces

The evacuee: navigating the situation

The warden: understanding the bigger picture

Why the distinction matters

The Real-Time Problem

Why UI Was More Than Visual Polish

Building Under Hackathon Constraints

What We Would Improve Next

The Result: Best UI at First Commit

Try CampusEvac

Wrong #2: `deduplicate_id`