PerchAI
How it works

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

Files you own hold the rules for a folder. Account memory holds notes about you and your work. Perch saves, corrects, and deletes notes when you ask or when it learns something that will matter later, and every chat shows which notes it used.

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.

PathWhat it holds
.perch/PERCH.mdThe 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.mdThe 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.mdRead only in a folder that has no AGENTS.md.
~/Documents/Perch/PERCH.mdGlobal 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

Lanes decide what gets into the window at the start of a turn. Compaction decides what comes out when a long run pushes against the limit. You need both, and they run at opposite ends of the same problem.