You open the editor. You ask the AI a question. The AI doesn't know what you're working on,
so you spend two minutes explaining the project: this is a Laravel app, the auth lives in
app/Auth, we don't use Eloquent, controllers are thin, the team really doesn't
want type coverage. The AI gets up to speed. You ask your question. You get a good answer.
Tomorrow, you open the editor. You ask the AI a question. The AI doesn't know what you're working on…
This is the morning re-explanation problem. It is the single biggest reason developers stop trusting an AI coding tool — not because the answers are wrong, but because the cost of getting to a good answer is the same every day.
What we did about it
Pearl Scout keeps a plain markdown file at .pearl/memory/project.md inside the
workspace. It's the project's onboarding document, but for the AI.
The file is yours. Read it, edit it, commit it to git if you want. Scout reads it at the start of relevant turns; Scout adds entries to it when it learns something durable. A memory chip in the chat input shows the current entry count and opens the file in a click for direct review.
What goes in it
Things you wouldn't get from reading the code:
- Conventions ("our controllers are thin, business logic lives in services")
- Prior incidents ("we got burned by mocking the database in 2025")
- In-flight initiatives ("the auth rewrite is paused until Q3")
- Where things live in external systems ("bugs in Linear project INGEST")
- The user's preferred trade-offs ("don't introduce abstractions for hypothetical future requirements")
Things that don't go in it:
- Anything you can derive from reading the project structure
- API keys or secrets (use the OS keychain)
- The conversation you just had — that's session history, not memory
- Anything you don't want committed to git, since the file lives in your workspace
Why a markdown file
Two reasons. First: it's auditable. You can read what the AI thinks it knows about your project. You can correct mistakes. You can show it to a coworker. None of that is true of opaque vector-store memory.
Second: it's portable. Switch from Pearl to another editor, and the memory comes with you as a plain markdown file. We don't want to be the tool you can't leave.
The version-control conversation
Some teams want memory committed (so new joiners get it). Some teams want it gitignored (it'll drift from the canonical onboarding doc). Both are valid. We took no position — Pearl doesn't gitignore the file by default; you decide. The convention we use internally is "commit the project-level entries; ignore developer-specific ones."
The senior-engineer-onboarding-a-new-hire problem
The reason this matters is the same reason onboarding documents matter: the cost of explaining a project from scratch is paid by the person who already knows it, and the savings accrue to everyone else. With AI assistants, the person paying that cost is the developer, and the savings accrue to nobody — because the next morning, the explanation has to happen again.
A markdown file is the lowest-tech, highest-leverage fix to that problem. It just had to be written.
Try it: open .pearl/memory/project.md
right now (it'll be empty). Write three lines about your project. Ask Scout a question that
depends on one of those lines. Note that you didn't have to say it twice.