# Pull requests for shared memory: proposals, archive and versions (/blog/pull-requests-for-shared-memory)

![Illustration: A small friendly robot with a round camera-eye head holds up a sticky note toward a large shared notebook open on a stand.](/blog/pull-requests-for-shared-memory/hero.webp)

Shared memory needs the same discipline as shared code. A stale shared memory misleads every agent in the organization, and a correction saved next to it does not stop the old one being retrieved. CoreSpeed's memory maintenance answers with three mechanisms: archive with a named successor, proposals that an author or admin merges like a pull request, and version history.

**A proposal is a pull request**

A teammate's memory changes only through a proposal with a reason.

* Agent → CoreSpeed: memory\_\_update\_memory(id, reason)
* CoreSpeed: memory belongs to a teammate: recorded, nothing changed
* CoreSpeed → Agent: status: proposed
* CoreSpeed → Author or admin: Dashboard, Memory, Proposals
* Author or admin → CoreSpeed: merge, or reject
* CoreSpeed: memory updated; prior version kept, three in all

If the memory changed first, merging records the proposal as outdated and applies nothing. Pending proposals expire after 30 days.

An agent can propose. Only a person merges.

## Why does a correction next to a stale fact fail? \[#why-does-a-correction-next-to-a-stale-fact-fail]

Memory is retrieved by search. When an agent asks "when do release notes go out", both the old memory and the new one match. The old one may rank higher, because it was written in the words the question used. Even when both come back, the agent now holds two answers and has to guess which is current. Multiply by every agent on the team and the stale fact keeps winning somewhere.

Deleting the old memory loses the record of what the team believed and when. What you want is what a merge gives you in a repository: the old state retired, the new state live, and the history kept.

## How does archive work? \[#how-does-archive-work]

`memory__archive_memory` takes a memory out of search, out of lists, and out of the memory index every session starts with. It is the retire operation. The `superseded_by` field names the memory that replaces it, and reading the archived memory by id says so. Nothing is deleted. `memory__restore_memory` brings it back.

The working pattern is write first, then retire:

```text
memory__remember          "Release notes go out on Wednesdays, decided 2026-10-02."
memory__archive_memory    old id, superseded_by: the new id
```

The old memory keeps its place in the history and a pointer forward. Any agent that still holds the old id, from an earlier session, follows the pointer instead of acting on the stale text. Archiving is also the only thing that writes a link of kind `supersedes`; that kind is reserved for it.

## How do proposals work? \[#how-do-proposals-work]

Who can change a memory depends on who wrote it:

| The memory belongs to            | What `update`, `archive` and `restore` do                        |
| -------------------------------- | ---------------------------------------------------------------- |
| you                              | apply at once                                                    |
| an agent you are accountable for | apply at once                                                    |
| a teammate                       | become a proposal with a `reason`, answered `status: "proposed"` |

A teammate's memory changes through a proposal. `memory__update_memory`, `memory__archive_memory` and `memory__restore_memory` on it take a `reason` and record a proposal instead of changing anything. The memory's author, or an org admin, merges or rejects it in Dashboard → Memory → Proposals. That is the pull request: a proposed diff, a stated reason, a reviewer who owns the file.

An agent can propose and never merge. The decision stays with a person, which is the same shape as [Smart Approval](/docs/approvals) for writes to apps. `memory__list_memory_proposals` lists the proposals on memories you can see, and `memory__withdraw_memory_proposal` takes back one you made.

## What happens if the memory changes first? \[#what-happens-if-the-memory-changes-first]

A proposal is written against the memory's current version. If the memory changes before review, merging records the proposal as `outdated` and applies nothing. Nothing is ever rebased, because a rebase would apply a reviewer's decision to text the reviewer never saw. The proposer re-reads the new version and proposes again if the change is still wanted.

Every change keeps the memory's three most recent prior versions, with who replaced each. The memory's page in the dashboard lists them and can restore one. Pending proposals expire after 30 days; resolved ones leave the list after another 30.

That gives a shared memory the audit shape a team expects of shared state: who wrote it, who changed it, what it replaced, and what was proposed and declined.

One row of the table above deserves a word. An agent principal saves memories under its own identity. The member who owns that agent, the one who answers for it, maintains those memories directly, without a proposal. An org admin can too. This mirrors the ownership rule on the [authentication page](/docs/authentication): ownership is accountability. The owner cleans up after the bot, and a teammate who spots a stale bot memory proposes the fix to that owner.

## Where is this rolled out? \[#where-is-this-rolled-out]

Memory maintenance, meaning archive and restore, proposals and version history, is rolling out organization by organization. Until your organization has it, `memory__archive_memory`, `memory__restore_memory`, `memory__list_memory_proposals` and `memory__withdraw_memory_proposal` are absent from `tools/list`, a teammate's memory can be changed only by its author, and the dashboard shows none of it. The [memory page](/docs/memory) is the reference for both states.

Absence of those tools is a decision about your organization's rollout, so do not treat it as an error. The eleven other memory tools work as before.

## FAQ \[#faq]

**Should I delete a stale shared memory or archive it?**
Archive it, with `superseded_by` naming the replacement. Archive keeps the history and a pointer forward; delete keeps nothing.

**Can my agent fix a teammate's wrong memory?**
It can propose the fix, with a reason. The author or an org admin merges it in Dashboard → Memory → Proposals. An agent never merges.

**What does `outdated` mean on a proposal?**
The memory changed after the proposal was written, so merging applied nothing. Re-read the current version and propose again.

**How many old versions are kept?**
The three most recent prior versions, each with who replaced it. The memory's dashboard page can restore any of them.

**Why are the archive and proposal tools missing from my tools/list?**
Your organization does not have memory maintenance yet. It is rolling out organization by organization.