Metadata-Version: 2.4
Name: recall-client
Version: 0.2.0
Summary: Official Python client for Recall — open-source memory for AI agents
Project-URL: Homepage, https://github.com/RecallWorks/Recall
Project-URL: Documentation, https://github.com/RecallWorks/Recall/tree/main/clients/python
Project-URL: Repository, https://github.com/RecallWorks/Recall
Project-URL: Issues, https://github.com/RecallWorks/Recall/issues
Author-email: RecallWorks contributors <maintainers@recall.works>
License-Expression: MIT
Keywords: ai-agents,llm,mcp,memory,recall,vector-search
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: respx>=0.21; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Description-Content-Type: text/markdown

<!-- @wbx-modified copilot-a3f7·MTN | 2026-04-24 | Python SDK README | prev: NEW -->
# recall-client (Python)

Official Python SDK for [Recall](https://github.com/RecallWorks/Recall) — open-source memory for AI agents.

## Install

```bash
pip install recall-client
```

## Quick start

```python
from recall_client import RecallClient

with RecallClient("http://localhost:8787", api_key="changeme") as client:
    print(client.health())  # {"status": "ok", "chunks": ..., "ready": True}

    client.remember("the user prefers dark mode", tags="pref,ui")
    res = client.recall("user preferences", n=5)
    print(res.result)  # markdown listing of hits
```

Every tool returns a `ToolResponse` envelope with three string fields: `result`, `tool`, `by`. The server formats results as markdown — parse `result` if you need structured fields.

## Async

```python
import asyncio
from recall_client import AsyncRecallClient

async def main():
    async with AsyncRecallClient("http://localhost:8787", api_key="changeme") as c:
        await c.remember("async memory works", tags="async")
        res = await c.recall("memory")
        print(res.result)

asyncio.run(main())
```

## Tool surface

The client exposes typed wrappers for the high-traffic tools:

| Method | Recall tool |
|--------|-------------|
| `remember()` | `remember` |
| `recall()` | `recall` |
| `reflect()` | `reflect` |
| `checkpoint()` | `checkpoint` |
| `pulse()` | `pulse` |
| `memory_stats()` | `memory_stats` |
| `forget()` | `forget` |
| `health()` | `GET /health` |

All 13 server tools have typed wrappers (`remember`, `recall`, `reflect`, `anti_pattern`, `session_close`, `checkpoint`, `pulse`, `memory_stats`, `forget`, `reindex`, `index_file`, `maintenance`, `snapshot_index`). For any custom or future tool, use the generic dispatch:

```python
client.call_tool("index_file", filepath="/data/notes.md")
client.call_tool("forget", source="agent-observation")
```

> Note: `forget()` takes a `source` label and **soft-archives** every chunk with that source. It does not delete a single chunk by id.

## Errors

All exceptions derive from `RecallError`:

- `RecallConnectionError` — server unreachable
- `RecallAuthError` — 401/403 (bad/missing API key)
- `RecallServerError` — 5xx
- `RecallToolError` — tool returned an explicit `error`

## License

MIT. See [LICENSE](https://github.com/RecallWorks/Recall/blob/main/LICENSE) at the root of the Recall repo.
