Memory

What every agent should know about how your team works — written once, kept beside the code, approved by a person.

A team knows things about how it works: what every agent must be told, the rules nobody breaks, the practices it prefers, what review has taught it, the decisions it has settled, its words, where things live, how to build and test, the traps, who owns what. Memory is where that goes — written for agents first and readable by people, one entry per file.

Its own, and what it receives

• The memory of the shared projects it receives. A shared project's memory reaches every project that picks it, under Settings → Memory → Memory this project receives. Every project receives the organization's default shared project's — what used to be the organization's memory — until someone with Manage workflows unticks it.
• A project's own, under the project's Settings → Memory. A project with a repository keeps it in .peractor/memory/ on its default branch — markdown files, reviewed and branched like the code, with an INDEX.md Peractor writes beside them. A project with none keeps it in Peractor, and is offered Move into the repository once it has one.

A project's memory can be kept elsewhere too — in Peractor's storage, or a bucket or repository of your organization's — with Move a folder under Settings → General (see Where files are kept). Every run receives it wherever it is.

Your old system prompts are already there: the organization's became its Organization guidelines entry, in the default shared project's memory now, and each project's is its Project guidelines. Peractor commits nothing into your repository on its own: a project's instructions stay where they were, marked Still the old setting, until someone with Manage workflows presses Commit to repository, which writes them to .peractor/memory/guidelines.md. Agents receive exactly what they did before, either way.

Entries

Every entry has a kind, and every kind but the note has a form with the sections it needs:

An entry applies always — sent in full to every run — or when relevant: a line in an index the agent is given, and opened when it fits what the agent is doing. A markdown file dropped into .peractor/memory/ from any editor is a note; nothing is refused for its shape.

Writing and approving

• The people who decide write — Manage workflows in the project whose memory it is, a shared one's too: a new entry from its kind's form, an edit, Edit as markdown, Archive (kept readable, never sent, and Unarchive brings it back) and Delete.
• Every other member proposes: their Save waits in the memory's Waiting list, and the people who decide there are told in the Inbox. One of them approves it, edits it and approves, or rejects it with a reason the proposer reads.

Runs propose too, from a prompt step marked May propose memory entries (proposeMemory: true): what its agent learned waits in the same queue, linked to the run, and the run's card says what became of it. So does the API: POST /api/v1/memory/proposals. Nothing an agent or a key writes reaches memory before a person approves it.

In a repository every write is one commit, authored by you and committed under your organization's git identity. When somebody else changed the same lines, the wiki's conflict screen asks which to keep; a protected branch offers a new branch instead to people who hold Create branches.

A project's memory is files, so a folder or an entry closed to you is left out of what you see of it, and writing takes Edit files at every file the write changes.

What an agent sees

Each run's Prompt card lists, under its Shared and Project layers, every entry and how it reached the agent — sent in full, listed, or not sent because a shared project's entry of the same name applies. The entries themselves are copied into the run's workspace, so an agent opens one the way it opens any file.

Keeping it tidy

• Repeats are caught. Saving a new entry that says what one of its kind already says — the same title, or most of the same words — asks first: Edit it instead, or Save anyway. A waiting proposal that repeats an entry says Looks like … in the queue.
• The budget. A run is sent about 8,000 characters of each memory's Always entries in full; past that, the rest are listed like When relevant ones, and the page says by how much and which. Instructions are never the ones cut.
• Consolidate memory. The Memory upkeep pack in the marketplace has a workflow whose one step reads the whole memory and proposes merges, rewrites and entries to archive. Run it by hand, or put it on a schedule with an ordinary trigger. Every proposal waits for a person.

Outside Peractor

A coding tool run on someone's own machine reads AGENTS.md, not Peractor. A project's memory page offers people with Manage workflows to point AGENTS.md at memory: one commit, shown as a diff first, adding a line that sends the tool to .peractor/memory/INDEX.md and the entries it lists.

The memory a project receives is kept by Peractor, so a tool on someone's machine can't read it. Someone with Manage workflows can add the shared memory to a project's repository: one commit copying its entries into .peractor/memory/organization/, which the project's index links. Anyone who can read the repository can read the copy. When the shared memory changes, the page says so and offers Update the copy — nothing updates it on its own. Peractor's own runs always get the live memory.