Anam

anam: Irish for soul.

A personal, longitudinal record of one person’s life, kept as immutable facts. Health readings, workouts, medicines, lab results, trips, documents and notes land on one timeline, each with where it came from and when it was true. The current state is derived from the facts, every cache of it is rebuilt by replay, and nothing is ever overwritten.

This is a personal project, published so others can read it and borrow from it. The sources, units and time zone in the examples are the author’s.

The inspector, served by the daemon, over a month of made-up facts. Each mark is a facet at its fact time; the green strip is the checkpoints.

Ideas

• The whole-person timeline is the default read. A trip, an illness or a training block is an optional lens over it, never a requirement.
• Facts accrete. A correction is a new version beside the old one. --as-of shows what Anam knew at any earlier moment.
• Two clocks. Fact time is when something was true. Anam time is when Anam learned it.
• One way in. Every fact arrives through an admission gate that checks it against a Definition, so a bad row never enters the record.
• Proof of what was shown. A projection prunes the timeline for a reader, and a receipt proves exactly what it served.
• Anam reads no source itself. Importers do that, and the facts can be resent from them. What Anam authors, and what a person says straight into it, come back from the backup.

Four words the commands print

The ledger is the record: an append-only file of facets. W is the watermark, the position of the newest event in it, and every answer says the W it stood on. The fold is the current value worked out from the ledger, and the canonical is that value’s hash: it moves when a fact lands and is the same after a rebuild from source. Checkpoints cache the fold by month, so a read need not replay everything.

Quick start

You need Go (see go.mod for the version). Nothing here needs another machine or a token; everything runs on loopback against two SQLite files.

make build

# person_id has no default on purpose: it is pinned into the ledger at init, so a
# defaulted one would name a person nobody chose for the life of the file.
export ANAM_PERSON_ID=me

# The ledger and the operational store are two SQLite files. Both default to
# ~/.local/share/anam/ (ledger.db and tracking.db); override with
# ANAM_LEDGER_PATH and ANAM_DB_PATH.
./anam init

# Run the daemon. On loopback it needs no token. Leave it running and use another terminal.
./anam daemon
curl http://127.0.0.1:8787/healthz                 # ready
ANAM_SERVER=http://127.0.0.1:8787 ./anam status   # the ledger id, W, and each importer's last batch