Documentation

The journal and FAQ

Once a day, Tokenome writes down what you decided and why. Every reason quotes the sentence it came from. If a claim cannot be quoted, it is not written down.

What a day is

A working day runs from 04:00 to 04:00 local time, not midnight to midnight, because a session that starts at 23:40 and ends at 02:15 is one day's work. A day becomes eligible once the clock has passed the end of its window, plus a settle period, and no new material for that day has arrived recently. Days you were not working produce nothing: the series is allowed to have holes, and padding it with empty entries would make everything else harder to find.

What gets written

A journal day in the Tokenome app: a one line summary, then a decision card reading that account lookups went back to direct reads, with the quoted sentence underneath, a reversed badge, and a link to open the cited turn. — One day, one decision, one quote, and the turn it came from. The project and its conversations are sample data; the software is not.

An entry has a short summary of the day and a list of decisions. Each decision carries:

The decision itself: In one sentence, as a decision rather than an activity.
The evidence: The verbatim span that proves it, never a paraphrase, with a link to the turn.
A status: Proposed, decided, rejected or reversed. A reversal is the most valuable state in the system, and the one a repository cannot hold.
A confidence: stated when a person or the assistant said the reason outright and the quote proves it; inferred when it was concluded from context. Both are kept, and only stated reasons are promoted into the FAQ.

The quoting rule

Evidence is verbatim or it is not evidence. A reason that cannot be tied to a sentence somebody actually wrote does not go into the record, and a stated reason outranks an inferred one everywhere. This is the guard against a confident, wrong, permanent entry, and it is why the journal adds structure without subtracting detail.

Where it lives, and what happens when it changes

Each day produces two files under ~/.tokenome/journal/<year>/: a markdown file for you to read, grep, diff or commit into the repository it describes, and a JSON file the FAQ is built from. Both are indexed separately from your conversations, so an entry can never outrank the turns it was written from.

If late material arrives for a past day, a ChatGPT export dropped in a week later, for example, that day is regenerated and the change is appended as a revision rather than silently rewritten. A journal that quietly edits its own past is not a record.

The running FAQ

The FAQ page with two promoted questions: one marked stable about where idempotency lives, and one marked reversed about caching account lookups, each with its quoted answer, its date and a link to the cited turn. — Two promoted answers, one stable and one reversed, each with the quote it rests on. Sample data.

The journal is chronological. The FAQ is the same material indexed by question, which is how it actually gets asked. A question gets in when you have genuinely asked it more than once, when two or more stated reasons support it, or when you pin it by hand. Everything below that threshold waits in a candidates list, so the FAQ does not become the journal again, sorted differently.

An answer is a history, not a value. Each question carries a status:

Status	What it means
`stable`	One answer, or a clean chain where each answer replaced the last.
`reversed`	The current answer contradicts an earlier one, and the reversal itself is evidenced.
`contested`	Two answers coexist and neither replaced the other. Surfaced for you to settle; never resolved automatically.
`open`	The question keeps coming up and no stated reason exists. This names the decisions that were never actually made.

How to ask why

Command	What it gives you
`tokenome journal`	Today's entry.
`tokenome journal --date 2026-09-27`	One day.
`tokenome journal --backfill`	Generate every eligible day that has no current entry.
`tokenome faq`	The whole running FAQ.
`tokenome faq "account lookups"`	The entries matching that text.

In the app, the Journal page has a "Why did we" box that searches the decisions rather than the raw turns, so the answer comes back as the reason plus its quote. Your agent can ask the same question for itself with the why_was and ask_faq tools; see Agents and MCP.