Introduction
HeapDB is an open-source database for timestamped events. Name an outcome, and it ranks the earlier events most likely to explain or serve it, each with a score and its evidence.
Abstract
We built HeapDB around one operation. You give it an effect or a question, and it returns the items most likely to explain it right now, ranked, each with its explanation. With SQL you describe the rows you want, and with vector search you get the items similar to your query. With HeapDB you name an outcome, and it ranks the earlier events most likely to explain or serve it at this moment.
The lead use case is code changes and incidents: errors spike on checkout, and HeapDB ranks the merged PRs, deploys and config changes before it by how likely each is to explain the spike, with the evidence for each. The same engine powers AI agent memory: heapdb-memory ranks an agent's memories by relevance, importance and learned usefulness, explains every recall, and learns from which memories the agent actually used.
The score behind that answer is time-varying (it depends on when the question is asked), query-dependent (an error spike and a latency spike implicate different changes), and learned (confirmed answers strengthen links). We make that score first-class and build storage, pruning and an API around it. Our running example is an error spike on checkout. The naive answer is the last deploy. HeapDB's answer is the change that falls in the right lag window and has features that have caused spikes before.
Motivation
Existing stores rank by a score that's fixed at write time or computed from scratch at read time, and neither fits attribution questions. A sorted set needs every key rewritten as time passes. A search engine with decay functions rescores every candidate on every query and has no notion of a causal lag or of learning from a confirmed answer.
| Store | Primary question | Score | What it lacks for attribution |
|---|---|---|---|
| B-tree / KV | Which record has key K? | None | Ranking of any kind |
| Search engine | Which documents match terms T? | Relevance, optional decay | Lag windows, learned links, early stop on bounds |
| Vector DB | What is similar to V? | Distance | Time and causality |
| Sorted set / priority queue | What has the highest static score? | Written once | Scores that move with time and with the question |
| HeapDB | What most likely explains E, now? | Kernel(lag) × link × weight, learned | — |
The gap shows up wherever people ask why about a recent stream of events: a symptom after meals, a latency spike after deploys, a bill jump after resource changes. Teams rebuild the same pipeline each time: an event log, a window query, a hand-tuned ranking and no feedback loop.
Code changes are where this matters most today. With AI coding tools merging many more PRs, "which change most likely broke this?" and "which open PR deserves a careful review?" are daily questions. We map the same gap across other domains in Use cases, and the use-case examples walk you through each one with setup, explanation and benchmarks. To try it first, open the interactive demo or go straight to Getting started.