tie – tie

Tie it all together

Thu, 12 Nov 2026 00:00:00 +0000

tiedb.com used to be a single page about a key-value-value store and a recipe example. The project is now three things that belong together:

tie, a content-addressed library where tags are a filesystem;
the tie apps, five native tools that use it;
anneal, a coding agent that stores its session memory in it.

This site is the front door. It is built with Hugo and Hextra, it has no analytics, no CDNs and no web fonts, and its screenshots are generated from the real applications by scripts in the repository. If a page and the app disagree, the app is right and the page is a bug.

The plan is simple: a landing page that explains the idea, a page per app that shows the actual UI, documentation that is useful, and stories that say what was measured and what was reverted. There is a brand page with the logo family, a glossary, and a 404 page that is a tag query.

The old page is not lost. The pasta-and-basil example still explains a triple better than any diagram, so it lives on in Triples 101. The name moved on; the idea didn’t.

The logo that was a bug

Tue, 10 Nov 2026 00:00:00 +0000

anneal’s logo was drawn as a thin amber outline of an A on a dark rounded tile: two legs, a crossbar and a small white dot on the apex. In the app it looks like a fat, solid amber shape with a pinhole. That is not what the SVG says.

The cause is a rendering bug. Fyne rasterises SVG with oksvg. In oksvg/svg_path.go, DrawTransformed applies the transform matrix to the path points, but calls SetStroke with the raw LineWidth. The stroke is therefore always 10 device pixels, regardless of the scale.

In anneal’s 26 px activity rail, a 10 px stroke is 38% of the icon. On the 128-unit viewBox that is a stroke width of 49.2, not 10. The thin outline fills in: the crossbar disappears, the upper counter closes, a small notch remains between the legs, and the apex dot becomes a white pinhole. The amber nearly reaches the tile edges.

It looks good. It is also fragile: at a different display scale the stroke would be proportionally thinner, and if the bug is ever fixed the logo turns back into an outline. So the site does not depend on the bug. The marks are drawn with the heavy geometry directly, as strokes with stroke-width="49.2" (rendered correctly by every browser), and the generator includes a fidelity check that compares the result with the app’s actual 26 px render.

That gave us a family rule:

a 128-unit tile, #181819, radius 28;
one heavy stroke, round caps and joins;
one white pinhole on the shape;
a silhouette that survives being filled in.

The marks are the A for anneal, a bow tie for tie, a folder for tie-fm, headphones for tie-audio, a star for tie-view, two peaks for imgview and a map pin for tie-browser. The palette is anneal’s: teal, amber, and a small set of saturated hues for the apps.

The brand page has the downloads and the full family. The generator is in tools/; the contact sheet is one make logos away.

Halving the heap

Thu, 05 Nov 2026 00:00:00 +0000

The real benchmark library is 7.4 GiB on disk with 60.7 million entries and 98.2 million associations. Loading it used to take 19.4 GiB of heap. The optimization note in the source repo is a record of what actually moved the number.

At 1M triples, the heap went 862 → 786 → 633 → 473 MiB — a 45% reduction — and objects per triple went from 21.5 to 10.0. Three changes did most of the work:

A TYPE_HASH record. Hashes were being stored as strings in the trie. A raw 32-byte record cut the heap by 28% at 100k triples.
Interning the trie chunks. Identical chunks in different levels are referenced in memory but written to disk, which is the same trade the original design made for strings.
Sharding the outer tree. Load time went from 4m32s to 2m46s (−39%) and the peak heap came down with it.

Two other experiments were reverted. They looked better in a microbenchmark and were worse on the real database. The note says why, and that is the point:

Measure both axes on the real DB. Guessing that a design “should” be better is not sufficient.

The opt-in reverse index saves about 29% of heap. That is a real trade: reverse queries become fast, but the index is opt-in per relation and the server’s default subset is deliberately small (tag,path,parent,tie-type,version-of,member-of).

The full note, including the two reverted experiments, is docs/memory-optimization.md.

Why triples, and why not just SQL

Sun, 01 Nov 2026 00:00:00 +0000

There is a section in tie’s internals note called “Why triples, and why not just SQL”. It contains this sentence:

We rebuilt a database… SQLite provides all of that for free.

That is the right place to start, because the interesting part of tie was never the triple store. It is the combination of a content-addressed blob store and a FUSE tag tree, joined by the content hash. The triple store exists because the schema is open and the core query is a reverse tag lookup, but a project that only wanted a database should use SQLite.

What triples buy in practice:

No migrations. A new relation is just a triple. The apps add rating, member-of, play-count, thumbnail, dimensions without a schema change.
Multi-valued by default. A file has many tags and many paths. In SQL this is a join table; here it is the native shape.
Reverse queries are the point. “Which files have this tag?” and “which scenes use this photo?” are the same operation, and the opt-in reverse index makes it cheap.
A path is a query. The mount turns the index into a directory tree. That is not a SQL feature; it is the API the apps and the file manager share.

The cost is also real: a custom storage engine, a custom query path, a custom fsck. The note documents the trade, including RDF/SPARQL and Datomic as prior art.

If you are choosing a database for a new project, read the note before choosing this one. If you want your photos, music and files in one place with tags that outlive the paths, the combination is worth it.

docs/internals.md

81 findings, 81 regression tests

Tue, 20 Oct 2026 00:00:00 +0000

In October 2026, tie got a full code review: 81 findings across the storage engine, the HTTP layer, the mounts, the importers and the tests. The rule for the fixes was simple and slow:

one commit per issue;
a regression test that fails before the fix;
the fix, and the test passes;
no drive-by cleanups in the same commit.

The categories were the usual ones for a young storage project: error paths that lost the error, lock ordering, partial writes on a full disk, path traversal in archive extraction, a cache that could return a stale size, and a handful of places where a context was not threaded through a retry.

None of it is glamorous. All of it is why the library now has a verify command you can trust, a filehost that treats its input as untrusted, and a test suite that includes the bug that was fixed.

The full review is in the source repo (docs/code-review.md). It is worth reading as a picture of what “done” meant at that point, not as a list of current bugs.