Why every coding session should start with /memoir:onboard

The twenty-minute warm-up tax

Open a new Claude Code session. The agent can read your files, but it doesn't know which modules matter, what the project's goal is versus what's a non-goal, or which past mistakes the codebase has already paid for. You have two choices: re-explain the project at the top of every session, or accept that the first twenty minutes will be Claude rediscovering things.

/memoir:onboard is a small fix for that waste. It builds a curated snapshot of your codebase that Claude reads at session start and updates as the code evolves.

Incremental, on the main branch

Onboarding isn't a one-shot index. The first run is a cold pass that builds the full snapshot. Every run after that is a warm pass: it diffs the codebase against the commit recorded in the last snapshot and only rewrites the modules and lessons that actually changed.

A 200-commit branch with churn in three files refreshes in seconds, not minutes. If nothing has changed since the last pass, onboarding short-circuits to a meta-only update. No wasted LLM calls, no stale rewrites.

The snapshot lives on the main memoir branch, so the history of how the project's shape evolved is itself versioned.

Brief, but the right brief

The snapshot isn't a dump of the repo. It's a structured digest:

codebase:onboard
├── goal           — what this project is for
├── non-goals      — what it deliberately isn't
├── modules        — layout + one-line summaries
├── procedures     — test, debug, deploy
├── rules          — project-specific conventions
└── lessons        — gotchas, invariants, the why behind decisions

It's the README you'd write for a new teammate, except it's auto-maintained. Small enough not to bloat the context window. Dense enough that Claude doesn't need to grep around to learn the basics.

Every session starts already-onboarded.

Every session deserves to start at minute twenty, not minute zero.

Manageable from the Memoir UI

The snapshot is just a Memoir memory — codebase:onboard (or project:onboard for non-git folders). It lives in your store like any other memory.

The web UI gives you a full grip on it: view the structured contents, edit a lesson, forget a stale module summary, branch the store to experiment, or roll back if a refresh went sideways. No bespoke settings panel — the same UI you already use for every other captured memory.

Learns from commits, not just the static tree

This is the part most static codebase indexers miss. A pure AST or file-tree scan tells you what's there now. It can't tell you why.

The warm path reads commits since the last onboarding pass. When a refactor happens — a CLI flag renamed, a service reshaped, a workaround removed — those changes get folded into the module summaries and the lessons list. New bugfixes become future lessons. A renamed module's old name doesn't haunt the next session.

The snapshot reflects intent and direction, not just current state.

---

Try it now

$ /memoir:onboard

One run is all it takes. The warm path keeps it fresh from then on. Memoir is Apache 2.0 and ships as a Claude Code plugin — head to the quickstart on the homepage.

Get started with Memoir

A new teammate gets a README. Your agent should get one too — versioned, current, and waiting at session start.