Skip to main content
Version: latest

agrag.memory.tasks.TaskMemory

TaskMemory(store:GraphStore, *, project_id:str, agent_id:str) -> None

Durable task state for one project, written on behalf of one agent.

Operations take the project and author from this constructor. Each write takes an optional request_id. A repeated write with the same id and arguments returns the stored result, and the same id with other arguments returns request_id_reused.

Functions:

  • create_task – Create a task, or return the existing task of that name.
  • get_task – Read the bounded resume view of a task.
  • list_events – Read events of a task in sequence order, one page at a time.
  • list_steps – Read every step of a task in one state, in name order.
  • record_event – Append one raw event to a task.
  • set_step – Create or update a step of a task.

Parameters:

  • store (GraphStore) – The graph store that holds the task memory.
  • project_id (str) – The project every operation is scoped to. Use a value from trusted configuration.
  • agent_id (str) – The author recorded on tasks and events.

create_task​

create_task(name:str, goal:str, *, request_id:str | None = None) -> CreateTaskResult

Create a task, or return the existing task of that name.

Parameters:

  • name (str) – The task name, unique within the project.
  • goal (str) – The goal. An existing task of the same name must have the same goal.
  • request_id (str | None) – Optional id of at most 64 characters for a safe retry.

Returns:

get_task​

get_task(name:str) -> TaskLookup

Read the bounded resume view of a task.

The view has the goal, status, last event sequence number and the first steps in view order, with counts for every state. It has no event bodies.

Parameters:

  • name (str) – The task name.

Returns:

  • TaskLookup – The view when the task exists in this project. Otherwise
  • TaskLookup – found is false.

list_events​

list_events(task_name:str, *, after_seq:int = 0, limit:int = 50) -> EventPage

Read events of a task in sequence order, one page at a time.

Parameters:

  • task_name (str) – The task name.
  • after_seq (int) – Return events with a larger sequence number than this.
  • limit (int) – Maximum events in the page, between 1 and 200.

Returns:

  • EventPage – The page. When the task does not exist, found is false and the
  • EventPage – page is empty.

list_steps​

list_steps(task_name:str, state:StepState) -> list[StepSummary]

Read every step of a task in one state, in name order.

Parameters:

  • task_name (str) – Task whose steps to read.
  • state (StepState) – State to select.

Returns:

  • list[StepSummary] – All matching steps, or an empty list if the task does not exist.
  • list[StepSummary] – Unlike the task view, this list is not capped at 50 steps.

record_event​

record_event(task_name:str, kind:EventKind, *, role:str | None = None, name:str | None = None, payload:str, request_id:str | None = None) -> RecordEventResult

Append one raw event to a task.

The payload is cut to MAX_PAYLOAD_CHARACTERS when longer, and the event records the hash of the full text. No model is called.

Parameters:

  • task_name (str) – The task the event belongs to.
  • kind (EventKind) – The kind of event.
  • role (str | None) – The speaker role for a message, or None.
  • name (str | None) – The tool or source name for a tool event, or None.
  • payload (str) – The event text.
  • request_id (str | None) – Optional id of at most 64 characters for a safe retry.

Returns:

set_step​

set_step(task_name:str, name:str, state:StepState, *, kind:StepKind = StepKind.OTHER, result_event_seq:int | None = None, request_id:str | None = None) -> SetStepResult

Create or update a step of a task.

Parameters:

  • task_name (str) – The task the step belongs to.
  • name (str) – The step name, unique within the task.
  • state (StepState) – The new state. Use unknown when the outcome is not known.
  • kind (StepKind) – The broad category of the step.
  • result_event_seq (int | None) – The sequence number of the event that holds the result, or None.
  • request_id (str | None) – Optional id of at most 64 characters for a safe retry.

Returns:

  • SetStepResult – The step when recorded. Otherwise task_not_found or
  • SetStepResult – event_not_found when result_event_seq names no event.