Garry's Opinionated OpenClaw/Hermes Agent Brain
Life Chronicle: automatic timeline events
Say to your agent: "What happened in my meetings last Tuesday?"
Say to your agent: "Turn off automatic event extraction."
Say to your agent: "Extract events from my older meeting notes."
When you save a meeting, conversation or calendar page, gbrain turns it into
timeline events (life/events/ pages plus a day-by-day projection) so
gbrain day <date>, gbrain since <date> and gbrain on-this-day can answer
"what happened". This runs automatically and is on by default. Each
eligible page costs one paid chat call, except an ended calendar invite, which
is projected without a model call (see Calendar invites).
To turn it off:
gbrain config set auto_chronicle false
Unsetting the key restores the default, which is on. Use set ... false to
opt out.
What qualifies
A page is extracted automatically when all of these hold:
- Its type is
meeting,conversationorcalendar-event, or its slug starts withmeetings/,conversations/,cal/orcalendar/. - Its body has at least 80 characters. Dream-generated pages, diary pages
(
life/diary/) and event pages themselves are never extracted. - It was written or changed while automatic extraction was active on the brain (v0.60.45.0 or later). History is never swept automatically.
- Its own date (frontmatter
date,startor an authored effective date) is withinchronicle.auto_recent_days(default 30). Undated pages count as recent. - A calendar invite has ended. An invite for next week is picked up once its end time passes, with no edit needed.
- The writer is not confined. Slug-bound, delegated or namespace-restricted
clients, and grants without
extract_facts, never trigger extraction. - The sync did not run with
--no-extract. A remote sync never extracts.
The page must also stay unchanged for chronicle.auto_settle_seconds (default
180) so a note written in several passes is extracted once.
What becomes an event
An event is something the page records as having happened by the end of its own day: the meeting or conversation itself, what was decided, said or agreed in it, and earlier events the text dates. Plans, follow-ups, deadlines and scheduled meetings are not events, even when the page gives them a date.
Two rules are enforced after the model answers, before anything is written:
- No event after the page's own day. The page's own day is the latest of
its own date (frontmatter
dateorstart, or an authored effective date), a calendar invite'send, and a conversation's last message, read inchronicle.tz(default UTC). Anything on that day counts. A proposed event dated later, or after today, is dropped asfuture_dated. "Board meeting in Austin on May 15" in an April 18 meeting note never becomes a May 15 event. - No invented days. Events are stored by day. A past event the text dates
only by year or month ("back in 2024", "last month") is dropped as
date_impreciserather than pinned to January 1 or the first of the month. - At most
chronicle.max_events_per_pageevents per page (default 25). The cap runs after the two date rules, so a proposal dropped for its date never takes a slot; the first dated proposals in the extraction's order are kept and the rest are dropped asover_cap. Counting costs no model call.
The phase result reports dropped proposals by reason in events_dropped. When
every proposed event of a page is dropped, its ledger row records that reason
instead of no_events (never over_cap: the cap always keeps at least one).
Calendar invites
A calendar invite is a page under calendar/ or cal/ (or of type
calendar-event) with a title and frontmatter start and end, the shape the
Google calendar import writes. Once its end time passes, the chronicle phase
turns it into one event without a chat call:
| Event field | Value |
|---|---|
what and title |
Scheduled: <invite title> |
when |
the invite's start |
who |
the invite's attendees |
where |
the invite's location |
kind |
meeting |
captured_via |
life-chronicle:invite |
An invite is not proof that you attended. The Scheduled: prefix and
captured_via: life-chronicle:invite say the meeting was on the calendar, not
that it happened; meeting notes under meetings/ carry what happened. The
projection takes no daily-limit slot and records a zero cost; publication,
operator-edit protection and retirement work exactly as for judged events. A
calendar page without a title, start and end is judged like a meeting page.
The date rules above apply to projected invites too.
Event pages
Each event is a life/events/<day>-<hash> page. <day> is the event's day in
the brain timezone (chronicle.tz, default UTC), and <hash> is derived from
who, what and the source page, so re-extracting the same content updates the
same page.
Two events of one page can share who, what and day, for example a morning and
an afternoon "Call with alice-example". Both are kept: one holds the bare slug
and the other gets -<hash6>, derived from its time, place and kind.
Byte-identical events get -2, -3. The assignment does not depend on the
order the model lists events: an event keeps the slug it already has across
reorderings and re-extractions, the earliest event takes a free bare slug, and
correcting one event moves only that event.
Cost and limits
| Setting | Default | What it does |
|---|---|---|
auto_chronicle |
on (unset) | gbrain config set auto_chronicle false turns automatic extraction off. |
chronicle.job_budget_usd |
0.25 |
Cap for one page's extraction call. This is a per-call cap, not a daily budget. |
chronicle.auto_daily_limit |
200 |
Automatic extraction calls per rolling 24 hours, across every writer. Retries count. |
chronicle.auto_recent_days |
30 |
How old a page's own date may be for automatic extraction. |
chronicle.auto_settle_seconds |
180 |
How long a page must stay unchanged before extraction. |
chronicle.judge_max_tokens |
4000 |
Output-token cap for one extraction call. |
chronicle.max_events_per_page |
25 |
Events published from one page extraction; later proposals are dropped as over_cap (1 to 1000). |
gbrain config set refuses values outside each range and names the range. A
value already stored out of range falls back to its default, and doctor warns
(chronicle_config_invalid).
The worst case per day is auto_daily_limit x job_budget_usd, so $50 at the
defaults for a priced model. Typical pages cost far less. If gbrain has no price
for your chat model, the default cap cannot apply: extraction warns and runs,
still limited by the daily call count. If you set chronicle.job_budget_usd
yourself, an unpriced model refuses with no_pricing; register its price with
gbrain pricing set (see spend controls).
Page text is sent to the configured chat provider. Events derived from a private page stay private to remote callers, including after the page is renamed or purged.
Check that it works
- Write a meeting page. Its write receipt carries
chronicle_backstop: { "pending": "next_cycle", "daily_remaining": <n> }. A skip carrieschronicle_backstop: { "skipped": "<code>", "why": ..., "fix": ... }(codes below). Ordinary notes have nochronicle_backstopfield. - Wait for the next autopilot cycle, or run the phase now (paid):
On PGLite this is how pending pages run when autopilot is not running.gbrain dream --phase chronicle - Read the day back:
gbrain day 2026-04-03
gbrain doctor reports the auto_chronicle check: whether it is on, 24 h use
of the daily limit and the largest writer's share, 7-day outcomes and spend
(priced dollars, unpriced calls and calls without a cost record are listed
apart), pending pages and the command that runs them. chronicle_duplicate_events
(info) counts pages that still hold events from earlier extraction runs beside
their newest run's, such as the reworded copies releases before #8972 added on
long conversations; it changes nothing.
After upgrading
Automatic extraction is on by default from v0.60.45.0. On a brain upgraded
from an earlier release, doctor shows auto_chronicle_default_on (info) until
you answer, and the advisor shows the same finding with ask_user: true. The agent relays the cost to you, then records
your answer:
gbrain config set auto_chronicle true # keep it
gbrain config set auto_chronicle false # opt out
A brain that already had auto_chronicle true sees the notice too, because
that setting had no effect before v0.60.45.0.
An upgrade that changes how events are extracted raises the extractor version,
which makes already-extracted pages new to the ledger. On an unmanaged brain,
the phase re-extracts recent pages changed since activation, under the daily
limit. A managed brain records no_write_decision for them, and backfill
re-extracts them on request. Ended calendar invites re-project without a call.
Re-extraction keeps each existing event's slug.
History: backfill on request
Older pages are extracted only when you ask. Backfill is paid, so preview it first and agree to the cost:
gbrain chronicle-backfill --since 2026-09-01 --limit 50 --dry-run
gbrain chronicle-backfill --since 2026-09-01 --limit 50 --yes
--since filters on the page's last update, not its own date. Re-running is
safe: content already extracted is not paid for again.
Bound the spend with --max-usd
--max-usd <usd> is a hard bound on everything the run queues, retries
included. A page is queued only while
queued pages × (chronicle.job_budget_usd + one call's ceiling) × 5 attempts ≤ --max-usd
The ceiling covers the one call that can overshoot the per-page cap before the
tracker sees it. Each queued row is stamped with the run's campaign id, the
per-attempt cap, the maximum attempts and the pricing policy, and the
chronicle phase runs it under those values even if you change
chronicle.job_budget_usd later. Attempts are counted when a row is claimed,
so a crash never earns a page an extra attempt; a page that uses every attempt
without finishing fails as campaign_exhausted. The bound is deliberately
conservative: real spend is usually near estimated_usd, far below
worst_case_usd.
gbrain chronicle-backfill --since 2026-09-01 --max-usd 20 --dry-run --json
gbrain chronicle-backfill --since 2026-09-01 --max-usd 20 --yes
--json adds these fields; before this release none of them existed. An
example with a Sonnet-class model at the default $0.25 per-page cap:
{ "queued": 8, "estimated_usd": 0.13, "max_usd": 20, "worst_case_usd": 17.9098,
"per_page_worst_case_usd": 2.2387, "max_attempts": 5, "fits_under_cap": 8,
"cap_reached": true, "campaign_id": "3f0c…", "spent_usd": 0,
"next_command": "gbrain dream --phase chronicle" }
cap_reached: true means eligible pages were left out. A larger bound is a new
paid run, so ask the user, then preview it with --dry-run. When no page fits,
nothing is queued, ask_user is true and next_command is that preview.
spent_usd is the campaign's recorded spend, summed across attempts.
With --max-usd, a chat model gbrain has no price for is refused with
no_pricing before anything is queued; the error's fix is the
gbrain pricing set registration (look up the rate first). Without
--max-usd, an unpriced model still warns and runs, and the message points at
price registration and --max-usd.
Skip and failure codes
Write receipts, doctor and the advisor use these codes. decision codes come
from the write; execution codes come from the chronicle phase. Values in angle
brackets are filled in with real values on each surface.
| Code | Stage | Meaning | Fix | Who acts | Consent |
|---|---|---|---|---|---|
auto_chronicle_off |
decision | Automatic event extraction is off on this brain by choice (gbrain config set auto_chronicle false). |
— | — | — |
auto_chronicle_invalid |
decision | auto_chronicle holds a value that is neither true nor false, so it reads as off. | gbrain config set auto_chronicle true |
agent | paid |
slug_bound_client |
decision | The writer is confined (slug-bound, delegated or namespace-restricted), so its writes never trigger extraction into life/events/. | gbrain chronicle-backfill --source <source> --since <YYYY-MM-DD> --limit 50 --yes (preview: gbrain chronicle-backfill --source <source> --since <YYYY-MM-DD> --limit 50 --dry-run) |
host_admin | paid |
operation_bound_client |
decision | The writer's grant lists operations without extract_facts, the permission that covers derived extraction. | gbrain chronicle-backfill --source <source> --since <YYYY-MM-DD> --limit 50 --yes (preview: gbrain chronicle-backfill --source <source> --since <YYYY-MM-DD> --limit 50 --dry-run) |
host_admin | paid |
no_extract |
decision | The sync ran with extraction turned off (--no-extract, or a remote sync, which never extracts). | gbrain chronicle-backfill --source <source> --since <YYYY-MM-DD> --limit 50 --yes (preview: gbrain chronicle-backfill --source <source> --since <YYYY-MM-DD> --limit 50 --dry-run) |
agent | paid |
history |
decision | The page's own date is more than 30 days old (chronicle.auto_recent_days); history is extracted only on request. | gbrain chronicle-backfill --source <source> --since <YYYY-MM-DD> --limit 50 --yes (preview: gbrain chronicle-backfill --source <source> --since <YYYY-MM-DD> --limit 50 --dry-run) |
agent | paid |
not_yet_happened |
decision | The calendar event has not ended yet; it is picked up automatically after its end time, with no edit needed. | — | — | — |
too_short |
decision | The page body is under 80 characters, too short to hold events. | — | — | — |
dream_generated |
decision | Dream-generated pages are never mined for events. | — | — | — |
page_body_segmented |
decision | An earlier release skipped this page: its body is over the 24 MiB single-string ceiling and is stored in segments. This release reads segmented pages, so the next revision or a backfill extracts it. | — | — | — |
no_write_decision |
discovery | This revision has no recorded write decision (written by an older binary or before this release activated), so only a trusted backfill extracts it. | gbrain chronicle-backfill --source <source> --since <YYYY-MM-DD> --limit 50 --yes (preview: gbrain chronicle-backfill --source <source> --since <YYYY-MM-DD> --limit 50 --dry-run) |
agent | paid |
not_chronicle_shaped |
decision | The page is no longer a meeting, conversation or calendar page, so the events extracted from it were retired. | — | — | — |
already_extracted |
decision | This exact content was already extracted; its events are current, so no new call is made. | — | — | — |
judge_input_unchanged |
execution | Nothing the extraction reads changed since the page was last extracted (for example only text past a long page's first 12,000 characters changed), so the earlier events are current and no new call is made. | — | — | — |
judge_input_failed |
execution | Earlier revisions of the page already spent every extraction attempt on exactly this text without publishing events (the judge's answer was cut off, unreadable, malformed or over the per-page spend cap), so it is not paid for again until the text extraction reads changes. | gbrain chronicle-backfill --source <source> --since <YYYY-MM-DD> --limit 50 --yes (preview: gbrain chronicle-backfill --source <source> --since <YYYY-MM-DD> --limit 50 --dry-run) |
agent | paid |
superseded |
execution | A newer revision replaced this content before extraction ran; the newer revision carries its own decision. | — | — | — |
daily_limit |
execution | The automatic daily limit (chronicle.auto_daily_limit = 200 calls per rolling 24 hours) is used up; pending pages wait for a free slot. | gbrain config set chronicle.auto_daily_limit 400 |
agent | paid |
judge_llm_unavailable |
execution | No chat provider is configured on the brain host, so extraction cannot run. | — | user | credentials |
no_pricing |
execution | chronicle.job_budget_usd was set explicitly, and gbrain has no price for provider:model, so the cap cannot be enforced. | gbrain pricing set <provider:model> --input <usd-per-1M-input-tokens> --output <usd-per-1M-output-tokens> --source <pricing-page-url> |
agent | — |
budget_exhausted |
execution | The extraction call cost more than chronicle.job_budget_usd allows for one page. | gbrain config set chronicle.job_budget_usd 0.50 |
agent | paid |
campaign_exhausted |
execution | The page used every attempt its capped backfill (chronicle-backfill --max-usd) authorized without finishing, so it stops before spending more. | gbrain chronicle-backfill --source <source> --since <YYYY-MM-DD> --limit 50 --dry-run |
agent | — |
judge_chat_error |
execution | The chat provider returned an error; the page retries with backoff. | — | provider | — |
judge_truncated |
execution | The extraction output hit chronicle.judge_max_tokens and was cut off, so nothing was written. | gbrain config set chronicle.judge_max_tokens 8000 |
agent | paid |
judge_parse_failed |
execution | The extraction output had no parseable JSON array, so nothing was written; the page retries on a later run. | — | — | — |
malformed_proposal |
execution | A proposed event failed validation, so the whole batch was rejected and nothing was written; the page retries on a later run. | — | — | — |
publish_error |
execution | Publishing the events failed; nothing from this attempt replaced the previous events, and the page retries on a later run. | — | — | — |
judge_refused |
execution | The chat model refused or filtered the page; no events were written. | — | — | — |
page_missing |
execution | The page was deleted before extraction ran. | — | — | — |
no_events |
execution | Extraction read the page and found no events. | — | — | — |
future_dated |
execution | Every event the extraction proposed was dated after the page's own day (a plan, follow-up or scheduled item), so none was written; only what happened by the end of the page's day becomes an event. | — | — | — |
date_imprecise |
execution | Every event the extraction proposed had only a year or a month ("back in 2024"), so none was written; the timeline stores days and never invents one. | — | — | — |
no_chat_provider |
phase | No chat provider is configured on the brain host, so the chronicle phase made no calls. | — | user | credentials |
A malformed_proposal refusal also says which check failed, without the
proposal itself. The chronicle phase prints one warning line per refused page
(code=when_unparseable field=when; proposal 2 of 7; 1 of 7 inspected invalid),
and the extractor result carries the same fields under malformed: code
(not_object, missing_field, wrong_type, when_too_short,
when_unparseable, what_blank, who_item_not_string, or beyond_bounds
when the defect lies past what was inspected), the schema field, the JSON
shape found there, and counts. It never contains a value, a key the model
invented, the prompt or the raw response. At most 50 proposals, 50 who
entries each and 256 characters per string are inspected, and nested values
are never walked. The refusal itself, its retry with backoff and the ledger
row are unchanged.
Don't hand-write life/events/ pages: extraction owns them and retires events
the page no longer supports. Edit the meeting page instead. Only a complete
re-extraction retires events: one that finds no events, drops or caps a
proposal, or reads a page longer than the judge's window keeps the earlier
events live. A page longer than the window counts as complete when the window
still starts with all the text the live events came from (the conversation
only grew at the end), so a re-extraction of it replaces them. A revision that
changes nothing extraction reads (for example only a long conversation's
newest messages, past the window) makes no call at all and records
judge_input_unchanged, and text the judge keeps failing on is paid for at
most the attempt limit across revisions (judge_input_failed). An extraction
that dropped proposals over chronicle.max_events_per_page is asked again
when that setting changes, and one that dropped proposals dated after the
page's last day is asked again once that day moves. Text past the
first 12,000 characters is not extracted yet.