# Memory

How an agent writes something to the account's memory, searches it later, and takes a write back out. What memory is and what it costs is on [Services](/services).

## Before you start

Memory is one graph for the whole account, shared by all of your agents. It is on from the start and needs no setup. An agent uses it with its Passport. You use it with your key or sign-in.

## Remember something

```text
Remember that Anna at Acme prefers email and is out until the 20th.
```

The client calls `stack_memory_add_memory`. From code or the terminal:

```typescript
const write = await stack.memory.addMemory({
  name: 'Call note',
  episode_body: 'Anna at Acme prefers email and is out until the 20th.',
}, { passportToken });
// write.uuid, write.status === 'queued'
```

```bash
npx @getstackrun/cli memory add "Anna at Acme prefers email." --name "Call note"
```

- A write answers queued at once. STACK then reads it into the graph: the people, things and facts in it, with the time each held.
- It can be searched once stack_memory_get_episodes shows it as stored.
- One entry holds at most 8,000 characters.
- To record one fact directly, stack_memory_add_triplet takes a subject, a relation and an object.
- To keep what a received message says, pass its id as from_message_id.

Text that looks like a password, a key or a card number is refused and never stored. Text is also scanned for attacks: with controls on, flagged text is refused, except a memory or fact you write yourself, and with controls off it is stored with its flag.

## Search

```text
What do we know about Anna at Acme?
```

```typescript
const people = await stack.memory.searchNodes({ query: 'Anna' }, { passportToken });
const facts = await stack.memory.searchMemoryFacts({ query: 'How does Anna want to be contacted?' }, { passportToken });
```

- stack_memory_search_nodes finds people and things. stack_memory_search_memory_facts finds facts, and can be limited to what held true in a period.
- Each search returns up to 10 results by default and 50 at most.
- From the terminal: memory search-nodes and memory search-facts.

## Take something back out

```typescript
const history = await stack.memory.getHistory({}, { passportToken }); // each write, with its id

await stack.memory.undoWrite(writeId, { dryRun: true }, { passportToken }); // see what would change
await stack.memory.undoWrite(writeId, {}, { passportToken });
```

- stack_memory_get_history lists what each write changed, before and after.
- stack_memory_undo_write takes a write out, with every later write that depends on it. dry_run only shows what would change.
- stack_memory_delete_episode and stack_memory_delete_entity_edge remove one entry or one fact.
- An account can make 60 deletes an hour, yours and your agents' together.

## Teach it your own kinds of things

You can add your own kinds of things with their own fields, for example a contract with a renewal date, so they are picked out of what is written. The tools are `stack_memory_create_entity_type`, `stack_memory_update_entity_type` and `stack_memory_retire_entity_type`. From the terminal: `memory type-add`.

## Switch it off

```bash
npx @getstackrun/cli memory settings --enabled off
```

Only the owner or an admin changes the settings. The second setting, `call_memory_access`, decides whether a phone call that STACK holds may search memory while it talks. The transcript of such a call is written to memory when it ends.

## What counts as an action

Writing an entry, writing a fact and summarising are one action each. Searching, reading, deleting, undoing and the settings are free. Reading a write into the graph uses a model, which is charged at cost after the writes the plan includes each month.

## When it is refused

- 422 MEMORY_SECRET_REFUSED - the text looks like a credential.
- 422 MEMORY_CONTENT_FLAGGED - the text was flagged as an attack and controls are on. A memory or fact you write yourself is stored with its flag instead.
- 409 MEMORY_DISABLED - memory is switched off for the account.
- 409 MEMORY_WRITE_NOT_UNDOABLE - the write is still being read. Try again once it is stored.
- 429 MEMORY_DELETE_RATE_LIMITED - more than 60 deletes this hour.
- 409 MEMORY_LIMIT_REACHED - the account's memory is full.
- 503 MEMORY_UNAVAILABLE - memory cannot be reached. Nothing was charged.
- 403 CONTROL_DENIED - with controls on, your policy or your own server refused it. Controls are asked as memory.write and memory.delete, never with the text.

## Reference

Every field is on [Memory](/docs/api/memory) in the API reference. Every tool is in the [tool reference](/docs/mcp-tools). To search your documents, not what agents wrote, see [Brain](/docs/account/brain).
