Metadata-Version: 2.5
Name: remember
Version: 0.3.0
Summary: Official Python client for the remember.dev managed memory service.
Project-URL: Homepage, https://remember.dev
Project-URL: Documentation, https://remember.dev/docs
Project-URL: Source, https://github.com/writeitai/ultimate-memory-cloud
Author-email: "WriteIt.ai s.r.o." <info@writeit.ai>
License: Apache-2.0
Keywords: agents,memory,remember.dev,rememberstack
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: httpx>=0.27
Requires-Dist: rememberstack>=0.8.1
Description-Content-Type: text/markdown

# remember

Official Python SDK for the [remember.dev](https://remember.dev) managed memory service.

This distribution provides:
- **`remember.Client`** (D65): The primary ergonomic client for memory operations. Connects directly to your dedicated tenant deployment ingress with a single deployment API token (`umc_dp_…`).
- **`remember.CloudClient`** (D53): The control-plane client for checking deployment readiness, credit balances, and spend gates using a control-plane token (`umc_cp_…`).
- **`remember-status`**: CLI tool for quick control-plane status checks.

## Install

```console
pip install remember
```

This automatically installs `rememberstack` (which provides the `remember` CLI tool on `PATH`).

## Quickstart: Memory Operations (`Client`)

Mint an **API Token** (`umc_dp_…`) from your dashboard at **Settings → API Tokens**, then initialize `Client`:

```python
import remember

# Client accepts a bare secret (umc_dp_...) or a full Bearer string,
# and converts string file paths automatically:
with remember.Client(
    api_key="umc_dp_…",
    base_url="https://<deployment-id>.dp.remember.dev",
) as memory:
    landed = memory.ingest("notes/project.md")
    print("Ingested version:", landed.version_id)

    # Search claims or chunks
    claims = memory.search_claims(query="architecture decisions")
```

### Environment Variables

For zero-config agent setups, set `REMEMBER_API_KEY` and `REMEMBER_API_URL`:

```console
export REMEMBER_API_URL="https://<deployment-id>.dp.remember.dev"
export REMEMBER_API_KEY="umc_dp_…"
```

```python
import remember

with remember.Client.from_env() as memory:
    landed = memory.ingest("notes/project.md")
```

`Client` also automatically falls back to `REMEMBERSTACK_API_AUTHORIZATION` and `REMEMBERSTACK_API_URL` for seamless compatibility.

## Quickstart: Status & Balances (`CloudClient`)

To check billing balance and deployment readiness in CI or monitoring bots, use `CloudClient` with an organisation-scoped control-plane token (`umc_cp_…`).

Control tokens are read-only, expiring status credentials (D53/D65). Because they are an API-only operational surface, mint one via the control-plane endpoint while authenticated with an owner session:
- **Endpoint**: `POST /app/api/v1/orgs/{org_id}/control-tokens` (or `POST /v1/orgs/{org_id}/control-tokens` against the direct control-plane URL).
- **Body**: `{"label": "ci-monitor", "expires_in_days": 90}` (accepts `label` and optional `expires_in_days` up to 90).

```console
export REMEMBER_CLOUD_TOKEN='umc_cp_…'
export REMEMBER_CLOUD_ORG='your-organisation-id'
```

```python
from remember import CloudClient

with CloudClient.from_env() as cloud:
    if cloud.is_ready():
        print("Balance:", cloud.billing_status().balance)
```

You can also run the status CLI:

```console
$ remember-status
deployment  active     bb81063d-6b7b-41d0-a1df-dc57d4f1fe87
endpoint    live       bb81063d-6b7b-41d0-a1df-dc57d4f1fe87.dp.remember.dev
billing     active     balance 42.10
spend       allow
```
