curl -X POST "http://localhost:8000/api/v2/agents/my-agent/recall/changed-since" \
-H "X-Session-Token: your_session_token" \
-H "Content-Type: application/json" \
-d '{
"since": "2026-05-01",
"limit": 20,
"type": ["fact", "decision"]
}'
curl -X POST "http://localhost:8000/api/v2/agents/my-agent/recall/changed-since" \
-H "X-Session-Token: your_session_token" \
-H "Content-Type: application/json" \
-d '{
"since": "2026-05-01T00:00:00Z"
}'
{
"agent_id": "my-agent",
"session_id": "sess_123abc",
"since_date": "2026-05-01T00:00:00+00:00",
"memories": [
{
"id": "4f792e13-b39d-5e2e-a743-c9ebef2e0e1d",
"title": "System Upgrade",
"content": "System upgraded to v2.0",
"text": "[FACT] System Upgrade\n\nSystem upgraded to v2.0",
"type": "fact",
"confidence": 0.9,
"status": "active",
"expired_at": null,
"expired_by": null,
"tags": [],
"created_at": "2026-05-04T10:15:30Z",
"updated_at": "2026-05-04T10:15:30Z",
"actor_id": "my-agent",
"source": "agent",
"source_ref": null,
"agent_id": "my-agent",
"score": null,
"provenance": "explicit_statement",
"change_type": "created"
}
],
"count": 1,
"temporal_mode": "changed_since"
}
{
"detail": {
"error": "SessionExpired",
"message": "Session has expired",
"details": {}
}
}
{
"detail": [
{
"type": "missing",
"loc": ["body", "since"],
"msg": "Field required",
"input": {}
}
]
}
{
"detail": {
"error": "InternalServerError",
"message": "An unexpected error occurred",
"details": {
"original_error": "Session is for agent 'other-agent', cannot access 'my-agent'"
}
}
}
Search & Discovery
Recall Changed Since
Differential retrieval — return memories created or updated after a specified timestamp.
POST
/
api
/
v2
/
agents
/
{agent_id}
/
recall
/
changed-since
curl -X POST "http://localhost:8000/api/v2/agents/my-agent/recall/changed-since" \
-H "X-Session-Token: your_session_token" \
-H "Content-Type: application/json" \
-d '{
"since": "2026-05-01",
"limit": 20,
"type": ["fact", "decision"]
}'
curl -X POST "http://localhost:8000/api/v2/agents/my-agent/recall/changed-since" \
-H "X-Session-Token: your_session_token" \
-H "Content-Type: application/json" \
-d '{
"since": "2026-05-01T00:00:00Z"
}'
{
"agent_id": "my-agent",
"session_id": "sess_123abc",
"since_date": "2026-05-01T00:00:00+00:00",
"memories": [
{
"id": "4f792e13-b39d-5e2e-a743-c9ebef2e0e1d",
"title": "System Upgrade",
"content": "System upgraded to v2.0",
"text": "[FACT] System Upgrade\n\nSystem upgraded to v2.0",
"type": "fact",
"confidence": 0.9,
"status": "active",
"expired_at": null,
"expired_by": null,
"tags": [],
"created_at": "2026-05-04T10:15:30Z",
"updated_at": "2026-05-04T10:15:30Z",
"actor_id": "my-agent",
"source": "agent",
"source_ref": null,
"agent_id": "my-agent",
"score": null,
"provenance": "explicit_statement",
"change_type": "created"
}
],
"count": 1,
"temporal_mode": "changed_since"
}
{
"detail": {
"error": "SessionExpired",
"message": "Session has expired",
"details": {}
}
}
{
"detail": [
{
"type": "missing",
"loc": ["body", "since"],
"msg": "Field required",
"input": {}
}
]
}
{
"detail": {
"error": "InternalServerError",
"message": "An unexpected error occurred",
"details": {
"original_error": "Session is for agent 'other-agent', cannot access 'my-agent'"
}
}
}
Overview
Returns memories that were created or updated after the specifiedsince timestamp — useful for “what changed since last week?” workflows.
This endpoint lists memories chronologically (sorted by updated_at descending) — there is no query parameter. For semantic search, use Recall instead.
Authentication
API clients do not send an API key orAuthorization header.
string
required
Session token from Activate Agent. Must match
agent_id.string
required
Must be
application/jsonPath Parameters
string
required
The unique identifier of the agent.
Body
string
required
Start of the change window. Accepts
YYYY-MM-DD (interpreted as start of day UTC) or a full ISO 8601 datetime, e.g. 2026-05-01T00:00:00Z.integer
Maximum number of results to return. Range
1–100. If omitted, the server default applies.array
Optional list of memory type filters (e.g.
["fact", "decision"]).string
default:"all"
Lifecycle filter:
all (default) returns active and expired memories
together so callers can label them, active or expired narrows to one.
See Memory Lifecycle.curl -X POST "http://localhost:8000/api/v2/agents/my-agent/recall/changed-since" \
-H "X-Session-Token: your_session_token" \
-H "Content-Type: application/json" \
-d '{
"since": "2026-05-01",
"limit": 20,
"type": ["fact", "decision"]
}'
curl -X POST "http://localhost:8000/api/v2/agents/my-agent/recall/changed-since" \
-H "X-Session-Token: your_session_token" \
-H "Content-Type: application/json" \
-d '{
"since": "2026-05-01T00:00:00Z"
}'
{
"agent_id": "my-agent",
"session_id": "sess_123abc",
"since_date": "2026-05-01T00:00:00+00:00",
"memories": [
{
"id": "4f792e13-b39d-5e2e-a743-c9ebef2e0e1d",
"title": "System Upgrade",
"content": "System upgraded to v2.0",
"text": "[FACT] System Upgrade\n\nSystem upgraded to v2.0",
"type": "fact",
"confidence": 0.9,
"status": "active",
"expired_at": null,
"expired_by": null,
"tags": [],
"created_at": "2026-05-04T10:15:30Z",
"updated_at": "2026-05-04T10:15:30Z",
"actor_id": "my-agent",
"source": "agent",
"source_ref": null,
"agent_id": "my-agent",
"score": null,
"provenance": "explicit_statement",
"change_type": "created"
}
],
"count": 1,
"temporal_mode": "changed_since"
}
{
"detail": {
"error": "SessionExpired",
"message": "Session has expired",
"details": {}
}
}
{
"detail": [
{
"type": "missing",
"loc": ["body", "since"],
"msg": "Field required",
"input": {}
}
]
}
{
"detail": {
"error": "InternalServerError",
"message": "An unexpected error occurred",
"details": {
"original_error": "Session is for agent 'other-agent', cannot access 'my-agent'"
}
}
}
Next Steps
- Recall As Of for point-in-time queries
- Recall Recent to fetch the most recently stored memories