This is the highest-leverage five minutes you can spend in Pearl. Three entries in
.pearl/memory/project.md will sharpen every subsequent Scout interaction in this
project — for the rest of the project's life.
Time required: 5 minutes. You need a project Scout has run in at least once.
Step 1 — Open the memory file
In Pearl's chat input, click the memory chip (it shows
Memory: 0 if nothing's there yet). The file opens for editing — it's a plain
markdown file at .pearl/memory/project.md inside your workspace.
You can also open it directly: File → Open File → type .pearl/memory/project.md.
Step 2 — Write three entries
The trick is picking the right three. We want entries that:
- Couldn't be derived from re-reading the code
- Will still be true in six months
- Would change the answer to a question Scout might be asked
Here are templates for the three highest-value entries in most projects:
Entry 1 — How you write code
# Code conventions
- Controllers are thin; business logic lives in `app/Services`.
- We don't use Eloquent's relationships — explicit joins only.
- No new dependencies without a written reason. Three similar
lines is better than a premature abstraction.
- We don't add docstrings to internal-only methods.These are the conventions Scout will violate without being told. If your team has a "controllers stay thin" rule, the memory entry makes Scout respect it from turn one.
Entry 2 — Where things live
# Project map
- Auth lives in `app/Auth`. SSO callbacks are in `SsoCallback.php`.
- AI gateway lives in `app/Modules/AiGateway`.
- All migrations go in `database/migrations/`, datestamped
prefix (`2026_05_17_000099_…`).
- Frontend assets are in `public/assets/`; we don't have a build
step (PHP renders templates directly).Scout can usually discover this by searching, but the round-trip cost is real. Tell it once.
Entry 3 — Recent decisions
# In-flight decisions
- Auth rewrite is paused until Q3. Don't touch SSO middleware.
- We're consolidating on PSR-7 — new HTTP code uses System\Http
abstractions, not raw $_SERVER access.
- The Loop billing webhook integration is a work-in-progress in
`app/Modules/Sync` — don't refactor that directory yet.This is the most underrated category. It captures the "don't go there yet" knowledge that new team members usually pick up the hard way.
Step 3 — Save and test
Save the file. The memory chip in the chat input now shows Memory: 3 (or
however many entries you wrote — Scout counts at the heading level).
Test it: ask Scout a question that depends on one of your entries. Something like:
Add a new endpoint for password reset. Where should it go?Scout should respect your "controllers are thin" convention and propose putting the logic in a service. If your entry was useful, the answer reflects it. If it didn't, the entry was too vague — tighten it.
What goes in memory — and what doesn't
| Goes in | Doesn't |
|---|---|
| Conventions Scout would violate | Things in the README already |
| Where unusual code lives | Standard file structure (Scout can find it) |
| Decisions that aren't documented | Day-to-day chat context |
| External system pointers (Linear, Slack) | API keys or secrets (use the OS keychain) |
| Trade-offs you've explicitly made | Generic "be careful" advice |
The commit question
Should you commit .pearl/memory/project.md to git? It depends:
- Commit it if entries are project-level (conventions, architecture) and you want new team members to benefit.
- Gitignore it if entries are developer-specific (your preferred coding style, your in-flight context).
- Split the difference: use Pearl's per-developer memory for personal entries; commit only the project-level ones.
What you just learned
- Three entries is plenty to start.
- Memory is yours — read, edit, delete, commit.
- Tighten entries that don't change Scout's answers.
Next
Now run a real Plan-mode refactor and notice that Scout respects your memory entries inside the plan it emits.