Go SDK

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

The GoodMem Go SDK offers an OpenAI-style API where any operation is accessed through client.<Namespace>().<Method>(ctx, ...) on a *goodmem.Client. It is synchronous and context.Context-driven — there is no async surface; cancellation and deadlines come from the context you pass in.

Installation

The SDK is distributed through GoodMem's public Gemfury Go module proxy — no account or token required. Point Go at the proxy once, then install as usual:

# One-time setup: resolve fury.io/pairsys/* through GoodMem's public proxy
# (the default proxy stays as the fallback for your other dependencies), and
# skip the public checksum database for that path only.
go env -w GOPROXY="https://go-proxy.fury.io/pairsys/,https://proxy.golang.org,direct"
go env -w GONOSUMDB="fury.io/pairsys/*"

# Install
go get fury.io/pairsys/goodmem@latest

import (
    goodmem "fury.io/pairsys/goodmem"
    "fury.io/pairsys/goodmem/models"
)

Do not set GOPRIVATE or GONOPROXY for fury.io/pairsys/* — those tell Go to bypass the proxy and fetch the module directly, which fails. The package is public and is served through the proxy.

Requirements: Go 1.23+. The SDK depends only on the standard library.

Client

The Go SDK ships a single synchronous *goodmem.Client. Every method takes a context.Context and returns a typed response plus an error. A Client is safe for concurrent use by multiple goroutines.

Construction

client, err := goodmem.New("http://localhost:8080", "gm_...")
if err != nil {
    log.Fatal(err)
}

• The base URL may carry a mount-path prefix (e.g. https://host/api) — it is preserved on every request.
• An empty API key is allowed (the unauthenticated bootstrap endpoints /v1/system/info and /v1/system/init are callable without one); every other endpoint returns 401 from the server.

To supply your own *http.Client (interceptors, proxy, custom TLS, connection pool tuning), use the WithHTTPClient option:

client, err := goodmem.New("http://localhost:8080", "gm_...",
    goodmem.WithHTTPClient(myHTTPClient))

In bring-your-own mode you own the redirect policy; the SDK-built default refuses to follow redirects so the x-api-key header cannot leak across a host boundary.

Quickstart

package main

import (
    "context"
    "log"

    goodmem "fury.io/pairsys/goodmem"
    "fury.io/pairsys/goodmem/models"
)

func main() {
    ctx := context.Background()
    client, err := goodmem.New("http://localhost:8080", "gm_...")
    if err != nil {
        log.Fatal(err)
    }

    // Create an embedder. The registry auto-fills provider, endpoint and
    // dimensionality from the model identifier; the bare apiKey is converted
    // to structured credentials.
    embedder, err := client.Embedders().Create(ctx, &models.EmbedderCreationRequest{
        DisplayName:     "My OpenAI",
        ModelIdentifier: "text-embedding-3-large",
    }, "sk-...")
    if err != nil {
        log.Fatal(err)
    }
    _ = embedder
}

Pagination

List methods that page return a *Page[T]. Range over All(ctx) to walk every item across pages transparently, or drive the cursor yourself with Items(), NextToken(), HasMore() and Next(ctx).

page, err := client.Memories().List(ctx, spaceID, nil)
if err != nil {
    log.Fatal(err)
}
for memory, err := range page.All(ctx) {
    if err != nil {
        log.Fatal(err)
    }
    _ = memory
}

Streaming

Streaming methods return a *Stream[T]. Range over Events() and always Close() the stream when done.

stream, err := client.Memories().Retrieve(ctx, "What do you know about ...?", nil)
if err != nil {
    log.Fatal(err)
}
defer stream.Close()
for event, err := range stream.Events() {
    if err != nil {
        log.Fatal(err)
    }
    _ = event
}

Errors

Every method returns a typed error on failure. Transport problems come back as *goodmem.NetworkError; non-2xx HTTP responses come back as an *goodmem.APIError (or one of its status-specific subtypes). Branch with errors.As (from the standard-library errors package):

resp, err := client.Spaces().Get(ctx, spaceID)
if err != nil {
    var notFound *goodmem.NotFoundError
    if errors.As(err, &notFound) {
        // 404 — handle missing space
    }
    var apiErr *goodmem.APIError
    if errors.As(err, &apiErr) {
        log.Printf("server returned %d: %s", apiErr.StatusCode, apiErr.Message)
    }
    log.Fatal(err)
}
_ = resp

The status-specific subtypes are *BadRequestError (400), *AuthenticationError (401), *PermissionDeniedError (403), *NotFoundError (404), *ConflictError (409), *UnprocessableEntityError (422), *RateLimitError (429) and *InternalServerError (5xx). All wrap *APIError, so an errors.As against *APIError matches any of them.

Namespaces

API reference

Every method — signature, parameters, return type, a runnable example and the REST equivalent — is documented on the per-namespace pages listed under Namespaces, together with the wire types only that namespace uses. Types shared between namespaces are documented below. The module is published from Gemfury (fury.io/pairsys/goodmem); there is no pkg.go.dev listing.

Common Data Models

Wire types shared across namespaces, with every field, its Go type and JSON wire name.

Index

• type ProviderType
• type Modality
• type EndpointAuthentication
• type DashScopeApiDialect
• type CredentialKind
• type ApiKeyAuth
• type GcpAdcAuth
• type SecretReference
• type GoodMemStatus
• type ChunkingConfiguration
• type NoChunkingConfiguration
• type RecursiveChunkingConfiguration
• type SentenceChunkingConfiguration
• type SeparatorKeepStrategy
• type LengthMeasurement
• type SortOrder
• type TransferOwnershipRequest
• type GoodMemInstance
• type ApiKeyResponse
• type ApiKeyAuthorityMode
• type AccessPolicyRule
• type Operation
• type Selector
• type AccessPolicyTarget
• type ResourceKind

type ProviderType

type ProviderType string

Embedding provider types

String enum (type ProviderType string): "OPENAI" · "VLLM" · "TEI" · "LLAMA_CPP" · "VOYAGE" · "COHERE" · "JINA" · "DASHSCOPE" · "GEMINI"

type Modality

type Modality string

Content modality types supported by embedders

String enum (type Modality string): "TEXT" · "IMAGE" · "AUDIO" · "VIDEO"

type EndpointAuthentication

type EndpointAuthentication struct{ … }

Structured credential payload describing how GoodMem should authenticate with an upstream provider.

• Kind (models.CredentialKind, wire kind) — Selected credential strategy
• APIKey (models.ApiKeyAuth, optional, wire apiKey) — Configuration when kind is CREDENTIAL_KIND_API_KEY
• GCPADC (models.GcpAdcAuth, optional, wire gcpAdc) — Configuration when kind is CREDENTIAL_KIND_GCP_ADC
• Labels (map[string]string, optional, wire labels) — Optional annotations to aid operators (e.g., "owner=vertex")

type DashScopeApiDialect

type DashScopeApiDialect string

DashScope request and response API dialect

String enum (type DashScopeApiDialect string): "UNSPECIFIED" · "EMBEDDING_NATIVE_TEXT" · "EMBEDDING_NATIVE_CONTENTS" · "LLM_NATIVE_TEXT" · "LLM_NATIVE_MULTIMODAL" · "RERANK_NATIVE_NESTED" · "OPENAI_COMPATIBLE" · "RERANK_COMPATIBLE_FLAT"

type CredentialKind

type CredentialKind string

Credential kinds supported for upstream endpoint authentication.

String enum (type CredentialKind string): "CREDENTIAL_KIND_UNSPECIFIED" · "CREDENTIAL_KIND_API_KEY" · "CREDENTIAL_KIND_GCP_ADC"

type ApiKeyAuth

type ApiKeyAuth struct{ … }

Configuration for classic API-key authentication.

• InlineSecret (string, optional, wire inlineSecret) — Secret stored directly in GoodMem (mutually exclusive with secretRef)
• SecretRef (models.SecretReference, optional, wire secretRef) — Reference to an external secret manager entry (mutually exclusive with inlineSecret)
• HeaderName (string, optional, wire headerName) — Desired HTTP header to carry the credential (defaults to Authorization)
• Prefix (string, optional, wire prefix) — Optional prefix prepended to the secret (e.g., "Bearer ")

type GcpAdcAuth

type GcpAdcAuth struct{ … }

Configuration for Google Application Default Credentials (ADC).

• Scopes ([]string, optional, wire scopes) — Additional OAuth scopes. Empty list falls back to the default cloud-platform scope.
• QuotaProjectID (string, optional, wire quotaProjectId) — Optional quota project used for billing

type SecretReference

type SecretReference struct{ … }

• URI (string, wire uri) — URI identifying where the secret can be resolved (e.g., vault://, env://)
• Hints (map[string]string, optional, wire hints) — Optional metadata to help resolvers decode the secret (e.g., {"encoding":"base64"})

type GoodMemStatus

type GoodMemStatus struct{ … }

Warning or non-fatal status with granular codes (operation continues)

• Code (string, wire code) — Status code for the warning or informational message
• Message (string, wire message) — Human-readable status message
• Details (map[string]string, optional, wire details) — Additional contextual details

type ChunkingConfiguration

type ChunkingConfiguration struct{ … }

Configuration for text chunking strategy used when processing content. Exactly one of none, recursive, or sentence must be provided.

• None (models.NoChunkingConfiguration, optional, wire none) — No chunking strategy - preserve original content as single unit
• Recursive (models.RecursiveChunkingConfiguration, optional, wire recursive) — Recursive hierarchical chunking strategy with configurable separators
• Sentence (models.SentenceChunkingConfiguration, optional, wire sentence) — Sentence-based chunking strategy with language detection

type NoChunkingConfiguration

type NoChunkingConfiguration struct{ … }

No chunking strategy - preserves original content as a single unit

(no exported fields)

type RecursiveChunkingConfiguration

type RecursiveChunkingConfiguration struct{ … }

Recursive hierarchical chunking strategy with configurable separators and overlap

• ChunkSize (int32, wire chunkSize) — Maximum size of a chunk (should be ≤ context window)
• ChunkOverlap (int32, wire chunkOverlap) — Sliding overlap between chunks
• Separators ([]string, optional, wire separators) — Hierarchical separator list (order = preference)
• KeepStrategy (models.SeparatorKeepStrategy, wire keepStrategy) — How to handle separators after splitting. KEEP_NONE is deprecated and behaves as KEEP_END.
• SeparatorIsRegex (bool, optional, wire separatorIsRegex) — Whether separators are regex patterns
• LengthMeasurement (models.LengthMeasurement, wire lengthMeasurement) — How to measure chunk length

type SentenceChunkingConfiguration

type SentenceChunkingConfiguration struct{ … }

Sentence-based chunking strategy with language detection support

• MaxChunkSize (int32, wire maxChunkSize) — Maximum size of a chunk
• MinChunkSize (int32, wire minChunkSize) — Minimum size before creating a new chunk
• EnableLanguageDetection (bool, optional, wire enableLanguageDetection) — Whether to detect language for better segmentation
• LengthMeasurement (models.LengthMeasurement, wire lengthMeasurement) — How to measure chunk length

type SeparatorKeepStrategy

type SeparatorKeepStrategy string

Strategy for handling separators after text splitting. KEEP_NONE is deprecated and treated as KEEP_END.

String enum (type SeparatorKeepStrategy string): "KEEP_NONE" · "KEEP_START" · "KEEP_END"

type LengthMeasurement

type LengthMeasurement string

Strategy for measuring chunk length during text splitting

String enum (type LengthMeasurement string): "CHARACTER_COUNT" · "TOKEN_COUNT" · "CUSTOM"

type SortOrder

type SortOrder string

String enum (type SortOrder string): "ASCENDING" · "DESCENDING" · "SORT_ORDER_UNSPECIFIED"

type TransferOwnershipRequest

type TransferOwnershipRequest struct{ … }

Names the principal that will become the resource owner.

• NewOwnerID (string, wire newOwnerId) — Existing principal UUID that will become the new owner.

type GoodMemInstance

type GoodMemInstance struct{ … }

The singleton GoodMem instance and its ownership audit metadata.

• InstanceID (string, wire instanceId) — Durable UUID of the singleton GoodMem instance.
• OwnerID (string, wire ownerId) — Current human owner principal UUID.
• CreatedAt (int64, wire createdAt) — Initialization timestamp in milliseconds since the Unix epoch.
• UpdatedAt (int64, wire updatedAt) — Most recent ownership-transfer timestamp in milliseconds since the Unix epoch.
• CreatedByID (string, wire createdById) — Principal or API-key actor UUID that initialized the instance.
• UpdatedByID (string, wire updatedById) — Principal or API-key actor UUID that last transferred ownership.

type ApiKeyResponse

type ApiKeyResponse struct{ … }

API key metadata without sensitive information.

• APIKeyID (string, wire apiKeyId) — Unique identifier for the API key.
• SubjectPrincipalID (string, wire subjectPrincipalId) — Principal authenticated by this API key.
• OwnerPrincipalID (string, wire ownerPrincipalId) — Principal that administratively owns this API key.
• AuthorityMode (models.ApiKeyAuthorityMode, wire authorityMode) — Immutable authority derivation mode.
• Ceiling ([]models.AccessPolicyRule, optional, wire ceiling) — Complete immutable issuance ceiling; omitted only when ceilingOmitted is true.
• CeilingOmitted (bool, wire ceilingOmitted) — True only when a BASIC list projection intentionally omitted the immutable ceiling.
• KeyPrefix (string, wire keyPrefix) — First few characters of the key for display/identification purposes.
• Status (string, wire status) — Compatibility usability status. ACTIVE means USABLE; INACTIVE combines NOT_YET_VALID, EXPIRED, and REVOKED.
• LifecycleState (string, wire lifecycleState) — Precise lifecycle state at the response evaluation instant.
• Labels (map[string]string, wire labels) — User-defined labels for organization and filtering.
• ExpiresAt (int64, optional, wire expiresAt) — Expiration timestamp in milliseconds since epoch. If not provided, the key does not expire.
• ValidFrom (int64, wire validFrom) — Inclusive activation time in milliseconds since epoch.
• RevokedAt (int64, optional, wire revokedAt) — Permanent revocation time in milliseconds since epoch.
• RevokedByID (string, optional, wire revokedById) — Exact audit actor UUID that revoked this key.
• LastUsedAt (int64, optional, wire lastUsedAt) — Last time this API key was used, in milliseconds since epoch.
• CreatedAt (int64, wire createdAt) — When the API key was created, in milliseconds since epoch.
• UpdatedAt (int64, wire updatedAt) — When the API key was last updated, in milliseconds since epoch.
• CreatedByID (string, wire createdById) — Exact principal or API-key actor that created this API key.
• UpdatedByID (string, wire updatedById) — Exact principal or API-key actor that last updated this API key.

type ApiKeyAuthorityMode

type ApiKeyAuthorityMode string

INHERIT_SUBJECT follows a human subject's live authority. SCOPED intersects the subject's live authority with an immutable, nonempty issuance ceiling.

String enum (type ApiKeyAuthorityMode string): "INHERIT_SUBJECT" · "SCOPED"

type AccessPolicyRule

type AccessPolicyRule struct{ … }

One operation, selector, and optional assigned resource.

• Operation (models.Operation, wire operation) — Protected operation.
• Selector (models.Selector, wire selector) — Resource-selection semantics.
• AssignedResource (models.AccessPolicyTarget, optional, wire assignedResource) — Required exactly for EXACT and DIRECT_MEMBERS_OF selectors.

type Operation

type Operation string

String enum (type Operation string): "CREATE_USER" · "READ_USER" · "UPDATE_USER" · "DELETE_USER" · "LIST_USER" · "MANAGE_USER_ENROLLMENT" · "CREATE_SERVICE_IDENTITY" · "READ_SERVICE_IDENTITY" · "UPDATE_SERVICE_IDENTITY" · "DELETE_SERVICE_IDENTITY" · "LIST_SERVICE_IDENTITY" · "CREATE_SPACE" · "READ_SPACE" · "UPDATE_SPACE" · "DELETE_SPACE" · "LIST_SPACE" · "CREATE_API_KEY" · "READ_API_KEY" · "UPDATE_API_KEY" · "DELETE_API_KEY" · "LIST_API_KEY" · "CREATE_EMBEDDER" · "READ_EMBEDDER" · "UPDATE_EMBEDDER" · "DELETE_EMBEDDER" · "LIST_EMBEDDER" · "PING_EMBEDDER" · "EXECUTE_EMBEDDER" · "READ_EMBEDDER_CREDENTIALS" · "CREATE_RERANKER" · "READ_RERANKER" · "UPDATE_RERANKER" · "DELETE_RERANKER" · "LIST_RERANKER" · "PING_RERANKER" · "EXECUTE_RERANKER" · "READ_RERANKER_CREDENTIALS" · "CREATE_LLM" · "READ_LLM" · "UPDATE_LLM" · "DELETE_LLM" · "LIST_LLM" · "PING_LLM" · "EXECUTE_LLM" · "READ_LLM_CREDENTIALS" · "PROXY_INFERENCE_TARGET" · "OCR_DOCUMENT" · "CREATE_MEMORY" · "READ_MEMORY" · "DELETE_MEMORY" · "LIST_MEMORY" · "CREATE_EXTENSION" · "READ_EXTENSION" · "UPDATE_EXTENSION" · "DELETE_EXTENSION" · "LIST_EXTENSION" · "DOWNLOAD_EXTENSION" · "READ_INSTANCE" · "TRANSFER_INSTANCE_OWNERSHIP" · "TRANSFER_RESOURCE_OWNERSHIP" · "RELOAD_LICENSE" · "DRAIN_SERVER" · "PURGE_BACKGROUND_JOBS" · "CREATE_RETRIEVE_MEMORY_LOG_POLICY" · "READ_RETRIEVE_MEMORY_LOG_POLICY" · "LIST_RETRIEVE_MEMORY_LOG_POLICY" · "DELETE_RETRIEVE_MEMORY_LOG_POLICY" · "MANAGE_ACCESS"

type Selector

type Selector string

String enum (type Selector string): "ANY" · "OWN" · "EXACT" · "DIRECT_MEMBERS_OF"

type AccessPolicyTarget

type AccessPolicyTarget struct{ … }

A typed access-policy target. resourceId is omitted for INSTANCE and required otherwise.

• Kind (models.ResourceKind, wire kind) — Concrete target kind.
• ResourceID (string, optional, wire resourceId) — Concrete resource UUID; omitted for the singleton INSTANCE target.

type ResourceKind

type ResourceKind string

String enum (type ResourceKind string): "INSTANCE" · "USER" · "SERVICE_IDENTITY" · "SPACE" · "API_KEY" · "EMBEDDER" · "RERANKER" · "LLM" · "MEMORY" · "EXTENSION" · "RETRIEVE_MEMORY_LOG_POLICY"

Support

File issues against the GoodMem repository. The Go SDK is generated from the same universal API IR (api_ir.json) that drives the Python, Java and MCP SDKs, so the wire contract is identical across every language.