---
title: "Remember a fact"
method: POST
path: "/v1/memory"
tags: ["Memory"]
---

# Remember a fact

`POST /v1/memory`

## Request

- Base URL: `https://api.zavu.dev`
- URL: `https://api.zavu.dev/v1/memory`
- Auth: HTTP bearer

Store one fact so the agent can recall it later by meaning. The text is embedded on write; retrieval is semantic, not keyword.

**Scope goes in the body here.** Pass `scope` plus the matching `contactId` / `conversationId`. Omit it for the project scope. Every read endpoint takes the scope as a `?scope=` query parameter instead — see the `scope` parameter on `GET /v1/memory`.

**One fact per call.** A paragraph carrying five unrelated facts is embedded as an average of all five and retrieved well by none of them.

## Request body

- MemoryAddRequest: Store one fact. It is embedded on write, so it becomes searchable by meaning rather than by keyword.
  - `text` string, required: What to remember. Max 8,192 bytes of UTF-8. Write one fact per call: a paragraph holding five unrelated facts embeds as an average of all five and is retrieved well by none of them.
  - `scope` 'project' | 'contact' | 'conversation': Which namespace a memory belongs to. Scopes are isolated: a search in one never returns a memory from another. - `project`: shared by the whole project. What the agent knows in general. - `contact`: what the agent knows about one person, across every conversation with them. - `conversation`: what the agent knows about one inbox thread. Defaults to `project` everywhere. `contact` and `conversation` require the matching id.
  - `contactId` string: Required when `scope` is `contact`.
  - `conversationId` string: Required when `scope` is `conversation`.
  - `metadata` object: Arbitrary string tags stored alongside the fact and returned with it. Keys max 64 chars, values max 512, whole object max 2,048 bytes. Not searchable — search matches `text` only.
  - `ttlSeconds` integer: Delete the fact after this many seconds. 60 to 63,072,000 (2 years). Omit to keep it until deleted.

## Response `201`

Fact stored.

- object
  - `memory` MemoryRecord, required: A stored fact, as returned when it is created.
    - `id` string, required
    - `scope` 'project' | 'contact' | 'conversation', required: Which namespace a memory belongs to. Scopes are isolated: a search in one never returns a memory from another. - `project`: shared by the whole project. What the agent knows in general. - `contact`: what the agent knows about one person, across every conversation with them. - `conversation`: what the agent knows about one inbox thread. Defaults to `project` everywhere. `contact` and `conversation` require the matching id.
    - `createdAt` string, date-time, required
    - `expiresAt` string, date-time: When the fact self-deletes. Present only when it was stored with `ttlSeconds`, or when the key is a test-mode key (forced to 30 days).

## Other responses

- `400`: Invalid body, oversized text, or a scope without its id.
- `401`: Unauthorized.
- `429`: A quota is exhausted. `memory_scope_full` means this scope is at its cap (10,000 facts for project, 2,000 per contact, 1,000 per conversation); `memory_limit_exceeded` means the plan's monthly unit quota is spent. Reads and deletes keep working in both cases.
- `503`: Memory is not available for this deployment.

## Changes

> 80 revisions in range; 1 not diffed.

- **2026-08-26** `6e8c555e1104`: 1 info
  - removed the non-success response with the status `403`
- **2026-08-26** `83caf7165722`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/zavudev/apis/zavu-unified-messaging-layer-api/changes/v1/memory/post.md)

---

[API](https://skmtc.dev/zavudev/apis/zavu-unified-messaging-layer-api.md) - [All operations](https://skmtc.dev/zavudev/apis/zavu-unified-messaging-layer-api/llms.txt) - [OpenAPI document](https://skmtc.dev/zavudev/apis/zavu-unified-messaging-layer-api/revisions/75bc777b0ffb?raw)