# `Jido.Agent.Identity`
[🔗](https://github.com/agentjido/jido/blob/v2.3.3/lib/jido/agent/identity.ex#L1)

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.

# `t`

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

# `bump`

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

Bump identity revision and updated_at timestamp.

# `evolve`

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

Pure evolution — increments profile age and bumps revision.

# `migrate_checkpoint`

```elixir
@spec migrate_checkpoint(map()) :: map()
```

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

# `migrate_legacy`

```elixir
@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`

```elixir
@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`

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

Create a new identity.

# `snapshot`

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

Return a public snapshot of the identity.

# `state_key`

```elixir
@spec state_key() :: :__identity__
```

Returns the reserved agent state key used for identity storage.