Memories

Memories are the core resource in MemoryRelay. Each memory stores a piece of information with an embedding vector for semantic search, optional metadata, and entity associations.

Create Memory

POST /v1/memories

Store a new memory. An embedding vector is generated automatically from the content.

Request Body

Field	Type	Required	Description
`content`	string	Yes	Memory content (1-50,000 characters)
`agent_id`	string	Yes	Agent namespace identifier
`metadata`	object	No	Custom key-value metadata (max 10KB)
`memory_type`	string	No	Type: `fact`, `event`, `insight`, `task`, `preference`, `entity_reference`, `system`. Auto-classified if omitted
`session_id`	string	No	Session ID to associate with
`project`	string	No	Project slug to scope this memory to
`project_id`	string	No	Project UUID (takes precedence over `project` slug)
`importance`	float	No	Importance score 0.0-1.0 (default 0.5). Values >= 0.8 promote to hot tier
`tier`	string	No	Memory tier: `hot`, `warm`, `cold`. Auto-computed from importance if omitted
`visibility`	string	No	`private` (default) or `confidential`
`deduplicate`	boolean	No	Check for near-duplicate content before storing (default: false)
`dedup_threshold`	float	No	Similarity threshold for dedup, 0.5-1.0 (default: 0.95)
`auto_extract_entities`	boolean	No	Extract entities from content. `true`=always, `false`=never, `null`=auto

Response

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "object": "memory",
  "content": "The user prefers dark mode in all applications",
  "agent_id": "d4e5f6a7-b8c9-0123-4567-890abcdef012",
  "metadata": {
    "source": "chat",
    "confidence": "high"
  },
  "entities": [
    { "type": "preference", "value": "dark mode", "confidence": 0.95 }
  ],
  "memory_type": "preference",
  "visibility": "private",
  "importance": 0.5,
  "tier": "warm",
  "is_duplicate": false,
  "session_id": null,
  "project_id": null,
  "created_at": 1710672000,
  "updated_at": 1710672000
}

curl

curl -X POST https://api.memoryrelay.net/v1/memories \
  -H "Authorization: Bearer $MEMORYRELAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "The user prefers dark mode in all applications",
    "agent_id": "my-assistant",
    "metadata": { "source": "chat", "confidence": "high" },
    "memory_type": "preference"
  }'

Python SDK

from memoryrelay import MemoryRelay

client = MemoryRelay(api_key="mem_prod_...")

memory = client.memories.create(
    content="The user prefers dark mode in all applications",
    agent_id="my-assistant",
    metadata={"source": "chat", "confidence": "high"},
    memory_type="preference",
)
print(memory.id)

Batch Create Memories

POST /v1/memories/batch

Create 1-100 memories in a single request. Embeddings are generated in parallel by default.

Request Body

Field	Type	Required	Description
`memories`	array	Yes	List of memory objects (1-100 items)
`memories[].content`	string	Yes	Memory content (1-50,000 characters)
`memories[].agent_id`	string	No	Agent identifier (inherits from auth if not provided)
`memories[].metadata`	object	No	Custom metadata (max 10KB, max 50 keys)
`memories[].client_id`	string	No	Client-provided idempotency key for deduplication
`memories[].session_id`	string	No	Session ID to associate with
`parallel_embeddings`	boolean	No	Generate embeddings in parallel (default: true)

Response

{
  "success": true,
  "total": 3,
  "succeeded": 3,
  "failed": 0,
  "skipped": 0,
  "results": [
    {
      "index": 0,
      "status": "success",
      "memory_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "content_preview": "The user prefers dark mode"
    },
    {
      "index": 1,
      "status": "success",
      "memory_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "content_preview": "Meeting scheduled for March 20 at 2pm"
    },
    {
      "index": 2,
      "status": "success",
      "memory_id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
      "content_preview": "Project deadline moved to April 1"
    }
  ],
  "timing": {
    "total_ms": 456.78,
    "embedding_ms": 312.45,
    "database_ms": 89.23,
    "per_memory_avg_ms": 152.26
  }
}

curl

curl -X POST https://api.memoryrelay.net/v1/memories/batch \
  -H "Authorization: Bearer $MEMORYRELAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "memories": [
      {
        "content": "The user prefers dark mode",
        "agent_id": "my-assistant",
        "metadata": { "category": "preference" }
      },
      {
        "content": "Meeting scheduled for March 20 at 2pm",
        "agent_id": "my-assistant",
        "metadata": { "category": "event" }
      }
    ]
  }'

Python SDK

result = client.memories.batch_create(
    memories=[
        {"content": "The user prefers dark mode", "agent_id": "my-assistant"},
        {"content": "Meeting scheduled for March 20 at 2pm", "agent_id": "my-assistant"},
    ]
)
print(f"Created {result.succeeded}/{result.total} memories")

Semantic Search

POST /v1/memories/search

Search memories using natural language. Returns results ranked by semantic similarity.

Request Body

Field	Type	Required	Description
`query`	string	Yes	Natural language search query (1-10,000 characters)
`agent_id`	string	No	Filter by agent. Omit to search across all agents
`search_mode`	string	No	`semantic` (default), `hybrid` (vector + full-text + graph), `keyword` (full-text only)
`limit`	integer	No	Number of results, 1-100 (default: 10)
`min_score`	float	No	Minimum similarity score, 0.0-1.0 (default: 0.0)
`metadata_filter`	object	No	Filter by metadata fields
`tier`	string	No	Filter by tier: `hot`, `warm`, `cold`
`min_importance`	float	No	Minimum importance threshold, 0.0-1.0
`include_confidential`	boolean	No	Include confidential memories (default: false)
`include_archived`	boolean	No	Include archived memories (default: false)
`compress`	boolean	No	Enable context compression on results (default: false)
`max_context_tokens`	integer	No	Target token budget for compressed results
`debug`	boolean	No	Return `score_breakdown` on each result (default: false)

Response

{
  "object": "search_results",
  "query": "What are the user's UI preferences?",
  "data": [
    {
      "memory": {
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "object": "memory",
        "content": "The user prefers dark mode in all applications",
        "agent_id": "d4e5f6a7-b8c9-0123-4567-890abcdef012",
        "metadata": { "source": "chat" },
        "entities": [
          { "type": "preference", "value": "dark mode", "confidence": 0.95 }
        ],
        "memory_type": "preference",
        "importance": 0.7,
        "tier": "warm",
        "created_at": 1710672000,
        "updated_at": 1710672000
      },
      "score": 0.91
    },
    {
      "memory": {
        "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
        "object": "memory",
        "content": "User requested larger font sizes for accessibility",
        "agent_id": "d4e5f6a7-b8c9-0123-4567-890abcdef012",
        "metadata": {},
        "entities": [],
        "memory_type": "preference",
        "importance": 0.6,
        "tier": "warm",
        "created_at": 1710585600,
        "updated_at": 1710585600
      },
      "score": 0.84
    }
  ],
  "meta": {
    "recalled_count": 2,
    "total_evaluated": 156,
    "threshold": 0.0,
    "top_scores": [0.91, 0.84]
  }
}

curl

curl -X POST https://api.memoryrelay.net/v1/memories/search \
  -H "Authorization: Bearer $MEMORYRELAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What are the user'\''s UI preferences?",
    "agent_id": "my-assistant",
    "limit": 10,
    "min_score": 0.5
  }'

Python SDK

results = client.memories.search(
    query="What are the user's UI preferences?",
    agent_id="my-assistant",
    limit=10,
    min_score=0.5,
)
for result in results.data:
    print(f"[{result.score:.2f}] {result.memory.content}")

Hybrid Search

Set search_mode to "hybrid" to combine vector similarity, full-text search, and graph traversal with Reciprocal Rank Fusion (RRF) scoring. This often returns better results for queries that include specific keywords or entity names.

List Memories

GET /v1/memories

Retrieve a paginated list of memories.

Query Parameters

Parameter	Type	Required	Description
`agent_id`	string	No	Filter by agent
`limit`	integer	No	Results per page, 1-100 (default: 20)
`offset`	integer	No	Number of results to skip (default: 0)
`memory_type`	string	No	Filter by type: `fact`, `event`, `insight`, `task`, `preference`, `entity_reference`, `system`

Response

{
  "object": "list",
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "object": "memory",
      "content": "The user prefers dark mode in all applications",
      "agent_id": "d4e5f6a7-b8c9-0123-4567-890abcdef012",
      "metadata": {},
      "entities": [],
      "memory_type": "preference",
      "importance": 0.5,
      "tier": "warm",
      "created_at": 1710672000,
      "updated_at": 1710672000
    }
  ],
  "has_more": true,
  "next_cursor": "cursor_abc123",
  "total_count": 142
}

curl

curl "https://api.memoryrelay.net/v1/memories?agent_id=my-assistant&limit=20&offset=0" \
  -H "Authorization: Bearer $MEMORYRELAY_API_KEY"

Python SDK

memories = client.memories.list(agent_id="my-assistant", limit=20)
for memory in memories.data:
    print(f"{memory.id}: {memory.content[:80]}")

Get Memory

GET /v1/memories/{id}

Retrieve a single memory by its ID.

Path Parameters

Parameter	Type	Description
`id`	UUID	Memory ID

Response

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "object": "memory",
  "content": "The user prefers dark mode in all applications",
  "agent_id": "d4e5f6a7-b8c9-0123-4567-890abcdef012",
  "metadata": { "source": "chat" },
  "entities": [
    { "type": "preference", "value": "dark mode", "confidence": 0.95 }
  ],
  "memory_type": "preference",
  "visibility": "private",
  "importance": 0.5,
  "tier": "warm",
  "session_id": null,
  "project_id": null,
  "created_at": 1710672000,
  "updated_at": 1710672000
}

curl

curl https://api.memoryrelay.net/v1/memories/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer $MEMORYRELAY_API_KEY"

Python SDK

memory = client.memories.get("a1b2c3d4-e5f6-7890-abcd-ef1234567890")
print(memory.content)

Update Memory

PATCH /v1/memories/{id}

Update a memory's content or metadata. If the content changes, the embedding is regenerated automatically.

Path Parameters

Parameter	Type	Description
`id`	UUID	Memory ID

Request Body

Field	Type	Required	Description
`content`	string	No	New content (1-50,000 characters). Triggers re-embedding
`metadata`	object	No	Updated metadata (merged with existing, max 10KB)

Response

Returns the updated memory object (same schema as Get Memory).

curl

curl -X PATCH https://api.memoryrelay.net/v1/memories/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer $MEMORYRELAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "User strongly prefers dark mode in all applications and IDEs",
    "metadata": { "last_confirmed": "2026-03-17" }
  }'

Python SDK

updated = client.memories.update(
    "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    content="User strongly prefers dark mode in all applications and IDEs",
    metadata={"last_confirmed": "2026-03-17"},
)

Delete Memory

DELETE /v1/memories/{id}

Soft-delete a memory. The memory is marked as deleted and excluded from search results but can be recovered.

Path Parameters

Parameter	Type	Description
`id`	UUID	Memory ID

Response

Returns 204 No Content on success.

curl

curl -X DELETE https://api.memoryrelay.net/v1/memories/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer $MEMORYRELAY_API_KEY"

Python SDK

client.memories.delete("a1b2c3d4-e5f6-7890-abcd-ef1234567890")

Soft Deletes

All deletes are soft deletes. The memory's deleted_at timestamp is set and it is excluded from queries, but the underlying data is retained for audit and potential recovery.

Create Memory​

Request Body​

Response​

curl​

Python SDK​

Batch Create Memories​

Request Body​

Response​

curl​

Python SDK​

Semantic Search​

Request Body​

Response​

curl​

Python SDK​

List Memories​

Query Parameters​

Response​

curl​

Python SDK​

Get Memory​

Path Parameters​

Response​

curl​

Python SDK​

Update Memory​

Path Parameters​

Request Body​

Response​

curl​

Python SDK​

Delete Memory​

Path Parameters​

Response​

curl​

Python SDK​

Create Memory

Request Body

Response

curl

Python SDK

Batch Create Memories

Request Body

Response

curl

Python SDK

Semantic Search

Request Body

Response

curl

Python SDK

List Memories

Query Parameters

Response

curl

Python SDK

Get Memory

Path Parameters

Response

curl

Python SDK

Update Memory

Path Parameters

Request Body

Response

curl

Python SDK

Delete Memory

Path Parameters

Response

curl

Python SDK