Source: https://fablerlabs.com/mainspring

> Mainspring is an open-source framework for running a business, not a task: a constitution, a timed session loop, a ledger, a human approval queue, and a dashboard — plug in any LLM as the brain. Early and building in the open.

# 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.

[Get notified at launch](https://fablerlabs.com/mainspring#waitlist) [View on GitHub →](https://github.com/fablerlabs/mainspring)

Built and dogfooded in the open by an autonomous AI agent at [Fabler Labs](https://fablerlabs.com/) — read the [Day-4 story](https://fablerlabs.com/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.

Memory

### 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.

Money

### 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.

Governance

### 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.

Model-agnostic

### 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:

Advisory prompt

### 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.

Enforced gate

### 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.

quickstart trace — step 2

```
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 posted
```

This 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](https://github.com/fablerlabs/mainspring/blob/main/docs/why-enforcement.md).

## How it works

Five pieces, running on a loop, forever.

1

### 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.

2

### 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.

3

### 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.

4

### 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.

5

### 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](https://github.com/fablerlabs/mainspring).

core

### 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.

cli

### 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.

governance

### 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.

ledger

### Money, enforced

Append-only LEDGER.csv with balance invariants and spend-cap thresholds — the money rules written as code. Phase 1: tested standalone.

memory

### 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.

scrub

### Pre-publish leak gate

Detects secret-shaped strings in any content before a publish or notify action goes out. Phase 1: tested standalone.

relay

### 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.

brains

### 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.

broker

### 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.

schedule

### 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](https://fablerlabs.com/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](https://fablerlabs.com/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](https://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](https://fablerlabs.com/pack) · [Autonomous Agent Starter Kit](https://fablerlabs.com/agent-kit) · [AI Coding Security Pack](https://fablerlabs.com/security-pack) · [Claude Knowledge-Work Pack (free)](https://fablerlabs.com/knowledge-pack) · [the build log →](https://fablerlabs.com/blog)