Skip to content
Sadie

Compile Cadence

Sadie’s output does not live update. A background compile job runs on a cadence, ingests new sources and feed items, applies incremental patches to your wiki, promotes Soul candidates that have crossed threshold, and refreshes discourse opportunities.

This page covers what the compile does, how to set the cadence, and what self-hosters need to wire up.

What an incremental compile does

Section titled “What an incremental compile does”

A compile run is not a full rebuild. It walks through four phases, each of which only touches what has changed since the last run:

  1. Source ingest. Any newly added source is extracted, themes detected, candidates produced. The incremental wiki pipeline matches candidates against existing entries and produces WikiPatch objects for surgical updates.
  2. Wiki patches. Each patch writes a wikiPatchEvents row with before and after content hashes. The idempotency index prevents double-patching the same content if a job retries.
  3. Soul promotion. Preference candidates that have accumulated enough evidence, distinct days, and distinct subject references get promoted into confirmed soul_state items or voice portrait adjustments. Decayed items are marked decayed if evidence has stopped arriving.
  4. Discourse refresh. Feed items are clustered by theme. Clusters that cross briefClusterMinSize produce briefs. Cross-referenced with wiki seeds and Soul, the top three clusters produce discourse opportunities for Today.

The SEPL loop runs on top of this: if accumulated XP has crossed the level-up threshold, a new agent version is generated, evaluated against recent interactions, and committed if it wins.

Cadence knob in Settings

Section titled “Cadence knob in Settings”

In Settings > Sadie, the Compile cadence card gives you four options:

  • Hourly. Rebuild every hour.
  • Every 4h. The default.
  • Daily. Rebuild once a day.
  • Manual only. Never automatically; only when you hit a recompile button.

The setting captures intent. For it to take effect, a scheduler has to actually call the compile endpoint.

Wiring a scheduler (self-hosters)

Section titled “Wiring a scheduler (self-hosters)”

Two supported paths:

Local development

Section titled “Local development”

Run the local scheduler in a second terminal:

Terminal window
pnpm dev:scheduler

This polls the compile endpoint on your chosen cadence. The scheduler reads the same setting, so changing cadence in the UI takes effect on the next tick.

Set SADIE_CRON_SECRET so the scheduler can authenticate to the endpoint:

Terminal window
SADIE_CRON_SECRET=your-shared-secret

When this is set, the Settings page shows “scheduler active” next to the cadence card.

Hosted (Cloudflare Worker)

Section titled “Hosted (Cloudflare Worker)”

In production, point a Cloudflare Worker cron trigger at /api/compile/run with the same SADIE_CRON_SECRET in the Authorization header. Fire the worker on whichever external cadence you prefer; Sadie respects the user setting when deciding whether to actually run.

Manual recompile

Section titled “Manual recompile”

Picking “Manual only” does not disable compile. It just removes the schedule. You can still trigger a recompile from the dock, from the Today empty state, or from any brief view that offers “refresh.” The compile runs on-demand and writes the same patches and activity rows as a scheduled run.

Section titled “Related”