> ## Documentation Index
> Fetch the complete documentation index at: https://docs.baselayer.id/llms.txt
> Use this file to discover all available pages before exploring further.

# record_memory

> Persist observations and context to your memory.

# record\_memory

Writes a new observation or memory into your memory for persistent storage. This triggers background distillation: BaseLayer's dream engine will extract entities and facts from the content asynchronously.

## Parameters

| Parameter          | Type   | Required | Default  | Description                                                                                                                                                 |
| ------------------ | ------ | -------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `content`          | string | Yes      | --       | The text content of the memory or observation                                                                                                               |
| `attach_to_entity` | string | No       | `"user"` | Entity slug to attach this memory to. Accepts bare slug (`"myproject"`), type/slug (`"project/myproject"`), or full URI (`"baselayer://project/myproject"`) |
| `metadata`         | string | No       | `null`   | Optional JSON string of metadata                                                                                                                            |

## Read-only

No. This tool writes to your memory.

## Example usage

```json theme={null}
{
  "content": "Decided to use WebSocket for real-time sync instead of polling. Reason: polling caused 2s latency spikes under load. Trade-off: more complex connection management.",
  "attach_to_entity": "project/my-api"
}
```

```json theme={null}
{
  "content": "User prefers dark mode in all IDEs and terminal applications.",
  "attach_to_entity": "user"
}
```

```json theme={null}
{
  "content": "Integration tests must hit a real database, not mocks. Why: prior incident where mock/prod divergence masked a broken migration. How to apply: any test that touches persistence."
}
```

## When to use

* After a significant decision or discovery
* When the user says "remember this"
* When you learn preferences, roles, or working style
* To save corrections or behavioral feedback for future sessions

<Tip>
  For behavioral feedback, structure as: **Rule** then **Why** (the reason) then **How to apply** (when and where this guidance kicks in). This format makes it easy for future AIs to apply the correction correctly.
</Tip>

## record\_memory vs. vault\_fact

* **record\_memory** is for general notes and observations. Content is distilled asynchronously by the dream engine into entities and facts.
* **vault\_fact** is for precise, immediate facts linking two entities. The fact appears in the graph right away.

Use `record_memory` when you have a general observation. Use `vault_fact` when you know the exact source entity, target entity, and relationship.

<Warning>
  A decision you don't record is a decision the next session will re-make from scratch. When in doubt, record it.
</Warning>