Give Slo a memory

A new session knows nothing about your project except what's in the code. The code tells it what exists. It doesn't say why the retry limit is 3, which module everyone is scared of, or that the staging database resets every night.

Slo has three places to keep that knowledge, and it can maintain all three for you. Set them up once and your tenth session starts where your ninth left off.

1. Write the rules: SLO.md

SLO.md in the project root is your standing brief. Slo loads it at the start of every session, along with AGENTS.md and CLAUDE.md if you already have those. Keep it short and specific:

# SLO.md

## How to verify
- Tests: `make test`. Lint: `make lint`. Both must pass before you call anything done.
- Integration tests need Docker running: `make test-integration`.

## Boundaries
- Never commit or push unless I ask.
- Never edit files under `migrations/` that have already been merged.
- Don't touch `deploy/`. Deployments go through CI only.

## Conventions
- Python: named arguments everywhere, type hints on every function.
- New endpoints need an entry in `docs/api.md`.

Rules that apply to all your projects go in ~/.slo/SLO.md.

2. Keep the facts: RESEARCH.md

RESEARCH.md is for knowledge that took effort to find out: architecture decisions, why things are the way they are, integration contracts, failure modes you've already hit. It is not an activity log.

Slo's built-in orientation skills tell it to read RESEARCH.md before planning, create it if it's missing, and update it when it learns something durable. Slo's default location for it is ~/.slo/projects/<repo-name>/RESEARCH.md, which keeps it out of your repository. If you'd rather version it with the code, put it at docs/RESEARCH.md: Slo loads that path automatically, every session.

Ask Slo to start it:

"Generate a RESEARCH.md for this project. Cover the architecture, the main workflows, and anything non-obvious you find."

Then, in your briefs, ask for updates as a deliverable:

"If you learn something durable while doing this, add it to RESEARCH.md."

A companion file, MEMORY.md in the same folder, holds things that are true right now: current priorities, work in flight, open questions. The rule of thumb: RESEARCH.md is what's permanently true and why; MEMORY.md is what's true today.

3. Share across projects: the knowledge base

If you work across several repositories, some knowledge doesn't belong to any one of them. How your services authenticate with each other. The incident last spring and what caused it. Which library version breaks the build.

Point Slo at a folder of markdown files:

export SLO_KB_DIR=~/notes/kb

With that set, Slo is told to consult the knowledge base before designing or debugging, starting from Home.md and then the relevant <repo>/index.md and <repo>/gotchas.md. It searches with the same tools it uses on code. It's also told to write back anything non-obvious it discovers: a bug whose cause wasn't visible in the code, a quirk, a decision someone would otherwise have to rediscover.

A simple layout that works:

~/notes/kb/
├── Home.md              what's here and where to start
├── payments/
│   ├── index.md         what the service does, how it fits in
│   └── gotchas.md       things that have bitten us
└── platform/
    ├── index.md
    └── gotchas.md

Leave SLO_KB_DIR unset and Slo simply works without one.

4. Make it a habit

Memory only helps if it's kept up to date. Two small habits do most of the work:

• End big briefs with "update RESEARCH.md and the knowledge base with anything durable you learned".
• When Slo gets something wrong because it didn't know a fact, add that fact to SLO.md, RESEARCH.md or the knowledge base straight away, not just to the current conversation.