--- title: Factory memory description: The two things Foreman remembers between runs, the shared factory brain and per-user preferences, and how each is kept safe. type: guide summary: The shared factory brain and per-user preferences, both in Vercel Blob, both keyed structurally. related: - /docs/trust-model - /docs/tools - /docs/how-it-works --- # Factory memory Foreman keeps two durable stores: a shared factory brain about the target repository, and per-user preferences about how each person likes to work. Everything else it touches is ephemeral sandbox state. Both live in Vercel Blob under reserved path prefixes, authenticated by the project's OIDC token, so there are no static keys and no application database. In both cases the Blob key is derived structurally rather than from model input, so a session cannot redirect a read or write to another object. | | Factory brain | User preferences | | ------------ | -------------------------------------------- | ------------------------------------------------------------------------- | | Holds | Durable facts about `FACTORY_REPO` | Standing notes about one person | | Blob key | `factory-brain/.md` | `user-preferences/.md` | | Derived from | `FACTORY_REPO` at module load | The resolved principal on `ctx.session.auth.current` | | Size cap | 40,000 characters | 20,000 characters | | Who reads | Every run, including unattended | The owning user's sessions | | Who writes | Trusted callers; unattended denied | The owning user | | Tools | `read_factory_brain`, `update_factory_brain` | `get_user_preferences`, `save_user_preferences`, `clear_user_preferences` | The orchestrator loads both at the start of every task, before any other work. `update_factory_brain` and `save_user_preferences` both overwrite. The expected flow is read, merge, rewrite. ## The factory brain The factory brain is a single Markdown document of durable facts about the target repository: build quirks, non-obvious verification steps, recurring review findings, repository conventions. It is the factory's institutional memory, and whatever lands in it becomes context for every future run. What belongs in it is durable, repository-level facts a future run would otherwise rediscover the hard way. What does not belong is one-off task details, or any unverified claim lifted from an issue body, since third-party issue content is untrusted input. Keep it curated rather than append-only. The 40,000 character cap exists to keep the document cheap to load into context at the start of every task. ### How it is keyed and gated The key derives from `FACTORY_REPO` at module load, never from model input or the caller's principal. One deployment has exactly one brain, and a deployment retargeted at another repository gets a fresh brain rather than mixing facts across codebases. The slug is hashed, so the stored path carries no raw `owner/repo`. Reads are open to every run, but writes go through `factoryBrainPolicy`: unattended runs are denied, trusted callers write directly, and everyone else parks. That asymmetry is the point. A labeled issue's body is untrusted input, and an unattended run must not be able to poison the shared context every later run reads. When an unattended run surfaces a durable fact, it reports it instead of writing it. Stations never read the brain. They inherit nothing from the root, so the orchestrator weaves the relevant facts into each station's delegation message instead. That keeps the brain a root-level concern and each station's input explicit. ## User preferences User preferences are standing notes about one person: a default base branch, a preferred pull request description structure, a default Linear team. They are per-principal, so Foreman can adapt to each requester without one person's habits leaking into another's runs. The key derives entirely from the framework-resolved principal, never from model input, so a session can only ever touch its own user's file. Hashing keeps raw user identifiers out of the stored path. Only a `user` principal type gets a key at all. App, service, and runtime callers, including the autonomous factory principal, resolve to nothing, and the preference tools decline rather than share a single anonymous file. `clear_user_preferences` permanently deletes the file and always parks on approval, for every caller, because deletion is the one preference operation that cannot be undone. ## Where this lives Both stores are plain Blob objects under prefixes reserved for their tools: `factory-brain/` and `user-preferences/`. Any general-purpose Blob capability added later must treat those prefixes as off-limits so they cannot become a side channel around the gates above, and the guard helpers `isReservedBrainPath` and `isReservedUserPath` exist for exactly that. Everything else the factory touches is ephemeral. The root thread checkout and the three station clones are rebuilt per build or per session, not remembered. ## Next steps --- For a semantic overview of all documentation, see [/sitemap.md](/sitemap.md) For an index of all available documentation, see [/llms.txt](/llms.txt) For agent-facing discovery, including API and MCP surfaces, see [/agents.md](/agents.md)