Mainspring — the engine that keeps
your business running.
Swap in any brain. Mainspring is an open-source framework for running a real, ongoing business — not a task, not a one-off agent run. Give it a constitution, point it at any LLM as its "brain," and it wakes on a timer forever: reading its own memory from disk, doing a slice of work, keeping a ledger, escalating anything it can't do alone to a human, and going back to sleep — until the next wake-up.
A prompt is advisory — the model can always ignore it. Mainspring makes your rules enforced: a runtime gate inspects every action the brain proposes and blocks the ones that break the constitution before they happen. Your rules should be checked by code, not vibes.
Built and dogfooded in the open by an autonomous AI agent at Fabler Labs — read the Day-4 story of the business it already runs on an earlier version of these ideas.
Task frameworks vs. a business framework
LangChain, AutoGPT, and CrewAI are excellent at wiring up a task: give an agent tools and a goal, let it run, get an answer. Mainspring exists for a different problem — what happens when there is no "done," because the thing you're running is a business that has to keep operating, spending, and earning, indefinitely, mostly unattended.
Amnesia-proof by design
Every session starts from zero context and total amnesia. Mainspring's session loop forces state — what happened, what's next, what's owed — onto disk before it sleeps, so the next wake-up (possibly with a different model entirely) picks up exactly where the last one left off.
A real ledger, real caps
Every business spends and earns. Mainspring bakes in a ledger and spend caps as first-class citizens — not something you bolt on after the agent already bought something it shouldn't have.
Hard rules nothing overrides
A constitution the agent can read but not rewrite, plus a human approval queue for the things it genuinely cannot or should not do alone — accounts, large spends, ambiguous calls. The human is in the loop only where it must be.
Swap the brain, keep the business
The constitution, memory, ledger, and approval queue are model-agnostic by design. Point Mainspring at Claude, GPT, Gemini, or a local model — the business keeps running on the same rails.
Advisory rules don't hold
Write "you are an AI and never claim otherwise" into an instruction file and you've made a
request. On a bad turn the model can propose the rule-breaking action anyway — the file didn't stop it,
because a prompt has no teeth. Mainspring routes every proposed action through a gate that runs before the
action happens. Same rule, checked by code instead of good intentions. Here is exactly what the runnable
examples/quickstart does when the brain tries to post without disclosing it's an AI:
The rule is read, then ignored
The constitution says "You are an AI and never claim otherwise when posting or publishing." The
brain still proposes a post-to-reddit action with no disclosure. With nothing but a prompt, that
action would post.
The action is blocked, with a citation
The same action hits the governance gate. The honesty-disclosure rule fires, returns
block, and the post never leaves — refused by name against constitution hard rule 2, not silently
dropped.
brain proposes: run post-to-reddit { text: "Check out our new tool, it's amazing!" }
gate verdict: block
fired rule: honesty-disclosure (block) — a post/publish-shaped run action
must carry args.disclosedAsAI === true
(constitution: "You are an AI and never claim otherwise
when posting or publishing.")
result: action refused; nothing was postedThis is real, offline behavior you can run today —
no model, no network, no API key. The block comes from @mainspring/governance's evaluate(),
which reads the hard rules out of your CONSTITUTION.md. What a runtime gate can and can't stop is
documented honestly in why-enforcement.md.
How it works
Five pieces, running on a loop, forever.
Constitution
A plain-language file defining the mission, hard rules, and money caps — read at the start of every session, never modified by the agent itself.
Timed session loop
A supervisor wakes the agent on a schedule for a short, focused session — no standing process, no infinite loop racking up cost.
Ledger + approval queue + dashboard
Money moved gets logged. Anything the agent can't do alone — an account, a large spend, an ambiguous call — goes to a human approval queue, visible on a live dashboard.
Commit
State, memory, and ledger changes are committed to disk (and version control) before the session ends — the only way the next wake-up can know what happened.
Repeat
Wake up, read state, do the next piece of work, commit, sleep. Forever — until the constitution says stop, or a human does.
Ten packages, one monorepo
Mainspring is ten small, model-agnostic TypeScript packages in one repo — each with its own test suite, each building clean under tsc --strict. Two are stable and wired into the reference loop; the other eight are Phase 1 — real and tested on their own, but not yet called automatically by the core loop. Apache-2.0, live now at github.com/fablerlabs/mainspring.
The session loop
The swappable-brain contract and the constitution-enforcing loop — assemble → gate → dispatch → commit — plus EchoBrain, a zero-API-key reference brain. Stable: this is the loop the CLI runs, tested end to end.
init · run · status · doctor
The mainspring command: scaffold a workspace, run one session, inspect what it did, and diagnose a broken setup. Stable: all four commands verified against a real workspace.
Constitution as code
Hard rules the brain cannot override, loaded from CONSTITUTION.md and enforced as guards on every proposed action. Phase 1: tested standalone.
Money, enforced
Append-only LEDGER.csv with balance invariants and spend-cap thresholds — the money rules written as code. Phase 1: tested standalone.
Between-session state
Deterministic STATE.md compaction, journal, and session-log utilities for the memory the loop carries across amnesiac wake-ups. Phase 1: tested standalone.
Pre-publish leak gate
Detects secret-shaped strings in any content before a publish or notify action goes out. Phase 1: tested standalone.
Human in the loop
A zero-dependency client for the human-approval wire protocol — the leg that hands off what the agent can't safely do alone. Phase 1: tested standalone.
Bring any model
Reference Brain implementations: a scripted MockBrain for tests and a zero-SDK ClaudeBrain adapter for Anthropic's Messages API. Phase 1: request/response mapping unit-tested.
Capability-gated side effects
Named capabilities — spend, message, publish — each behind a cap of max amount, calls per day, and target allowlist, checked before every handler runs, allow or deny, with one audit entry either way. A compromised session can do no more than its caps allow. Phase 1: tested standalone.
When to wake next
Pure next-wake logic: a STOP-file kill switch, a fixed interval or cron expression, and exponential backoff while failing — no timers, no clock reads, so it stays deterministic and testable. Phase 1: tested standalone.
Three runnable, offline examples wire the packages into full scripted sessions — no API key, no network. quickstart runs five packages through an allowed write and a governance-blocked post; content-agent takes a publish blocked for missing AI-disclosure through a human relay approval and then the publish; full-stack-test composes seven packages across spend caps, a secret-scan block, a relay hand-off, and a scripted sale. The gate carries its own adversarial edge-case suite: writing the malformed and malicious inputs a real deployment hits surfaced and fixed a genuine fail-open bug — a path-traversal action id and a secret-scan bypass that had been slipping past the gate. Fail-closed is the rule, and the suite proves it.
FAQ
Is Mainspring a framework for autonomous-agent governance?
Yes — that's the wedge. Every side effect the agent's "brain" proposes passes a Constitution-checked
gate before it can happen (money caps, workspace-path safety, secret-shaped content), and the reason for
every block is logged. Hard rules load from a plain CONSTITUTION.md and can only tighten,
never loosen, the built-in checks.
How do I give an agent durable memory across sessions?
The session loop reads and rewrites on-disk state (STATE.md, journal,
LEDGER.csv) every wake-up, so memory survives amnesiac restarts by design rather than as a
bolt-on — the same amnesia-proof loop described under "How it works" above, generalized as the
@mainspring/memory package.
Can I enforce a spend limit or scan for leaked secrets in an AI agent?
Yes. The @mainspring/ledger package tracks an append-only ledger with per-action and daily
spend-cap thresholds, and @mainspring/scrub flags secret-shaped strings before any publish or
notify — both part of the governance layer above. Want a ready-made constitution to start from instead of
writing one? See the Agent Constitution Pack.
Early — and building in the open
Mainspring is pre-release. Nothing here is a shipped product yet: it's Phase 1 — a public repo with a green build and test suite, but no released npm package and no case studies beyond the business it's being distilled from. What's true today is that its core ideas — constitution, memory protocol, ledger, human approval queue — are already running in production inside Fabler Labs' own autonomous agent, documented honestly on the Story page, warts and all. Mainspring is that operating system, generalized and open-sourced so anyone can plug in their own brain and rules. The repo is live now at github.com/fablerlabs/mainspring — Apache-2.0, or join the list below and we'll email you when the packages hit npm.
Get notified at launch
The repo is already public — one email, the day the @mainspring/* packages hit npm. No spam, no other lists bundled in.
Also from Fabler Labs: AI Coding Workflow Pack · Autonomous Agent Starter Kit · AI Coding Security Pack · Claude Knowledge-Work Pack (free) · the build log →