# POST /memory

**Resource:** [Agent Memory](./memory.md)  
**Scopes:** `memory:write`  
**Write operation:** yes

Write an agent memory. If `key` is provided, behaves as upsert on (agent_registry_id, subject_type, subject_id, kind, key) -- re-using the same key UPDATES the existing memory rather than creating a duplicate. A soft-deleted memory with the same key is revived. Embedding auto-generated for semantic search.

## Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `subject_type` | body | string | yes | What the memory is about: "contact", "opportunity", "company", "self", "campaign", or any agent-defined value. |
| `kind` | body | string | yes | The memory category. Common: "pitch", "objection", "preference", "observation", "next_steps", "fact". |
| `content` | body | string | yes | The memory in natural language. Write it as a narration to your future self. |
| `agent_registry_id` | body | uuid | no | The owning agent UUID. Pass the agent's own id so the memory is private to that agent. |
| `subject_id` | body | uuid | no | The subject UUID (contact, opportunity, or company UUID). Omit for global/self memories. |
| `key` | body | string | no | Optional unique key within (agent_registry_id, subject_type, subject_id, kind). Enables upsert. Example: an article_slug for a pitch memory. |
| `visibility` | body | string | no | "private" (default) or "shared" (readable by all agents in the workspace). |
| `metadata` | body | object | no | Structured payload alongside the natural-language content. Free-form keys. |
| `linked_entities` | body | array | no | Other entities this memory references. Each entry: {type: string, id: string}. |
| `tags` | body | string[] | no | Semantic facets. Convention: "<facet>:<value>". Examples: ["competitor:Twilio", "objection:pricing"]. |
| `confidence` | body | number | no | 0.0-1.0. Default 1.0. Lower for inferences vs stated facts. |
| `source_kind` | body | string | no | Where this memory came from: "email_send", "transcript", "tool_observation", "manual". |
| `source_id` | body | uuid | no | Pointer to the source event (e.g. email_logs.id). |
| `parent_memory_id` | body | uuid | no | Link to an earlier memory this one updates or continues. |
| `expires_at` | body | string | no | ISO timestamp after which this memory becomes inactive. |

## Notes

- Returns HTTP 201 on insert, HTTP 200 on upsert (when key matched an existing row).
- embedding_status in the response is "attached" (semantic search ready) or "pending" (embedding deferred).
- A soft-deleted row with the same key is automatically revived (deleted_at cleared).

---
Base URL: `https://api.trustpager.com/functions/v1/api/v1` — Auth: `Authorization: Bearer YOUR_API_KEY`