Ali Husain Software engineer and product designer

02 Intelligence/Holdfast

Holdfast

Command-line tool · open source

A memory for coding agents in which every fact carries its own proof.

Holdfast's ledger after two changes to the machine: three facts are no longer true, each with the proof that failed, and the answer an agent is given beside the stale notes file.Holdfast's ledger after two changes to the machine: three facts are no longer true, each with the proof that failed, and the answer an agent is given beside the stale notes file.
Holdfast's ledger on a phone: three broken facts, each struck through with the reason.Holdfast's ledger on a phone: three broken facts, each struck through with the reason.
Recall on a phone: a notes file still says Go is pinned to 1.24, and Holdfast answers that the fact is broken.Recall on a phone: a notes file still says Go is pinned to 1.24, and Holdfast answers that the fact is broken.

An agent's notes go stale without a sound: the port moves, the version is bumped, the service goes away, and the note still reads as true. Holdfast stores each fact with a check that proves it and runs that check again before the agent is told anything. What no longer holds comes back as broken, with the reason. A fact whose check fails cannot be stored at all, and a check only touches what a person allowed.

1,651
automated tests, run on Linux and macOS
10
kinds of check, from a line in a file to a live endpoint
4
tools an agent calls: remember, recall, verify, retract
0
Go dependencies: one static 8 MB binary

Why it exists

A coding agent keeps notes between sessions: the API's port, the Go version, how a release is cut. Each is right on the day it is written. Then someone upgrades Go, nothing tells the notes, and the next session acts on something that stopped being true.

What it does

Holdfast is a memory in which every fact carries a check that proves it, such as contains go.mod "go 1.24". The check runs before the fact is stored and again before an agent is given it (an answer from the network may be up to 30 seconds old). What stopped being true comes back marked BROKEN, with what the check found instead.

It is one binary: a command line, a tool server for agents (the Model Context Protocol) and a browser ledger.

How it is built

  • One check gates both doors

    The same check is the gate for storing a fact and for getting it back, so an agent cannot store a guess as proved.

  • A grammar, never a shell

    A check is one line in a grammar of ten kinds, parsed when stored and never passed to a shell.

  • Only a person widens it

    A policy file says what checks may touch. None of the agent's four tools can change it, and a cloned policy grants nothing extra until approved on that machine.

  • Facts in git, proof at home

    Facts are a committed file that merges without conflicts. Evidence stays out of git, because proof is about one machine at one moment.

How I know it works

1,651 tests
1,614 Go test cases, run with the race detector on Linux and once more, without it, on macOS, plus 37 for the page.
5 scenarios
End-to-end runs against the binary that ships, including an agent calling the tool server.
2 reviews
Two independent reviews before the first release. Every issue they found is held by a regression test.

What was hard

A check that did not finish

I mean HOLDS to say a fact was proved moments ago. A review before the first release found a case where it did not: when a call ran out of time, facts whose checks had not finished kept their last status, so one was shown as HOLDS under "Proved again just now".

Such a fact is now labelled TIMED OUT, and holdfast check exits 1. A review also read the JSON: the status word still said holds, with the truth in another field. It is now written as timed_out.

Limits

  • An agent that also has a shell can edit the policy file itself.
  • Recall matches words, not meaning: database does not find a fact that says only Postgres.
  • A fact with no check is only a note: nothing proves it, and it goes stale after 30 days by default unless a person vouches for it.
  • It does not run on Windows.

Also in Intelligence

Open to remote work.

ali@gallowforge.dev