Garry's Opinionated OpenClaw/Hermes Agent Brain
Conversation archive
The conversation archive writes one redacted page per conversation per local day, read from your agent harnesses (Claude Code, Codex, OpenClaw, Hermes, Grok), plus one index page per day. On a personal brain it is on by default and the maintenance pass runs it; a shared team brain is only offered it and stays off until its owner turns it on.
gbrain transcripts archive off # turn it off; pages already written stay
gbrain transcripts archive on # turn it on (a shared brain, or after off)
gbrain transcripts archive run --dry-run # preview the last two local days
gbrain transcripts archive run # write them
gbrain transcripts archive backfill --from 2026-09-01 # older history, newest days first
gbrain transcripts archive status # readers as of the last run, timezone, archived and held days
gbrain doctor --only transcript_archive_freshness # is it keeping up?
On by default
transcripts.archive.enabled decides. Set to on or off, it always wins. Unset, it is on when the brain is personal
(brain.audience personal, or an undeclared brain the audience heuristic reads as personal; see
ambient writeback) and off on a shared or unknown brain,
which is only offered it. It is always off on a thin client and for a remote caller: the archive reads the harness
sessions of the brain host's own machine. If the setting cannot be read, it counts as off.
gbrain init and gbrain setup <harness> state the archive in their first-run settings, and an existing personal
brain sees a one-time upgrade notice saying it is on and how to turn it off. Neither waits for an answer.
What leaves the machine
On a keyless brain, nothing: pages are written to the local brain and searched by keyword.
With an embedding key, the archived text of new days is sent to that provider to be embedded, like any new page: unattended upkeep caps that at
maintenance.embed_daily_usd; autopilot and a managed brain's write coordinator embed new pages as they arrive. Older history written by backfill is keyword-only, and its embedding waits until you see the price and approve it:gbrain embed --held --dry-run # what it would cost gbrain embed --held # after you agreeNo facts are extracted and no Dream synthesis runs on archive pages.
The maintenance pass
The archive runs from the existing maintenance pass: the idle upkeep of an agent's gbrain serve,
gbrain maintain --unattended (and gbrain maintain --schedule), and the autopilot tick (gbrain autopilot --install).
Each pass archives the forward window (archive run), then one capped backfill run of older days, newest first,
until none are left. It runs at most once per transcripts.archive.maintenance_floor_min (default 360), one runner at
a time, never when the archive is off, and never fails the pass: its outcome, errors included, is recorded in
transcripts.archive.last_maintenance and shown by doctor. One pass is bounded by count (the run window and
transcripts.archive.backfill_days_per_run older days) and by time: after 120 seconds it starts no new conversation,
and the next pass picks up the rest.
gbrain transcripts archive run archives now, on demand, whatever the pass is doing; it works with automatic
maintenance turned off (maintenance.auto false), and gbrain transcripts archive status says so when it is off.
run and backfill exit 1 when anything in the run failed, and 0 otherwise, even when most days were written:
the days that did not make it are retried by the next run on their own, and a script or scheduler should see that
this run left work behind. Every failure is in the errors list of --json (a reader that could not be read, a day
that could not be written, with its day and code, a day index, or the archive_owner_unset hold on a shared
brain), so the list is empty exactly when the exit code is 0. A --dry-run reports the write_mode the real run
will use (coordinator on a brain whose writes go through the write coordinator), even before the archive source
exists.
On a managed brain the pass writes each day page as a put_page write request through the write coordinator, under the
same local identity as gbrain transcripts archive run (local_cli). Waiting for the coordinator counts against the
120 seconds; a write it accepted but has not published yet counts as archived, publishes on the coordinator's next turn,
and is not written again.
Search
An archive page ranks a little below a page you wrote that scores close to it (rank prior 0.8), and one result list
holds at most two archive hits for the same day. A question about a conversation or a date ("what did we discuss",
"when did ...", "yesterday", 2026-11-02) ranks archive pages like any other. gbrain config set search.rank_priors false turns both off.
Doctor
gbrain doctor --only transcript_archive_freshness (brain category) warns when:
- a harness's newest archived day is more than
transcripts.archive.stale_days(default 2) behind the newest session day the last run read. The fix isgbrain transcripts archive run, orgbrain transcripts archive backfill --from <first missing day>when the gap is wider than one run; - no archive run has read a reader successfully in that long, for example when maintenance passes keep stopping at
their deadline before that reader. The fix is
gbrain transcripts archive run; - the archive is on but no maintenance pass has run it in that long. The fix is
gbrain autopilot --install(a persistent service, so it asks first); - days are held (each is listed with its code, such as
archive_owner_unsetorarchive_redaction_failed), a reader failed on the last run, or the last pass recorded an error.
Off is ok with no detail, and a harness with no readable sessions, or one no run has read yet, is informational.
Neither this check nor gbrain transcripts archive status reads a session or calls the OpenClaw Gateway, so both
answer in about a second however many sessions there are. They read the archive's ledger and config, and what each
run (run, backfill or the maintenance pass, never a --dry-run) recorded about every reader: how many
conversations it read, the newest session day any run has seen, and the reader's error if the last run failed. Status
shows those as of that run, with its time; a reader no run has read yet says so.
Every command takes --json and --source <id> (the archive source, conversations by default).
What it writes
conversations/<harness>/<YYYY-MM-DD>/<label>-<hash8>: the messages of one conversation that fall on that local day, in the same speaker format asgbrain transcripts ingest. A long day splits into-p2,-p3parts.conversations/days/<YYYY-MM-DD>: an index of every conversation archived for that day.
Frontmatter carries transcript_archive (harness, day, timezone, message count, first and last timestamp, whether
the day is complete) beside the usual transcript_import block.
Running the archive again on the same input changes nothing. A day still in progress is rewritten in place as it
grows, and closes once its last message is older than transcripts.archive.quiet_minutes (default 180).
Days and timezone
Days are local days in transcripts.archive.timezone (an IANA name such as America/Los_Angeles; the machine's
zone when unset). The first run pins the zone for the archive source, so a later timezone change never re-slices
days already written. run covers today and the previous transcripts.archive.run_window_days days (default 2).
Backfill
backfill needs --from (and takes --to, default today). One run writes at most
transcripts.archive.backfill_days_per_run days, newest first; status and the run output say how many wait for
the next run, and the next run skips the days already finished. A run reads each session file once to learn its
days, then reads again only the conversations on the days it writes, and writes them in batches, so a folder of
thousands of sessions stays bounded in memory. Backfilled pages are searchable by keyword at once, and their
embedding is held until you approve its cost (gbrain embed --held --dry-run shows it, gbrain embed --held runs it).
Old archive folders
If an earlier tool already archived conversations into a folder (a home-made script or cron job), retire it in three
steps. First, adopt-legacy lists the days the folder covers so backfill skips them instead of writing a second copy:
gbrain transcripts archive adopt-legacy --dir ~/brain/conversations # preview, writes nothing
gbrain transcripts archive adopt-legacy --dir ~/brain/conversations --apply # record the covered days
The covered days are recorded in the brain's config, so they count before the archive source exists, and later
runs skip them whichever archive source they write to (the brain turning shared included). The old pages are never
changed or deleted. Second, remove the old script's schedule yourself (its crontab line or
scheduled job), so two archivers do not run side by side. Third, let the maintenance pass fill the gap, or run
gbrain transcripts archive backfill --from <day> now.
Privacy
Every page is redacted before anything is written (the same secret scan and your pattern file as
gbrain transcripts ingest). If redaction fails for a conversation, its days are held with
archive_redaction_failed and retried on the next run; a day is never written unredacted.
On a personal brain, archive pages carry no readable_by. On a shared brain (a non-personal audience, or two or
more enabled members), every page names its readers:
- the owner member always reads it. With no owner named, every day is held with
archive_owner_unsetuntil you rungbrain access owner set <member>; - a group chat whose chat type the harness verified also lists
group:chat-<hash8>, where the hash is the first 8 hex characters of sha256 of<harness>:<conversation key>, but only when that group already exists. Create the group (gbrain access group add chat-<hash8>) and add members to it to share that chat's pages with them.
On a shared brain whose archive source is a git checkout, pages go to a database-only <source>-owner source so
private conversations never land in the shared repository.
When a personal brain becomes shared
Pages archived while the brain was personal name no readers. Until they are kept to the owner, every member reads
them. The command that makes the brain shared does that before it returns: gbrain access member add or
gbrain access member enable when it makes two or more enabled members, gbrain config set brain.audience shared,
and gbrain access owner set on a brain that is already shared. member add and member enable do it before the
member is added, enabled or bound to a token, so its credentials never read those pages; if that step fails, the
command changes nothing and exits non-zero. Each prints one line on stderr per archive source,
saying the pages are now kept to the owner or why they still wait (the codes below); --json output is unchanged.
When the brain turns shared some other way, the next archive run (gbrain transcripts archive run) or maintenance pass
does it, also before it writes anything. That includes members added or enabled from the admin page over HTTP or by
gbrain access serves several --members <ids> --yes. A command run while an archive run that started on the personal
brain is still writing the source keeps the pages archived so far to the owner at once; the pages that run still writes
wait for the run after it (archive_rescope_pending). Either way, every folder that holds an archive page at that moment (one per
harness and day, such as conversations/codex/2026-10-01/, plus conversations/days/) gets an access rule readable
only by the owner. Other pages in the archive source, outside conversations/, keep the rules they had. This re-scope replaces any existing rule on those folders, including one the owner made wider on
purpose; re-add the wider readers afterwards (gbrain access rule add, which waits for gbrain access apply) if
you still want them. A rule on the whole conversations/ folder is left in place, and a page under both rules is read
only by members both allow. Folders written later get no rule, so a group conversation archived on the shared brain
keeps its group, while a group chat added to a day archived before the switch stays the owner's.
A source holds at most 256 folder rules. When the archive folders written while personal, plus the source's other
rules, would pass that limit (about three months of history with three harnesses), the re-scope writes one owner-only
rule on the whole conversations/ folder instead. Every earlier day is still kept to the owner, but group conversations
archived afterwards stay owner-only too, because a page has to pass every rule above it: a wider rule on one chat's
folder does not open it. Widening the conversations/ rule opens every earlier personal day to the same readers, not
just one chat. gbrain transcripts archive status and gbrain doctor --only transcript_archive_freshness say so in
one line (archive_rescope_folder_cap) while that rule keeps the folder to the owner alone; once you widen it, they
stop.
The re-scope never drops one of your rules to make room. A source that already held 256 other rules therefore ends
with 257: the days stay closed, but gbrain access rule export then import fails validation until you remove one of
the other rules, and the same line says so while the source stays over the limit.
The re-scope waits, and gbrain transcripts archive status and gbrain doctor --only transcript_archive_freshness
each say so in one line, when the shared brain names no owner (archive_rescope_owner_unset: run
gbrain access owner set <member>) or when the source keeps its access rules in git (archive_rescope_git_rules:
add a rule with prefix conversations/ and the owner as its reader to the source's .gbrain/access.yml).
Three ways a brain becomes shared leave those earlier pages open to every member until you act. In each, as in the
paths above that wait for the next archive run,
gbrain transcripts archive status prints not kept to the owner yet (<code>): <what to do>, its --json carries
the same rescope object (code and message), and gbrain doctor warns on transcript_archive_freshness with that
message, whether the archive is on or off:
- The audience flips from client usage, with no command. With
brain.audienceunset, three or more people's MCP clients active in 30 days make the brain read as shared. No command runs, so the code isarchive_rescope_pendinguntilgbrain transcripts archive runor a maintenance pass runs; with automatic maintenance turned off (maintenance.auto false) no pass runs, so only the archive run does it. Declaringgbrain config set brain.audience sharedalso runs it at once. - A shared brain with no owner. The re-scope has no one to keep the pages to, so it waits with
archive_rescope_owner_unset.gbrain access owner set <member>runs it at once. - Rules kept in git. gbrain never writes a source's
.gbrain/access.yml, so it waits witharchive_rescope_git_rulesuntil you add theconversations/rule there and sync. A repo-less brain keeps its rules in the database and never hits this case.
OpenClaw
Current OpenClaw keeps live sessions in a database owned by its Gateway. gbrain reads them with
openclaw gateway call (sessions.list, then chat.history per session), so the openclaw CLI must be on
PATH. Point it at a Gateway with GBRAIN_OPENCLAW_GATEWAY_URL and pass its token with
GBRAIN_OPENCLAW_GATEWAY_TOKEN; gbrain hands both to openclaw through its environment (OPENCLAW_GATEWAY_URL,
OPENCLAW_GATEWAY_TOKEN), never on the command line. Errors map to archive_gateway_unreachable,
archive_gateway_auth and archive_gateway_failed; a failed read leaves the archive ledger unchanged, so the next
run retries. Checked against OpenClaw 2026.10.9 and 2026.11.3, which list sessions and return history the same way.
Each openclaw gateway call is a new process, and starting one takes far longer than the Gateway takes to answer,
so gbrain asks for the largest history page the Gateway gives (1,000 messages within 4 MiB; OpenClaw before 2026.11
caps a page at 512 KiB, and one before 2026.10 refuses the byte budget, so gbrain asks again without it) and reads up
to 4 sessions at once. The messages of each session, and the order of the conversations, are the same as one read at
a time; if any session cannot be read, the whole Gateway read fails once the reads already running have ended.
Session files OpenClaw keeps on disk are read too, even when the Gateway is down: <id>.jsonl.reset.<stamp>, the
zstd-compressed <id>.jsonl.deleted.<stamp>.<hex>.zst and the legacy compact backup <id>.jsonl.bak.<stamp>.
Several files of one session merge into one conversation (gbrain transcripts ingest reads only live files). Migration copies (*.migrated, *.migrated.<n>,
<id>.jsonl.pre-doctor-*-repair-<stamp>.bak) and Doctor's recovery copies (<id>.jsonl.bak-<pid>-<stamp>) are
skipped: their sessions live in the Gateway's database, which the next run with the Gateway up reads.
Three OpenClaw limits to know:
sessions.listdoes not list archived sessions, so a session archived before gbrain first read it is only found through its file on disk.- On 2026.10.9 a session created by an operator has no
chatType, so the archive treats it as unverified and keeps it to the owner. sessions.resetkeeps the same session id and the Gateway then returns only the messages after the reset. The archive merges the.jsonl.reset.<stamp>file of the same session with the Gateway's history, each message once, so the earlier messages stay. When neither holds a message the day page already has, the page is kept as it is (day statuskept), so a reset never shrinks or replaces the archive.
Repo-less brains
A brain with no git repository archives straight into the database; the archive source is created database-only
when it does not exist. On a personal brain whose archive source is a git checkout, the archive writes the files,
commits only those paths with gbrain git commit-push, and syncs the checkout.