Python SDK

Installation

pip install goodmem

Package metadata

To help debug, two package metadata are baked in the SDK package:

• goodmem.__version__ — SDK package version (e.g., '0.1.34')
• goodmem.__based_on_goodmem_commit__ — GoodMem server commit hash this SDK was generated from.

import goodmem
print(goodmem.__version__)                    # '0.1.34'
print(goodmem.__based_on_goodmem_commit__)    # '9cf830ff...'

Clients

The Python SDK offers OpenAI-style API, where any operation can be accessed via client.<namespace>.<method>(...) where client is either a synchronous Goodmem or asynchronous AsyncGoodmem instance.

For example, to create an embedder, in the synchronous way, you do:

from goodmem import Goodmem
client = Goodmem(base_url='http://localhost:8080', api_key='gm_...')
embedder = client.embedders.create(
   display_name='My Embedder',
   model_identifier='text-embedding-3-large', # model registry will auto-fill the provider type, endpoint url, dimensionality, etc. based on the model identifier
   api_key='sk-...', # the api key for the model provider, which is OpenAI in this case
)

In the asynchronous way, you do:

from goodmem import AsyncGoodmem
client = AsyncGoodmem(base_url='http://localhost:8080', api_key='gm_...')
embedder = await client.embedders.create(
   display_name='My Embedder',
   model_identifier='text-embedding-3-large', # model registry will auto-fill the provider type, endpoint url, dimensionality, etc. based on the model identifier
   api_key='sk-...', # the api key for the model provider, which is OpenAI in this case
)

Context manager

You may also instantiate the client as a context manager to ensure the connection pool is closed:

with Goodmem(base_url='http://localhost:8080', api_key='gm_...') as client:
    ...

async with AsyncGoodmem(base_url='http://localhost:8080', api_key='gm_...') as client:
    ...

Constructor options

Goodmem and AsyncGoodmem can be instantiated in two mutually exclusive usage patterns.

Pattern 1 — Simple mode (base_url + api_key):

Goodmem(base_url: str, api_key: str | None = None, *, timeout: float | httpx.Timeout | None = 30.0, verify: bool | str = True, stream_max_line_bytes: int | None = None)
AsyncGoodmem(base_url: str, api_key: str | None = None, *, timeout: float | httpx.Timeout | None = 30.0, verify: bool | str = True, stream_max_line_bytes: int | None = None)

• base_url — Goodmem server's URL, e.g., 'http://localhost:8080' (note: no v1 suffix)
• api_key — Goodmem API key, e.g., 'gm_...'
• timeout — Maximum time to wait for the server to respond; equivalent to httpx.{Client/AsyncClient}.timeout. Defaults to 30.0 seconds. You might want a bigger number because many operations such as memory retrieval with LLM generation (RAG) can take a long time.
• verify — Whether/how to verify the server's TLS certificate; equivalent to httpx.{Client/AsyncClient}.verify. See TLS configuration for more details.

Pattern 2 — http_client mode (http_client):

Goodmem(*, http_client: httpx.Client, stream_max_line_bytes: int | None = None)
AsyncGoodmem(*, http_client: httpx.AsyncClient, stream_max_line_bytes: int | None = None)

Pass a pre-configured httpx.Client or httpx.AsyncClient for full control over transport, auth headers, timeout, and TLS. When using this mode, configure timeout, verify, and headers directly on the httpx client — passing them to Goodmem raises an error.

TLS configuration

GoodMem enables TLS by default. The SDK supports several ways to configure certificate verification depending on your environment.

1. Default — publicly signed certificates

   No extra configuration needed. The SDK uses your system's trusted CA store.

   client = Goodmem(base_url='https://goodmem.example.com', api_key='gm_...')

2. Skip verification

   Disable certificate verification entirely. Useful for quick local testing, but not recommended for production.

   client = Goodmem(base_url='https://localhost:8081', api_key='gm_...', verify=False)

3. Custom CA file — trusts only that CA

   Point verify at your CA's root certificate.

   client = Goodmem(
       base_url='https://localhost:8081',
       api_key='gm_...',
       verify='/path/to/rootCA.pem',
   )

4. Custom CA + system CAs via http_client

   If you need to trust both a custom CA and the default system CAs, build an ssl.SSLContext and pass it through http_client:

   import ssl
   import httpx
   from goodmem import Goodmem
   
   ctx = ssl.create_default_context()          # loads system CAs
   ctx.load_verify_locations('/path/to/rootCA.pem')  # adds your CA
   
   client = Goodmem(
       http_client=httpx.Client(
           base_url='https://localhost:8081',
           headers={'x-api-key': 'gm_...'},
           verify=ctx,
       ),
   )

Namespaces

Common Data Models

Types shared across multiple API namespaces. 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).

AccessPolicyRule

One operation, selector, and optional assigned resource.

• operation (Operation | None) — Protected operation.
• selector (Selector | None) — Resource-selection semantics.
• assigned_resource (AccessPolicyTarget, optional) — Required exactly for EXACT and DIRECT_MEMBERS_OF selectors.

AccessPolicyTarget

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

• kind (ResourceKind | None) — Concrete target kind.
• resource_id (str, optional) — Concrete resource UUID; omitted for the singleton INSTANCE target.

ApiKeyAuth

Configuration for classic API-key authentication.

• inline_secret (str, optional) — Secret stored directly in GoodMem (mutually exclusive with secret_ref)
• secret_ref (SecretReference, optional) — Reference to an external secret manager entry (mutually exclusive with inline_secret)
• header_name (str, optional) — Desired HTTP header to carry the credential (defaults to Authorization)
• prefix (str, optional) — Optional prefix prepended to the secret (e.g., "Bearer ")

ApiKeyAuthorityMode

String enum: "INHERIT_SUBJECT" · "SCOPED"

ApiKeyResponse

API key metadata without sensitive information.

• api_key_id (str) — Unique identifier for the API key.
• subject_principal_id (str) — Principal authenticated by this API key.
• owner_principal_id (str) — Principal that administratively owns this API key.
• authority_mode (ApiKeyAuthorityMode | None) — Immutable authority derivation mode.
• ceiling (list[AccessPolicyRule], optional) — Complete immutable issuance ceiling; omitted only when ceiling_omitted is true.
• ceiling_omitted (bool) — True only when a BASIC list projection intentionally omitted the immutable ceiling.
• key_prefix (str) — First few characters of the key for display/identification purposes.
• status (Optional[Literal['ACTIVE', 'INACTIVE']]) — Compatibility usability status. ACTIVE means USABLE; INACTIVE combines NOT_YET_VALID, EXPIRED, and REVOKED.
• lifecycle_state (Optional[Literal['NOT_YET_VALID', 'USABLE', 'EXPIRED', 'REVOKED']]) — Precise lifecycle state at the response evaluation instant.
• labels (dict[str, str]) — User-defined labels for organization and filtering.
• expires_at (int, optional) — Expiration timestamp in milliseconds since epoch. If not provided, the key does not expire.
• valid_from (int) — Inclusive activation time in milliseconds since epoch.
• revoked_at (int, optional) — Permanent revocation time in milliseconds since epoch.
• revoked_by_id (str, optional) — Exact audit actor UUID that revoked this key.
• last_used_at (int, optional) — Last time this API key was used, in milliseconds since epoch.
• created_at (int) — When the API key was created, in milliseconds since epoch.
• updated_at (int) — When the API key was last updated, in milliseconds since epoch.
• created_by_id (str) — Exact principal or API-key actor that created this API key.
• updated_by_id (str) — Exact principal or API-key actor that last updated this API key.

AsyncPage

Async version of Page. Returned by list methods on AsyncGoodmem. Supports async for item in page to auto-paginate all items, or async for p in page.iter_pages() to iterate page-by-page.

• data (list[T]) — The items in this page.
• next_token (str | None) — Token to fetch the next page, or None if this is the last page.

ChunkingConfiguration

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

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

CredentialKind

String enum: "CREDENTIAL_KIND_UNSPECIFIED" · "CREDENTIAL_KIND_API_KEY" · "CREDENTIAL_KIND_GCP_ADC"

DashScopeApiDialect

String enum: "UNSPECIFIED" · "EMBEDDING_NATIVE_TEXT" · "EMBEDDING_NATIVE_CONTENTS" · "LLM_NATIVE_TEXT" · "LLM_NATIVE_MULTIMODAL" · "RERANK_NATIVE_NESTED" · "OPENAI_COMPATIBLE" · "RERANK_COMPATIBLE_FLAT"

EndpointAuthentication

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

• kind (CredentialKind | None) — Selected credential strategy
• api_key (ApiKeyAuth, optional) — Configuration when kind is CREDENTIAL_KIND_API_KEY
• gcp_adc (GcpAdcAuth, optional) — Configuration when kind is CREDENTIAL_KIND_GCP_ADC
• labels (dict[str, str], optional) — Optional annotations to aid operators (e.g., "owner=vertex")

GcpAdcAuth

Configuration for Google Application Default Credentials (ADC).

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

GoodMemInstance

The singleton GoodMem instance and its ownership audit metadata.

• instance_id (str) — Durable UUID of the singleton GoodMem instance.
• owner_id (str) — Current human owner principal UUID.
• created_at (int) — Initialization timestamp in milliseconds since the Unix epoch.
• updated_at (int) — Most recent ownership-transfer timestamp in milliseconds since the Unix epoch.
• created_by_id (str) — Principal or API-key actor UUID that initialized the instance.
• updated_by_id (str) — Principal or API-key actor UUID that last transferred ownership.

GoodMemStatus

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

• code (Optional[Literal['GOODMEM_STATUS_CODE_UNSPECIFIED', 'INVALID_ARGUMENT', 'NOT_FOUND', 'PERMISSION_DENIED', 'FAILED_PRECONDITION', 'EMBEDDER_FAILED', 'EMBEDDER_UNAVAILABLE', 'EMBEDDER_TIMEOUT', 'VECTOR_SEARCH_FAILED', 'VECTOR_SEARCH_PARTIAL', 'VECTOR_SEARCH_TIMEOUT', 'SPACE_INACCESSIBLE', 'SPACE_NOT_FOUND', 'SPACE_NO_EMBEDDERS', 'CHUNK_NOT_FOUND', 'MEMORY_LOAD_FAILED', 'MEMORY_CONTENT_UNAVAILABLE', 'RERANKING_FAILED', 'SUMMARIZATION_FAILED', 'SUMMARIZATION_TIMEOUT', 'RATE_LIMITED', 'RESOURCE_EXHAUSTED', 'CONFIGURATION_ERROR', 'LLM_CAPABILITY_INFERRED', 'FEATURE_DISABLED']]) — Status code for the warning or informational message
• message (str) — Human-readable status message
• details (dict[str, str], optional) — Additional contextual details

LengthMeasurement

String enum: "CHARACTER_COUNT" · "TOKEN_COUNT" · "CUSTOM"

Modality

String enum: "TEXT" · "IMAGE" · "AUDIO" · "VIDEO"

NoChunkingConfiguration

No chunking strategy - preserves original content as a single unit

No parameters.

Operation

String enum: "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"

Page

A page of results from a list endpoint. The first page is pre-loaded; subsequent pages are fetched lazily. Access .data for items and .next_token to resume. Supports for item in page to auto-paginate through all items, or .iter_pages() to iterate page-by-page.

• data (list[T]) — The items in this page.
• next_token (str | None) — Token to fetch the next page, or None if this is the last page.

ProviderType

String enum: "OPENAI" · "VLLM" · "TEI" · "LLAMA_CPP" · "VOYAGE" · "COHERE" · "JINA" · "DASHSCOPE" · "GEMINI"

RecursiveChunkingConfiguration

Recursive hierarchical chunking strategy with configurable separators and overlap

• chunk_size (int) — Maximum size of a chunk (should be ≤ context window)
• chunk_overlap (int) — Sliding overlap between chunks
• separators (list[str], optional) — Hierarchical separator list (order = preference)
• keep_strategy (SeparatorKeepStrategy | None) — How to handle separators after splitting. KEEP_NONE is deprecated and behaves as KEEP_END.
• separator_is_regex (bool, optional) — Whether separators are regex patterns
• length_measurement (LengthMeasurement | None) — How to measure chunk length

ResourceKind

String enum: "INSTANCE" · "USER" · "SERVICE_IDENTITY" · "SPACE" · "API_KEY" · "EMBEDDER" · "RERANKER" · "LLM" · "MEMORY" · "EXTENSION" · "RETRIEVE_MEMORY_LOG_POLICY"

SecretReference

SecretReference

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

Selector

String enum: "ANY" · "OWN" · "EXACT" · "DIRECT_MEMBERS_OF"

SentenceChunkingConfiguration

Sentence-based chunking strategy with language detection support

• max_chunk_size (int) — Maximum size of a chunk
• min_chunk_size (int) — Minimum size before creating a new chunk
• enable_language_detection (bool, optional) — Whether to detect language for better segmentation
• length_measurement (LengthMeasurement | None) — How to measure chunk length

SeparatorKeepStrategy

String enum: "KEEP_NONE" · "KEEP_START" · "KEEP_END"

SortOrder

String enum: "ASCENDING" · "DESCENDING" · "SORT_ORDER_UNSPECIFIED"

TransferOwnershipRequest

Names the principal that will become the resource owner.

• new_owner_id (str) — Existing principal UUID that will become the new owner.

Errors

All SDK methods raise typed exceptions on HTTP errors. Error class names align with the OpenAI and Anthropic Python SDKs.

from goodmem import Goodmem, NotFoundError, APIError

with Goodmem(base_url='http://localhost:8080', api_key='gm_...') as client:
    try:
        memory = client.memories.get(id='nonexistent-id')
    except NotFoundError:
        print('Memory not found')
    except APIError as e:
        print(f'API error {e.status_code}: {e.body}')

Support

Reach out to [email protected] for any questions or feedback.