Memory
Perch keeps two kinds of standing context: instruction files you own in a folder, and account memory that follows you across chats and devices. Here is what each one does, how notes get saved and corrected, and how you see what a turn used.
Perch works from two kinds of standing context, and they do different jobs. Instruction files carry the rules for a piece of work, and they live in the folder. Account memory carries what is true about you across all of it, and it follows you to every chat and device.
This page covers both, then how notes get saved and corrected, and how you can see what a turn was given.
The short version
Instruction files
Instruction files live on disk, in the folder you are working in. They are plain text, you own them, and you can read or edit any of them without going through Perch.
| Path | What it holds |
|---|---|
.perch/PERCH.md | The project manual. Standing instructions Perch follows in this folder. A PERCH.md at the folder's root is read when there is no .perch/PERCH.md. |
.perch/rules/ | Project rules, as .md or .txt files, kept separate from prose. |
AGENTS.md | The repository's shared instructions. Perch reads every AGENTS.md from the repository root down to the folder you are working in, and the nearest file wins. |
CLAUDE.md | Read only in a folder that has no AGENTS.md. |
~/Documents/Perch/PERCH.md | Global manual. Applies in every folder, not just this one. |
PERCH.md is the right home for anything you would tell a new teammate joining the project: the conventions for this work, the output format for this client, the paths that matter, the things never to touch without asking. AGENTS.md files are usually committed and shared with a team, so Perch does not edit them unless you ask.
Perch only reads instruction files inside folders you approved, and the repository those folders sit in. A chat names the files it loaded on a Loaded instructions line at its start. You can edit the global and project PERCH.md in Settings → Memory under Guidance files.
Alongside the files, the desktop shell supplies folder scope metadata for the turn: the project name, your notes, a memory summary, and the preferred root.
Notes in .perch/memory
Earlier versions of Perch kept notes as files in a folder's .perch/memory. When Perch Desktop finds notes there, it asks once per folder whether to add them to your account memory: Add, Not now, or Never for this folder. Notes you add reach every chat on every device. The files stay where they are.
Account memory
Account memory belongs to your account, not to a folder. It holds what stays true as you move between projects and surfaces: your role, your conventions, how you like results presented, the facts you have told Perch once and should not have to repeat.
It is a set of individual notes, not one blob pasted into every prompt. Each note has a name, a short description, a type (user, feedback, project, or reference), and a scope: private to you, or shared with the workspace.
How notes reach a chat
Notes reach the model two ways:
- A list of your notes. At the start of a chat, Perch gives the model a list of your saved notes: each one's name, description, type, and the date it was saved. The list stays the same for the chat until the chat compacts. Notes you have not used or edited in a long time drop off the list and stay searchable.
- The notes that match. On each turn, Perch finds the few notes whose meaning matches your message and adds their full text for that turn.
The model can also list, search, and read notes itself when it needs one that was not attached.
Recalled notes are handed to the model as data, never as instructions.
Saving and correcting notes
Perch has one memory tool, and it works the same in Perch Desktop, the CLI, cloud runs, and web chat. With it Perch can save a note, correct one, or delete one. It does that when you ask ("remember that I use pnpm"), or when it learns something that will matter later.
- Correcting is the update. When you tell Perch a note is wrong, it replaces the note. The earlier version is kept, and you can see it under Earlier versions in Settings.
- Outside text cannot write to memory. If a chat has read a web page, an email, a document, or another outside source, Perch changes memory only when you ask for it in your own words. A line on a page that says "remember this" does not count.
Seeing what Perch is working from
Each reply that used saved notes says so under it, for example "Recalled 2 memories", with the names of the notes. Each name opens that note in Settings. A new chat shows how many notes are available to it.
In Perch Desktop, the Context window panel shows what the turn was built from, with the note list and each recalled note as rows of their own.
Staying in control
Open Settings → Memory to manage account memory:
- Search your notes, filter them by type, and sort them by recent or confidence.
- Edit a note, or Forget it.
- See where a note was saved: the chat it came from, the CLI, a cloud run, or web chat.
- Use memory decides whether saved notes reach your chats at all.
- Learn new memories decides whether Perch can save, correct, and delete notes.
Both switches are stored on your account, so they apply in Perch Desktop, the CLI, cloud runs, and web chat.
Instruction files are plain files. Open them, edit them, delete them, or check them into version control with the rest of the project.
How memory fits in the window
Context is finite, so Perch renders each turn's content into named lanes under a token budget: project memory, permanent memory, thread evidence, tool evidence, files, tools, the selected skills, and the selected model, with a reserve held back for the model's own output.
Lanes and compaction are different things
Web search
Perch searches the public web when a question needs current or outside facts, opens the pages it finds, and keeps web sources labeled apart from your own documents.
Context
How Perch manages the context window so long, tool heavy runs stay accurate instead of drifting or overflowing as the window fills.

