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

# Python SDK

> Official Engramme Python client

The `engramme` package is the official Python SDK for the Engramme API. Use it from notebooks, scripts, backend services, and internal tools.

## Installation

```bash theme={null}
pip install engramme
```

The latest PyPI package is [`engramme`](https://pypi.org/project/engramme/), currently published as `0.1.1`.

## Quick Start

```python theme={null}
from engramme import Engramme

client = Engramme()

print(client.health_check())

upload = client.memorize(
    file=b"Meeting notes about the Q4 roadmap and launch timeline.",
    user_name="Sanket",
    source_type="text",
    filename="meeting-notes.txt",
)

print(upload["item_id"])

results = client.recall("Q4 roadmap launch timeline")

for memory in results.get("memories", []):
    print(memory)
```

<Note>
  Memorization starts asynchronous processing. A successful `memorize` response means the upload was accepted and processing started; the content may not be immediately recallable.
</Note>

## Authentication

<CodeGroup>
  ```python Direct theme={null}
  from engramme import Engramme

  client = Engramme(api_key="eng_sk_...")
  ```

  ```python Environment Variable theme={null}
  from engramme import Engramme

  client = Engramme()
  ```
</CodeGroup>

API key resolution order:

1. Explicit `api_key` passed to `Engramme(...)`
2. `ENGRAMME_API_KEY`
3. Active profile in `~/.engramme/config.yaml`

You can also save and manage a local key with the CLI:

```bash theme={null}
engramme login
engramme whoami
engramme profiles
engramme logout
```

Local credentials are stored in `~/.engramme/config.yaml`. Override that path with `ENGRAMME_CONFIG_PATH`.

## Methods

### `Engramme(...)`

```python theme={null}
client = Engramme(
    api_key=None,
    profile=None,
    base_url="https://memorymachines-gateway-prod-btf57kda.uc.gateway.dev",
    timeout=30,
)
```

<ParamField body="api_key" type="str">
  API key to use directly. If omitted, the SDK checks environment variables and local profiles.
</ParamField>

<ParamField body="profile" type="str">
  Local profile name from `~/.engramme/config.yaml`.
</ParamField>

<ParamField body="base_url" type="str" default="https://memorymachines-gateway-prod-btf57kda.uc.gateway.dev">
  API base URL.
</ParamField>

<ParamField body="timeout" type="int" default="30">
  Request timeout in seconds.
</ParamField>

***

### `memorize(...)`

Upload a document for memory extraction.

```python theme={null}
# From file path
result = client.memorize(
    file="notes.txt",
    user_name="Sanket",
    source_type="text",
)

# From bytes
result = client.memorize(
    file=b"Some text",
    user_name="Sanket",
    source_type="text",
    filename="note.txt",
)
```

<ParamField body="file" type="str | pathlib.Path | bytes" required>
  File path, `pathlib.Path`, or raw bytes to upload.
</ParamField>

<ParamField body="user_name" type="str">
  Name associated with the memories.
</ParamField>

<ParamField body="source_type" type="str" default="text">
  Type of content, such as `text`, `email`, `pdf`, `github`, or `google_meets`.
</ParamField>

<ParamField body="item_id" type="str">
  Optional stable identifier for the uploaded item.
</ParamField>

<ParamField body="filename" type="str">
  Filename to send when `file` is bytes.
</ParamField>

***

### `recall(...)`

Retrieve memories by semantic similarity.

```python theme={null}
results = client.recall(
    "meetings about roadmap planning",
    source="text",
    enable_trace=True,
    alpha=0.5,
)
```

<ParamField body="text" type="str" required>
  Query text, max 1,000 characters.
</ParamField>

<ParamField body="source" type="str">
  Optional source filter.
</ParamField>

<ParamField body="enable_trace" type="bool">
  Include trace metadata when the API supports it.
</ParamField>

<ParamField body="alpha" type="float">
  Optional hybrid search weight between `0.0` and `1.0`.
</ParamField>

***

### `health_check()`

Check API status.

```python theme={null}
ok = client.health_check()
```

Returns `True` when `GET /v1/health` returns HTTP 200.

## Error Handling

```python theme={null}
from engramme import Engramme, EngrammeError, AuthenticationError

client = Engramme()

try:
    client.recall("team meetings")
except AuthenticationError:
    print("Invalid API key")
except EngrammeError as e:
    print(f"Error: {e}")
```

| Exception             | Cause              |
| --------------------- | ------------------ |
| `AuthenticationError` | Invalid API key    |
| `RateLimitError`      | Too many requests  |
| `NotFoundError`       | Resource not found |
| `ValidationError`     | Invalid parameters |
| `APIError`            | Other API errors   |

## Next Steps

<CardGroup cols={2}>
  <Card title="API Reference" icon="code" href="/api-reference/overview">
    Full REST API documentation.
  </Card>

  <Card title="Authentication" icon="key" href="/authentication">
    API key best practices.
  </Card>
</CardGroup>