Client-Specified Identifiers

GoodMem allows clients to optionally specify a UUID when creating resources (such as Memories, Spaces, Embedders, and Extensions). This enables deterministic resource identification, facilitating advanced deployment patterns and synchronization strategies.

By default, if you do not provide an ID, the server generates a random UUID v4 for the new entity. However, by supplying a known ID, you gain control over the identity of your resources across different environments and time.

Why use Client-Specified IDs?

Allowing the client to dictate the ID unlocks several powerful patterns:

1. Infrastructure as Code (IaC) & Idempotency

When defining your GoodMem infrastructure (like Embedders, Rerankers, or standard Spaces) in tools like Terraform or Ansible, you can hardcode the UUIDs. This ensures that applying your configuration is idempotent:

• If the resource with that ID doesn't exist, it is created.
• If it allows updates and exists, it can be managed.
• If it exists but implies a conflict (see Collision Handling), the system prevents duplicate creation.

2. Multi-Environment Parity

You can maintain identical resource identifiers across staging and production environments. A specific "OpenAI Ada-002" embedder can have the exact same UUID in both systems, simplifying application configuration and data migration scripts.

3. Offline-First & Async Operations

Clients (such as mobile apps or edge devices) can generate a valid UUID offline, queue the creation operation, and proceed immediately to use that ID for local references or subsequent requests. When connectivity is restored, the creation request is sent with the pre-generated ID.

4. Deterministic Testing

In integration tests, you can use fixed UUIDs for your test fixtures. This makes assertions predictable and simplifies test data setup and teardown.

How It Works

Usage

When creating a resource via the CLI, gRPC, or REST API, you can populate the optional id field.

CLI Example

# Create a space with a specific UUID
goodmem space create \
  --id "550e8400-e29b-41d4-a716-446655440000" \
  --name "Engineering Knowledge Base"

REST API Example

POST /v1/memories
Content-Type: application/json

{
  "memory_id": "550e8400-e29b-41d4-a716-446655440000",
  "content": "Application state must be predictable."
}

Collision Handling

The system enforces a Strict creation policy for client-specified IDs:

• Success: If the ID does not exist, the resource is created.
• Conflict (409): If a resource with the specified ID already exists, the request fails with an ALREADY_EXISTS error.

This behavior prevents accidental overwrites. The API does not perform an "upsert" (update if exists) when an ID is provided during creation; you must explicitly use the update endpoints to modify existing resources.

Best Practices

Use UUID v4

Always use UUID version 4 (randomly generated) for your identifiers.

• Uniqueness: Minimizes the risk of collision between independently generating clients.
• Security: Prevents "enumeration attacks" where a malicious user might guess resource IDs (which is easier with sequential IDs).

Validation

The server validates that provided IDs are:

• Exactly 16 bytes (standard UUID format).
• Not "nil" (all zeros).

Audit & Tracking

Even when you provide the ID, the server maintains control over audit fields like created_at and created_by. This ensures that while you control the identity, the system of record truthfully tracks the lifecycle.