Sign in
Docs Contents

HeapDB docs

Here’s how HeapDB works and how to run it. We cover the design of our time-aware ranking engine and the database we’re growing it into, the code-change, incident and agent-memory use cases, the engine you can install today, and the connectors, available on request.

Read the introductionGetting startedCode changes
  1. IntroductionHeapDB 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.
  2. Why not Postgres, Redis or your own code?You can write time-aware ranking in SQL or application code. HeapDB packages the parts that are tedious to get right and keep right.
  3. Getting started with heapdb-coreInstall heapdb from PyPI, run the quickstart and the examples, and build from source to contribute.
  4. What's availableWhat you can run today, from the engine and server to HeapDB Cloud, the integrations and agent memory, and what's coming next.
  5. ConnectorsConnectors turn Sentry, PostHog, Kafka, OpenTelemetry, GitHub and any JSON source into HeapDB events, effects and feedback. HeapDB Cloud runs them for you; the self-run connectors are available on request.
  6. Use cases across domainsEvery use case has the same three parts — an event stream, an effect asked about later, and a ranked, explainable answer.
  7. Data modelHeapDB stores four things — events, effects, links and kernels — and scores each event against a question.
  8. Core algorithmsA time-invariant key for pure decay, and bounded segment scans for lag kernels.
  9. Learning loop and explanationsFeedback turns “the last thing I ate” into “the last thing I ate that usually does this to me.”
  10. Design scopeWhat HeapDB is designed for, how to read a score, how it learns from feedback, and which tools to pair it with.
  11. BenchmarksMeasured, not promised. The Rust engine (0.5) is faster than SQLite and PostgreSQL at every size measured, 16× faster than SQLite at p50 on 1M events and 36× on 10M.
  12. Storage, distribution and system architectureA HeapDB node is a set of entity shards; each shard runs write, read and learn paths over the same data.
  13. Query language and APIThree verbs cover the surface — insert events, ask for top causes, and give feedback.
  14. Related work and positioningEach ingredient exists elsewhere. We built the combination, designed around one score.
  15. Open problems, privacy and roadmapWhat we're working on in learning and calibration, how privacy is built into the data model, and what comes next.
  16. HeapDB CloudHosted HeapDB databases with a connection URL, API keys, hosted connectors and usage-based plans, in early access, on the open-source heapdb-server data plane.
  17. Self-hosting with heapdb-serverRun heapdb-server, the same data plane behind HeapDB Cloud, on your own infrastructure. It's on heapdb-core main (0.6.0), with an edge container image.