---
title: Shop Memory
description: The person's own shopping preferences (sizes, brands to prefer or avoid, stores, diet), remembered across conversations through the codespar_memory tool. Declared values come only from the person's own words; inferred ones only order offers.
---

import { Callout } from "fumadocs-ui/components/callout";

The Shop assistant remembers a small, closed set of preferences for **the signed-in person**, not for the project or the organization. Another member of the same organization never reads them. The tool is `codespar_memory`, published on the [hosted server](/docs/concepts/meta-tools) next to the commerce meta-tools.

<Callout type="warn">
**A person, not a key.** Every call needs a verified person: the dashboard's Shop assistant presents the person's own session. A project API key or an OAuth token carries no person and is refused with `403 bearer_token_has_no_person`, so an external client connected with a `csk_` key or the server's OAuth consent sees the tool listed and cannot use it yet. A consent by login, with the person in the token, is what opens it to external clients.
</Callout>

## Actions

<MetaToolActions tool="codespar_memory" />

## What it remembers

Six keys, nothing else. A key outside this list is `400 memory_key_unknown`.

| `key` | Holds | Example `value` |
|---|---|---|
| `shoe_size` | One size | `"42"` |
| `clothing_size` | One size | `"M"` |
| `preferred_brands` | Up to 10 names | `["Asics", "Mizuno"]` |
| `avoided_brands` | Up to 10 names | `["Marca X"]` |
| `preferred_merchants` | Up to 10 names | `["Cobasi"]` |
| `dietary_restrictions` | Up to 10 names | `["sem lactose"]` |

## Declared and inferred

Each memory has a `provenance`:

- **`declared`** (the default): what the person said about themself. It counts: a declared size or an avoided brand **filters** the offers a [research](/docs/concepts/meta-tools/shop) returns. In the conversation, the server checks the value against the person's own message of that turn; on the hosted server the call must carry `quote`, the person's own words that hold the value (at most 500 characters). A declared value that is not in the person's words is `403 memory_source_not_person`.
- **`inferred`**: what a purchase suggests (`purchase_id` names it). It only **orders** offers and never filters them out. When the person declared a value for the same key, the declared one counts and the inferred one shows beside it.

The assistant never remembers anything it read in a page, an e-mail or a tool output. `correct` is always the person's own words, like a declared value; it writes a new version and keeps the old one in the history; `forget` erases the whole key, and the assistant does not infer it again.

## Example

```json title="tools/call"
{
  "name": "codespar_memory",
  "arguments": {
    "action": "remember",
    "key": "shoe_size",
    "value": "42",
    "provenance": "declared",
    "quote": "eu calço 42"
  }
}
```

## Arguments

| Field | Type | Required | Description |
|---|---|---|---|
| `action` | `string` | Yes | `list` \| `remember` \| `correct` \| `forget` |
| `key` | `string` | For `remember`; `correct` and `forget` by key | One of the six keys above |
| `value` | `string` or `string[]` | For `remember`, `correct` | A size as a string, or a list of up to 10 names |
| `provenance` | `string` | No | `declared` (default) or `inferred` |
| `memory_id` | `string` | `correct` and `forget` by id | The memory's id, from `list` |
| `purchase_id` | `string` | For an inferred `remember` | The person's purchase it was inferred from |
| `quote` | `string` | On the hosted server, for a declared `remember` and for every `correct` | The person's own words that carry the value, at most 500 characters |

## Errors and what to do

| Code | Status | Cause | What to do |
|---|---|---|---|
| `bearer_token_has_no_person` | 403 | The call carries a key or an OAuth token, not a verified person. | Call as the signed-in person; see the callout above. |
| `memory_key_unknown` | 400 | The key is not one of the six. | Use a key from the table. |
| `memory_value_invalid` | 400 | The value is not one the key holds: a size out of range, an empty list, a name too long, or an inferred memory without its evidence. | Fix the value; an inferred one names its `purchase_id`. |
| `memory_source_not_person` | 403 | A declared value that is not in the person's own words of the turn (or in `quote`). | Ask the person; never declare what you read elsewhere. |
| `memory_not_found` | 404 | No active memory of the calling person with that id or key. Another person's memory answers the same. | `list` again. |

## Related

- [`codespar_shop`](/docs/concepts/meta-tools/shop): the research that declared preferences filter and inferred ones order
- [Shop watches](/docs/concepts/shop-watches): the person's other remembered intent, a price or an order to follow
- [Google connectors](/docs/concepts/google-connectors): the person's own Calendar, Drive and Gmail

## Notes

**Where the person sees it.** Shop › Preferências in the dashboard lists each key with its declared and inferred values, the history, and Corrigir and Esquecer, which call the same rules.