GoodMemGoodMem
ReferenceSdkV2Go

Spaces

package goodmem // import "fury.io/pairsys/goodmem"

Memory space management — the top-level container for memories.

Methods are called as client.Spaces().<Method>(ctx, ...) on a *goodmem.Client. Service: SpacesService.

Index

type SpacesService

type SpacesService struct{ … }

Access this service as client.Spaces() on a *goodmem.Client. Its methods follow.

func (s *SpacesService) Create

func (s *SpacesService) Create(ctx context.Context, req *models.SpaceCreationRequest) (*models.Space, error)

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 ownerId 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 {ownerId, name} (case-sensitive). Requires CREATE_SPACE_OWN permission (or CREATE_SPACE_ANY for admin users). This operation is NOT idempotent.

HTTP — POST /v1/spaces

Parameters

  • ctx (context.Context) — carries the deadline and cancellation signal for the call.
  • req (*models.SpaceCreationRequest) — the request payload. The linked type documents every field and its JSON wire name.

Returns — (*models.Space, error)

Example

space, err := client.Spaces().Create(ctx, &models.SpaceCreationRequest{
	Name: "Doc Space",
	SpaceEmbedders: []models.SpaceEmbedderConfig{
		{EmbedderID: "your-embedder-id", DefaultRetrievalWeight: goodmem.Ptr(1.0)},
	},
	Labels: map[string]string{"env": "docs"},
})
if err != nil {
	log.Fatal(err)
}
_ = space

func (s *SpacesService) Get

func (s *SpacesService) Get(ctx context.Context, id string) (*models.Space, error)

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.

HTTP — GET /v1/spaces/&#123;id&#125;

Parameters

  • ctx (context.Context) — carries the deadline and cancellation signal for the call.
  • id (string) — The unique identifier of the space to retrieve

Returns — (*models.Space, error)

Example

space, err := client.Spaces().Get(ctx, "your-space-id")
if err != nil {
	log.Fatal(err)
}
_ = space.Name

func (s *SpacesService) List

func (s *SpacesService) List(ctx context.Context, params *SpacesListParams) (*Page[models.Space], error)

List spaces accessible to the caller, with optional filtering by owner, labels, and name. Results are paginated; pass the response's nextToken back as a query parameter to fetch subsequent pages.

HTTP — GET /v1/spaces

Parameters

  • ctx (context.Context) — carries the deadline and cancellation signal for the call.
  • params (*SpacesListParams, optional) — typed query parameters; pass nil for an empty filter set. The linked pkg.go.dev page lists every field.

Returns — (*Page[models.Space], error)

Examples

Example 1:

// Auto-paginate ALL spaces, fetching pages on demand.
page, err := client.Spaces().List(ctx, nil)
if err != nil {
	log.Fatal(err)
}
for space, err := range page.All(ctx) {
	if err != nil {
		log.Fatal(err)
	}
	_ = space.SpaceID
	_ = space.Name
}

Example 2:

// Auto-paginate but stop after 2 items total.
page, err := client.Spaces().List(ctx, nil)
if err != nil {
	log.Fatal(err)
}
count := 0
for space, err := range page.All(ctx) {
	if err != nil {
		log.Fatal(err)
	}
	if count >= 2 {
		break
	}
	_ = space.SpaceID
	count++
}

Example 3:

// Iterate page-by-page instead of item-by-item.
page, err := client.Spaces().List(ctx, &goodmem.SpacesListParams{MaxResults: goodmem.Ptr(int32(5))})
if err != nil {
	log.Fatal(err)
}
for page != nil {
	_ = len(page.Items())
	_ = page.NextToken()
	page, err = page.Next(ctx)
	if err != nil {
		log.Fatal(err)
	}
}

Example 4:

// Page-by-page with a total cap across all pages.
page, err := client.Spaces().List(ctx, &goodmem.SpacesListParams{MaxResults: goodmem.Ptr(int32(2))})
if err != nil {
	log.Fatal(err)
}
total := 0
for page != nil && total < 2 {
	total += len(page.Items())
	page, err = page.Next(ctx)
	if err != nil {
		log.Fatal(err)
	}
}

Example 5:

// Cap the number of items you consume, regardless of page size.
page, err := client.Spaces().List(ctx, nil)
if err != nil {
	log.Fatal(err)
}
var spaces []models.Space
for space, err := range page.All(ctx) {
	if err != nil {
		log.Fatal(err)
	}
	if len(spaces) >= 3 {
		break
	}
	spaces = append(spaces, space)
}

Example 6:

// One page. MaxResults controls how many items the server returns per
// API call.
page, err := client.Spaces().List(ctx, &goodmem.SpacesListParams{MaxResults: goodmem.Ptr(int32(5))})
if err != nil {
	log.Fatal(err)
}
_ = page.Items()     // up to 5 spaces
_ = page.NextToken() // "" when there are no more

Example 7:

// MaxResults (server batch size) and a client-side cap do different
// things: fetch 2 per call, stop after 5 total.
page, err := client.Spaces().List(ctx, &goodmem.SpacesListParams{MaxResults: goodmem.Ptr(int32(2))})
if err != nil {
	log.Fatal(err)
}
count := 0
for space, err := range page.All(ctx) {
	if err != nil {
		log.Fatal(err)
	}
	if count >= 5 {
		break
	}
	_ = space.SpaceID
	count++
}

Example 8:

// Save the token from the first page, then resume later.
page, err := client.Spaces().List(ctx, &goodmem.SpacesListParams{MaxResults: goodmem.Ptr(int32(1))})
if err != nil {
	log.Fatal(err)
}
savedToken := page.NextToken()
if savedToken != "" {
	resumed, err := client.Spaces().List(ctx, &goodmem.SpacesListParams{NextToken: goodmem.Ptr(savedToken)})
	if err != nil {
		log.Fatal(err)
	}
	for space, err := range resumed.All(ctx) {
		if err != nil {
			log.Fatal(err)
		}
		_ = space.Name
	}
}

Example 9:

// Resume from a saved token but only consume up to 10 more items.
page, err := client.Spaces().List(ctx, &goodmem.SpacesListParams{MaxResults: goodmem.Ptr(int32(1))})
if err != nil {
	log.Fatal(err)
}
savedToken := page.NextToken()
if savedToken != "" {
	resumed, err := client.Spaces().List(ctx, &goodmem.SpacesListParams{NextToken: goodmem.Ptr(savedToken)})
	if err != nil {
		log.Fatal(err)
	}
	n := 0
	for _, err := range resumed.All(ctx) {
		if err != nil {
			log.Fatal(err)
		}
		if n >= 10 {
			break
		}
		n++
	}
}

func (s *SpacesService) Update

func (s *SpacesService) Update(ctx context.Context, id string, req *models.UpdateSpaceRequest) (*models.Space, error)

Updates an existing space with new values for the specified fields. Only name, publicRead, and labels can be updated. Fields not included in the request remain unchanged. IMMUTABLE FIELDS: space_embedders, default_chunking_config, and ownerId 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.

HTTP — PUT /v1/spaces/&#123;id&#125;

Parameters

  • ctx (context.Context) — carries the deadline and cancellation signal for the call.
  • id (string) — The unique identifier of the space to update
  • req (*models.UpdateSpaceRequest) — the request payload. The linked type documents every field and its JSON wire name.

Returns — (*models.Space, error)

Example

updated, err := client.Spaces().Update(ctx, "your-space-id", &models.UpdateSpaceRequest{
	Name:        goodmem.Ptr("Doc Space (updated)"),
	MergeLabels: map[string]string{"version": "2"},
})
if err != nil {
	log.Fatal(err)
}
_ = updated.SpaceID

func (s *SpacesService) Delete

func (s *SpacesService) Delete(ctx context.Context, id string) error

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.

HTTP — DELETE /v1/spaces/&#123;id&#125;

Parameters

  • ctx (context.Context) — carries the deadline and cancellation signal for the call.
  • id (string) — The unique identifier of the space to delete

Returns — error — nil on success.

Example

err := client.Spaces().Delete(ctx, "your-space-id")
if err != nil {
	log.Fatal(err)
}

type SpaceCreationRequest

type SpaceCreationRequest struct{ … }

Request body for creating a new Space. A Space is a container for organizing related memories with vector embeddings.

  • Name (string, wire name) — The desired name for the space. Must be unique within the user's scope.
  • Labels (map[string]string, optional, wire labels) — A set of key-value pairs to categorize or tag the space. Used for filtering and organizational purposes.
  • SpaceEmbedders ([]models.SpaceEmbedderConfig, wire spaceEmbedders) — 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.
  • PublicRead (bool, optional, wire publicRead) — Indicates if the space and its memories can be read by unauthenticated users or users other than the owner. Defaults to false.
  • OwnerID (string, optional, wire ownerId) — Optional owner ID. If not provided, derived from the authentication context. Requires CREATE_SPACE_ANY permission if specified.
  • DefaultChunkingConfig (models.ChunkingConfiguration, wire defaultChunkingConfig) — Default chunking strategy for memories in this space
  • SpaceID (string, optional, wire spaceId) — Optional client-provided UUID for idempotent creation. If not provided, server generates a new UUID. Returns ALREADY_EXISTS if ID is already in use.

type SpaceEmbedderConfig

type SpaceEmbedderConfig struct{ … }

Configuration for associating an embedder with a space.

  • EmbedderID (string, wire embedderId) — The UUID for the embedder to associate with the space.
  • DefaultRetrievalWeight (float64, optional, wire defaultRetrievalWeight) — 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.

type Space

type Space struct{ … }

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

  • SpaceID (string, wire spaceId) — The UUID for this space.
  • Name (string, wire name) — The name of the space.
  • Labels (map[string]string, wire labels) — Key-value pairs of metadata associated with the space.
  • SpaceEmbedders ([]models.SpaceEmbedder, wire spaceEmbedders) — The list of embedders associated with this space.
  • CreatedAt (int64, wire createdAt) — Timestamp when this space was created (milliseconds since epoch).
  • UpdatedAt (int64, wire updatedAt) — Timestamp when this space was last updated (milliseconds since epoch).
  • OwnerID (string, wire ownerId) — The ID of the user who owns this space.
  • CreatedByID (string, wire createdById) — The ID of the user who created this space.
  • UpdatedByID (string, wire updatedById) — The ID of the user who last updated this space.
  • PublicRead (bool, wire publicRead) — Whether this space is publicly readable by all users.
  • DefaultChunkingConfig (models.ChunkingConfiguration, optional, wire defaultChunkingConfig) — Default chunking strategy for memories in this space

type SpaceEmbedder

type SpaceEmbedder struct{ … }

Associates an embedder with a space, including retrieval configuration.

  • SpaceID (string, wire spaceId) — The UUID for the space.
  • EmbedderID (string, wire embedderId) — The UUID for the embedder.
  • DefaultRetrievalWeight (float64, wire defaultRetrievalWeight) — The default weight for this embedder during retrieval operations.
  • CreatedAt (int64, wire createdAt) — Timestamp when this association was created (milliseconds since epoch).
  • UpdatedAt (int64, wire updatedAt) — Timestamp when this association was last updated (milliseconds since epoch).
  • CreatedByID (string, wire createdById) — The ID of the user who created this association.
  • UpdatedByID (string, wire updatedById) — The ID of the user who last updated this association.

type ListSpacesResponse

type ListSpacesResponse struct{ … }

Response containing a list of spaces and optional pagination token.

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

type UpdateSpaceRequest

type UpdateSpaceRequest struct{ … }

Request parameters for updating a space.

  • Name (string, optional, wire name) — The new name for the space.
  • PublicRead (bool, optional, wire publicRead) — Whether the space is publicly readable by all users.
  • ReplaceLabels (map[string]string, optional, wire replaceLabels) — Labels to replace all existing labels. Mutually exclusive with mergeLabels.
  • MergeLabels (map[string]string, optional, wire mergeLabels) — Labels to merge with existing labels. Mutually exclusive with replaceLabels.

On this page

Indextype SpacesServicefunc (s *SpacesService) Createfunc (s *SpacesService) Getfunc (s *SpacesService) Listfunc (s *SpacesService) Updatefunc (s *SpacesService) Deletetype SpaceCreationRequesttype SpaceEmbedderConfigtype Spacetype SpaceEmbeddertype ListSpacesResponsetype UpdateSpaceRequest