Payload Structure

Payloads carry the actual knowledge inside an event. They are the smallest unit of structured agent knowledge that you control directly, so shape them well.

Recommended Format

Use a flat object with topic and value keys:

{
  "payload": {
    "topic": "user_preference",
    "value": "dark mode"
  }
}

The topic field helps LocusGraph index and cluster related knowledge. The value field holds the actual content.

Good Payloads

Keep payloads flat and descriptive:

{ "topic": "api_rate_limit", "value": "1000 requests per minute" }

{ "topic": "deployment", "value": "v2.3 deployed to production", "environment": "prod" }

{ "topic": "user_feedback", "value": "prefers shorter responses", "rating": 4 }

Adding extra flat keys alongside topic and value is fine. The admission pipeline indexes topic and value first, then scans additional keys.

Bad Payloads

Avoid deep nesting. The admission pipeline flattens nested objects, which can lose structure:

{
  "user": {
    "preferences": {
      "theme": {
        "mode": "dark",
        "accent": "blue"
      }
    }
  }
}

Instead, store each piece as a separate event or flatten the structure:

{ "topic": "theme_mode", "value": "dark" }

{ "topic": "theme_accent", "value": "blue" }

One Idea per Event

A good payload captures a single learning. Two reasons:

1. Graduation works on shape. When events line up around a single topic, repeated occurrences reinforce each other and graduate cleanly into a pattern, then a skill.
2. Retrieval stays sharp. A payload that bundles five unrelated facts dilutes the semantic signal and pollutes downstream context windows.

If you find yourself stuffing multiple ideas into one payload, split into multiple events and link them with related_to.

Constraints

Next