title	Client API
description	High-level API reference for the Namespaced MemMachineClient
icon	code

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

Parameter	Type	Default	Description
base_url	str	"http://localhost:8080"	The root URL of your MemMachine server.
api_key	`str	None`	None
timeout	float	30.0	Global request timeout in seconds.

---

Namespaces

The client is divided into specialized sub-clients. Accessing these allows you to perform operations specific to those domains.

Namespace	Accessor	Purpose
Projects	client.projects	Create, delete, and list isolated memory namespaces.
Memories	client.memories	Ingest episodic messages and perform hybrid searches.
Semantic	client.semantic	Manage the "Knowledge Graph" (Sets, Categories, and Tags).
Configuration	client.config	Manage LLMs, Embedders, and runtime memory settings.
System	client.system	Monitor 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")

Parameter	Type	Description
method	str	HTTP verb (e.g., "POST", "GET", "PUT", "DELETE").
path	str	The endpoint path (e.g., "/projects").
**kwargs	any	Additional 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

Context Manager (Recommended)

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