Jido.Agent.Identity (Jido v2.3.0)

Copy Markdown View Source

Agent identity state for lifecycle/profile facts.

The identity is stored at the reserved :__identity__ key in agent state and captures lifecycle facts such as age, origin, and generation. The core agent identity lives under Jido.Agent so the top-level Jido.Identity namespace can be owned by identity extensions such as the external jido_identity package.

This module used to be named Jido.Identity. The module namespace moved so the core framework's agent identity state does not conflict with top-level identity modules. The state key, default plugin metadata name, default :identity capability, and "identity_evolve" action name remain anchored to the existing :__identity__ plugin state slice.

Identity state is immutable — updates produce a new struct with a bumped revision.

Summary

Types

t()

Functions

bump(identity, opts \\ [])

Bump identity revision and updated_at timestamp.

evolve(identity, opts \\ [])

Pure evolution — increments profile age and bumps revision.

migrate_checkpoint(checkpoint)

Migrates a checkpoint map's :state identity value when present.

migrate_legacy(identity)

Converts legacy %Jido.Identity{} agent identity structs to %Jido.Agent.Identity{}.

migrate_state(state)

Migrates the identity value inside an agent state map.

new(opts \\ [])

Create a new identity.

snapshot(identity)

Return a public snapshot of the identity.

state_key()

Returns the reserved agent state key used for identity storage.

Types

t()

@type t() :: %Jido.Agent.Identity{
  created_at: integer(),
  profile: map(),
  rev: integer(),
  updated_at: integer()
}

Functions

bump(identity, opts \\ [])

@spec bump(
  t(),
  keyword()
) :: t()

Bump identity revision and updated_at timestamp.

evolve(identity, opts \\ [])

@spec evolve(
  t(),
  keyword()
) :: t()

Pure evolution — increments profile age and bumps revision.

migrate_checkpoint(checkpoint)

@spec migrate_checkpoint(map()) :: map()

Migrates a checkpoint map's :state identity value when present.

migrate_legacy(identity)

@spec migrate_legacy(term()) :: t() | term()

Converts legacy %Jido.Identity{} agent identity structs to %Jido.Agent.Identity{}.

This helper supports persisted checkpoints created before the identity namespace moved out of Jido.Identity. Values that are already identities, custom plugin state, or invalid legacy shapes are returned unchanged.

migrate_state(state)

@spec migrate_state(map()) :: map()

Migrates the identity value inside an agent state map.

The state key is still :__identity__; only the struct module is migrated.

new(opts \\ [])

@spec new(keyword()) :: t()

Create a new identity.

snapshot(identity)

@spec snapshot(t()) :: map()

Return a public snapshot of the identity.

state_key()

@spec state_key() :: :__identity__

Returns the reserved agent state key used for identity storage.