Write and Search Session Memory

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

{
  "key": "user_preference_temperature",
  "value": "User prefers Celsius.",
  "metadata": {"topic": "units"}
}

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

{
  "key": "user_preference_temperature",
  "value": "User prefers Celsius.",
  "metadata": {"topic": "units"}
}

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

POST /v1/agents/sessions/{session_id}/memory

Authentication

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

Path Parameters

string

required

The agent session identifier.

Request Body

string

required

Unique key for the memory item.

string

required

The text value to store.

object

Optional arbitrary metadata object.

Response

string

The stored key.

string

The stored value.

object

Stored metadata.

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

{
  "key": "user_preference_temperature",
  "value": "User prefers Celsius.",
  "metadata": {"topic": "units"}
}

Search Memory

Endpoint

GET /v1/agents/sessions/{session_id}/memory

Query Parameters

string

required

Semantic search query.

integer

Maximum number of results to return.

string

Optional metadata filter expression.

Response

array

Array of matching memory items.

string

Item key.

string

Item value.

number

Semantic similarity score.

object

Item metadata.

curl "https://agent.example.com/v1/agents/sessions/sess_01J5X8/memory?q=preference&limit=5" \
  -H "Authorization: Bearer <api-key>"

{
  "items": [
    {
      "key": "user_preference_temperature",
      "value": "User prefers Celsius.",
      "score": 0.92,
      "metadata": {"topic": "units"}
    }
  ]
}

PIN API

ROUTER API

AGENT API

Write and Search Session Memory

Write Memory

Endpoint

Authentication

Path Parameters

Request Body

Response

Search Memory

Endpoint

Query Parameters

Response

​Write Memory

​Endpoint

​Authentication

​Path Parameters

​Request Body

​Response

​Search Memory

​Endpoint

​Query Parameters

​Response

Write Memory

Endpoint

Authentication

Path Parameters

Request Body

Response

Search Memory

Endpoint

Query Parameters

Response