Spaces

Methods on this page are called as client.spaces.<method>(...) where client is either a synchronous Goodmem or asynchronous AsyncGoodmem instance initialized below:

from goodmem import Goodmem
client = Goodmem(base_url='http://localhost:8080', api_key='gm_...')

from goodmem import AsyncGoodmem
client = AsyncGoodmem(base_url='http://localhost:8080', api_key='gm_...')

Create a new Space

Creates a new space with the provided name, labels, and embedder configuration. A space is a container for organizing related memories.

OWNER DEFAULTS: Owner defaults to authenticated user unless owner_id is provided (requires CREATE_SPACE_ANY if differs).

EMBEDDER REQUIREMENTS: At least one embedder configuration must be specified.

DUPLICATE DETECTION: Returns ALREADY_EXISTS if another space exists with identical {owner_id, name} (case-sensitive). Requires CREATE_SPACE_OWN permission (or CREATE_SPACE_ANY for admin users). This operation is NOT idempotent.

• name (str) — The desired name for the space. Must be unique within the user's scope.
• space_embedders (list[SpaceEmbedderConfig]) — List of embedder configurations to associate with this space. At least one embedder configuration is required. Each specifies an embedder ID and a relative default retrieval weight used when no per-request overrides are provided.
• default_chunking_config (ChunkingConfiguration, optional, SDK default={"recursive":{"chunkSize":512,"chunkOverlap":64,"keepStrategy":"KEEP_END","lengthMeasurement":"CHARACTER_COUNT"}}) — Default strategy to chunk any memory ingested into this space. Can be overriden by per-memory chunking strategy.
• labels (dict[str, str], optional) — A set of key-value pairs to categorize or tag the space. Used for filtering and organizational purposes.
• owner_id (str, optional) — Optional owner ID. If not provided, derived from the authentication context. Requires CREATE_SPACE_ANY permission if specified.
• public_read (bool, optional, server default=False) — Indicates if the space and its memories can be read by unauthenticated users or users other than the owner. Defaults to false.
• space_id (str, optional) — Optional client-provided UUID for idempotent creation. If not provided, server generates a new UUID. Returns ALREADY_EXISTS if ID is already in use.

space = client.spaces.create(
    name="Doc Space",
    space_embedders=[
        {"embedder_id": "your-embedder-id", "default_retrieval_weight": 1.0},
    ],
    labels={"env": "docs"},
)

Get a space by ID

Retrieves a specific space by its unique identifier. Returns the complete space information, including name, labels, embedder configuration, and metadata.

PUBLIC SPACE ACCESS: When public_read=true, any authenticated user can retrieve the space metadata, bypassing ownership checks. Otherwise, requires ownership or DISPLAY_SPACE_ANY permission. Requires DISPLAY_SPACE_OWN permission for owned spaces (or DISPLAY_SPACE_ANY for admin users to view any space). This is a read-only operation safe to retry.

• id (str) — The unique identifier of the space to retrieve

space = client.spaces.get(id="your-space-id")
print(space.name)

List spaces

List spaces accessible to the caller, with optional filtering by owner, labels, and name. Results are paginated — the returned Page eagerly fetches the first page. Access .data for items and .next_token to resume. Use for space in page to auto-paginate all pages, page_size to control items per API call, and max_items to cap total results.

• label (dict[str, str], optional) — Filter by label key-value pairs. Label filters accept either label.<key>=<value> or label[key]=value (for example, label.environment=production or label[environment]=production).
• max_items (int, optional) — Maximum total number of items to return across all pages.
• name_filter (str, optional) — Filter spaces by name using glob pattern matching.
• next_token (str, optional) — Pagination token for retrieving the next set of results
• owner_id (str, optional) — Filter spaces by owner ID. With LIST_SPACE_ANY permission and owner_id omitted, returns all visible spaces. Otherwise returns caller-owned spaces only. Specifying owner_id without LIST_SPACE_ANY returns PERMISSION_DENIED.
• page_size (int, optional, server default=50) — Number of results per page (defaults to 50, clamped to [1, 1000] by the server).
• sort_by (str, optional, server default='created_time') — Field to sort by: 'created_time', 'updated_time', or 'name' (default: 'created_time'). Unsupported values return INVALID_ARGUMENT.
• sort_order (SortOrder, optional, server default='DESCENDING') — Sort order (ASCENDING or DESCENDING, default: DESCENDING).

# Auto-paginate ALL spaces. Fetches pages behind the scenes until
# exhausted. If you have 100 spaces, this loops 100 times.
for space in client.spaces.list():
    print(space.space_id, space.name)

# Auto-paginate but stop after 2 items total, regardless of how many
# spaces exist. Useful for "give me a few" use cases.
count = 0
for space in client.spaces.list(max_items=2):
    print(space.space_id, space.name)
    count += 1

# Iterate page-by-page instead of item-by-item. Each page has .data
# (list of items) and .next_token. Fetches all pages, 5 items each.
for page in client.spaces.list(page_size=5).iter_pages():
    print(len(page.data), page.next_token)

# Page-by-page with a total cap. Stops yielding pages once 2 items
# have been delivered across all pages.
total = 0
for page in client.spaces.list(max_items=2).iter_pages():
    total += len(page.data)
assert total <= 2

# Get one page, capped at 3 items total. If the server returns more
# than 3 in the first page, .data is truncated to 3.
page = client.spaces.list(max_items=3)
page.data          # [Space, ...] (at most 3)

# Get one page. page_size controls how many items the server returns
# per API call. Fetches 1 page of up to 5 items.
page = client.spaces.list(page_size=5)
page.data          # [Space, ...] (up to 5)
page.next_token    # "abc123" or None

# page_size and max_items do different things:
#   page_size=2  -> fetch 2 items per API call (batch size)
#   max_items=5  -> stop after 5 items total (cap)
# This makes up to 3 API calls (2+2+1) and yields at most 5 spaces.
count = 0
for space in client.spaces.list(page_size=2, max_items=5):
    print(space.space_id, space.name)
    count += 1

# Save the token from the first page, then resume later.
# Fetches all remaining spaces from that point.
page = client.spaces.list(page_size=1)
saved_token = page.next_token
if saved_token:
    for space in client.spaces.list(next_token=saved_token):
        print(space.name)

# Resume from a saved token but only fetch up to 10 more items.
page = client.spaces.list(page_size=1)
saved_token = page.next_token
if saved_token:
    resumed = list(client.spaces.list(
        next_token=saved_token, max_items=10
    ))

Update a space

Updates an existing space with new values for the specified fields. Only name, public_read, and labels can be updated. Fields not included in the request remain unchanged.

IMMUTABLE FIELDS: space_embedders, default_chunking_config, and owner_id cannot be modified after creation.

NAME UNIQUENESS: Name must be unique per owner - returns ALREADY_EXISTS if name conflicts with existing space. Requires UPDATE_SPACE_OWN permission for spaces you own (or UPDATE_SPACE_ANY for admin users). This operation is idempotent.

• id (str) — The unique identifier of the resource to update.
• request (UpdateSpaceRequest | dict) — The update payload. Accepts a UpdateSpaceRequest instance or a plain dict with the same fields. Only specified fields will be modified.

from goodmem.types import UpdateSpaceRequest
# Option 1: typed request object
updated = client.spaces.update(id="your-space-id", request=UpdateSpaceRequest(
    name="Doc Space (updated)",
    merge_labels={"version": "2"},
))
assert updated.space_id == "your-space-id"
# Option 2: plain dict (validated via pydantic)
updated = client.spaces.update(id="your-space-id", request={
    "name": "Doc Space (updated)",
    "merge_labels": {"version": "2"},
})
assert updated.space_id == "your-space-id"

Delete a space

Permanently deletes a space and all associated content. This operation cannot be undone.

CASCADE DELETION: Removes the space record and cascades deletion to associated memories, chunks, and embedder associations. Requires DELETE_SPACE_OWN permission for spaces you own (or DELETE_SPACE_ANY for admin users). This operation is safe to retry - may return NOT_FOUND if already deleted.

• id (str) — The unique identifier of the space to delete

client.spaces.delete(id="your-space-id")

Async usage: client.spaces exposes the same methods on AsyncGoodmem; use await / async for as needed.

Data Models

All data models are pydantic v2 models. Fields are shown with their Python attribute names; JSON responses use camelCase aliases (e.g., owner_id → ownerId).

SpaceEmbedderConfig

Configuration for associating an embedder with a space.

• embedder_id (str) — The UUID for the embedder to associate with the space.
• default_retrieval_weight (float, optional) — Relative weight for this embedder used by default during retrieval. If omitted, defaults to 1.0; values need not sum to 1 and can be overridden per request.

Space

A Space is a container for organizing related memories with vector embeddings.

• space_id (str) — The UUID for this space.
• name (str) — The name of the space.
• labels (dict[str, str]) — Key-value pairs of metadata associated with the space.
• space_embedders (list[SpaceEmbedder]) — The list of embedders associated with this space.
• created_at (int) — Timestamp when this space was created (milliseconds since epoch).
• updated_at (int) — Timestamp when this space was last updated (milliseconds since epoch).
• owner_id (str) — The ID of the user who owns this space.
• created_by_id (str) — The ID of the user who created this space.
• updated_by_id (str) — The ID of the user who last updated this space.
• public_read (bool) — Whether this space is publicly readable by all users.
• default_chunking_config (ChunkingConfiguration, optional) — Default chunking strategy for memories in this space

SpaceEmbedder

Associates an embedder with a space, including retrieval configuration.

• space_id (str) — The UUID for the space.
• embedder_id (str) — The UUID for the embedder.
• default_retrieval_weight (float) — The default weight for this embedder during retrieval operations.
• created_at (int) — Timestamp when this association was created (milliseconds since epoch).
• updated_at (int) — Timestamp when this association was last updated (milliseconds since epoch).
• created_by_id (str) — The ID of the user who created this association.
• updated_by_id (str) — The ID of the user who last updated this association.

ListSpacesResponse

Response containing a list of spaces and optional pagination token.

• spaces (list[Space]) — The list of spaces matching the query criteria.
• next_token (str, optional) — Pagination token for retrieving the next set of results. Only present if there are more results available.

UpdateSpaceRequest

Request parameters for updating a space.

• name (str, optional) — The new name for the space.
• public_read (bool, optional) — Whether the space is publicly readable by all users.
• replace_labels (dict[str, str], optional) — Labels to replace all existing labels. Mutually exclusive with merge_labels.
• merge_labels (dict[str, str], optional) — Labels to merge with existing labels. Mutually exclusive with replace_labels.