Garry's Opinionated OpenClaw/Hermes Agent Brain
Page history: why a page changed
Say to your agent: "Update the refund policy to a 30-day window, and record that the client asked for it."
Every page write in gbrain keeps the text it replaced as a version. A write can also carry a short human reason, so the history says why the text changed, not only that it did. This guide covers how to give a reason, where it is stored, who can read it, and what happens on a brain with no Git repository.
Reasons
Pass reason on put_page, edit_page, revert_version or on any item of
put_pages:
{ "slug": "policies/refunds", "expected_revision": "…", "content": "…",
"reason": "Client asked for the 30-day window." }
The parameter is listed on the full MCP tool surface. The starter surface leaves
it out of the tool schemas to keep them small, but still accepts it, so an agent
on the starter surface can pass it too. On the CLI the same parameter is --reason, for example
gbrain put policies/refunds --reason "Client asked for the 30-day window." < refunds.md.
A reason is one line of at most 500 characters. Tabs and line breaks become
spaces, other control characters are removed, and an empty reason counts as
none. It is checked before the write is accepted, so a refused reason leaves no
copy anywhere, except opt-in serve --log-full-params logging:
- longer than 500 characters:
change_reason_rejectedwith reasonreason_too_long(the wireerrorisinvalid_params), naming the length and the limit; - it looks like it holds a credential:
change_reason_rejectedwith reasonreason_contains_secret, naming the detector and the character position, never the value.
Shorten the reason or remove the secret, then send the write again. The reason
is part of the request's identity: replaying a request_id with the same
reason replays the write, and replaying it with a different reason is a
conflict. In put_pages, one refused reason refuses the whole batch and names
the item; two copies of a page with the same reason are written once, and two
copies with different reasons are refused.
Where the reason is stored
A version is the page as it was before a write. So the reason is stored on the
version that write archived, and get_versions shows it on that version as
replaced_because. The newest version's replaced_because explains the text
you read now. gbrain history <slug> prints it as changed because: … under
each version.
A page's first write archives nothing, so its reason has no version to sit on.
Every write result says where its reason went in reason_recorded:
| Field | Meaning |
|---|---|
reason |
The reason as stored, after the cleanup above. |
version |
true when a version carries it. |
version_why |
Why no version carries it: page_created (first write) or no_change (the write changed nothing). |
git |
Where Git stands, below. |
git is one of:
committed: on a git-canonical source the commit landed with the write.queued: the file's commit is queued and will carry the reason.superseded: a newer write to the same file committed first (shown on the receipt,get_write_request, with areason_not_committednotice). The reason stays in gbrain's history but is in no commit. Nothing needs fixing, and retrying the write would be wrong.private: the page is private, so its reason stays out of every commit message, group commits for other pages included. Visibility is checked when the commit is made: a page that a later page in the sameput_pagesgroup made private (throughderived_from, for example) commits without its reason, and so does a queued commit whose page a later write made private.not_file_backed: the page has no file (database-only), so the reason is in gbrain's history only.no_repository: the brain has no Git repository (below).none: the write changed nothing.
In Git
When the page's file reaches Git, its commit carries the reason as a trailer naming the file:
gbrain-reason: policies/refunds.md: Client asked for the 30-day window.
There is one trailer per file, in the same trailer block as any
gbrain-repair: trailer, so git interpret-trailers --parse lists them all.
A write without a reason commits exactly the message it did before. A commit
you make yourself can give a reason the same way:
git commit --trailer "gbrain-reason: policies/refunds.md: Client asked for the 30-day window."
A sync reads these trailers back into page history (reasons from Git). A pushed commit message cannot be changed, so treat a reason like any other text you push. There is no operation to add a reason to a past write.
Repo-less brains
A brain without a Git repository, such as the default keyless install, gets the
same feature. The database is the record there: the reason is stored on the
version by the same write, get_versions shows it the same way, and
reason_recorded.git is no_repository. Nothing is refused because there is no
repository. If you connect a repository later, the reasons already stored stay
where they are; old versions are not rewritten into commits.
Who can read a reason
A trusted local caller sees every stored reason. A remote caller (an MCP client) sees a version's reason only when both that version and the version that replaced it are world-visible. The reason for turning a page private, or for any change made while it was private, is therefore never shown remotely. When the replacing version was later pruned (large pages and holding pages keep a few versions), its visibility can no longer be checked and the reason is withheld from remote callers. Remote reasons go through the same text sanitizer as version bodies.
Reasons from Git
When gbrain sync imports a changed file from a Git checkout, it reads the
gbrain-reason trailers of the commits it is importing and stores the
file's reason on the version that import archives. A commit you make yourself
with git commit --trailer "gbrain-reason: <path>: <text>" therefore shows up
in get_versions as replaced_because, the same as a reason given to
put_page.
How a sync picks the reason for a file:
- It reads the commits between the last synced commit and the new one along the first-parent line, which is the history the checked-out branch came from. A merge counts as changing every file it changed relative to its first parent.
- The newest of those commits that changed the file decides. Its trailer for that file is the reason. If it has none, the version gets no reason, so an older reason is never shown against newer text.
- A merge that resolved a conflict decides with its own trailer, so put the trailer in the merge message. A commit on a merged side branch never decides, whether its edit was kept or discarded.
- The trailer names the file by its path in the repository (or under the
source's folder when the source is a subfolder), then
:and the text. A trailer that names no file its commit changed is skipped and counted in the sync result'sreason_trailers_malformed. - A reason from Git gets the same cleanup and limits as a written reason. One longer than 500 characters is skipped and counted the same way.
- A file's first import creates its page and archives nothing, so it stores no reason, as with a page's first write.
When one sync imports more than one commit for a file, the versions in between were never stored. The sync marks the page as having a gap in its history, so readers of old versions know some are missing.
A trailer already in Git that looks like a credential is not stored. The sync
prints the reason_trailer_secret notice, which names the commit and the file,
never the value. Rotate that credential: Git history keeps the commit message.
If reading the trailers fails (a Git error, or more than two minutes), the sync
prints reason_scan_failed. If the range holds more than 10,000 commits, it
prints reason_scan_capped instead of reading them. Either way the content is
imported, because reasons never hold up content. Every version that sync
archives stores no reason, and each page it changed is marked with a history
gap. This release does not backfill reasons for that range: the sync still
moves its last synced commit forward, and a later sync does not read the range
again. The reasons are still in Git, and the notice's command lists them:
git log --first-parent --format='%H %(trailers:key=gbrain-reason,valueonly)' <range>
A commit and file that a purge has tombstoned (below) never gives a reason again, not even on a full re-import, or a sync that read the trailer before the purge and saved the page after it.
A source with no Git checkout (a repo-less brain, or a folder imported with
gbrain import) reads no trailers, prints none of these notices and marks no
gap. Its reasons come only from the writes that carry them.
Purge and reasons
gbrain forget <id> --purge (expire versus purge)
reaches every copy of a reason that quotes the claim:
- Versions. The reason is replaced with
[purged]on every version that carries it, inline and segmented alike, and counted inremoved.page_versions. - Queued and kept Git commits. The source's Git effects whose commit message
would quote the claim, whether queued, failed or kept after they ran, are
redacted in the same transaction: the line becomes
[purged]and the trailer that quotes it is dropped (removed.persistence_effects). If one is being written right now, the purge stops withpurge_blocked_pending_recovery; retry once it finishes. - Commits already in the repository. Purge never rewrites Git history, so a
pushed commit keeps its message text, as it keeps the file's earlier
contents. Before it deletes anything, purge reads the
gbrain-reasontrailers on the source's first-parent history up toHEAD(up to 200,000 commits) and records each commit and file whose reason quotes the claim. The record holds no text. No later sync, cold re-import or re-derive stores that reason again. The receipt counts these inremoved.reason_purge_tombstonesand lists the commits under thegit_commit_messagesresidual.
Before #8635 was fixed, a sync that read a reason just before a purge could
still save it afterwards. gbrain repair purged-change-reasons finds those
versions and, after you agree, sets them to [purged]
(purged change reasons).
Purge refuses before it changes anything when it cannot read that history:
reason_purge_scan_failed: reading the trailers failed: the source's folder is missing or moved,gitis not installed, Git refuses the repository (an unsafe owner or a corrupt.git/config), or the read timed out. Nothing was changed; fix the cause or wait, then run the same purge again.reason_purge_scan_capped: the history is longer than 200,000 commits. Your agent asks you to choose: purge now and check only the newest commits, with--reason-scan-limit <n>set to the number you pick, or stop. With a limit, a reason in an older commit is not tombstoned and a re-import could store it again; the receipt says so.
A source counts as having no Git checkout only when it has no folder, or when Git itself says its folder is in no repository. Then there is no history to read, so purge redacts the database copies and never raises either refusal.
gbrain delete <slug> --purge also reaches the purged page's own reasons. Before
anything is deleted it reads every reason the page's versions and write
receipts recorded, then removes them from the page's receipts and stored
intents, and drops the commit line and trailers from every Git effect of the
page, queued, failed or kept, with the same purge_blocked_pending_recovery
refusal while one carrying a reason is being written. Its receipt checks both
stores (persistence_requests, persistence_effects). Commits already in the
repository keep their messages, as above.
Choosing how to record a change
A reason explains an edit to one document. Pick the shape that matches what happened:
| What happened | Do this |
|---|---|
| The same document changed (a new edition, a correction) | Edit the page in place with expected_revision and a reason. |
| A separate document amends part of it | Write the amendment as its own page with an amends link (since the date it applies). |
| A different document replaces it entirely | Keep both pages and add a supersedes link from the new one. |
Do not create a second page for a new edition of the same document: the history of one page, with reasons, is what readers and agents follow.
Valid time
A page can say when its text takes effect. Put valid_from (and, if the text
stops applying, valid_until) in its frontmatter:
---
title: Refund policy
valid_from: '2026-07-01'
valid_until: '2027-01-01'
---
The dates are part of the page, so on a brain with a Git repository they live
in the file and in every commit, and gbrain keeps them on each retained version.
The interval is half-open: the text is in force from valid_from up to, but
not including, valid_until, the same rule links use. Write the dates quoted.
An unquoted YAML date also works; a partial date (2026-07), a time of day or
another zone does not, and the write result warns valid_from_unparsed.
Say to your agent: "What did our refund policy say on March 1?" The agent
reads the page with get_page {slug, as_of: '2026-03-01'} (CLI:
gbrain get <slug> --as-of 2026-03-01).
Nothing changes until a page carries valid_from or a caller passes as_of.
There is no config key.
Which tool records a change in effect
| The change | Record it as | as_of reads |
|---|---|---|
| The text of the page changes from a date on (a new edition) | edit the page in place and set valid_from to that date (keep the old date for a plain correction) |
the edition whose valid_from is the latest on or before the date |
| A separate document changes part of it (an addendum, a rider) | an amendment record: its own page with an amends link to this page, dated by its since |
the page's own edition; amendments dated after that edition and on or before the date are listed in valid_time.amendments_not_applied, not merged into the text |
| A new page replaces this one | a supersedes link from the new page |
this page's editions only; follow the link for the new page |
How the edition is chosen
The candidates are the current page and its retained versions. The answer is
the edition with the greatest valid_from on or before the date; when two
share that date, the one recorded last wins, as a correction of that edition.
Nothing is excluded by guesswork.
Some histories look alike: a corrected date, a renewal of unchanged text, a
backfilled old edition and a withdrawn scheduled edition all leave the same
shape. When the versions around the date have that shape (the same body under
another valid_from, or a version recorded later with an earlier
valid_from), the answer is still the rule's pick, and it says so:
valid_time.uncertain: true, why: ambiguous_edition_dates, with
competing_version_ids. Its fix asks the user which date the edition took
effect, then offers an edit_page that sets valid_from.
If the chosen edition is private (or below the caller's min_trust), a remote
caller gets the answer a private page gets: not found. It never falls back to an
older edition it may see. Reasons follow the same rule as get_versions.
The answer
valid_time is in every answer:
| Field | Meaning |
|---|---|
as_of |
the date asked about, echoed |
status |
in_force, not_in_force (its valid_until has passed), not_yet_in_force (every edition starts later, and gbrain holds the page's whole history), before_recorded_history (every known edition starts later, but earlier editions may exist outside gbrain) |
chosen_version_id, chosen_is_current |
which edition was picked (null id for the current page) |
valid_from, valid_until |
the chosen edition's dates |
introduced_because, replaced_because |
the reasons given for the write that produced the edition and the one that replaced it |
history |
retained, incomplete or unknown |
uncertain, why |
whether to trust the pick, and the one reason not to |
undated_versions |
versions with no readable valid_from; they are never picked |
amendments_not_applied |
amendment records in force on the date that the text does not include |
recorded_since |
when gbrain recorded the chosen edition |
Only in_force returns the text at the top level. Any other status puts the
edition under last_in_force or earliest_known, so a reader that ignores
the status cannot quote expired or future text as current.
A large edition is returned in windows. Each next call carries the slug,
source, date and a cursor pinned to that edition, so the read stays on it even
if the page changes meanwhile.
On the CLI, gbrain get --as-of prints a [gbrain] valid_time line on
stderr. An in_force answer prints the page on stdout and exits 0. Any other
status prints status: and why: on stdout, no page, and exits 15
(exit codes).
A plain read (get_page, gbrain get) of a page whose own valid_from is
after today, or whose valid_until has passed, also carries valid_time
(status, as_of today and both dates), and the CLI prints it on stderr.
When history is incomplete
gbrain can only answer from the versions it kept. The answer says when that is not enough, and only when it matters for the date asked about:
history_prunedorhistory_gap: versions were pruned, or a sync imported several commits of the file at once, inside the chosen edition's span (or the date is before every retained edition). Dates the retained editions cover after the gap stay certain.history_unknown: the page has enough large or segmented versions that a prune may have run before gbrain recorded prunes.before_recorded_history: the page came from a file, so editions before its first gbrain version may exist in Git.edition_pruned: the edition a window cursor pinned is no longer retained; no text is returned.
The fix depends on where the missing history lives. For a page whose file
sits in a Git checkout, it is git log --follow -p -- <path> (a remote caller
gets it as a command to relay). For a private, database-only or unfiled page,
and on a brain with no Git repository, it asks the user for a retained copy or
a backup; retrying the read unchanged gives the same answer.
Brains with no Git repository
The default keyless install has no Git repository, and valid time works the same there: the dates are in the stored frontmatter of each version, the pick and every status come from the database, and the recovery asks for a backup instead of naming a Git command.
Writes that keep or change the date
A write result can carry a valid_time advisory:
valid_time_correction: the body changed andvalid_fromdid not, so the change is read as a correction of the edition in force since that date. Setvalid_fromif the change takes effect later.valid_time_date_only: onlyvalid_fromchanged. That is a question, not an error: is this a correction of the earlier date, or a renewal of unchanged text? as_of reads around those dates are markedambiguous_edition_dates.valid_from_unparsed:valid_fromis not a date gbrain can read.
valid_time_undeclared
No retained version of the page has a readable valid_from. gbrain does not
invent one. The fix asks the user when the text took effect, then offers an
edit_page that adds a quoted valid_from. To ask what the brain had
recorded at a moment instead, read with known_as_of (recorded time).
Refusals
as_of takes a calendar date. An instant is refused clock_mismatch with
reason instant_for_date (clock mismatch). It does
not combine with known_as_of, or with include_content or
content_only: writing an old edition back would silently revert the page.
A slug that exists in two sources you can read is refused until you pass
source_id.
host_upgrade_required
The gbrain CLI or an MCP client asked a host for as_of, and the reply did
not echo valid_time.as_of. An older host ignores the parameter and returns
the current page, so the client prints nothing and exits 16. The error names
the client version, the host version and the minimum host version. Run
gbrain upgrade on the brain host, or ask whoever runs it. Without
valid_time in a reply, the reply is the current page.