A single rules file stops your AI from forgetting the basics. But real projects pile up knowledge: why you picked that database, the weird bug in the payment flow, what you were halfway through on Friday. If that only lives in your head (or in a chat you'll never find again), the AI starts every session half-blind.

The fix is to give the project a small memory system: a few plain files in the repo, each with one job, all backed up with git.

The layout

my-project/
├── AGENTS.md              # (or CLAUDE.md / GEMINI.md) the core brain
├── .agents/rules/         # scoped rules by topic (or your tool's rules folder)
│   ├── data.md
│   ├── deploy.md
│   └── brand.md
└── docs/brain/
    ├── NOW.md             # session handoff: current state + next steps
    ├── decisions.md       # decision log
    ├── architecture.md    # how the pieces fit
    ├── gotchas.md         # traps, weird bugs, "don't do X because Y"
    └── playbooks/         # step-by-step recipes for repeated tasks
        └── add-product.md

Folder names are up to you. Some tools load rules from their own folders automatically (for example .cursor/rules/); for anything a tool doesn't load on its own, the core brain file just points to it.

Layer 1: a short core brain file

The main file is loaded every session, so it holds only what's always relevant: overview, stack, commands, top rules, security. Then it says where the rest of the memory lives:

## Memory
- Start every session by reading docs/brain/NOW.md.
- Before changing architecture, read docs/brain/architecture.md
  and docs/brain/decisions.md.
- Topic rules: .agents/rules/data.md, deploy.md, brand.md.
  Read the relevant one before touching that area.
- Recipes for repeated tasks: docs/brain/playbooks/.

Layer 2: a knowledge folder

This is where longer, slower-changing knowledge goes. The AI reads these when relevant instead of on every request, which keeps context lean.

architecture.md: the main parts of the system and how data flows between them. Ten bullet points beats ten pages.
gotchas.md: things that bit you. "The prices API returns cents, not dollars." "Never run the import script twice; it duplicates rows." This file pays for itself fast.
glossary.md (optional): project words that mean something specific. "A binder is a user's collection page, not a PDF."

Layer 3: a decision log

AI assistants love to "improve" things by undoing decisions they don't know you made. A decision log stops that and saves you from re-arguing settled questions:

# Decisions

## 2026-10-02: Static site + JSON data, no database
Why: catalog is under 2,000 items and changes weekly; static is free,
fast, and simple to deploy.
Alternatives: Supabase (overkill for now), SQLite on a VPS (more ops).
Revisit if: we need user accounts or real-time stock.

## 2026-10-09: Prices rounded to .99 in the build step, not in data
Why: keeps raw data honest; rounding rules may change.

Add a rule: "Don't reverse a decision in decisions.md without asking. If one seems wrong, say why."

Layer 4: a session handoff file

NOW.md is short-term memory that survives between sessions. It answers "where were we?":

# NOW (updated 2026-10-20)

## Done last session
- Search box filters by name and set; works on mobile

## Next
1. Add sort by price
2. Fix: images on slow 3G pop in late (try width/height attrs)

## Open questions
- Should sold-out items be hidden or greyed out?

End every session with a prompt like this:

Before we stop: update docs/brain/NOW.md with what we did, what's
next, and open questions. Add any new decisions to decisions.md and
any traps we hit to gotchas.md. If I corrected you on the same thing
twice today, propose a rule for AGENTS.md. Then show me the diff.

Next time, "Read NOW.md and continue" picks up exactly where you left off. Reviewing the diff matters: you're the editor of the memory, not the AI.

Layer 5: scoped rules by topic

When the core file grows past a page or two, split topic rules into their own files. Here's the shape of a real project we learned from: a card shop catalog deployed on Cloudflare Pages, whose GEMINI.md had sections like these, with more detail in .agents/rules/*.md:

# GEMINI.md: card shop catalog

## Data rules
- data/inventory.json is the single source of truth for stock.
- Never edit generated files by hand; change the source and rebuild.

## Deploy security
- Only the public/ folder is deployed. Never deploy the project root,
  config files, scripts, or raw data.
- Credentials live outside the repo. Never print or commit them.

## Architecture and git sync
- Build script reads data/, writes public/.
- Commit and push after each working change so the remote is the backup.

## Pricing logic
- Prices are computed in one function from market price + rules.
  Never hardcode a price in HTML.

## Performance targets
- Catalog page interactive in under 2s on mid-range phones.
- Lazy-load images below the fold; always set width and height.

## Brand rules
- Use the brand palette and fonts only; friendly, collector-to-collector tone.

Notice what makes this work: every section is about a specific area where mistakes are expensive, and every rule is concrete enough to check.

Layer 6: playbooks (some tools call them skills)

For tasks you repeat, write the recipe down once. Then "follow playbooks/add-product.md for the Charizard card" gets consistent results every time:

# Playbook: add a product
1. Add the item to data/inventory.json (fields: id, name, set, price, image).
2. Put the image in public/img/ as {id}.webp, 600px wide.
3. Run `npm run build` and check the catalog page locally.
4. Commit with message "Add product: {name}".

Some AI tools have built-in features for packaging reusable instructions like this, usually called skills, commands, or prompt files. A plain Markdown playbook works with any of them, and you can convert it later.

Back it all up with git

Your AI's memory is just files, so back it up the same way you back up code:

Commit the brain with the code. Rules, notes, and decisions change together with the code they describe. Same repo, same commits.
Push to a private remote (GitHub, GitLab, or similar). A laptop dying shouldn't cost you months of context.
Commit often. Small commits after each working step double as an undo history for AI changes.
Tag milestones (git tag v1.0) so you can always get back to a known-good state, brain included.
Never commit secrets. Keep .env and credential files in .gitignore. If a secret lands in a commit, rotate it: deleting the file later doesn't remove it from history.
Keep personal or global memory separate. Preferences that apply to all your projects (your coding style, your OS) belong in your tool's user-level rules, not in each repo.

## Backup
- Commit after each working step: "feat: ...", "fix: ...", "docs(brain): ..."
- Ask before pushing, force-pushing, or rewriting history.
- .env and anything in secrets/ must never be committed.

Keep memory healthy

Prune monthly. Delete rules and notes that are no longer true. Stale memory is worse than none.
Move, don't duplicate. Each fact lives in one file; others link to it.
Keep the core short. If the main file keeps growing, it's time to split out a topic file.

Start with just the core file and NOW.md. Add the rest as the project earns it. The generator's memory options write the matching rules for you.