Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
Key files: Core Cycle primitive
Subsystem index. Read only the entries relevant to your change. Current behavior and load-bearing invariants; history belongs in Git and CHANGELOG.
src/core/cycle.ts— brain maintenance cycle primitive (ALL_PHASESis the ordered source of truth;fence_repairfollowssyncand runs thefencesrepair kind throughcycle/fence-repair.ts).runCycle(engine: BrainEngine | null, opts: CycleOpts): Promise<CycleReport>composes phases in semantic order along the core spine lint → backlinks → sync → synthesize → extract → patterns → recompute_emotional_weight → embed → orphans, with the extraction/graph/consolidation phases (extract_facts, extract_atoms, resolve_symbol_edges, …) slotted between per the ordering comments onALL_PHASES.synthesizeruns after sync (cross-references see a fresh brain) and before extract (auto-link materializes its writes);patternsruns after extract so it reads a fresh graph (subagent put_page setsctx.remote=trueand skips auto-link/timeline by default, so extract is the canonical materialization);recompute_emotional_weightsees the union ofsyncPagesAffected+synthesizeWrittenSlugs+ the source window's slugs (cycle/source-window.ts: a per-source cycle that runs no sync works on at most 2,000 pages changed since its previous cycle, #6803, #8573; its cursor is stamped as UTC ISO with microseconds viato_char, never::text, so a non-ISO session DateStyle cannot reset the walk, #8771) incrementally, or all pages when none of those anchors is set (full backfill viagbrain dream --phase recompute_emotional_weight).CycleReport.schema_version: "1"is stable;totalsis additive (pages_emotional_weight_recomputed,transcripts_processed,synth_pages_written,patterns_written). Three callers:gbrain dreamCLI,gbrain autopilotdaemon inline path, the Minionsautopilot-cyclehandler.runPhaseLintskips withstatus: 'skipped'anddetails.reason: 'disabled'before any scan whencycle.lint.enabledis explicitly false (#6369,cycleLintPhaseEnabledincycle/lint-fix-setting.ts;onceForPhase === 'lint'threads through asopts.onceand bypasses it for one run;gbrain lintnever reads it), repairs withfix: trueunless DB configcycle.lint_fixis explicitly false (report-only;gbrain lint --fixunaffected);cycle.lint_exclude(#6134,cycle/lint-fix-setting.tscycleLintExcludes/parseCycleLintExclude) lists basenames the lint phase and thelint/lint-fixminion handlers skip (details.excluded;config setrefuses a path); managed repairs left pending keep the phase atwarnand surface asdetails.pending(test/managed-lint.test.ts). Coordination viagbrain_cycle_locksDB table +~/.gbrain/cycle.lockfile lock with PID-liveness for PGLite; the two handles compose into ONE lock whoserefresh()treats the fenced DB row as the authoritative multi-writer identity and the file half as best-effort freshness — the file lock is refreshed ONLY while the fenced DB refresh reports ownership, so a losing holder can never clobber the successor's file lock on the very tick it detects the steal. A dedicated serialized refresher —startCycleLockRefresher(lock, controller, lockId)(exported; unref'dsetIntervalatmax(15s, TTL/6), env-only overrideGBRAIN_CYCLE_LOCK_REFRESH_MS, in-flight guard so a slow refresh never overlaps the next tick) — heartbeats the lock through long phases (synthesis/patterns/consolidation waits routinely outlive the TTL with no other heartbeat). A fenced miss aborts the controller withLockStolenError; that steal signal combines with the worker's external signal via the exportedanyAbortSignal(signals)(src/core/abort-signals.ts, re-exported; duck-type-tolerant — stubs withoutaddEventListenerare observed by poll; returns{signal, dispose}and dispose detaches the caller-signal listener + clears the poll timer so daemons don't leak), and the run stops at the next phase boundary with a structured partial report carryingreason: 'lock_stolen'(for the 5 long phases — synthesize / extract_atoms / patterns / synthesize_concepts / consolidate — the steal races the phase promise and stops the WAIT immediately; extract_atoms also receives the cycle signal as a realAbortSignaland stops at its next item, the others run to their own bounded timeout). A busy DB lock'scycle_already_runningskip carrieslock_holder(id,holder_pid,holder_host,age_ms). A source-scoped cycle that selects a brain-wide phase (in NEEDS_LOCK and notsourcescope) also tries the sharedgbrain-cyclelease throughcycle/lock-set.ts; when another cycle holds it, the source phases run and each brain-wide phase is reportedskippedwithmaintenance_lock_busy(an all-skipped selection reportsskipped). Transient refresh errors log and retry next tick (the TTL stays the backstop).yieldBetweenPhasesruns between phases;yieldDuringPhaseis in-phase keepalive;onPhaseStart(phase, index, count)is awaited insidetimePhaseas each selected phase starts its work (index and count within the resolved selection; a throwing hook is logged, never fatal), which theautopilot-cyclehandler turns into job progress. Engine nullable; lock-skip on read-only phase selections.CycleOpts.signal?: AbortSignalpropagates the worker's abort signal withcheckAborted()between every phase.CycleOpts.deadlineAtMs(the enclosing minion job's ABSOLUTE wall-clock deadline, threaded fromMinionJobContext.deadlineAtMsby the autopilot-cycle handler; null for directgbrain dreamcallers) flows into patterns, propose_takes, synthesize AND fence_repair so time-spending phases derive their deadlines from the REAL remaining job budget instead of duplicated literals that collide with the job's own kill timer. Pinned bytest/cycle-lock-steal.serial.test.ts(mid-run steal → partial report, no further phases, successor row intact) +test/cycle-any-abort-signal.test.ts+test/db-lock-fencing.test.ts.runPhaseSyncreturnspagesAffectedviaSyncPhaseResult(threaded torunPhaseExtractas the 4th arg) and takeswillRunExtractPhase: booleansettingnoExtract: phases.includes('extract')sogbrain dream --phase syncdoesn't silently lose extraction. The extract phase callsrunExtractCoreandextractStaleFromDBwithquiet: true(andjsonMode: false), so the helpers' human summaries never land on stdout ahead of thedream --jsonCycleReport while batch-loss diagnostics stay human-readable on stderr (quietis its own knob onExtractOpts— usingjsonMode: trueas a stand-in flipped the stderr channel to JSON events in a plaingbrain dream);totals.pages_extractedcounts pages (pages_processedfrom the targeted pass +stale_pages_drained), not links created.resolveSourceForDir(engine, brainDir)threadssourceIdtoperformSync()so sync reads the per-sourcesources.last_commitanchor (not the drift-prone globalconfig.sync.last_commit). It matches only an absolutelocal_path; with no match the sync phase checksdefaultand failssync_anchor_relative(with its fix) while that path is relative.CycleOpts.brainDirisstring | null; when null (checkout-less postgres/Supabase brain, or a connector source) the 5 filesystem phases (lint/backlinks/sync/synthesize/patterns) skip withdetails.reason: 'no_brain_dir', extract runs the database-only stale drain (cycle/connector-extract.ts), and the DB-only phases run;resolveSourceForDiris null-tolerant.cycleSourceId = opts.sourceId ?? resolveSourceForDir(engine, brainDir)is the canonical per-source scope forextract_facts/extract_atoms/calibration — and forsynthesize(threaded asSynthesizePhaseOpts.sourceIdso synthesized pages land in the cycle's resolved source, not'default') — sogbrain dream --source repo-areconciles repo-a's facts even with no checkout (instead of scoping to'default'while stamping repo-a fresh).deriveStatuscountsedges_resolved/edges_ambiguousas work so an edges-only cycle reportsoknotclean, and scores ONLY attempted phases — the implicit source-cycle exclusion skip-records are bookkeeping and never dilute failure aggregation; thejobs.tsautopilot-cycle+ phase-wrapper handlers passnull(not'.') when no repo is configured. The cycle is SPLIT for autopilot fan-out along thePHASE_SCOPEtaxonomy insrc/core/cycle/phase-scope.ts(see its entry): cycle.ts derivesSOURCE_PHASES/MIXED_PHASES/GLOBAL_PHASES/MAINTENANCE_PHASES(mixed ∪ global, original cycle order) plusSOURCE_FRESHNESS_PHASES(deterministic, non-LLM: lint/backlinks/sync/extract/extract_facts/recompute_emotional_weight — defined in phase-scope.ts) andSOURCE_BACKGROUND_PHASES(LLM-backed/unbounded source work = SOURCE minus FRESHNESS).resolveCyclePhases(requested, sourceId)at the shared runCycle boundary: default/no-source →requested ?? ALL_PHASES(the canonicaldefaultcycle remains full); a named non-default source with NO explicit phases →SOURCE_FRESHNESS_PHASESonly (the freshness keeper's implicitdream --source Xpath must stamp freshness without first draining LLM-backed maintenance); explicit phase lists are honored VERBATIM —dream --source X --phase synthesize(and--input <file>, which implies synthesize) is deliberate operator intent, and--phase orphans --source Xstill narrows orphans viaforceGlobalOrphans. The N-way duplication guard lives at the QUEUE boundary instead: theautopilot-cyclehandler intersects queued per-source payloads withSOURCE_FRESHNESS_PHASES(queued payloads may carry mixed+background phases; an all-rejected or empty list is an explicit no-op skip with reasonall_phases_rejected_by_normalization, never an implicit run, and rejected phases surface on the job result asphases_rejected_by_normalization). On the implicit path, excluded phases surface asskippedwithdetails.reason: 'excluded_from_implicit_source_cycle'+phase_scope. Per-sourceautopilot-cyclejobs enqueuephases: SOURCE_FRESHNESS_PHASESand stamplast_source_cycle_at; the singleautopilot-global-maintenancejob runsMAINTENANCE_PHASES(nosourceId) and stamps the brain-levelautopilot.last_global_atconfig key (LAST_GLOBAL_AT_KEY). SOURCE_BACKGROUND phases have NO automatic lane on multi-source brains (the legacy full-cycle job fires only when the brain has no sources rows) — run them explicitly (gbrain dream --source X --phase extract_atoms) until the background lane lands (see TODOS). The freshness stamp gate isopts.sourceId && phases.length > 0 && engine && !dryRun && !aborted && status ∈ {ok, clean, partial};last_full_cycle_atis still written alongsidelast_source_cycle_aton a per-source success for doctor/legacy readers (not a gate for the brain-wide phases). A lost filesystem-walk or incremental extract write (ExtractBatchWriteError, codeextract_write_lost,src/core/extract-watermark.ts) leaves only its pages unstamped and makes the extract phase warn, like a GBRA-130 A-1 stale drain failure; the same cycle's stale drain retries those pages. Pinned bytest/dream-postgres.serial.test.ts+test/jobs-autopilot-cycle-braindir.test.ts+test/autopilot-global-maintenance.test.ts+test/cycle-enabled-phase-completeness.test.ts.runPhaseLint+runPhaseBacklinkscarry theexportkeyword so behavioral tests can drive them directly (internal helpers exposed for test-only consumption; downstream code should NOT depend on them). Pinned bytest/cycle-legacy-phases.test.ts(11 cases across both phases: clean run → status='ok', partial fix → status='warn' withdryRunin details, dry-run path doesn't write, throw-from-lib → status='fail' with the wrapper's try/catch envelope populated). withsrc/core/cycle/extract-atoms.ts+src/core/cycle/synthesize-concepts.ts+src/commands/extract.ts+src/commands/doctor.ts+src/core/op-checkpoint.ts: six daily-driver ops behaviors. (1) Batch idempotency:atomsExistingForHashes(engine, sourceId, hashes[])(exported fromsrc/core/cycle/extract-atoms.ts) answers in one batched SQL roundtrip (never a per-hash loop) returning already-extractedcontent_hash16values; fail-open (SQL error → empty set, extraction proceeds); powered by migration v104pages_atom_source_hash_idx(partial expression index onfrontmatter->>'source_hash'for atom rows wheredeleted_at IS NULL; PostgresCREATE INDEX CONCURRENTLYwith invalid-remnant pre-drop, PGLite plain). (2) Cycle lock TTL + heartbeat:LOCK_TTL_MINUTES = 5;buildYieldDuringPhase(lock, outer)(exported, withLockHandle) callslock.refresh()+ any external hook on every fire, throttled to 30s viamaybeYield, firing both in the main loop AND immediately after everyawait chat(...);synthesize_conceptsuses the same throttled hook. A crashed cycle releases its lock within one short TTL, while the dedicatedstartCycleLockRefresherinterval (see the coordination sentence above) keeps a healthy long-running cycle alive even across a single multi-minuteawait chat(...)— the timer fires during awaits, so no single slow call can silently expire the lock. (3) Progress wiring:progress?: ProgressReporteropt onExtractAtomsOptsandSynthesizeConceptsOpts; cycle.ts passes its phase-level reporter down (NOT a child reporter, which would collide oncycle.extract_atoms.extract_atoms.work); phases only calltick()/heartbeat(), cycle.ts ownsstart()/finish(). (4)by-mentionresume:mentionsFingerprint({source, type, since, gazetteerHash})insrc/core/op-checkpoint.ts— the gazetteer hash (hashGazetteerinsrc/core/by-mention.ts— every entry's source_id/slug/title/tokens, not just the first-token bucket keys, so a new "Acme Labs" beside an existing "Acme Corp" moves it) is load-bearing (adding entity pages mid-pause shifts the hash → new fingerprint → fresh scan against the new gazetteer, never silent skip);findMentionedEntitieskeys its self-link guard and first-mention dedup on(source_id, slug), so underlink_resolution.cross_sourcea foreign namesake of the scanning page is a real target and same-slug pages in two sources both link; the gazetteer itself is entity-page titles PLUS live-verifiedpage_aliasesentries joined to entity-typed pages (ambiguous aliases and alias-vs-title collisions within a source are skipped), so body mentions of a documented alias link too;gbrain extract links --by-mentionresumes viaop_checkpointswithflushAndCheckpointordering (links flush to DB FIRST, page keys commit to checkpoint SECOND, persist THIRD, so a crash mid-batch leaves the page un-checkpointed and resume re-scans it); persist every 1000 items OR 30s; clean exit clears the checkpoint;--dry-runskips both load and write. (5)sync_consolidationdoctor check (multi-source brains see a paste-readygbrain sync --all --parallel 4 --workers 4 --skip-failed; a managed brain (managedPersistenceEnabled, false whenpersistence_brainis missing) seesgbrain sync --all --no-pull --hard-deadline 13mevery 15 minutes on the owner host withgbrain sources refresh <id>;chained first for remote-tracking checkouts; single-source "not applicable"; SQL errors returnwarnvia the check's own try/catch). (6) Test-isolation:test/cycle-last-full-cycle-at.test.ts+test/schema-cli.test.tsuse per-testGBRAIN_HOME=tempdir. Pinned bytest/cycle/extract-atoms-batch.test.ts,test/core/cycle.serial.test.ts(5-minute DB-lock and file-lock TTL behavior),test/op-checkpoint-mentions-fingerprint.test.ts,test/cycle/extract-atoms-progress.test.ts,test/cycle/synthesize-concepts-progress.test.ts,test/cycle/yield-during-phase-refresh.test.ts,test/cycle/yield-during-phase-throttle.test.ts,test/extract-by-mention-resume.test.ts,test/doctor-sync-consolidation.test.ts. Companionsync --allrecipe block inskills/cron-scheduler/SKILL.md.synthesize_conceptswrites concept pages throughimportFromContent(the same parse→chunk→embed pipeline put_page uses, with put_page'sisAvailable('embedding')→noEmbedgate) soconcepts/pages carrycontent_chunks+ embeddings and are reachable by retrieval (wheresource-boost.tsweights them 1.3×).purgephase (soft-delete TTLs) also GCs staleop_checkpointsrows older than 7 days and, whencycle.purge.mcp_request_log_retention_daysis set, prunes the request log (runMcpLogRetention;purged_mcp_request_log_countin details only when above 0). Non-fatal on pre-v67 brains (DROP-target-table check before DELETE). The cycle threads its abort signal into the embed phase (runPhaseEmbed(engine, dryRun, signal)) so a timed-out cycle's long embed phase honors cancellation and releasesgbrain_cycle_locksright away instead of after a full backlog run. Theextract_factsphase runs the S9 conflict sweep as its tail (ai/decide/sweep.tsconflictSweepTail) only whendecide.slots.conflict.modeis not off, addingdetails.decide_conflict; with the slot off the phase output is unchanged. The extract_atoms / synthesize_concepts pack gate (#6393) issrc/core/cycle/pack-phase-gate.ts(Core Cycle (continued));packDeclaresPhase(engine, phase, sourceId?)delegates to it.