# trustmem-client

HTTP client for [TrustMem](https://github.com/sator-inc-com/trustmem) server.

Lightweight client with only `httpx` as a dependency — no `trustmem` package needed.

## Install

```bash
pip install trustmem-client
```

## Quick Start

```python
from trustmem_client import TrustMemClient

# Auto-load from environment variables (TRUSTMEM_BASE_URL, TRUSTMEM_API_KEY)
client = TrustMemClient()

# Or specify explicitly
client = TrustMemClient(base_url="http://localhost:8080", api_key="tm-xxx")

# Add memories from conversation messages
client.add(
    [{"role": "user", "content": "Alex likes sushi"}],
    user_id="alex",
)

# Shared knowledge (no specific user)
client.add(
    [{"role": "user", "content": "Company policy: 20 vacation days"}],
    visibility="organization",
)

# Search (returns user memories + shared knowledge)
result = client.search("food preferences", user_id="alex")
print(result)  # {"results": [...], "relations": [...]}

# List all memories for a user
all_memories = client.get_all(user_id="alex")

# Delete
client.delete(memory_id)

# Clean up
client.close()
```

## Configuration

| Environment Variable | Default | Description |
|---|---|---|
| `TRUSTMEM_BASE_URL` | `http://localhost:8080` | Server URL |
| `TRUSTMEM_API_KEY` | — | API key for Bearer authentication |

Environment variables can be set in a `.env` file (requires `pip install trustmem-client[dotenv]`).

Constructor arguments take priority over environment variables.

## Scoping

All data methods require either `user_id` or `visibility="organization"`:

```python
client.add(data, user_id="alex")              # User-specific memory
client.add(data, visibility="organization")   # Shared knowledge
client.add(data)                              # Error
```

When searching with `user_id`, both user-specific and shared memories are returned.

## API

| Method | Scope | Description |
|---|---|---|
| `add(data, *, user_id, visibility)` | `user_id` or `visibility` | Extract and store memories from conversation messages |
| `search(query, *, user_id, visibility)` | `user_id` or `visibility` | Hybrid search (vector + keyword) with ZTM trust filtering |
| `search_raw(query, *, user_id, visibility)` | `user_id` or `visibility` | Pure cosine similarity search (no TrustMem ranking) |
| `get_all(*, user_id, visibility)` | `user_id` or `visibility` | Get all memories and relations |
| `delete(memory_id)` | — | Delete a memory by ID |
| `close()` | — | Close the HTTP connection |

`TrustMemClient` supports the context manager protocol (`with` statement).

## License

BSL-1.1 — See [LICENSE](../LICENSE) for full terms.
