| name | map-memory-surface |
| description | Name the storage surface a write actually lands on — who holds the bytes, who executes the write, and what trust model comes with it. Reach for this before writing any memory design down. |
Skill: Map the memory surface
Decision 2 of the six-decision spine — who holds the bytes, and who executes the write? Two surfaces can share an API shape and have opposite trust and data-residency models. Collapsing them misstates the only part that matters (§3 #4).
This skill deliberately carries no header strings, status labels, caps or multipliers. Those are the fastest-moving facts in the plugin, and they live in exactly one place so a staleness sweep can see them: memory surfaces (2026). Read them there, at the moment you write the design — never from recall.
Step 1 — Answer the two questions, in writing
| Question | What it decides |
|---|
| Who holds the bytes? Your storage, or the vendor's? | Data residency, DPA scope, and who can be compelled to produce them |
| Who executes the write? Your code, or the vendor's runtime? | Who owns path traversal, size caps, expiry and redaction |
A design that cannot answer both is not a memory design yet. If a platform cannot answer them and tell you whether a historical value can be redacted, you do not have a memory surface — you have a bucket.
Step 2 — Separate durable memory from context pressure
This is where most designs go wrong before they start.
| Symptom | Mechanism | Does anything survive? |
|---|
| Tool results are bloating the prompt | Context editing | No — it deletes from the prompt |
| The whole conversation is too long | Compaction | No — it summarizes, and the pre-summary blocks are dropped |
| Duplicates and stale entries are piling up | An offline consolidation job | Yes, into a new store — the input store is untouched |
| A fact must be readable by a later session | A durable memory surface | Yes — this is the memory decision |
The vendor's own pairing guidance is the cleanest frame available: context editing clears specific tool results; compaction summarizes the whole conversation; memory is what must survive both.
Step 3 — Name the surface, as one of five
Anthropic currently ships five distinct surfaces, and they are not one product with five names. Teach them as five; the most common error in circulation is the collapsed version of this table.
| # | Surface | Who holds the bytes | Who executes the write |
|---|
| 1 | Memory tool (Messages API) | You | You — the model only requests file operations; your application performs them |
| 2 | Context editing | n/a — it removes content from the prompt | The API, server-side, before the prompt reaches the model |
| 3 | Compaction | n/a — it summarizes the conversation | The API, server-side, in an extra sampling pass you are billed for |
| 4 | Claude Code instruction files + auto memory | Your machine — repo files and a local per-project directory | You write the instruction file; Claude writes auto memory |
| 5 | Managed Agents memory stores | The vendor — a workspace-scoped server-side resource | The agent, via file tools in its sandbox, or you, via REST |
Consolidation ("dreams") is a sixth mechanism attached to surface 5, not a free feature of it — its own access gate, its own header, its own bill. Decide it separately.
Surfaces 1 and 5 are the pair people fuse. They are the opposite answer to question 1: surface 1 is client-side and you own every control on it; surface 5 is server-side and the vendor ships the controls. Current status, exact header and type strings, and every hard cap: memory surfaces (2026).
Step 4 — Read today's status, strings and caps from the knowledge file
Open memory surfaces (2026) and copy out, with its Last verified date:
- The surface's release status. A beta-to-GA transition changes required headers; a GA-to-deprecated transition changes everything.
- The exact header or type string, if the surface takes one. Two endpoint families on the same product can require different headers, and sending the wrong one is a failed request, not a mislabel.
- Every hard cap — per-item size, items per store, stores per session, index load budget.
- What happens at the cap. This is the question nobody asks, and the answer differs by surface: some caps make new writes fail loudly; others silently drop the overflow at load time. Same word, opposite failure mode, opposite design.
The freshness sweep reports age, never correctness. Re-verify against the vendor's current docs before any of this reaches a deliverable.
Step 5 — Walk the sharp edges for the surface you picked
Each of these has bitten someone and none is obvious from a skim. The full list, with sources, is in memory surfaces (2026); the ones that change a design are:
- A client-side memory path prefix is virtual, and path traversal is your problem. The docs warn explicitly that a crafted relative path can escape, and put the responsibility on the implementer — prefix check, canonicalize, containment-check, reject encoded traversal.
- The other client-side safeguards are named for you but not enforced for you: stripping sensitive content, size caps, capping what a read returns, and expiry.
- An instruction file is context, not enforced configuration. To block an action regardless of what the model decides, use a hook or a permission deny (§3 #6). Never write a design whose control column says "documented in the memory file."
- Auto memory is keyed per git repo, not per worktree — concurrent sessions in two worktrees write to one index.
- Server-side stores attach only at session creation, and read-only versus read-write is enforced at the filesystem level. There is no mid-session promotion.
- Rollback may be retrieve-then-rewrite, which itself creates a new version. Rehearse it before you need it.
- A prefix cache is an optimisation, not a memory tier — it is opportunistic and replica-local, so it is never durable persistence (§3 #4).
Step 6 — Record it
Into the memory design record: surface · who holds the bytes · who executes the write · release status · the date you read that status · the caps and what happens at each. Then hand the write path to memory-poisoning-review and the retention story to design-forgetting-policy.
Porting this off one vendor
The vendor changes; the questions do not. For any platform, answer: who holds the bytes · who executes the write · what is the status and the exact string today · what are the caps and what happens at each · is there an audit trail and can a historical value be redacted · does anything consolidate or forget on its own. The last one's answer is almost always no (§3 #3).
Output
A named surface with its byte-holder, its write executor, its dated release status, its caps and their failure modes, and the sharp edges that apply. Traverse Tree 2 in the decision trees.
