Memory
Perch runs three memory systems at once: project files you own, durable account memory retrieved by hybrid search, and learning captured from your corrections. Here is what each one does and how it reaches the model.
Most agent harnesses ship one memory system, usually a file you edit by hand. Perch runs three, and they do genuinely different jobs. Project files carry the standing rules for a piece of work. Durable memory carries what is true about you across all of it. Learning capture turns your corrections into memory without you writing anything down.
This page covers all three, and then the part that matters most: how any of it actually reaches the model on a given turn, and how you can see exactly what did.
The short version
Layer one: project memory
Project memory lives on disk, in the folder you are working in. It is plain markdown, you own it, and you can read or edit any of it without going through Perch.
| Path | What it holds |
|---|---|
.perch/PERCH.md | The project manual. Standing instructions Perch follows on every turn in this folder. |
.perch/memory/*.md | Individual memory files, one fact or note per file. |
.perch/rules/ | Project rules, kept separate from prose so they can be applied strictly. |
~/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 case, the output format for this client, the paths that matter, the things never to touch without asking. Perch reads it on every turn in that folder and follows it over its own defaults.
Perch can write to these itself when you ask it to remember something, but the result is always a file you can open. Nothing about project memory is hidden from you.
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. That is how Perch knows which project it is in before it reads a single file.
Layer two: durable memory
Durable memory is account level rather than folder level. It holds what stays true about you 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 not a single blob that gets pasted into every prompt. It is a set of individual cards, and each turn runs a retrieval step to decide which ones are worth their tokens.
How retrieval works
Perch searches durable memory two ways at once and combines the results:
- Semantic search over embeddings, which finds cards that mean the same thing as the current turn even when the wording differs.
- Sparse keyword search, which catches exact terms, names, and identifiers that embeddings routinely blur.
The two ranked lists are merged with reciprocal rank fusion, so a card that both methods rank moderately well beats a card that only one of them loves. The fused score is then adjusted by the card's own confidence and by how recently it was written, and the top results are admitted.
If embeddings are unavailable, retrieval degrades in order rather than failing: hybrid, then semantic alone, then sparse alone, then plain recency. You get worse recall, never a broken turn.
What each card carries
Every durable memory card admitted to a turn brings its own metadata, which is what makes the system inspectable rather than magical:
- Type and scope, which say what kind of memory it is and how widely it applies.
- A freshness label, and a stale flag when a card has aged past the point where it should be trusted without checking.
- A confidence score, expressed as a percentage.
- A truncation flag, set when the card had to be shortened to fit the memory budget for that turn.
- The reasons it was retrieved, carried through from the search step.
Layer three: learning from corrections
The third system is the one you never operate. When you correct Perch, that correction is captured as an event. Learning capture reads those events and can propose new permanent memories from them.
This is the difference between a tool that remembers what you typed into a settings page and one that remembers being told it was wrong. Correcting Perch once is the intended way to teach it, and you do not have to also go write the lesson down somewhere.
How memory reaches the model
Having three memory systems is only useful if what they hold actually arrives in the model's context, and the hard part is that context is finite. Perch handles this with ordered lanes under a token budget.
Each turn, content is rendered into named lanes and admitted in order until the budget is spent. The lanes include 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 so a long answer never gets truncated by its own context.
Two properties make this worth understanding:
- Admission is explicit. When something does not make it into the turn, that is a decision with a recorded reason, not a silent drop.
- Every section carries a reason. Each piece of admitted context has a short explanation of why it is there, and skipped sections record why they were not.
Lanes and compaction are different things
Seeing what Perch is working from
Because every admitted section carries its lane, label, and reason, the desktop app can render the whole thing. The Context Window panel shows the turn's context as rows, with each durable memory card as its own row carrying its status, freshness, and confidence.
This is the answer to the question every agent tool eventually raises, which is "why did it do that." You can look at what the model was actually given.
Staying in control
Project memory is plain files. Open them, edit them, delete them, or check them into version control with the rest of the project. Durable memory is scoped to your account and follows you across the web chat, the desktop app, and the CLI, so what Perch learns in one surface is available in the others.
When a newer statement conflicts with an older one, Perch prefers the newer. Correcting Perch is the update mechanism, and it is meant to be that simple.
