Skip to main content
MemMachineClient is the primary interface for managing episodic and semantic memory. The client is organized into logical Namespaces to improve discoverability and match the modular backend architecture.

​
Initialization

The client manages a persistent HTTP session, handles authentication, and provides global timeout settings for all sub-client requests. 
from memmachine_client import MemMachineClient

client = MemMachineClient(
    base_url="http://localhost:8080",
    api_key="your-api-key-here",
    timeout=30.0
)

​
Parameters

ParameterTypeDefaultDescription
base_urlstr"http://localhost:8080"The root URL of your MemMachine server.
api_key`strNone`NoneOptional bearer token for authenticated environments.
timeoutfloat30.0Global request timeout in seconds.

​
Namespaces

The client is divided into specialized sub-clients. Accessing these allows you to perform operations specific to those domains.
NamespaceAccessorPurpose
Projectsclient.projectsCreate, delete, and list isolated memory namespaces.
Memoriesclient.memoriesIngest episodic messages and perform hybrid searches.
Semanticclient.semanticManage the “Knowledge Graph” (Sets, Categories, and Tags).
Configurationclient.configManage LLMs, Embedders, and runtime memory settings.
Systemclient.systemMonitor health, metrics, and server versioning.

​
Core Client Methods

While most operations live in namespaces, the root client provides session management and raw request capabilities.

​
request

Make an authenticated HTTP request using the client’s internal session. 
response = client.request(method="GET", path="/health")
ParameterTypeDescription
methodstrHTTP verb (e.g., "POST", "GET", "PUT", "DELETE").
pathstrThe endpoint path (e.g., "/projects").
**kwargsanyAdditional arguments passed to the underlying HTTP client.

​
close

Cleanly shut down the HTTP connection pool. This is called automatically if using the client as a context manager. 
client.close()

​
health_check

A convenience method to verify connectivity to the server. 
status = client.health_check()
Returns: A dictionary containing status, service, and version.

​
Usage Patterns

Using a context manager ensures that connections are released even if an error occurs. 
with MemMachineClient(base_url="http://localhost:8080") as client:
    project = client.projects.get("my_org", "my_proj")
    # client.close() is called automatically here

​
Error Handling

The SDK raises custom RestError exceptions for API-level validation or logic errors, allowing for granular error catching. 
from memmachine_client.exceptions import RestError

try:
    client.projects.delete("org", "non_existent_proj")
except RestError as e:
    print(f"Server returned {e.code}: {e.message}")