uygnoey Commerce agent memory
A returning customer should not have to restate that they are allergic to shellfish, that they wear a size 11, or which store they collect from. Long-term memory is what makes the second session better than the first.
Instructions
1. Store memory in your database, not in model context
Memory belongs in a production database. Structure each fact as a typed record:
| Field | Meaning |
|---|---|
key |
The fact's identity — shoe_size, default_store. |
value |
The remembered value. |
category |
The class of fact, used for retention and retrieval policy. |
source_session |
Where the fact came from, for audit and correction. |
A ready-to-fill record shape is in templates/memory-fact-record.json.
2. Write memory asynchronously, outside the agent
Do not give the agent a remember_this tool. Instead, run extraction in the harness: at the
end of each turn, or every few turns, a separate thread or process reads the conversation and
creates, updates, or deletes facts.
Why this wins:
- No latency added to the user-facing turn.
- Measured 13% higher fact recall in internal evals than tool-based writing.
- The agent no longer has to decide what is worth remembering while it is also trying to answer.
The extraction prompt must read only user and assistant text — never tool results. Otherwise product descriptions from the catalog turn into "facts about the user".
3. Read memory in three layers
- Always in context. The small set of fixed facts nearly every request needs — default store, fulfillment preference.
- Pre-fetched per turn. Facts made relevant by signals in the current request.
- Lookup tool. Everything else, behind an explicit retrieval call.
The layering is what keeps memory from eating the context window and the cache prefix.
4. Meet the data-handling requirements
- Decide which types of memory you retain, and enforce that at the write path with a validator — not with a prompt instruction.
- Give users an interface to view, correct and delete stored facts.
- Set retention periods; preferences age out.
- Make memory a per-deployment toggle so jurisdictions with different rules can run the same agent.
Full requirements are in references/memory-data-handling.md.
Examples
A fact that should be extracted
User: "no shellfish for me, I'm allergic"
Extraction writes {key: "dietary_restriction", value: "no shellfish", category: "safety", source_session: "..."}. Because the category is safety, this fact goes in layer 1 — always in
context — for a grocery or restaurant agent.
A fact that should not be extracted
A catalog tool result describes a jacket as "waterproof to 10,000mm". Because the extractor reads
only user and assistant text, this never becomes {key: "waterproof_rating"} on the user's
record. This is exactly the failure the tool-result exclusion prevents.
A layer-3 fact
User, six months ago: "the dining table I bought was for the lake house"
Not needed on most turns. It lives behind the lookup tool and surfaces when the user asks about furniture again.
An update, not an append
User: "actually I moved — use the Oakland store now"
Extraction updates default_store in place rather than adding a second record. Extraction
creates, updates and deletes.
Source
- https://claude.com/blog/the-anatomy-of-effective-commerce-agents (published 2026-09-02)