Python SDK

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. The signatures below are introspected directly from the SDK source so they always match runtime behavior:

Goodmem(base_url: str, api_key: str, *, timeout: float = 30.0, verify: bool | str = True)

Goodmem(*, http_client: httpx.Client)

Pattern 1 — Simple mode (base_url + api_key):

• 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): 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.

Package metadata

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

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

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

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).

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 ")

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"

EndpointAuthentication

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

• kind (CredentialKind) — 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

GoodMemStatus

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

• code (str) — 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.

Page

An eagerly-fetched page of results from a list endpoint. Access .data for items and .next_token to resume. Supports for item in page to auto-paginate all pages, 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"

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) — 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) — How to measure chunk length

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"})

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) — How to measure chunk length

SeparatorKeepStrategy

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

SortOrder

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

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 forrest@pairsys.ai for any questions or feedback.