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

# Write and Search Session Memory

> Store key-value context fragments in an agent session with semantic search retrieval. Use POST to write and GET to search memory items.

Session memory persists key-value pairs as context fragments using pgvector. Write memory with a POST request, then retrieve relevant items later with a semantic GET search.

## Write Memory

### Endpoint

```http theme={null}
POST /v1/agents/sessions/{session_id}/memory
```

## Authentication

Pass one of `Authorization: Bearer <api-key>` or `Authorization: ApiKey <key>`.

## Path Parameters

<ParamField path="session_id" type="string" required>
  The agent session identifier.
</ParamField>

## Request Body

<ParamField body="key" type="string" required>
  Unique key for the memory item.
</ParamField>

<ParamField body="value" type="string" required>
  The text value to store.
</ParamField>

<ParamField body="metadata" type="object">
  Optional arbitrary metadata object.
</ParamField>

### Response

<ResponseField name="key" type="string">
  The stored key.
</ResponseField>

<ResponseField name="value" type="string">
  The stored value.
</ResponseField>

<ResponseField name="metadata" type="object">
  Stored metadata.
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://agent.example.com/v1/agents/sessions/sess_01J5X8/memory \
    -H "Authorization: Bearer <api-key>" \
    -H "Content-Type: application/json" \
    -d '{
      "key": "user_preference_temperature",
      "value": "User prefers Celsius.",
      "metadata": {"topic": "units"}
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "key": "user_preference_temperature",
    "value": "User prefers Celsius.",
    "metadata": {"topic": "units"}
  }
  ```
</ResponseExample>

## Search Memory

### Endpoint

```http theme={null}
GET /v1/agents/sessions/{session_id}/memory
```

## Query Parameters

<ParamField query="q" type="string" required>
  Semantic search query.
</ParamField>

<ParamField query="limit" type="integer">
  Maximum number of results to return.
</ParamField>

<ParamField query="filter" type="string">
  Optional metadata filter expression.
</ParamField>

### Response

<ResponseField name="items" type="array">
  Array of matching memory items.
</ResponseField>

<ResponseField name="items[].key" type="string">
  Item key.
</ResponseField>

<ResponseField name="items[].value" type="string">
  Item value.
</ResponseField>

<ResponseField name="items[].score" type="number">
  Semantic similarity score.
</ResponseField>

<ResponseField name="items[].metadata" type="object">
  Item metadata.
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl "https://agent.example.com/v1/agents/sessions/sess_01J5X8/memory?q=preference&limit=5" \
    -H "Authorization: Bearer <api-key>"
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "items": [
      {
        "key": "user_preference_temperature",
        "value": "User prefers Celsius.",
        "score": 0.92,
        "metadata": {"topic": "units"}
      }
    ]
  }
  ```
</ResponseExample>


## Related topics

- [Get Memory Item](/api-reference/agent/memory/get.md)
- [Delete an Aria Agent Cloud Session by ID](/api-reference/agent/sessions/delete.md)
- [Create Aria Agent Cloud Session for an Agent](/api-reference/agent/sessions/create.md)
- [List Subagents](/api-reference/agent/subagents/list.md)
- [Get Subagent](/api-reference/agent/subagents/get.md)