Behavioral Graph (L2)

The Behavioral Graph is the core data structure of Fusemomo. It is an immutable, append-only ledger of every action every agent has taken on every entity, through any connected API.

Why a Graph?

Most agent systems either:

• Keep no record of what actions were taken and what happened, or
• Store only the latest state (e.g., "status: resolved"), discarding the history of how they got there

Fusemomo records every event as an immutable fact, not as a mutable state change. This is what enables behavioral pattern recognition over time.

The graph connects:

• Entities (resolved canonical records, see Identity Resolution)
• Interactions (individual agent actions, with their outcomes)
• Agents (the specific agent that performed each action)
• APIs (the external service used for each action)

Anatomy of an Interaction

When you log an interaction, you record:

Field	Type	Required	Description
entity_id	string	✅	The canonical entity this action was taken on
agent_id	string	✅	Identifier of the agent that took the action
api	string	✅	The external service used
action_type	string	✅	High-level category of the action
action	string	✅	Specific description of what was done
outcome	string	✅	Result: success, failed, pending, ignored, unknown
intent	string	✅	Goal the agent was trying to achieve
external_ref	string	—	External ID for tracing (e.g., a webhook ID)
metadata	object	—	Any additional structured data

Outcome Values

Outcome	Meaning
success	The intended goal was achieved
failed	The action was executed but the goal was not achieved
ignored	The entity received the action but did not respond
pending	The result is not yet known, outcome will be determined asynchronously
unknown	The outcome could not be determined

Action Types vs. Actions

action_type is a normalized category used for grouping, analytics, and recommendations. action is the raw description of the specific thing that happened.

For example:

• action_type: "send_notification" → action: "Sent Slack DM to octocat about PR #42"
• action_type: "update_ticket_status" → action: "Changed JIRA-2491 from In Review → Done"

Always keep action_type consistent as a controlled vocabulary so the intelligence layer can compare like-for-like outcomes.

Multi-Agent Tracking

Fusemomo tracks the agent_id on every interaction, enabling you to:

• Audit what a specific agent has done on an entity
• Differentiate behavior across agent versions (outreach-bot-v1 vs outreach-bot-v2)
• Measure per-agent success rates in the analytics dashboard

Append-Only Guarantee

Interaction records are never modified or deleted through normal API operations. This ensures:

• A fully trustworthy audit trail
• Consistent behavioral pattern data for the intelligence layer
• Compliance-friendly event sourcing

NOTE

Hard deletes can be performed for GDPR/compliance purposes via the Entity delete endpoint, which anonymizes all associated interactions.

Batch Logging

For high-throughput agents, you can log up to 100 interactions in a single request:

POST /v1/core/interactions/batch

This is the recommended approach for agents that execute multiple parallel actions.