Space

Services

SpaceService Service

Service for managing Spaces in the GoodMem system.

Spaces are the fundamental storage units for organizing memories with associated embedding models and access controls. This service provides lifecycle management including creation, retrieval, listing, updating, and deletion of spaces.

Authentication: gRPC metadata x-api-key: <api-key>

Global errors: All RPCs may return DEADLINE_EXCEEDED, CANCELLED, UNAVAILABLE, RESOURCE_EXHAUSTED, INTERNAL.

Authorization model:

• Every RPC evaluates a typed authorization operation against the GoodMem instance or a particular space.
• Ownership, code-defined role assignments, and direct grants can supply authority; an API-key ceiling may further restrict the authenticated principal's effective authority.
• Listing requires LIST_SPACE on the instance and returns only spaces on which the caller has READ_SPACE.

Security considerations:

• Space names must be unique per owner to prevent conflicts
• Shared authenticated access is represented by authorization grants
• Embedder associations are validated during creation to ensure at least one embedder is supplied, every referenced embedder exists, and the caller may execute every embedder

CreateSpace

Creates a new Space with embedder associations and configuration.

Auth: gRPC metadata x-api-key: <api-key>

Authorization Required: CREATE_SPACE on the proposed space, evaluated using its proposed owner, and EXECUTE_EMBEDDER on every referenced embedder.

Summary:

• Owner defaults to the authenticated principal unless owner_id is provided; authorization is evaluated against that proposed owner
• At least one space_embedder must be specified
• ALREADY_EXISTS: another space exists with identical {owner_id, name} (case-sensitive)
• Validates all embedder IDs exist and the caller has EXECUTE_EMBEDDER on each one
• Duplicate embedder IDs in the same request → INVALID_ARGUMENT

Side Effects:

• Persists space with embedder associations; sets audit fields

Error Codes:

• UNAUTHENTICATED: missing/invalid auth
• PERMISSION_DENIED: lacks CREATE_SPACE for the proposed owner or EXECUTE_EMBEDDER on a referenced embedder
• INVALID_ARGUMENT: empty/invalid name; duplicate embedders; unknown embedder_id; label key/len violations
• ALREADY_EXISTS: matching space name for owner
• INTERNAL: unexpected server error

Examples:

grpcurl -plaintext \\
-H 'x-api-key: gm_xxx' \\
-d '{
"name": "My Knowledge Base",
"space_embedders": [
{
"embedder_id": "BASE64_UUID_BYTES_HERE",
"default_retrieval_weight": 1.0
}
],
"labels": {"org": "acme", "env": "prod"}
}' \\
localhost:8080 goodmem.v1.SpaceService/CreateSpace

Note: bytes fields in JSON must be base64.

Idempotency: Non-idempotent; clients SHOULD NOT blindly retry on unknown failures.

GetSpace

Retrieves details of a specific Space including embedder associations.

Auth: gRPC metadata x-api-key: <api-key>

Authorization Required: READ_SPACE on the requested space.

Summary:

• Loads the space before evaluating authorization, preserving the distinct NOT_FOUND and PERMISSION_DENIED contract
• Returns complete space details including all embedder associations

Error Codes:

• UNAUTHENTICATED: missing/invalid auth
• PERMISSION_DENIED: lacks READ_SPACE on the requested space
• INVALID_ARGUMENT: invalid space ID format
• NOT_FOUND: space does not exist
• INTERNAL: unexpected server error

Idempotency: Read-only; safe to retry; results may change over time.

Examples:

grpcurl -plaintext \
-H 'x-api-key: gm_xxx' \
-d '{ "space_id": "BASE64_UUID_BYTES_HERE" }' \
localhost:8080 goodmem.v1.SpaceService/GetSpace

Note: bytes fields in JSON must be base64.

ListSpaces

Lists Spaces accessible to the authenticated principal with filtering and pagination.

Auth: gRPC metadata x-api-key: <api-key>

Authorization Required: LIST_SPACE on the GoodMem instance and READ_SPACE on each returned space. The standard user role may enumerate the catalog and read owned spaces; direct grants can expose additional spaces.

Request Parameters:

• owner_id (optional, bytes UUID): filter the already-authorized result set by owner
• label_selectors (optional): AND of exact key=value matches (case-sensitive)
• name_filter (optional): glob over full name; * any sequence; ? single char; \ escapes; case-sensitive
• Pagination: next_token is an opaque string; do not parse. max_results defaults to 50; clamped to [1, 1000]
• Sorting: sort_by in {"created_at","name"}; sort_order {"ASCENDING","DESCENDING"}. Default: created_at DESC. Unsupported sort_by → INVALID_ARGUMENT

Note: bytes fields in JSON must be base64.

Error Codes:

• UNAUTHENTICATED: missing/invalid auth
• PERMISSION_DENIED: lacks instance-level LIST_SPACE
• INVALID_ARGUMENT: invalid filters, pagination token, or parameters
• INTERNAL: unexpected server error

Idempotency: Read-only; safe to retry; results may change over time.

Examples:

grpcurl -plaintext \
-H 'x-api-key: gm_xxx' \
-d '{ "label_selectors": {"env": "prod"}, "name_filter": "kb*", "max_results": 25 }' \
localhost:8080 goodmem.v1.SpaceService/ListSpaces

UpdateSpace

Updates mutable properties of a Space (name, labels).

Auth: gRPC metadata x-api-key: <api-key>

Authorization Required: UPDATE_SPACE on the requested space.

Summary:

• Only mutable fields can be updated: name, labels
• space_embedders and default_chunking_config are immutable
• Label updates support replace (clear all, set new) or merge (upsert) strategies
• Name uniqueness is enforced per owner during updates

Side Effects:

• Persists changes; updates updated_at and updated_by_id

Error Codes:

• UNAUTHENTICATED: missing/invalid auth
• PERMISSION_DENIED: lacks UPDATE_SPACE on the requested space
• INVALID_ARGUMENT: invalid fields, empty name, both label strategies set, or no updatable fields provided
• NOT_FOUND: space does not exist
• ALREADY_EXISTS: name conflicts with existing space for owner
• INTERNAL: unexpected server error

Idempotency: Idempotent with identical input; safe to retry.

Examples:

grpcurl -plaintext \
-H 'x-api-key: gm_xxx' \
-d '{
"space_id": "BASE64_UUID_BYTES_HERE",
"name": "Updated Knowledge Base",
"merge_labels": { "items": {"status": "active"} }
}' \
localhost:8080 goodmem.v1.SpaceService/UpdateSpace

Note: bytes fields in JSON must be base64.

TransferSpaceOwnership

Transfers ownership of a Space to another active principal.

Auth: gRPC metadata x-api-key: <api-key>

Authorization Required: TRANSFER_RESOURCE_OWNERSHIP on the requested space, derived from current space ownership, current instance ownership, or an instance-level ADMIN role. A space-level SPACE_ADMIN role and MANAGE_ACCESS alone are insufficient. A scoped API key must also carry a matching immutable ceiling.

Summary:

• Loads the requested space before evaluating authorization, preserving GoodMem's distinct NOT_FOUND and PERMISSION_DENIED contract
• Resolves new_owner_id only after the caller passes authorization
• Accepts an active human or service principal as the new owner
• Rejects transfer to the current owner without changing audit history

Side Effects:

• Changes only the space owner and update-audit fields
• Preserves all grants and role assignments
• Immediately changes the derived ownership domain of every memory contained by the space

Error Codes:

• UNAUTHENTICATED: missing/invalid auth
• PERMISSION_DENIED: caller lacks derived TRANSFER_RESOURCE_OWNERSHIP authority or a scoped API key lacks the required ceiling
• INVALID_ARGUMENT: invalid space_id or new_owner_id format
• NOT_FOUND: space or destination principal does not exist
• FAILED_PRECONDITION: destination principal is deleted or already owns the space
• ALREADY_EXISTS: destination principal already owns a space with the same name
• ABORTED: a concurrent ownership or policy change invalidated the transaction; the caller may retry after reading the current owner
• INTERNAL: unexpected server error

Idempotency: Not idempotent under response semantics: retrying a completed transfer returns FAILED_PRECONDITION. After an unknown outcome, read the current space before retrying.

DeleteSpace

Permanently deletes a Space and its associated content.

Auth: gRPC metadata x-api-key: <api-key>

Authorization Required: DELETE_SPACE on the requested space.

Side Effects:

• Removes the space record permanently
• Cascades deletion to associated memories, chunks, and embedder associations

Error Codes:

• UNAUTHENTICATED: missing/invalid auth
• PERMISSION_DENIED: lacks DELETE_SPACE on the requested space
• INVALID_ARGUMENT: invalid space ID format
• NOT_FOUND: space does not exist
• INTERNAL: unexpected server error

Idempotency: Safe to retry; may return NOT_FOUND if already deleted or never existed.

Examples:

grpcurl -plaintext \
-H 'x-api-key: gm_xxx' \
-d '{ "space_id": "BASE64_UUID_BYTES_HERE" }' \
localhost:8080 goodmem.v1.SpaceService/DeleteSpace

Note: bytes fields in JSON must be base64.

Messages

SpaceEmbedder

Represents the association between a Space and an Embedder with retrieval configuration.

SpaceEmbedders define which embedding models are available for a space and their relative weights during retrieval operations. Each space must have at least one embedder association.

Immutability:

• All fields are immutable after creation (no update operations supported).
• Created as part of space creation process.

Notes:

• All timestamps are UTC (google.protobuf.Timestamp).
• Weights are used for blending multiple embedder results during retrieval.

Space

Represents a Space - the fundamental storage unit in GoodMem for organizing memories.

A Space is a logical container for memories with associated embedding models, access controls, and metadata. Each space has a unique name per owner and defines the embedding and chunking strategies for its contained memories.

Security:

• Shared authenticated access is represented by authorization grants.
• Space ownership and creator are tracked separately for administrative purposes.

Immutability:

• space_embedders are effectively immutable (no update operations supported)
• owner_id changes only through TransferSpaceOwnership, never through UpdateSpace
• default_chunking_config updates are not yet supported

Uniqueness:

• Space names must be unique per owner (case-sensitive).
• System prevents duplicate spaces with identical {owner_id, name} combination.

Notes:

• All timestamps are UTC (google.protobuf.Timestamp)
• Each space must have at least one associated embedder for memory processing

See also: SpaceService for management operations, SpaceEmbedder for embedder associations

Space.LabelsEntry

CreateSpaceRequest

CreateSpaceRequest.LabelsEntry

SpaceEmbedderConfig

Configuration for creating a space-embedder association during space creation.

Used to specify which embedders should be associated with the space and their retrieval weights. All specified embedders must exist before space creation.

GetSpaceRequest

ListSpacesRequest

ListSpacesRequest.LabelSelectorsEntry

ListSpacesResponse

ListSpacesNextPageToken

INTERNAL: Pagination token structure for ListSpaces.

Clients MUST treat next_token as opaque and MUST NOT construct or parse it. The current implementation encodes this structure as base64, but this may change without notice.

ListSpacesNextPageToken.LabelSelectorsEntry

UpdateSpaceRequest

DeleteSpaceRequest

TransferSpaceOwnershipRequest

Request to transfer a Space to another principal.

TransferSpaceOwnershipResponse

Response returned after transferring ownership of a Space.