Garry's Opinionated OpenClaw/Hermes Agent Brain
Planner statistics on PGLite
PGLite (the embedded engine) has no autovacuum, so nothing collects planner statistics on its own. Without them the query planner guesses row counts and runs search and graph reads as nested loops over every page: a search that takes 40 ms on an analyzed 10,000-page brain can take tens of seconds on an unanalyzed one. GBrain keeps these statistics fresh for you. This is on by default; Postgres brains are unaffected (autovacuum owns statistics there).
How it works
- Every statement that changes
pages,links,facts,takes,content_chunksortimeline_entriesrecords how many rows it touched inplanner_stats_deltas. The record commits or rolls back with the data and survives crashes and restarts, so changes from remoteput_page,remember, raw SQL or a killed process all count. - A table is stale when the rows changed since its last ANALYZE exceed
max(500, 10% of the table), or when it has rows but no statistics. - Stale tables are analyzed (
ANALYZE <table>, bounded by sample size, not table size) at these points:- the first search,
get_health, orphan, backlink, graph or page-list read (at most one check every 2 seconds per process); - every
import.analyze_every_pagesfiles (default 500) duringgbrain importand managed sync; - before a stale link drain of at least 500 pages (
gbrain extract --stale, the dream cycle's extract phase, link extraction after a managed sync) and everyimport.analyze_every_pagespages during it;link_transitionsandlink_relationshipsare analyzed wheneverlinksis; - after the dream cycle's freshness phases, and when the resident write consumer is idle;
- the full ANALYZE that import and sync already run at the end resets every table's pending count.
- the first search,
- A new index on an expression (for example
lower(title)) has no statistics of its own until its whole table is analyzed; a column-list ANALYZE skips it. Schema migrations analyze the table right after they build an index (building <index> on ~N rows, then analyzing <table>). If that ANALYZE fails, the migration still completes with the valid index and prints a warning naminggbrain repair planner-stats --apply. A brain whose index was built before this (an upgraded brain with the v240 name-lookup indexes: a 50-nameentity namesbatch on a 55k-page brain took 5.4 s instead of 1.2 s) gets the statistics at the next maintenance point above (import, managed sync, link drain, dream cycle, idle consumer); a search's first read never runs this check. An expression whose values are all null still gets statistics, and an empty table or a partial index matching no rows is not flagged. - If a table's last ANALYZE took longer than
planner.first_read_budget_ms(default 2000), a read does not wait for it: the table is analyzed right after the read answers.
Check and repair
gbrain doctor # planner_stats_stale names each stale table and expression index
gbrain repair planner-stats # preview: stale tables, pending row counts, indexes without statistics
gbrain repair planner-stats --apply # ANALYZE them now (works with auto-analyze off)
Doctor reports an expression index without statistics on its own line,
expression index <name> (on <table>) has no statistics, separate from the
row-delta count. On both engines the check covers the hot tables above and
skips an index whose statistics the database role cannot see (unknown, not
absent).
On Postgres nothing collects an existing index's statistics automatically:
autovacuum analyzes a table only after 10% of its rows change, so a quiet
brain keeps the gap. Doctor warns, and an operator runs
gbrain repair planner-stats --apply on the brain host (one whole-table
ANALYZE per table, 60 s statement timeout, deferred while another session
holds the table).
On Postgres, planner_stats_stale reads pg_stat_user_tables and warns only
when a table is over the same threshold and neither ANALYZE nor autoanalyze ran
in the last hour; the repair runs each ANALYZE with a 60 s statement timeout.
ANALYZE never waits on a vacuum (Postgres)
ANALYZE takes the same table lock as VACUUM and autovacuum, and Postgres
cancels an autovacuum once another session has waited deadlock_timeout
(1 s by default) for that lock. On a large content_chunks an ANALYZE after
every embed drain could cancel every autovacuum of the table before it
finished, leaving millions of dead rows in every index (#7083). So every
ANALYZE gbrain runs on Postgres on its own (the import, sync, reindex and
embed refreshes, the search guard, gbrain repair planner-stats --apply
and the ANALYZE after a migration builds an index) first locks the table with NOWAIT: when a vacuum, another
ANALYZE or an index build holds it, the ANALYZE is deferred with a warning
(the repair reports the table deferred) and never waits. The embed
drain's chunk refresh also skips a drain that changed fewer than 50 + 10% of
the table's chunks once the chunk statistics exist; autovacuum's own analyze
covers what small drains add up to.
planner_stats_stale also warns when a hot table of at least 100,000 rows
holds more dead rows than autovacuum's vacuum threshold and no vacuum has
completed on it for 24 hours: something keeps cancelling its autovacuum.
Look for canceling autovacuum task in the server log and the statement
logged next to it; once nothing cancels it, autovacuum finishes on its own,
or the database operator runs VACUUM (VERBOSE) <table> in a quiet window.
Postgres can also lose the statistics outright: pg_upgrade carries none and
resets the modification counters, so autovacuum never collects them again
until 10% of a table changes. Without the page columns search filters read,
search plans as nested loops over every page (50-60 s per search at 5,000
pages instead of 0.5 s). gbrain guards this two ways, both through the same
refresh as import and sync (ANALYZE pages(...) and
ANALYZE content_chunks(model, modality, page_id, body_generation), 30 s bounded):
- The first search of each process checks in the background and collects them when the database role owns the tables. The search does not wait for it.
planner_stats_stalewarns with the absent columns, andgbrain repair planner-stats --applycollects them (run it as the table owner when the brain's role is not).
Settings and opt-out
| Setting | Default | Effect |
|---|---|---|
planner.auto_analyze (env GBRAIN_PLANNER_AUTO_ANALYZE, which wins) |
true |
false turns off every automatic ANALYZE, including the full ANALYZE at the end of import and sync (which falls back to the narrow pages refresh the search projection needs). Doctor still reports stale tables. |
planner.first_read_budget_ms |
2000 |
A stale table whose last ANALYZE took longer is analyzed after the read instead of before it. |
import.analyze_every_pages |
500 |
Import, managed sync and stale link drains check statistics every N files or pages; 0 disables that cadence. |
To opt out: gbrain config set planner.auto_analyze false. To turn it back on:
gbrain config set planner.auto_analyze true.