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 authorization: Bearer <api-key>

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

Permissions model:

• *_SPACE_OWN: operate on caller-owned spaces
• *_SPACE_ANY: operate on any user's spaces (requires elevated role)
• Public spaces (public_read=true) can be read by anyone with basic permissions

Security considerations:

• Space names must be unique per owner to prevent conflicts
• Public read access bypasses ownership restrictions for query operations
• Embedder associations are validated during creation to ensure embedder existence
• Default embedder is used if no embedders are specified during creation

CreateSpace

Creates a new Space with embedder associations and configuration.

Auth: gRPC metadata authorization: Bearer <api-key>

Permissions Required: CREATE_SPACE_OWN or CREATE_SPACE_ANY

Summary:

• Owner defaults to authenticated user unless owner_id is provided (requires *_ANY if differs)
• If no embedders are specified, a system-default embedder is attached
• ALREADY_EXISTS: another space exists with identical {owner_id, name} (case-sensitive)
• Validates all embedder IDs exist before creation
• 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_*
• 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 'authorization: Bearer gm_xxx' \\
-d '{
"name": "My Knowledge Base",
"labels": {"org": "acme", "env": "prod"},
"public_read": false
}' \\
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 authorization: Bearer <api-key>

Permissions Required: DISPLAY_SPACE_OWN or DISPLAY_SPACE_ANY (public spaces bypass ownership restrictions)

Summary:

• When public_read=true, any authenticated user can retrieve the space metadata
• Otherwise, requires ownership or DISPLAY_SPACE_ANY permission
• Returns complete space details including all embedder associations

Error Codes:

• UNAUTHENTICATED: missing/invalid auth
• PERMISSION_DENIED: lacks DISPLAY_SPACE_* for private space or owned 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 'authorization: Bearer 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 user with filtering and pagination.

Auth: gRPC metadata authorization: Bearer <api-key>

Permissions Required: LIST_SPACE_OWN or LIST_SPACE_ANY

Request Parameters:

• owner_id (optional, bytes UUID): with LIST_SPACE_ANY and owner_id omitted, returns all visible spaces; otherwise caller-owned
• 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 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 'authorization: Bearer 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, public_read).

Auth: gRPC metadata authorization: Bearer <api-key>

Permissions Required: UPDATE_SPACE_OWN or UPDATE_SPACE_ANY

Summary:

• Only mutable fields can be updated: name, labels, public_read
• 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_*
• 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 'authorization: Bearer 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.

DeleteSpace

Permanently deletes a Space and its associated content.

Auth: gRPC metadata authorization: Bearer <api-key>

Permissions Required: DELETE_SPACE_OWN or DELETE_SPACE_ANY

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_*
• 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 'authorization: Bearer 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, with a default embedder used if none are specified at creation.

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:

• public_read controls access to space metadata and content. When true, the space's metadata (GetSpace) and content (Query) are accessible to any authenticated user. When false, access is restricted by ownership and permissions (e.g., *_SPACE_ANY).
• Space ownership and creator are tracked separately for administrative purposes.

Immutability:

• space_embedders are effectively immutable (no update operations supported)
• owner_id is set at creation and cannot be modified
• 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