Metadata-Version: 2.5
Name: mnemoverse
Version: 0.2.0
Summary: Official Python SDK for Mnemoverse — persistent memory for AI agents. Sync and async REST client.
Project-URL: Homepage, https://mnemoverse.com
Project-URL: Documentation, https://mnemoverse.com/docs/api/python-sdk
Project-URL: Repository, https://github.com/mnemoverse/mnemoverse-sdk-python
Project-URL: Source, https://github.com/mnemoverse/mnemoverse-sdk-python
Project-URL: Issues, https://github.com/mnemoverse/mnemoverse-sdk-python/issues
Project-URL: Changelog, https://github.com/mnemoverse/mnemoverse-sdk-python/blob/main/CHANGELOG.md
Author-email: Eduard Izgorodin <helloworld@uinside.org>
License-Expression: MIT
License-File: LICENSE
Keywords: ai-agents,ai-memory,chatgpt,claude,cursor,hebbian-memory,llm-memory,long-term-memory,persistent-memory,rest-api,semantic-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 :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: httpx>=0.25.0
Requires-Dist: pydantic>=2.0.0
Provides-Extra: dev
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest-httpx>=0.30; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Description-Content-Type: text/markdown

[![PyPI version](https://img.shields.io/pypi/v/mnemoverse.svg?color=blue)](https://pypi.org/project/mnemoverse/)
[![Python versions](https://img.shields.io/pypi/pyversions/mnemoverse.svg)](https://pypi.org/project/mnemoverse/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
[![Research: SLoD arXiv](https://img.shields.io/badge/Research-arXiv%3A2603.08965-b31b1b)](https://arxiv.org/abs/2603.08965)

# Mnemoverse Python SDK

Persistent memory for AI agents. Not vector search — statistical learning backed by [Hebbian associations](https://arxiv.org/abs/2603.08965).

## Installation

```bash
pip install mnemoverse
```

## Quick Start

```python
from mnemoverse import MnemoClient

client = MnemoClient(api_key="mk_live_YOUR_KEY")

# Store a memory
result = client.write(
    "Retry with exponential backoff fixed the timeout issue",
    concepts=["retry", "backoff", "timeout"]
)

# Query — Hebbian associations expand "timeout" → "retry", "backoff"
memories = client.read("how to handle timeouts?")

# Report outcome — the system learns what works
client.feedback(
    atom_ids=[item.atom_id for item in memories.items],
    outcome=1.0,
    query_concepts=memories.query_concepts
)
```

## Async Client

```python
from mnemoverse import AsyncMnemoClient

async with AsyncMnemoClient(api_key="mk_live_YOUR_KEY") as client:
    result = await client.write("async memory", concepts=["async"])
    memories = await client.read("what about async?")
```

## Features

- **Circuit breaker** — 5 failures → open → 30s half-open → probe
- **Retry with backoff** — 3 attempts, rate-limit-aware
- **Sync + async** — `MnemoClient` for scripts, `AsyncMnemoClient` for FastAPI
- **Type-safe** — Pydantic models, full type hints

## Methods

| Method | Description |
|--------|-------------|
| `write(content, concepts, domain, metadata)` | Store a memory |
| `write_batch(items)` | Store up to 500 memories |
| `read(query, top_k, domain, since, until, order_by, exclude_author)` | Semantic search — "what do I know about X" |
| `recent(domain, since, until, exclude_author, limit, cursor)` | Newest-first feed — "what happened lately" |
| `feedback(atom_ids, outcome)` | Report success/failure |
| `stats()` | Memory statistics |
| `health()` | API health check |

Every method exists on both `MnemoClient` (sync) and `AsyncMnemoClient` (async).

### Search or feed?

`read()` answers *what do I know about X* and ranks by relevance. `recent()`
answers *what happened lately* and is complete within one scope by
construction — nothing is skipped, which a semantic search cannot promise.
Reach for `recent()` to resume after a break or to catch up on a shared room.

```python
from mnemoverse import MnemoClient

client = MnemoClient(api_key="mk_live_...")

# Catch up on a shared room. Rooms are SEPARATE stores: pass the address as
# `domain`, or an unscoped feed will not cover them.
page = client.recent(domain="xroom:room_01ABC", since="2026-08-01T00:00:00Z", limit=20)
for item in page.items:
    print(item.created_at, item.content)

if page.next_cursor:
    page = client.recent(domain="xroom:room_01ABC", cursor=page.next_cursor)
```

Read items carry `created_at` and `provenance` (who wrote it, where from).

## Documentation

- [Getting Started](https://mnemoverse.com/docs/api/getting-started)
- [API Reference](https://mnemoverse.com/docs/api/reference)
- [Python SDK Docs](https://mnemoverse.com/docs/api/python-sdk)

## License

MIT
