wyrm_session_prime

Category

Sessions

Use first at session start - load everything you need to know before starting work, and catch me up on where we left off last time: ground truths, memory brief, reasoning scaffold, and active quests in one call. First call every agent makes in a run.

Signature

Argument	Type	Required	Description
project_id	number
project_name	string
projectPath	string
task	string		Drives scaffold + memory selection
log_session	boolean		Also log a session row
run_id	string		Fleet: brief cached per (run_id, role)
role	string
token_budget	number
for_spawn	boolean

Fleet mode (run_id / role)

Passing run_id switches to the byte-stable cached-brief path: the first prime of a (run_id, role) compiles a role-sliced brief under token_budget (default 1,200 tokens) and CAS-caches it in run_briefs, so every later prime of the same key — even across processes, even after the underlying memory changed — returns the byte-identical cached prefix (one shared prompt-cache prefix for the whole role).

Distribute-once (for_spawn: true)

For the lowest fleet cost, the orchestrator primes once per role with for_spawn: true and embeds the result in each same-role agent's spawn-prompt prefix — the agents never call prime themselves:

// orchestrator, once per role
const { structuredContent } = await wyrm_session_prime({
  run_id, role: 'builder', for_spawn: true,
});
// structuredContent.brief        -> clean embeddable markdown (byte-EQUAL to
//                                    what an agent-side prime would receive)
// structuredContent.brief_hash   -> sha256 of those exact bytes
// structuredContent.cache_key    -> { table: 'run_briefs', run_id, role }
spawnPromptPrefix = structuredContent.brief + '\n\n' + perAgentInstructions;

Because the brief is embedded in a prefix shared by every agent of that role, the cacheable share of the fleet's prime cost becomes never-sent bytes (a 12-agent / 4-role run drops from 12 prime deliveries to 4). It is purely additive and adoption-gated: an agent that still calls wyrm_session_prime({ run_id, role }) reads the same CAS row and receives the byte-identical brief, so a forgetful orchestrator degrades to the unchanged per-agent cost — never below it.