POST /memories — Store a New Memory for Your Agent

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.

Endpoint: POST https://api.remem.online/memories

Request Headers

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

Request Body Parameters

string

required

The memory text to embed and store. Minimum 1 character, maximum 10,000 characters.

string

required

Identifier for the end user this memory belongs to. Use the same value consistently across requests.

string

required

Identifier for the agent storing the memory. Memories are scoped to a user_id + agent_id pair.

string

default:"episodic"

The category of memory. One of episodic (events and interactions), semantic (stable facts and preferences), or summary (compressed overviews).

float

default:"0.5"

A priority score between 0.0 (low) and 1.0 (high). Higher importance memories surface more readily during retrieval ranking.

object

default:"{}"

Arbitrary key-value data stored alongside the memory. Use this to attach application-specific context such as session IDs or source labels.

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.

Code Examples

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
  }'

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

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())

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);

Response

200 — Memory Stored

{
  "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
}

string

UUID of the stored memory. Save this if you need to update or delete it later.

string

The memory text as stored.

string

The user identifier this memory is scoped to.

string

The agent identifier this memory is scoped to.

string

The memory category: episodic, semantic, or summary.

float

The importance score as stored, between 0.0 and 1.0.

object

The metadata object stored alongside the memory.

string

ISO 8601 timestamp of when the memory was created.

string | null

ISO 8601 expiry timestamp, or null if the memory is permanent.

boolean

true if this call was skipped because a near-identical memory already exists. false when the memory was newly stored.

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.

​Request Headers

​Request Body Parameters

​Code Examples

​Response

​200 — Memory Stored

​Error Responses

​Duplicate Detection

Request Headers

Request Body Parameters

Code Examples

Response

200 — Memory Stored

Error Responses

Duplicate Detection