Metadata-Version: 2.4
Name: harny
Version: 0.1.2
Summary: Python SDK for the Harny memory API
Author-email: Harny <platform@harny.ai>
License: Apache-2.0
Project-URL: Homepage, https://harny.ai
Project-URL: Documentation, https://harny.ai/docs/memory-api/quickstart
Keywords: harny,memory,agent-memory,api,sdk
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx<1.0.0,>=0.27.2
Requires-Dist: pydantic<3.0.0,>=2.9.0
Requires-Dist: email-validator<3.0.0,>=2.2.0
Provides-Extra: otel
Requires-Dist: opentelemetry-api<2.0,>=1.20; extra == "otel"
Provides-Extra: dev
Requires-Dist: pytest<9.0.0,>=8.3.0; extra == "dev"
Requires-Dist: pytest-asyncio<1.0.0,>=0.24.0; extra == "dev"
Requires-Dist: PyYAML<7.0,>=6.0; extra == "dev"
Dynamic: license-file

# Harny Python SDK

Harny gives each person your app's AI serves a private memory that keeps up when facts change. This package is the Python client: ingest timestamped text, check its status, delete it when required, and recall current facts with evidence.

#1 on BEAM at 128K tokens, the public benchmark for long-term memory in agents. [Results and methodology](https://harny.ai/benchmarks)

Documentation: [Quickstart](https://harny.ai/docs/memory-api/quickstart) · [Memory API overview](https://harny.ai/docs/memory-api/overview)

## Installation

```
pip install harny
```

Requires Python 3.10+.

## Key

Sign up at [console.harny.ai](https://console.harny.ai/signup) and create an app key, or run `harny init` in your project folder and the key is saved to `.env`. The client reads it from `HARNY_API_KEY`.

## Quickstart

```python
from harny import SyncHarnyClient

with SyncHarnyClient() as harny:  # reads HARNY_API_KEY
    harny.provision_user("demo-user", "demo@example.com")  # add each person once; repeating it is safe
    receipt = harny.ingest_data_point(
        "Budget for the Acme pilot moved to 40k.",
        timestamp="2026-07-28T16:00:00Z",
        user="demo-user",
    )
    harny.wait_for_ingestion(receipt.ingestionId, user="demo-user")
    page = harny.recall("What is the Acme pilot budget?", user="demo-user")
    print(page.results[0].content)
```

`user` names the person; each recall returns that person's memory and nothing from anyone else's. `HarnyClient` is the async client: `async with HarnyClient() as harny:` and `await` each call.

The same calls from the command line: `harny ingest "<fact>" --user <id>` and `harny query "<question>" --user <id>`.

## Methods

- `ingest_data_point` — send one fact with the time it happened. The same `id` with changed text replaces the old memory.
- `ingest_batch` — send 1 to 1,000 facts at once.
- `get_ingestion` / `wait_for_ingestion` — `processing`, `completed` or `failed`. `nothingNew` is true when the send added nothing new.
- `recall` — ranked, dated facts for a question; `level` (`low` to `extra-high`) or `max_tokens` sets how much comes back.
- `delete_data_point`, `delete_data_points`, `delete_ingestion` — remove a fact, or a whole send, and the memories that rest only on it.
- `get_usage` — this month's usage for the app.

For agents, the client also has `provision_user`, `assemble_context`, `record_action` and `list_actions`. See the [agent harness overview](https://harny.ai/docs/agent-harness/overview).

## Errors

```python
from harny import HarnyAPIError, HarnyConnectionError

try:
    page = harny.recall("What is the Acme pilot budget?", user="demo-user")
except HarnyConnectionError:
    ...  # nothing reached Harny; retry
except HarnyAPIError as e:
    print(e.status_code, e.error_code, e.recovery_hint, e.retry_after_s)
```

## Where next

- [Quickstart](https://harny.ai/docs/memory-api/quickstart) in cURL, Python and TypeScript
- [Memory API overview](https://harny.ai/docs/memory-api/overview)
- [MCP server](https://harny.ai/docs/mcp/overview) for Claude, Cursor, VS Code and other MCP clients
- [support@harny.ai](mailto:support@harny.ai)

## License

Apache-2.0.
