Pages on HyperCrux.com

About

Mon, 01 Jan 0001 00:00:00 +0000

HyperCrux.com is the home of HyperCrux, a small database where every record has four handles. You can look a record up by its key, query it with SQL, follow its links to other records, or find it by how close its vector is to a question. All four reach the same records, in one SQLite file, so they always agree.

Why It Exists

Apps that use AI tend to spread one set of facts across three systems. The records sit in a regular database. Their embeddings sit in a vector database, so the app can search by meaning. The connections between them sit in a graph database. Every change then has to be copied from one to the others, and sooner or later a copy goes missing. Search finds a document that was deleted. A link points at a record that isn’t there. For a small team, that’s three systems to run and a sync job to babysit, often for a few thousand documents.

Contact

Mon, 01 Jan 0001 00:00:00 +0000

HyperCrux.com would like to hear from:

Anyone trying HyperCrux out. What worked, what got in the way, and what you used before.
Anyone who found a bug. A search that missed a closer record, a link that outlived its record, an error you didn’t expect.
Anyone with an idea for something HyperCrux should do, or a language it should have an example for.

Write to info@hypercrux.com.

Bug reports are also welcome on GitHub. It helps to include what hypercrux version prints, your operating system, and the steps that show the problem. Please don’t send real customer data: a few made-up records that show the same thing are enough.

Download HyperCrux

Mon, 01 Jan 0001 00:00:00 +0000

The hypercrux command is one file with nothing else to install. Each archive below holds it with its license files. The links always point to the latest release.

System	Download
Linux, x86-64	hypercrux_linux_amd64.tar.gz
Linux, ARM64	hypercrux_linux_arm64.tar.gz
macOS, Apple silicon	hypercrux_darwin_arm64.tar.gz
macOS, Intel	hypercrux_darwin_amd64.tar.gz
Windows, x86-64	hypercrux_windows_amd64.zip

Checksums are in SHA256SUMS. Every release is listed on GitHub.

Install

On Linux or macOS:

tar -xzf hypercrux_linux_amd64.tar.gz
sudo mv hypercrux /usr/local/bin/
hypercrux version

The Linux binaries are static, so they run on any distribution. The macOS binaries aren’t signed by Apple, so macOS may block the first run; allow it in System Settings under Privacy & Security, or run xattr -d com.apple.quarantine hypercrux. On Windows, unzip the archive and put hypercrux.exe in a folder on your PATH.

Quick Start

Mon, 01 Jan 0001 00:00:00 +0000

HyperCrux is a database where every record can be reached four ways: by key, by SQL, by following links and by similarity. This page takes you from nothing to all four in a few minutes, from the command line, from Go and from any other language.

1. Get the hypercrux Command

Download the archive for your system from the download page, unpack it and put hypercrux somewhere on your PATH. Check it works:

Reference

Mon, 01 Jan 0001 00:00:00 +0000

Everything HyperCrux offers, in one place: the Go calls, the commands, the SQL functions and the rules for keys, fields, links and vectors. The README on GitHub explains each of them at more length, and FORMAT.md describes the file for programs that write it without HyperCrux.

The Rules

Keys are written table:id, such as docs:7. The table name is lower-case letters, digits and underscores, starting with a letter, up to 63 characters. Anything can follow the colon, up to 1,024 bytes for the whole key. A key never changes.
Fields are the table’s columns. A put sets the fields it’s given, leaves the others alone, and adds a column for a field the table hasn’t seen. Setting a field to null clears it. Maps and lists are stored as JSON text.
Vectors go in the field vec, stored as float32 values. The first vector in a table sets the size for the whole table. A vector can’t be empty, all zeros, or contain NaN or infinity.
Links go one way, from one record to another, with a type of 1 to 200 characters, such as owns or cites. Both records must exist. Deleting a record deletes its links.
Distance is cosine distance: 0 for the same direction, 1 for unrelated, 2 for opposite. Search compares every vector that passes the filter, so results are exact.

Go

go get github.com/hypercrux/hypercrux

Call	Does
`Open(path)`	Opens a file, creating it if needed
`Get(key)`	A record’s fields, or `ErrNotFound`
`Put(key, fields)`	Creates or updates a record
`Delete(key)`	Deletes a record and its links
`Scan(prefix, after, limit)`	Records whose keys start with `prefix`, in key order
`Exec`, `Query`, `QueryRow`	Plain SQL, with HyperCrux’s functions available
`Link(from, type, to)`	Links two records
`Unlink(from, type, to)`	Removes a link. An empty type removes every type
`Neighbours(key, dir, type)`	A record’s links: `Out`, `In` or `Both`
`Walk(key, dir, type, depth)`	Every record up to `depth` links away, nearest first
`Nearest(table, vector, k, where, args...)`	The `k` closest vectors, with an optional SQL filter
`Update(func(tx) error)`	Runs a function as one transaction. `Tx` has all the calls above
`Adopt(table)`	Makes a table created with plain SQL a record table, or brings one back in step after a schema change
`Drop(table)`	Deletes a record table with its records and their links
`Check()`	Confirms keys, rows, links and vectors agree

Errors that break a rule wrap ErrInvalid, and missing keys, links and tables wrap ErrNotFound. The full documentation is on pkg.go.dev.