Skip to main content
GET
/
api
/
v1
/
memory
/
tasks
Task Memory API
curl --request GET \
  --url https://api.example.com/api/v1/memory/tasks
{
  "id": 123,
  "title": "<string>",
  "status": "<string>",
  "priority": "<string>",
  "createdAt": {},
  "updatedAt": {},
  "metadata": {}
}

​
Overview

The Task Memory API provides persistent storage for agent task management. It allows LLMs and AI agents to track pending and completed tasks across sessions.
Task memory is useful for multi-step workflows where agents need to remember context between tool executions.

​
List Pending Tasks

Retrieve all tasks that are currently pending completion.

​
Request

curl -X GET "http://localhost:8080/api/v1/memory/tasks" \
  -H "Authorization: Bearer YOUR_TOKEN"

​
Response

Returns an array of TaskMemory objects:
​
id
Long
Unique task identifier
​
title
string
Task title or description
​
status
string
Task status. Possible values:
  • PENDING
  • IN_PROGRESS
  • COMPLETED
  • FAILED
​
priority
string
Task priority. Possible values:
  • LOW
  • MEDIUM
  • HIGH
  • URGENT
​
createdAt
Instant
Timestamp when the task was created (ISO-8601)
​
updatedAt
Instant
Timestamp when the task was last updated (ISO-8601)
​
metadata
object
Additional task metadata (JSON object)

​
Example Response

[
  {
    "id": 42,
    "title": "Deploy new API endpoint to production",
    "status": "PENDING",
    "priority": "HIGH",
    "createdAt": "2026-03-03T10:30:00Z",
    "updatedAt": "2026-03-03T10:30:00Z",
    "metadata": {
      "assignedTo": "ai-agent-001",
      "estimatedDuration": "30m"
    }
  },
  {
    "id": 43,
    "title": "Update documentation for new features",
    "status": "PENDING",
    "priority": "MEDIUM",
    "createdAt": "2026-03-03T11:15:00Z",
    "updatedAt": "2026-03-03T11:15:00Z",
    "metadata": {
      "relatedFiles": ["README.md", "API.md"]
    }
  }
]

​
List Completed Tasks

Retrieve all tasks that have been marked as completed.

​
Request

curl -X GET "http://localhost:8080/api/v1/memory/tasks/completed" \
  -H "Authorization: Bearer YOUR_TOKEN"

​
Response

Returns an array of completed TaskMemory objects with the same structure as pending tasks.

​
Example Response

[
  {
    "id": 38,
    "title": "Generate monthly analytics report",
    "status": "COMPLETED",
    "priority": "MEDIUM",
    "createdAt": "2026-03-01T09:00:00Z",
    "updatedAt": "2026-03-01T14:30:00Z",
    "metadata": {
      "completedBy": "ai-agent-001",
      "outputFile": "reports/2026-02-analytics.pdf"
    }
  }
]

​
Delete Task

Remove a task from memory by its ID.

​
Request

curl -X DELETE "http://localhost:8080/api/v1/memory/tasks/42" \
  -H "Authorization: Bearer YOUR_TOKEN"

​
Path Parameters

​
id
Long
required
Unique identifier of the task to delete

​
Response

Returns HTTP 204 No Content on successful deletion.
Task deletion is permanent and cannot be undone. Ensure you have any necessary data from the task before deleting it.

​
Use Cases

Multi-Step Workflows

Track progress on complex tasks that span multiple tool executions

Session Persistence

Remember context between agent sessions for long-running projects

Task Prioritization

Organize and prioritize work for autonomous agents

Audit History

Review completed tasks to understand agent activity over time

​
Example Agent Workflow

Here’s how an AI agent might use the Task Memory API:
1

List pending tasks

Agent retrieves pending tasks to determine what work needs to be done
GET /api/v1/memory/tasks
2

Execute highest priority task

Agent processes the most urgent pending task using appropriate tools
3

Mark task as completed

After successful completion, agent updates task status (via internal service)
4

Clean up old tasks

Periodically delete completed tasks that are no longer needed
DELETE /api/v1/memory/tasks/{id}
Task creation and status updates are typically managed through internal services rather than direct API calls. The API provides read and delete operations for agent task management.

Build docs developers (and LLMs) love

Get started for freeTalk to us