brainfile-lite

Persistent memory and working conventions for Claude Code — the simple, open standard.

Claude Code is brilliant for a session and amnesiac between them. Every project ends up re-explaining the same stack, the same rules, the same "no, we decided against that in March." A brainfile is the fix: a small set of plain-Markdown files, in your repo, that Claude reads at the start of every session — so context, decisions, and lessons persist and compound instead of resetting to zero.

This repo is the free, open core of that convention. No accounts, no lock-in, no telemetry — just files. Use it, fork it, make it yours.

What it looks like

Your always-loaded memory index is tiny — one line per lesson, detail in small files:

# MEMORY.md — index (always loaded; keep under 60 lines)
- [Reply style](memory/feedback_reply_style.md) — terse, code-first, no summaries
- [Never do](memory/feedback_never_do.md) — never force-push; never touch prod configs
- [Tooling picks](memory/project_tooling.md) — pnpm not npm; biome not eslint (locked)
- [Deploy quirk](memory/feedback_deploy_flag.md) — staging needs --legacy-peer-deps

Next session, Claude opens with your rules already loaded. Correct it once, it becomes a file the same day, and you never have that argument again.

Quickstart (2 minutes)

git clone https://github.com/brainfile-io/brainfile-lite.git && cd brainfile-lite
./install.sh /path/to/your/project

Then open Claude Code in your project and say:

"Read START-HERE.md and interview me to set up my brainfile."

Ten minutes of answering questions, and Claude writes your MEMORY.md, memory files, and starter rules itself. You edit; you don't author.

No installer preferences? It's three Markdown files — copy brainfile/ in by hand and rename MEMORY-template.md to MEMORY.md.

The conventions

File	What it is
CLAUDE.md	Your operating rules — Claude Code loads this automatically every session.
MEMORY.md	A tiny always-read index: one line per lesson, pointing at a detail file.
memory/*.md	One small file per lesson: feedback_* (corrections), project_* (decisions), reference_* (facts).
brain/	Working state: decisions.md (locked, don't re-litigate), backlog.md (never-empty work classes), HANDOFF.md (survive context resets).
START-HERE.md	The 10-minute setup, including the interview prompt that makes Claude write these files for you.

The load-bearing idea: agents don't learn between sessions — files do. Keep the always-loaded layer tiny (an index, not an essay), push detail into small named files, and turn every correction into a file the same day.

near-misses, and why "noted" is not an outcome). It's the convention we run our own agent operations on.

The bf command

install.sh also adds a tiny bf function to your shell profile (zsh/bash; skipped for other shells). Type bf in any terminal and you're in your project with Claude Code running and your brainfile loaded — the whole system, one word away:

bf() {
  cd "$HOME/your-project" || return 1   # install.sh fills in your real path
  claude
}

It's added between two # >>> brainfile-lite bf >>> marker lines — delete the block to remove it, or re-run install.sh on another project to repoint it. (We run our own businesses this way; ours is called mb. The paid pack extends bf into an Autopilot launcher — bf 8h starts a timed run that ends with a written end-of-run brief.)

Why files, not a platform

• Your repo is the database. Everything is greppable, diffable, and versioned with your code. Leave anytime; the files are still yours (they're just Markdown).
• It works today, with stock Claude Code. No wrapper, no plugin, no API key.
• The convention is the product. If your teammates' projects all speak MEMORY.md / brain/decisions.md / HANDOFF.md, every agent session — anyone's — starts oriented.

When you might not want this

Honesty section: if your project is a weekend script, CLAUDE.md alone is enough — skip the rest. If you're already deep into another memory convention that works for you, keep it; the ideas here (tiny index, same-day correction files, locked decisions) port to any file layout. brainfile-lite earns its keep on projects you'll still be working on next month.

What the paid pack adds (honest version)

Everything in this repo is complete and genuinely useful on its own — it is not a crippled demo. What brainfile.io sells is the maintained, living layer on top of these conventions:

• Autopilot depth — the full timed-run protocol we operate our own businesses on: pre-flight work selection, evidence-gated completion, end-of-run briefs, a ledger that never forgets an obligation.
• The freshness feed — the conventions here are a snapshot; the pack updates as Claude Code changes and as we learn new failure modes running agents daily (stale locks, hallucinated completions, context-reset recovery — the judgment layer).
• Interview onboarding, hosted — plus role packs and personalization.
• Support and a feedback loop — your issues shape what ships next.

30-day full trial, no card, at brainfile.io/trial. If you never upgrade, this repo still works forever — that's the point of an open standard.

Contributing

Issues and PRs are very welcome — see CONTRIBUTING.md. Issues are our feedback intake: tell us where the conventions fall short in real projects and we'll fold improvements back in fast, with credit.

License

MIT. Do anything you want with it.