01A database you can open in a text editor
Most databases keep your data in a format only the database program understands. A TTDB is a Markdown file, the same plain format used for README files and notes apps. You can open it in Notepad, email it, print it, or look at what changed in version control. Nothing is hidden.
The example running here is the notebook of a small garden robot looking after one backyard bed. It has four parts, always in the same order:
- A title, the line starting with
#. - A settings block (
mmpdb). It holds the database's name, its rules, and whose point of view it is written from. - A cursor block, which records what the reader is looking at right now (more on that below).
- Records, one note each, separated by
---lines.
The settings block also says whose world this is. TTDB calls this the umwelt, a word biologists use for the world as one particular creature experiences it. A tick, a bat and a person standing in the same field each live in a different umwelt. A TTDB never claims to hold the objective truth. It is one librarian's view, written down, and every link in it is that librarian's claim. Here the librarian is the garden robot.
02Every note has an address on a globe
Each record starts with an ID that looks like a map coordinate: @LAT40LON0 means latitude 40, longitude 0. The globe isn't Earth. It's a map of what the librarian knows, and the settings block says how to read it. For the garden robot, north is sunny and south is shady; west is down in the soil and east is up in the air. Things that belong together end up near each other, and empty parts of the globe show what the librarian hasn't learned about yet.
An address never changes once it's given out. If the librarian changes its mind, it writes a new record and links it to the old one, so the history stays readable.
What if two notes want the same spot? TTDB has a fixed rule for it, called southeast_step: if the spot is taken, move one step on both axes and try again. Because the rule is fixed, two devices that never talk to each other will still give the same note the same address.
03Links that say what they mean
In many graph databases a link just means "these two are connected." In TTDB every link has a type, written right in the record's first line: relates:needs>@LAT60LON40 reads as "this needs that." On the globe each arrow is colored by its type. Pick a record to see its links.
Links point one way. If tomatoes need sun, the database does not assume the sun needs tomatoes. A few link types do work both ways, such as companion (plants that grow well side by side) and opposes. Even then, the link has to be written on both records. That keeps the file honest: nothing is in there that someone didn't actually write.
contradicts | opposes | |
|---|---|---|
| Means | These two claims can't both be true | These two are opposite ends of one scale |
| Both true? | At most one | Yes, easily |
| In the garden | A hunch that tomatoes want shade vs. the note that they need sun | A dry spell vs. deep watering |
04The file remembers where you were looking
Most databases forget you the moment you close them. A TTDB keeps a cursor: a short block near the top of the file that records which record is selected, a short preview of it, and the last question asked. Pick up the file on another machine, or hand it to an AI assistant, and it opens on the same place.
Records can be looked up with a librarian that understands four short commands. They're short and fixed on purpose, so a small chip with no internet connection can answer them. The answer is written back into the cursor block.
05How sure is it?
A note about a passing temperature reading and a note about something fundamental shouldn't count the same. A record can carry a four-line epistemic weight block, [ew], saying how much the librarian trusts it:
conf: confidence, 0 to 255. How settled the belief is.rev: how many times it has been rewritten. Something that keeps getting corrected is something the librarian keeps getting wrong.sal: salience, how often it gets looked up. Each time you open a record on this page, itssalgoes up by one. Check the file.touched: when any of this last changed.
The idea comes from neuroscience. The free energy principle describes brains as machines that try to reduce surprise. The notes most worth checking are the ones the librarian relies on a lot but trusts little. On the globe, a node's size shows salience and its color shows confidence (● low, ● middling, ● high).
06Dreaming: turning episodes into beliefs
The robot's notes are episodes: individual things it saw. To act quickly it also needs beliefs, general patterns it can rely on without re-reading everything. People are thought to build these while asleep, by replaying the day's memories. TTDB does something similar in its Dream Cycle.
When the device is idle, it takes many short random walks through the links. Each step favors records with high salience. It counts which records keep showing up on the same walks. A group of three or more that keep appearing together, and that the librarian trusts on average, becomes a Locus Point: a new @BELIEF: record with its own [lp] block, pinned at the middle of the group. The walks ignore dates on purpose, so a pattern only counts if it holds across the whole notebook, not just recently. A second phase (not shown here) looks at gaps surrounded by known notes and makes guesses about them, each marked clearly as a hypothesis.
07Where it goes from here
TTDB is specified in a set of short, numbered documents (RFCs), and it's the memory layer for the rest of the Toot Toot projects: a mesh radio network, small autonomous devices, and the Locus framework for modeling experience. A few of the stranger ideas, each one link away:
Real TTDB files to explore on the globe browser: feelings, banjo, the RFCs themselves. Read the specification starting at TTDB-RFC-0001, or the source on GitHub.