---
title: Identity (TypeID)
description: How Cortex uses prefix-qualified, globally unique identifiers for every entity.
---

Every entity in Cortex has a TypeID. TypeIDs are globally unique, sortable, URL-safe identifiers built on UUIDv7 with a human-readable prefix that tells you what kind of entity you're looking at.

A TypeID looks like this:

```
agt_01h455vb4pex5vsknk084sn02q
```

The `agt` prefix identifies this as an agent. The suffix is a base32-encoded UUIDv7 that encodes creation time, so IDs sort chronologically.

## The `id` package

The `id` package wraps the [TypeID Go library](https://github.com/jetify-com/typeid-go) (v2) with a single `ID` struct. All entity types share the same struct -- the prefix distinguishes them.

### Creating IDs

```go
import "github.com/xraph/cortex/id"

agentID         := id.New(id.PrefixAgent)          // agt_01h455vb...
agentRunID      := id.New(id.PrefixAgentRun)       // arun_01h455vb...
toolID          := id.New(id.PrefixTool)           // tool_01h455vb...
toolCallID      := id.New(id.PrefixToolCall)       // tcall_01h455vb...
stepID          := id.New(id.PrefixStep)           // astp_01h455vb...
memoryID        := id.New(id.PrefixMemory)         // mem_01h455vb...
checkpointID    := id.New(id.PrefixCheckpoint)     // acp_01h455vb...
orchestrationID := id.New(id.PrefixOrchestration)  // orch_01h455vb...
skillID         := id.New(id.PrefixSkill)          // skl_01h455vb...
traitID         := id.New(id.PrefixTrait)          // trt_01h455vb...
behaviorID      := id.New(id.PrefixBehavior)       // bhv_01h455vb...
personaID       := id.New(id.PrefixPersona)        // prs_01h455vb...
```

Convenience constructors: `id.NewAgentID()`, `id.NewAgentRunID()`, `id.NewToolID()`, `id.NewToolCallID()`, `id.NewStepID()`, `id.NewMemoryID()`, `id.NewCheckpointID()`, `id.NewOrchestrationID()`, `id.NewSkillID()`, `id.NewTraitID()`, `id.NewBehaviorID()`, `id.NewPersonaID()`.

### Parsing IDs

```go
parsed, err := id.Parse("agt_01h455vb4pex5vsknk084sn02q")
parsed, err := id.ParseWithPrefix("agt_01h455vb...", id.PrefixAgent)  // validates prefix
parsed, err := id.ParseAgentID("agt_01h455vb...")                     // convenience
```

### Nil ID

```go
var empty id.ID
empty.IsNil()  // true
empty.String() // ""
id.Nil.IsNil() // true
```

### Database storage

`id.ID` implements `Scanner` and `driver.Valuer`. Stores as a string, returns `NULL` for nil IDs.

### JSON serialization

`id.ID` implements `TextMarshaler` and `TextUnmarshaler`. Nil IDs serialize as empty strings.

## Prefix reference

| Constant | Prefix | Entity |
|----------|--------|--------|
| `id.PrefixAgent` | `agt` | Agent |
| `id.PrefixAgentRun` | `arun` | Agent run |
| `id.PrefixTool` | `tool` | Tool |
| `id.PrefixToolCall` | `tcall` | Tool call |
| `id.PrefixStep` | `astp` | Step |
| `id.PrefixMemory` | `mem` | Memory |
| `id.PrefixCheckpoint` | `acp` | Checkpoint |
| `id.PrefixOrchestration` | `orch` | Orchestration |
| `id.PrefixSkill` | `skl` | Skill |
| `id.PrefixTrait` | `trt` | Trait |
| `id.PrefixBehavior` | `bhv` | Behavior |
| `id.PrefixPersona` | `prs` | Persona |