Skip to content

Graph ID Model

Memory graph objects have two distinct ID fields that serve different purposes. Understanding the difference is critical for building correct integrations.

As of SDK v0.8.0, every GraphObject and GraphRelationship has four ID fields (two are the canonical names, two are deprecated aliases):

Field Alias (deprecated) Stability Changes on update?
VersionID ID Version-specific Yes — changes on every UpdateObject
EntityID CanonicalID Stable No — stable for the lifetime of the object

Use EntityID when you need a stable reference to an object across updates.
Use VersionID when you need to reference the exact version (e.g., in relationship endpoints).

obj, err := client.Graph.GetObject(ctx, someID)
if err != nil {
return err
}
// Stable identifier — use for bookmarks, links, foreign keys
stableRef := obj.EntityID
// Version-specific — changes after UpdateObject
versionRef := obj.VersionID
// Update the object
updated, err := client.Graph.UpdateObject(ctx, obj.VersionID, &graph.UpdateObjectRequest{
Properties: map[string]any{"status": "active"},
})
// updated.VersionID != obj.VersionID ← new version created
// updated.EntityID == obj.EntityID ← same entity

In v0.8.0, the old names were deprecated:

  • GraphObject.ID → use GraphObject.VersionID
  • GraphObject.CanonicalID → use GraphObject.EntityID
  • Same for GraphRelationship.ID and GraphRelationship.CanonicalID

The old fields still exist and are cross-populated for backward compatibility — they always contain the same value as their replacements. But they will be removed in a future major version.

The SDK uses custom UnmarshalJSON on GraphObject and GraphRelationship to cross-populate all four fields regardless of which JSON field names the server sends. Server responses may use id/canonical_id (old) or version_id/entity_id (new) — the SDK handles both.

Use GetByAnyID when the caller might have either a version-specific or entity-stable ID:

// Works with both obj.VersionID and obj.EntityID
obj, err := client.Graph.GetByAnyID(ctx, anyKindOfID)

The graph/graphutil package provides helpers designed for the dual-ID model:

import "github.com/emergent-company/emergent.memory/apps/server/pkg/sdk/graph/graphutil"
// Create an ID set for membership testing
ids := graphutil.NewIDSet(obj)
ids.Contains(someID) // true for both VersionID and EntityID
// Build a lookup index from a slice of objects
idx := graphutil.NewObjectIndex(objects)
obj := idx.Get(anyID) // O(1) lookup by either ID
// Deduplicate a result set by EntityID (keeps newest version of each entity)
unique := graphutil.UniqueByEntity(objects)

See the graphutil reference for full API details.