Client API

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`	Optional bearer token for authenticated environments.
`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}")

Introduction

MCP Tools

REST API

Typescript REST SDK

PythonSDK Client

Python SDK Server

Initialization

Parameters

Namespaces

Core Client Methods

`request`

`close`

`health_check`

Usage Patterns

Context Manager (Recommended)

Error Handling

​Initialization

​Parameters

​Namespaces

​Core Client Methods

​request

​close

​health_check

​Usage Patterns

​Context Manager (Recommended)

​Error Handling

Initialization

Parameters

Namespaces

Core Client Methods

`request`

`close`

`health_check`

Usage Patterns

Context Manager (Recommended)

Error Handling