Goal Grain

What is a Goal grain?

A Goal grain represents an objective that an agent is working toward. Goals have lifecycle states (active, satisfied, failed, suspended), priority levels, satisfaction criteria, and support for hierarchical decomposition and multi-agent delegation within the context database.

Goals drive agent planning and decision-making in the AI agent memory system. During session bootstrap, agents load active goals to determine what to work on. The autonomous memory engine tracks progress toward satisfaction through the progress field and supports goal hierarchies through parent_goals, letting you decompose complex objectives into sub-goals that multiple agents can pursue independently.

The text representation used for embedding and BM25 indexing is the description concatenated with the criteria: "deploy v2 to production all health checks passing". This lets agents recall relevant goals by describing the situation they face.

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

How do I create a Goal?

Pass description and optionally priority and criteria through the /batch-add endpoint with grain_type: "goal". New goals default to goal_state: "active".

Write the description as a concrete objective, not a vague aspiration. “Deploy v2 to production” is actionable; “improve performance” is not. The criteria field defines what “done” means in human-readable terms. For machine-evaluable criteria, use criteria_structured with a JSON object your agent can check programmatically.

Use priority to rank goals relative to each other. When an agent has multiple active goals, it processes "critical" before "high", "high" before "medium", and so on. The expiry_policy field can auto-transition goals to "failed" after a deadline, preventing stale objectives from consuming agent attention.

import areev

db = areev.open("./data")
h = db.add("goal", {
    "description": "Deploy v2 to production",
    "priority": "high",
    "criteria": "all health checks passing, zero error rate for 10 minutes"
})

POST /api/memories/default/batch-add
Content-Type: application/json

{
  "grains": [
    {
      "grain_type": "goal",
      "fields": {
        "description": "Deploy v2 to production",
        "priority": "high",
        "criteria": "all health checks passing, zero error rate for 10 minutes"
      }
    }
  ]
}

areev add goal description="Deploy v2 to production" priority=high criteria="all health checks passing"

How do I track Goal state transitions?

Goals are immutable. To record a state transition, supersede the current goal with a new version that has the updated goal_state and a state_reason explaining the change.

The supersession chain preserves the full state history: active, then satisfied (or failed/suspended). This is critical for audit trails where you must demonstrate not just the current state of an objective but how and why it transitioned. Include satisfaction_evidence when marking a goal as satisfied to record the proof that criteria were met.

The progress field (0.0 to 1.0) tracks incremental advancement. Update it by superseding the goal with each milestone. Agents can query active goals sorted by progress to identify which objectives need attention and which are nearly complete.

active_hash = db.add("goal", {
    "description": "Deploy v2 to production",
    "priority": "high",
    "criteria": "all health checks passing"
})

satisfied_hash = db.supersede(active_hash, "goal", {
    "description": "Deploy v2 to production",
    "goal_state": "satisfied",
    "state_reason": "deployment completed, all checks green",
    "satisfaction_evidence": {"deploy_id": "d-2026-03-09", "error_rate": 0.0},
    "progress": 1.0
})

POST /api/memories/default/supersede
Content-Type: application/json

{
  "blob_hash": "<active_hash>",
  "fields": {
    "description": "Deploy v2 to production",
    "goal_state": "satisfied",
    "state_reason": "deployment completed, all checks green",
    "satisfaction_evidence": {"deploy_id": "d-2026-03-09", "error_rate": 0.0},
    "progress": 1.0
  }
}

How do I build Goal hierarchies?

Use parent_goals to link sub-goals to their parent, creating a tree structure. Each sub-goal references the hash of the parent it contributes to.

Goal hierarchies let you decompose a complex objective into independently trackable sub-goals. Each sub-goal has its own lifecycle (active/satisfied/failed) and can be assigned to a different agent via delegate_to. The parent goal is typically marked satisfied only after all sub-goals are satisfied, though you enforce this logic in your agent code rather than in Areev.

Query sub-goals by searching for the parent hash in related_to, or tag goals with a shared namespace to group them. For large hierarchies (10+ sub-goals), use a namespace like "project-v2" to retrieve the full tree without relying on hash-based traversal.

parent = db.add("goal", {
    "description": "Launch product v2",
    "priority": "critical"
})

db.add("goal", {
    "description": "Deploy v2 to production",
    "priority": "high",
    "parent_goals": [parent]
})

db.add("goal", {
    "description": "Complete v2 documentation",
    "priority": "medium",
    "parent_goals": [parent]
})

db.add("goal", {
    "description": "Run load tests at 10k RPS",
    "priority": "high",
    "parent_goals": [parent]
})

When should I use Goal vs. Workflow?

Use Goal to define what you want to achieve. Use Workflow to define how to achieve it. Goals track objectives and their lifecycle; workflows encode the step-by-step procedure.

A common pattern is to create a Goal, then a Workflow that describes the plan to satisfy it, then Action grains for each step executed. Link them with related_to for full traceability from objective through plan to execution.

Related

• Grain Types: Overview of all 10 OMS grain types and shared fields
• Workflow: For multi-step plans that pursue a goal
• Action: For operations performed toward a goal
• Reasoning: For the inference chain behind goal prioritization