Sessions

Sessions group related memories into logical work units. Use sessions to track what happened during a conversation, coding session, or task. Memories created with a session_id are automatically associated with that session.

Create Session

POST /v1/sessions

Request Body

Field	Type	Required	Description
`agent_id`	string	No	Agent to scope the session to (UUID or name)
`external_id`	string	No	External semantic key for multi-agent collaboration (max 255 characters)
`project`	string	No	Project label for filtering
`title`	string	No	Session title or goal (max 500 characters)
`metadata`	object	No	Custom metadata (max 10KB)

Response `201 Created`

{
  "id": "e1f2a3b4-c5d6-7890-ef12-345678901234",
  "agent_id": "d4e5f6a7-b8c9-0123-4567-890abcdef012",
  "external_id": null,
  "project": "northrelay",
  "status": "active",
  "title": "Fix email queue retry logic",
  "summary": null,
  "metadata": {
    "environment": "development"
  },
  "memory_count": 0,
  "started_at": "2026-03-17T10:00:00Z",
  "ended_at": null,
  "created_at": "2026-03-17T10:00:00Z",
  "updated_at": "2026-03-17T10:00:00Z"
}

curl

curl -X POST https://api.memoryrelay.net/v1/sessions \
  -H "Authorization: Bearer $MEMORYRELAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "my-assistant",
    "project": "northrelay",
    "title": "Fix email queue retry logic",
    "metadata": { "environment": "development" }
  }'

Python SDK

from memoryrelay import MemoryRelay

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

session = client.sessions.create(
    agent_id="my-assistant",
    project="northrelay",
    title="Fix email queue retry logic",
)
print(session.id)

Get or Create Session

POST /v1/sessions/get-or-create

Idempotent session creation by external_id. If a session with the given external_id already exists, it is returned. Otherwise, a new session is created. The response includes a created boolean indicating which action was taken.

Request Body

Field	Type	Required	Description
`external_id`	string	Yes	External semantic session key (1-255 characters)
`agent_id`	string	No	Agent to scope the session to
`title`	string	No	Session title (used when creating)
`project`	string	No	Project label for filtering
`metadata`	object	No	Custom metadata (used when creating)

Response

{
  "id": "e1f2a3b4-c5d6-7890-ef12-345678901234",
  "agent_id": "d4e5f6a7-b8c9-0123-4567-890abcdef012",
  "external_id": "northrelay-campaign-2026-03",
  "project": "northrelay-prod",
  "status": "active",
  "title": "NorthRelay Campaign System Implementation",
  "summary": null,
  "metadata": { "phase": "implementation" },
  "memory_count": 14,
  "created": false,
  "contributors": ["my-assistant", "code-reviewer"],
  "started_at": "2026-03-01T10:00:00Z",
  "ended_at": null,
  "created_at": "2026-03-01T10:00:00Z",
  "updated_at": "2026-03-17T10:00:00Z"
}

curl

curl -X POST https://api.memoryrelay.net/v1/sessions/get-or-create \
  -H "Authorization: Bearer $MEMORYRELAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "northrelay-campaign-2026-03",
    "agent_id": "my-assistant",
    "title": "NorthRelay Campaign System Implementation",
    "project": "northrelay-prod"
  }'

Python SDK

session = client.sessions.get_or_create(
    external_id="northrelay-campaign-2026-03",
    agent_id="my-assistant",
    title="NorthRelay Campaign System Implementation",
)
print(f"Session {'created' if session.created else 'already existed'}: {session.id}")

Multi-Agent Collaboration

Use external_id to let multiple agents contribute to the same session. Each agent stores memories with the shared session_id, building a unified session history across agents.

List Sessions

GET /v1/sessions

Query Parameters

Parameter	Type	Default	Description
`limit`	integer	20	Results per page (1-100)
`offset`	integer	0	Number of results to skip
`agent_id`	string	--	Filter by agent
`project`	string	--	Filter by project label
`status`	string	--	Filter by status: `active`, `ended`

Response

{
  "data": [
    {
      "id": "e1f2a3b4-c5d6-7890-ef12-345678901234",
      "agent_id": "d4e5f6a7-b8c9-0123-4567-890abcdef012",
      "project": "northrelay",
      "status": "ended",
      "title": "Fix email queue retry logic",
      "summary": "Fixed retry logic: increased max attempts to 5, added jitter",
      "metadata": {},
      "memory_count": 3,
      "started_at": "2026-03-01T10:00:00Z",
      "ended_at": "2026-03-01T11:30:00Z",
      "created_at": "2026-03-01T10:00:00Z",
      "updated_at": "2026-03-01T11:30:00Z"
    }
  ],
  "next_cursor": null,
  "has_more": false,
  "total_count": 1
}

curl

curl "https://api.memoryrelay.net/v1/sessions?project=northrelay&status=active&limit=20" \
  -H "Authorization: Bearer $MEMORYRELAY_API_KEY"

Python SDK

sessions = client.sessions.list(project="northrelay", status="active")
for s in sessions.data:
    print(f"[{s.status}] {s.title} ({s.memory_count} memories)")

Get Session

GET /v1/sessions/{id}

Retrieve a single session. Optionally include all associated memories.

Path Parameters

Parameter	Type	Description
`id`	UUID	Session ID

Query Parameters

Parameter	Type	Default	Description
`include_memories`	boolean	false	Include the session's memories in the response

Response

{
  "id": "e1f2a3b4-c5d6-7890-ef12-345678901234",
  "agent_id": "d4e5f6a7-b8c9-0123-4567-890abcdef012",
  "project": "northrelay",
  "status": "active",
  "title": "Fix email queue retry logic",
  "summary": null,
  "metadata": {},
  "memory_count": 3,
  "memories": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "content": "Identified root cause: retry counter not incremented on timeout",
      "created_at": 1710672000
    }
  ],
  "started_at": "2026-03-17T10:00:00Z",
  "ended_at": null,
  "created_at": "2026-03-17T10:00:00Z",
  "updated_at": "2026-03-17T10:00:00Z"
}

info

The memories array is only populated when include_memories=true.

curl

curl "https://api.memoryrelay.net/v1/sessions/e1f2a3b4-c5d6-7890-ef12-345678901234?include_memories=true" \
  -H "Authorization: Bearer $MEMORYRELAY_API_KEY"

Python SDK

session = client.sessions.get(
    "e1f2a3b4-c5d6-7890-ef12-345678901234",
    include_memories=True,
)
for mem in session.memories:
    print(mem["content"])

End Session

POST /v1/sessions/{id}/end

Mark a session as ended. Optionally provide a summary of what was accomplished and additional metadata.

Path Parameters

Parameter	Type	Description
`id`	UUID	Session ID

Request Body

Field	Type	Required	Description
`summary`	string	No	Summary of what was accomplished (max 50,000 characters)
`metadata`	object	No	Additional metadata to merge into the session

Response

Returns the updated session object with status: "ended" and ended_at timestamp set.

curl

curl -X POST https://api.memoryrelay.net/v1/sessions/e1f2a3b4-c5d6-7890-ef12-345678901234/end \
  -H "Authorization: Bearer $MEMORYRELAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "summary": "Fixed retry logic: increased max attempts to 5, added exponential backoff with jitter"
  }'

Python SDK

ended = client.sessions.end(
    "e1f2a3b4-c5d6-7890-ef12-345678901234",
    summary="Fixed retry logic: increased max attempts to 5, added exponential backoff with jitter",
)
print(f"Session ended at {ended.ended_at}")

Auto-Summarize Session

POST /v1/sessions/{id}/summarize

Automatically generate a summary of the session based on its associated memories. The generated summary is saved to the session.

Path Parameters

Parameter	Type	Description
`id`	UUID	Session ID

Response

{
  "session_id": "e1f2a3b4-c5d6-7890-ef12-345678901234",
  "summary": "Investigated and fixed email queue retry logic. Root cause was the retry counter not incrementing on timeout errors. Increased max retry attempts from 3 to 5 and added exponential backoff with jitter to prevent thundering herd.",
  "memory_count": 5,
  "generated_at": "2026-03-17T12:00:00Z"
}

curl

curl -X POST https://api.memoryrelay.net/v1/sessions/e1f2a3b4-c5d6-7890-ef12-345678901234/summarize \
  -H "Authorization: Bearer $MEMORYRELAY_API_KEY"

Python SDK

result = client.sessions.summarize("e1f2a3b4-c5d6-7890-ef12-345678901234")
print(result.summary)

Delete Session

DELETE /v1/sessions/{id}

Soft-delete a session. Associated memories are preserved by default.

Path Parameters

Parameter	Type	Description
`id`	UUID	Session ID

Response

{
  "id": "e1f2a3b4-c5d6-7890-ef12-345678901234",
  "deleted": true,
  "deleted_at": "2026-03-17T12:00:00Z",
  "cascade_memories": false
}

curl

curl -X DELETE https://api.memoryrelay.net/v1/sessions/e1f2a3b4-c5d6-7890-ef12-345678901234 \
  -H "Authorization: Bearer $MEMORYRELAY_API_KEY"

Python SDK

client.sessions.delete("e1f2a3b4-c5d6-7890-ef12-345678901234")

Create Session​

Request Body​

Response 201 Created​

curl​

Python SDK​

Get or Create Session​

Request Body​

Response​

curl​

Python SDK​

List Sessions​

Query Parameters​

Response​

curl​

Python SDK​

Get Session​

Path Parameters​

Query Parameters​

Response​

curl​

Python SDK​

End Session​

Path Parameters​

Request Body​

Response​

curl​

Python SDK​

Auto-Summarize Session​

Path Parameters​

Response​

curl​

Python SDK​

Delete Session​

Path Parameters​

Response​

curl​

Python SDK​

Create Session

Request Body

Response `201 Created`

curl

Python SDK

Get or Create Session

Request Body

Response

curl

Python SDK

List Sessions

Query Parameters

Response

curl

Python SDK

Get Session

Path Parameters

Query Parameters

Response

curl

Python SDK

End Session

Path Parameters

Request Body

Response

curl

Python SDK

Auto-Summarize Session

Path Parameters

Response

curl

Python SDK

Delete Session

Path Parameters

Response

curl

Python SDK