Identity Resolution (L1)

Identity Resolution is the foundation of Fusemomo. It answers one question: Is this the same entity I've seen before?

The Identity Problem

In a world where agents operate across multiple APIs and services, the same underlying entity may appear under a completely different identifier in every system. Without a unified identity layer, an agent working on the same underlying record across multiple platforms would treat them as separate entities, losing all accumulated context and outcome history.

Fusemomo solves this by maintaining a canonical entity record that consolidates all known identifiers into a single, stable entity_id.

How Resolution Works

When you call POST /v1/core/entities/resolve, you provide a set of known identifiers:

{
  "identifiers": {
    "email": "user@example.com",
    "crm_id": "crm_abc123"
  }
}

Entity Identifiers

An identifier has three components:

Field	Description	Example
Source (key)	The system or API where this ID originates	email, github_user, jira_id, stripe_customer
Value	The raw identifier string	user@example.com, octocat, JIRA-1234
Confidence	How certain the link is (optional, used for probabilistic matching)	0.95

Linking Additional Identifiers

If you later discover a new identifier for an already-resolved entity, you can add it explicitly:

POST /v1/core/entities/{id}/link

{
  "identifiers": {
    "slack_user": "U03ABCDEF"
  }
}

Fusemomo will link the new identifier to the existing canonical entity.

Entity Types

Use entity_type to categorize what kind of record this is. Fusemomo does not restrict or validate entity types; use any string that makes sense for your domain:

Domain	Entity Types
SaaS / CRM	user, customer, account, organization
DevOps	repository, ticket, deployment, pull_request
Support	contact, ticket, conversation
Finance	invoice, subscription, payment_method

Behavioral Score

Every resolved entity has a behavioral_score between 0.0 and 1.0. This score reflects the historical success rate of all interactions on that entity, a normalized measure of how reliably actions on this entity have succeeded.

A fresh entity starts at 0.0 and the score evolves as interactions are logged.

Best Practices

• Always resolve first. Never assume you have a valid entity_id from a previous session without confirming via a fresh resolve call.
• Use meaningful source keys. The source key (e.g., email, github_handle) should be consistent across all calls. Inconsistent key naming breaks deterministic matching.
• Pass all known identifiers at once. Providing multiple identifiers in a single call allows Fusemomo to merge previously separate entities immediately.