goodmem-client 1.5.13

API for interacting with the GoodMem service, providing vector-based memory storage and retrieval with multiple embedder support.

goodmem-client

Python client for GoodMem - a vector-based memory storage and retrieval service. Provides APIs for creating memory spaces, storing memories with vector embeddings, and performing semantic search with streaming retrieval. Supports multiple embedding providers and advanced metadata handling.

This Python package is automatically generated by the OpenAPI Generator project:

• API version: v1
• Package version: 1.5.13
• Generator version: 7.13.0
• Build package: org.openapitools.codegen.languages.PythonClientCodegen For more information, please visit https://goodmem.io/support

Server Compatibility

This client version is generated with GoodMem server v1.0.261.

Requirements.

Python 3.9+

Installation & Usage

pip install

You can install the package directly from PyPI:

pip install goodmem-client

If you prefer uv:

uv pip install goodmem-client

Then import the package:

import goodmem_client

Setuptools

Install via Setuptools.

python setup.py install --user

(or sudo python setup.py install to install the package for all users)

Then import the package:

import goodmem_client

Tests

Execute pytest to run the tests.

Getting Started

Please follow the installation procedure and then run the following:

# Import required modules
from goodmem_client.api import APIKeysApi, SpacesApi
from goodmem_client.configuration import Configuration
from goodmem_client.api_client import ApiClient
from goodmem_client.models import CreateApiKeyRequest
from goodmem_client.streaming import MemoryStreamClient
from goodmem_client.rest import ApiException
from pprint import pprint

# Configure the API client
configuration = Configuration()
configuration.host = "http://localhost:8080"  # Use your server URL

# Set authentication
configuration.api_key = {"ApiKeyAuth": "your-api-key"}

# Create API client
api_client = ApiClient(configuration=configuration)  # Your API key here

# Create an instance of the API class
api_instance = APIKeysApi(api_client=api_client)

# Prepare a create request with labels
create_request = CreateApiKeyRequest(
    labels={
        "environment": "development",
        "service": "chat-ui"
    }
)

try:
    # Create a new API key
    api_response = api_instance.create_api_key(create_api_key_request=create_request)
    print("API Key created successfully:")
    print(f"API Key ID: {api_response.api_key_metadata.api_key_id}")
    print(f"Raw API Key: {api_response.raw_api_key}")
except ApiException as e:
    print(f"Exception when calling APIKeysApi->create_api_key: {e}")

Streaming Memory Retrieval

For memory retrieval operations, use the streaming client which is the primary way to search and retrieve memories:

from goodmem_client.api import SpacesApi
from goodmem_client.streaming import MemoryStreamClient
from goodmem_client.configuration import Configuration
from goodmem_client.api_client import ApiClient

# Configure client
configuration = Configuration()
configuration.host = "http://localhost:8080"
configuration.api_key = {"ApiKeyAuth": "your-api-key"}

api_client = ApiClient(configuration=configuration)

# Create streaming client
spaces_api = SpacesApi(api_client=api_client)
stream_client = MemoryStreamClient(api_client)

# Get space ID (first available space)
spaces = spaces_api.list_spaces()
space_id = spaces.spaces[0].space_id if spaces.spaces else None

# Stream memory retrieval using advanced POST endpoint with custom post-processor
for event in stream_client.retrieve_memory_stream(
    message="your search query",
    space_ids=[space_id] if space_id else None,
    requested_size=5,
    fetch_memory=True,
    fetch_memory_content=False,
    format="ndjson",
    post_processor_name="com.goodmem.retrieval.postprocess.ChatPostProcessorFactory",
    post_processor_config={
        "llm_id": "your-llm-uuid",
        "reranker_id": "your-reranker-uuid",
        "relevance_threshold": 0.5,
        "max_results": 10
    }
):
    if event.abstract_reply:
        print(f"Abstract: {event.abstract_reply.text}")
    elif event.retrieved_item and event.retrieved_item.memory:
        memory = event.retrieved_item.memory
        print(f"Memory: {memory.get('memoryId')}")
        if 'metadata' in memory:
            print(f"Metadata: {memory['metadata']}")

# Alternative: Use convenience method for ChatPostProcessor with simple parameters
for event in stream_client.retrieve_memory_stream_chat(
    message="your search query",
    space_ids=[space_id] if space_id else None,
    requested_size=5,
    fetch_memory=True,
    format="ndjson",
    pp_llm_id="your-llm-uuid",
    pp_reranker_id="your-reranker-uuid",
    pp_relevance_threshold=0.5,
    pp_max_results=10
):
    if event.abstract_reply:
        print(f"Abstract: {event.abstract_reply.text}")

For comprehensive examples, see the samples directory:

• apikey_sample.py - API key CRUD operations
• streaming_sample.py - Memory retrieval with streaming
• reproduce_issue_71.py - Memory creation with metadata

Using Filter Expressions

Filter expressions allow you to pre-filter memories based on metadata before semantic search. This enables more precise retrieval by combining metadata filtering with vector similarity.

from goodmem_client.streaming import MemoryStreamClient
from goodmem_client.models.space_key import SpaceKey
from goodmem_client.configuration import Configuration
from goodmem_client.api_client import ApiClient

# Configure client
configuration = Configuration()
configuration.host = "http://localhost:8080"
configuration.api_key = {"ApiKeyAuth": "your-api-key"}

api_client = ApiClient(configuration=configuration)
stream_client = MemoryStreamClient(api_client)

# Example 1: Filter by category
space_key = SpaceKey(
    space_id="your-space-id",
    filter="CAST(val('$.category') AS TEXT) = 'technology'"
)

for event in stream_client.retrieve_memory_stream(
    message="artificial intelligence",
    space_keys=[space_key],
    requested_size=5
):
    if event.retrieved_item and event.retrieved_item.chunk:
        chunk = event.retrieved_item.chunk
        print(f"Chunk: {chunk.chunk.get('chunkText', '')[:100]}...")

# Example 2: Filter by time range
space_key = SpaceKey(
    space_id="your-space-id",
    filter="CAST(val('$.created_at') AS TEXT) >= '2025-01-01T00:00:00Z'"
)

for event in stream_client.retrieve_memory_stream(
    message="recent developments",
    space_keys=[space_key],
    requested_size=5
):
    if event.retrieved_item and event.retrieved_item.chunk:
        chunk = event.retrieved_item.chunk
        print(f"Relevance: {chunk.relevance_score:.4f}")
        print(f"Text: {chunk.chunk.get('chunkText', '')[:80]}...")

# Example 3: Complex filter with multiple conditions
space_key = SpaceKey(
    space_id="your-space-id",
    filter="""
        CAST(val('$.priority') AS TEXT) = 'high'
        AND CAST(val('$.status') AS TEXT) = 'active'
        AND CAST(val('$.score') AS INTEGER) >= 80
    """
)

for event in stream_client.retrieve_memory_stream(
    message="important tasks",
    space_keys=[space_key],
    requested_size=10
):
    if event.retrieved_item and event.retrieved_item.chunk:
        print(f"Found matching chunk")

# Example 4: Different filters for different spaces
space_keys = [
    SpaceKey(
        space_id="space-1-id",
        filter="CAST(val('$.category') AS TEXT) = 'research'"
    ),
    SpaceKey(
        space_id="space-2-id",
        filter="CAST(val('$.category') AS TEXT) = 'documentation'"
    )
]

for event in stream_client.retrieve_memory_stream(
    message="machine learning concepts",
    space_keys=space_keys,
    requested_size=10
):
    if event.memory_definition:
        space_id = event.memory_definition.get('spaceId')
        metadata = event.memory_definition.get('metadata', {})
        print(f"Memory from space: {space_id}, category: {metadata.get('category')}")

# Example 5: Mix filtered and unfiltered spaces
space_keys = [
    SpaceKey(
        space_id="space-1-id",
        filter="CAST(val('$.source') AS TEXT) = 'trusted_source'"
    ),
    SpaceKey(
        space_id="space-2-id"  # No filter - all memories from this space
    )
]

for event in stream_client.retrieve_memory_stream(
    message="information query",
    space_keys=space_keys,
    requested_size=10
):
    if event.retrieved_item and event.retrieved_item.chunk:
        print(f"Relevance: {event.retrieved_item.chunk.relevance_score:.4f}")

Filter Expression Syntax:

• Extract field: val('$.field_name')
• Extract array: vals('$.array_field[*]')
• Check field exists: exists('$.field_name')
• String comparison: CAST(val('$.category') AS TEXT) = 'technology'
• Numeric comparison: CAST(val('$.score') AS INTEGER) >= 80
• Date comparison: CAST(val('$.created_at') AS DATE) >= CAST('2025-01-01' AS DATE)
• String pattern: CAST(val('$.title') AS TEXT) LIKE '%AI%'
• Case-insensitive pattern: CAST(val('$.title') AS TEXT) ILIKE '%ai%'
• Array membership: 'tag1' IN vals('$.tags')
• Multiple conditions: Use AND, OR, NOT operators

For more details on filter expressions, see the GoodMem filter documentation.

Documentation for API Endpoints

All URIs are relative to http://localhost:8080

Class	Method	HTTP request	Description
APIKeysApi	create_api_key	POST /v1/apikeys	Create a new API key
APIKeysApi	delete_api_key	DELETE /v1/apikeys/{id}	Delete an API key
APIKeysApi	list_api_keys	GET /v1/apikeys	List API keys
APIKeysApi	update_api_key	PUT /v1/apikeys/{id}	Update an API key
AdministrationApi	drain_server	POST /v1/admin:drain	Request the server to enter drain mode
AdministrationApi	purge_background_jobs	POST /v1/admin/background-jobs:purge	Purge completed background jobs
AdministrationApi	reload_license	POST /v1/admin/license:reload	Reload the active license from disk
EmbeddersApi	create_embedder	POST /v1/embedders	Create a new embedder
EmbeddersApi	delete_embedder	DELETE /v1/embedders/{id}	Delete an embedder
EmbeddersApi	get_embedder	GET /v1/embedders/{id}	Get an embedder by ID
EmbeddersApi	list_embedders	GET /v1/embedders	List embedders
EmbeddersApi	update_embedder	PUT /v1/embedders/{id}	Update an embedder
LLMsApi	create_llm	POST /v1/llms	Create a new LLM
LLMsApi	delete_llm	DELETE /v1/llms/{id}	Delete an LLM
LLMsApi	get_llm	GET /v1/llms/{id}	Get an LLM by ID
LLMsApi	list_llms	GET /v1/llms	List LLMs
LLMsApi	update_llm	PUT /v1/llms/{id}	Update an LLM
MemoriesApi	batch_create_memory	POST /v1/memories:batchCreate	Create multiple memories in a batch
MemoriesApi	batch_delete_memory	POST /v1/memories:batchDelete	Delete memories in batch
MemoriesApi	batch_get_memory	POST /v1/memories:batchGet	Get multiple memories by ID
MemoriesApi	create_memory	POST /v1/memories	Create a new memory
MemoriesApi	delete_memory	DELETE /v1/memories/{id}	Delete a memory
MemoriesApi	get_memory	GET /v1/memories/{id}	Get a memory by ID
MemoriesApi	get_memory_content	GET /v1/memories/{id}/content	Download memory content
MemoriesApi	get_memory_page_image_content	GET /v1/memories/{id}/pages/{pageIndex}/image	Download memory page image content
MemoriesApi	list_memories	GET /v1/spaces/{spaceId}/memories	List memories in a space
MemoriesApi	list_memory_page_images	GET /v1/memories/{id}/pages	List memory page images
MemoriesApi	retrieve_memory	GET /v1/memories:retrieve	Stream semantic memory retrieval
MemoriesApi	retrieve_memory_advanced	POST /v1/memories:retrieve	Advanced semantic memory retrieval with JSON
OCRApi	ocr_document	POST /v1/ocr:document	Run OCR on a document or image
PingApi	ping_once	POST /v1/ping:once	Run a single ping probe
PingApi	ping_stream	POST /v1/ping:stream	Stream ping probe results
RerankersApi	create_reranker	POST /v1/rerankers	Create a new reranker
RerankersApi	delete_reranker	DELETE /v1/rerankers/{id}	Delete a reranker
RerankersApi	get_reranker	GET /v1/rerankers/{id}	Get a reranker by ID
RerankersApi	list_rerankers	GET /v1/rerankers	List rerankers
RerankersApi	update_reranker	PUT /v1/rerankers/{id}	Update a reranker
SpacesApi	create_space	POST /v1/spaces	Create a new Space
SpacesApi	delete_space	DELETE /v1/spaces/{id}	Delete a space
SpacesApi	get_space	GET /v1/spaces/{id}	Get a space by ID
SpacesApi	list_spaces	GET /v1/spaces	List spaces
SpacesApi	update_space	PUT /v1/spaces/{id}	Update a space
SystemApi	get_system_info	GET /v1/system/info	Retrieve server build metadata
SystemApi	initialize_system	POST /v1/system/init	Initialize the system
UsersApi	get_current_user	GET /v1/users/me	Get current user profile
UsersApi	get_user	GET /v1/users/{id}	Get a user by ID
UsersApi	get_user_by_email	GET /v1/users/email/{email}	Get user by email address

Documentation For Models

• AbstractReply
• ActiveLicenseMetadata
• AdminDrainRequest
• AdminDrainResponse
• AdminPurgeJobsRequest
• AdminPurgeJobsResponse
• AdminReloadLicenseResponse
• ApiKeyAuth
• ApiKeyResponse - API key metadata and information
• BackgroundJobAttempt
• BackgroundJobSummary
• BatchDeleteMemorySelectorRequest
• BatchMemoryDeletionRequest - Request for deleting multiple memories
• BatchMemoryResponse
• BatchMemoryResult
• BatchMemoryRetrievalRequest - Request for retrieving multiple memories
• BinaryContent
• BoundingBox
• ChunkReference
• ChunkingConfiguration
• ChunkingConfigurationOneOf
• ChunkingConfigurationOneOf1
• ChunkingConfigurationOneOf2
• ContextItem
• ContextItemOneOf
• ContextItemOneOf1
• CreateApiKeyRequest - Request for creating a new API key
• CreateApiKeyResponse - Response containing new API key details
• CreateLLMResponse
• CredentialKind
• DistributionType
• DocumentTimings
• EmbedderCreationRequest - Request for creating a new embedder
• EmbedderResponse - Embedder configuration and metadata
• EmbedderWeight
• EndpointAuthentication
• ErrorDetail
• FilteredDeleteMemorySelectorRequest
• GcpAdcAuth
• GoodMemStatus
• HnswIterativeScan
• HnswOptions
• ImageInfo
• JsonBatchMemoryCreationRequest
• JsonMemoryCreationContentRequirement
• JsonMemoryCreationContentRequirementOneOf
• JsonMemoryCreationContentRequirementOneOf1
• JsonMemoryCreationRequest
• LLMCapabilities
• LLMCreationRequest
• LLMProviderType
• LLMResponse
• LLMSamplingParams
• LLMUpdateRequest
• LLMUpdateRequestNot
• LengthMeasurement
• ListApiKeysResponse - Response containing list of API keys
• ListEmbeddersResponse - Response containing list of embedders
• ListLLMsResponse
• ListMemoryPageImagesResponse
• ListRerankersResponse
• ListSpacesResponse - Response containing list of spaces
• Memory - Memory object with content and metadata
• MemoryChunkResponse
• MemoryCreationRequest - Request for creating a new memory
• MemoryListResponse - Response containing list of memories
• MemoryPageImage
• Modality - Enumeration of supported modalities (TEXT, IMAGE, etc.)
• OcrCategory
• OcrCell
• OcrDocumentRequest
• OcrDocumentResponse
• OcrInputFormat
• OcrLayout
• OcrPage
• OcrPageResult
• PageTimings
• PingEndpointInfo
• PingEvent
• PingEventOneOf
• PingEventOneOf1
• PingEventOneOf2
• PingNotice
• PingOnceRequest
• PingPayloadType
• PingResult
• PingStreamRequest
• PingSummary
• PingTargetType
• PingTiming
• PostProcessor
• ProcessingHistory
• ProviderType - Enumeration of embedding providers (OPENAI, etc.)
• RecursiveChunkingConfiguration
• RerankerCreationRequest
• RerankerResponse
• ResultSetBoundary
• RetrieveMemoryEvent
• RetrieveMemoryRequest
• RetrievedItem
• RetrievedItemOneOf
• RetrievedItemOneOf1
• RpcStatus
• SecretReference
• SentenceChunkingConfiguration
• SeparatorKeepStrategy
• SortOrder
• Space - Space object for organizing memories
• SpaceCreationRequest - Request for creating a new space
• SpaceEmbedder - Associates an embedder with a space, including retrieval configuration
• SpaceEmbedderConfig - Configuration for associating an embedder with a space
• SpaceKey
• SystemInfoResponse
• SystemInitResponse - Response from system initialization
• UpdateApiKeyRequest - Request for updating an API key
• UpdateEmbedderRequest - Request for updating an embedder
• UpdateRerankerRequest
• UpdateSpaceRequest - Request for updating a space
• UserResponse - User account information

Documentation For Authorization

Authentication schemes defined for the API:

BearerAuth

• Type: Bearer authentication

ApiKeyAuth

• Type: API key
• API key parameter name: x-api-key
• Location: HTTP header

Contact & Support

For questions or issues with the Python client, please visit:

• GitHub repository: https://github.com/PAIR-Systems-Inc/goodmem
• PyPI package: https://pypi.org/project/goodmem-client/

Author

[e-mail]