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

# POST /memories — Store a New Memory for Your Agent

> Embed and persist a memory for a user and agent pair. Accepts content, memory_type, importance, metadata, and an optional TTL for auto-expiry.

Call this endpoint whenever your agent learns something worth remembering about a user. Remem embeds the text, checks for near-identical existing memories, and persists the result. If a duplicate is detected the store is skipped automatically, so you never accumulate repeated facts about the same user.

<Note>
  **Endpoint:** `POST https://api.remem.online/memories`
</Note>

## Request Headers

| Header         | Required | Value                              |
| -------------- | -------- | ---------------------------------- |
| `X-API-Key`    | Yes      | Your Remem API key (`rm_live_xxx`) |
| `Content-Type` | Yes      | `application/json`                 |

## Request Body Parameters

<ParamField body="content" type="string" required>
  The memory text to embed and store. Minimum 1 character, maximum 10,000 characters.
</ParamField>

<ParamField body="user_id" type="string" required>
  Identifier for the end user this memory belongs to. Use the same value consistently across requests.
</ParamField>

<ParamField body="agent_id" type="string" required>
  Identifier for the agent storing the memory. Memories are scoped to a `user_id` + `agent_id` pair.
</ParamField>

<ParamField body="memory_type" type="string" default="episodic">
  The category of memory. One of `episodic` (events and interactions), `semantic` (stable facts and preferences), or `summary` (compressed overviews).
</ParamField>

<ParamField body="importance" type="float" default="0.5">
  A priority score between `0.0` (low) and `1.0` (high). Higher importance memories surface more readily during retrieval ranking.
</ParamField>

<ParamField body="metadata" type="object" default="{}">
  Arbitrary key-value data stored alongside the memory. Use this to attach application-specific context such as session IDs or source labels.
</ParamField>

<ParamField body="ttl_days" type="integer" default="null">
  Number of days until the memory auto-expires. Set to `null` (default) for a permanent memory. Expired memories are excluded from search results and deleted by a background job.
</ParamField>

## Code Examples

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST https://api.remem.online/memories \
    -H "X-API-Key: rm_live_xxx" \
    -H "Content-Type: application/json" \
    -d '{
      "content":     "User prefers concise bullet points",
      "user_id":     "user_123",
      "agent_id":    "support_bot",
      "memory_type": "semantic",
      "importance":  0.8
    }'
  ```

  ```python Python SDK theme={null}
  from remem import RememClient

  client = RememClient(api_key="rm_live_xxx")

  result = client.remember(
      "User prefers concise bullet points",
      user_id="user_123",
      agent_id="support_bot",
      memory_type="semantic",
      importance=0.8,
  )

  print(result.id)        # memory UUID
  print(result.duplicate) # False — stored successfully
  ```

  ```python Python (httpx) theme={null}
  import httpx

  resp = httpx.post(
      "https://api.remem.online/memories",
      headers={"X-API-Key": "rm_live_xxx"},
      json={
          "content":     "User prefers concise bullet points",
          "user_id":     "user_123",
          "agent_id":    "support_bot",
          "memory_type": "semantic",
          "importance":  0.8,
      }
  )
  print(resp.json())
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://api.remem.online/memories", {
    method: "POST",
    headers: {
      "X-API-Key":    "rm_live_xxx",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      content:     "User prefers concise bullet points",
      user_id:     "user_123",
      agent_id:    "support_bot",
      memory_type: "semantic",
      importance:  0.8,
    }),
  });
  const data = await response.json();
  console.log(data.id);
  ```
</CodeGroup>

## Response

### 200 — Memory Stored

```json theme={null}
{
  "id":          "775263ee-73af-4416-9804-1f274048ae08",
  "content":     "User prefers concise bullet points",
  "user_id":     "user_123",
  "agent_id":    "support_bot",
  "memory_type": "semantic",
  "importance":  0.8,
  "metadata":    {},
  "created_at":  "2026-06-07T12:00:00Z",
  "expires_at":  null,
  "duplicate":   false
}
```

<ResponseField name="id" type="string">
  UUID of the stored memory. Save this if you need to update or delete it later.
</ResponseField>

<ResponseField name="content" type="string">
  The memory text as stored.
</ResponseField>

<ResponseField name="user_id" type="string">
  The user identifier this memory is scoped to.
</ResponseField>

<ResponseField name="agent_id" type="string">
  The agent identifier this memory is scoped to.
</ResponseField>

<ResponseField name="memory_type" type="string">
  The memory category: `episodic`, `semantic`, or `summary`.
</ResponseField>

<ResponseField name="importance" type="float">
  The importance score as stored, between `0.0` and `1.0`.
</ResponseField>

<ResponseField name="metadata" type="object">
  The metadata object stored alongside the memory.
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO 8601 timestamp of when the memory was created.
</ResponseField>

<ResponseField name="expires_at" type="string | null">
  ISO 8601 expiry timestamp, or `null` if the memory is permanent.
</ResponseField>

<ResponseField name="duplicate" type="boolean">
  `true` if this call was skipped because a near-identical memory already exists. `false` when the memory was newly stored.
</ResponseField>

## Error Responses

| Code  | Meaning                    | Fix                                                                             |
| ----- | -------------------------- | ------------------------------------------------------------------------------- |
| `401` | Invalid or missing API key | Ensure your key starts with `rm_` and is passed in the `X-API-Key` header       |
| `402` | Plan memory limit reached  | Upgrade your plan at remem.online/pricing                                       |
| `422` | Validation error           | Check your request body — `content`, `user_id`, and `agent_id` are all required |

## Duplicate Detection

Remem automatically detects near-duplicate memories before storing. When you call this endpoint, the new content is embedded and compared against all existing memories for the same `user_id` + `agent_id` pair. If any existing memory has a cosine similarity above **0.95**, the store is skipped and `duplicate: true` is returned in the response body. This prevents the same fact from accumulating across repeated sessions without any action needed on your side.