Identity (TypeID)
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_01h455vb4pex5vsknk084sn02qThe 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 (v2) with a single ID struct. All entity types share the same struct -- the prefix distinguishes them.
Creating IDs
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
parsed, err := id.Parse("agt_01h455vb4pex5vsknk084sn02q")
parsed, err := id.ParseWithPrefix("agt_01h455vb...", id.PrefixAgent) // validates prefix
parsed, err := id.ParseAgentID("agt_01h455vb...") // convenienceNil ID
var empty id.ID
empty.IsNil() // true
empty.String() // ""
id.Nil.IsNil() // trueDatabase 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 |