Action Grain

What is an Action grain?

An Action grain records a discrete operation that was performed — a tool call, API request, code execution, or computer-use action. Actions provide a complete audit trail in the context database with the tool name, input arguments, output content, error status, and execution duration.

OMS 1.2 renamed this grain type from ToolCall (OMS 1.1) and changed three field names: arguments became input, result became content, and success became is_error (with inverted boolean logic). The AI memory system uses the text representation tool_name + content for embedding and BM25 indexing, so queries like “web_search weather” match actions by both the tool called and what it returned.

Actions are the execution layer of autonomous memory. Where a Workflow describes what steps to take and a Goal defines what to achieve, Actions record what actually happened. This three-layer pattern (Goal, Workflow, Action) gives agents full traceability from objective through plan to execution result.

FieldTypeRequiredDescription
tool_namestringyesName of the tool or function invoked
inputobjectnoInput arguments passed to the tool (JSON)
contentstringnoOutput or result of the operation
is_errorboolnoWhether the action ended in an error
errorstringnoError message if the action failed
duration_msintnoExecution time in milliseconds
parent_task_idstringnoID of the parent task or workflow step
output_schemaobjectnoJSON Schema describing the action’s return value (OMS 1.3)

Plus all common fields (confidence, tags, namespace, etc.).

How do I create an Action?

Pass tool_name and any relevant fields through the /batch-add endpoint with grain_type: "action". Only tool_name is required; all other fields are optional.

Record both successful and failed actions. For successful operations, include content with the output text and optionally duration_ms for performance tracking. For failures, set is_error: true and provide the error message. This distinction lets agents learn from past failures — querying for actions where is_error is true surfaces recurring tool problems.

Use parent_task_id to associate actions with a workflow or task. Use input to capture the exact arguments passed to the tool, which is critical for reproducibility. The output_schema field (OMS 1.3) lets you declare the structure of the return value so downstream systems can parse content programmatically.

import areev

db = areev.open("./data")

# Successful action
h = db.add("action", {
    "tool_name": "web_search",
    "input": {"query": "weather in tokyo"},
    "content": "72F, partly cloudy, humidity 65%",
    "duration_ms": 340
})

# Failed action
h = db.add("action", {
    "tool_name": "database_query",
    "input": {"sql": "SELECT * FROM users"},
    "is_error": True,
    "error": "connection timeout after 5000ms",
    "duration_ms": 5000
})
POST /api/memories/default/batch-add
Content-Type: application/json

{
  "grains": [
    {
      "grain_type": "action",
      "fields": {
        "tool_name": "web_search",
        "input": {"query": "weather in tokyo"},
        "content": "72F, partly cloudy, humidity 65%",
        "duration_ms": 340
      }
    }
  ]
}
areev add action tool_name=web_search content="72F, partly cloudy" duration_ms=340

How do I track action chains?

Use parent_task_id to link actions to a parent workflow or task, and related_to (a common field) to create explicit links between actions in a sequence.

When executing a multi-step workflow, assign the same parent_task_id to every action that belongs to that workflow run. This lets you query all actions for a given task with a single filter. For sequential dependencies (step 2 depends on step 1’s output), add a related_to link from step 2 back to step 1’s hash.

Batch multiple actions in a single /batch-add request when they occur close together. Each action in the batch gets its own hash and can reference the same parent_task_id. This reduces HTTP round trips and ensures all actions in a workflow step are written atomically.

# Log a sequence of actions for a workflow
step1 = db.add("action", {
    "tool_name": "fetch_data",
    "content": "200 OK, 1.2MB",
    "parent_task_id": "task-001"
})

step2 = db.add("action", {
    "tool_name": "transform_data",
    "content": "processed 500 records",
    "parent_task_id": "task-001"
})
POST /api/memories/default/batch-add
Content-Type: application/json

{
  "grains": [
    {
      "grain_type": "action",
      "fields": {
        "tool_name": "fetch_data",
        "content": "200 OK, 1.2MB",
        "parent_task_id": "task-001"
      }
    },
    {
      "grain_type": "action",
      "fields": {
        "tool_name": "transform_data",
        "content": "processed 500 records",
        "parent_task_id": "task-001"
      }
    }
  ]
}

How do I query Actions?

Search by tool name, output content, or both using the standard /recall endpoint with grain_type: "action". The text representation combines tool_name and content, so both contribute to BM25 ranking.

For operational monitoring, query for failed actions by searching for error-related terms. Combine grain_type: "action" with namespace filtering to scope results to a specific agent or session. Use tags to label actions by category (e.g., "api-call", "code-execution", "file-operation") for deterministic filtering.

Duration tracking through duration_ms lets you build performance profiles. Query actions for a specific tool and analyze the distribution of execution times to identify slow operations or degrading external services.

# Find all web_search actions
results = db.recall(query="web_search", grain_type="action")

# Find failed actions
results = db.recall(grain_type="action", query="error timeout")
POST /api/memories/default/recall
Content-Type: application/json

{"query": "web_search weather", "grain_type": "action", "limit": 10}
  • Grain Types: Overview of all 10 OMS grain types and shared fields
  • Workflow: For the procedural plan that actions execute
  • Event: For passive occurrences rather than agent-initiated operations
  • Reasoning: For the inference chain that led to the action