> ## Documentation Index
> Fetch the complete documentation index at: https://docs.memmachine.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Client API

> High-level API reference for the Namespaced MemMachineClient

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

```python theme={null}
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.

```python theme={null}
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.

```python theme={null}
client.close()
```

### `health_check`

A convenience method to verify connectivity to the server.

```python theme={null}
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.

```python theme={null}
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.

```python theme={null}
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}")
```