Metadata-Version: 2.4
Name: memoryintelligence
Version: 0.1.1
Summary: Official Python SDK for Memory Intelligence. Structured, verifiable memory for AI.
Author-email: Memory Intelligence Team <sdk@memoryintelligence.io>
License: MIT
Project-URL: Homepage, https://memoryintelligence.io
Project-URL: Documentation, https://docs.memoryintelligence.io
Project-URL: Repository, https://github.com/somewhere11/memoryintelligence-python-sdk
Project-URL: Changelog, https://github.com/somewhere11/memoryintelligence-python-sdk/blob/main/CHANGELOG.md
Keywords: ai,llm,memory,rag,embeddings,privacy,compliance,hipaa,gdpr,provenance,umo
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.27.0
Provides-Extra: dotenv
Requires-Dist: python-dotenv>=1.0.0; extra == "dotenv"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: pytest-httpx>=0.30; extra == "dev"
Requires-Dist: pytest-cov>=5.0; extra == "dev"
Requires-Dist: mypy>=1.8; extra == "dev"
Requires-Dist: ruff>=0.3; extra == "dev"
Requires-Dist: python-dotenv>=1.0.0; extra == "dev"
Dynamic: license-file

# Memory Intelligence API

**Memory without meaning is just storage.**

This API turns raw content (text, conversations, images) into structured meaning. Searchable, explainable, provenance-tracked. No black box. No hallucinations.

**For Python backends:** FastAPI, Django, Flask, Lambda, Cloud Functions.

---

## Installation

```bash
pip install memoryintelligence
```

**Get your API key:** [memoryintelligence.io/beta](https://memoryintelligence.io/beta)

---

## Quick Start

```python
from memoryintelligence import MemoryIntelligence

mi = MemoryIntelligence.from_env()          # reads MI_API_KEY

# Turn content into a structured, verifiable memory
note = mi.capture(
    "Discussed pricing with ACME. They prefer quarterly billing.",
    source="sales_call",
)

# Ask by meaning, not keywords
for hit in mi.ask("what did ACME say about billing?"):
    print(f"{hit.score:.2f}  {hit.summary}")

# Every memory has a receipt
if mi.verify(note.id):
    print("intact")
```

> **Upgrading from `MemoryClient`?** The flat `MemoryIntelligence` client above is
> the recommended surface. The older `MemoryClient` (the `mi.umo.*` namespace, with
> multi-tenant `user_ulid`) still works for advanced use, and `EdgeClient` still
> serves regulated on-premise deployments, but `MemoryClient` is deprecated and will
> be removed in a future major. See [Core Operations](#core-operations) for the full
> eight-verb surface.

---

## What It Does

- **Processes** → Extracts entities, topics, relationships, sentiment
- **Searches** → Returns ranked results with explainability
- **Matches** → Compares memories for relevance/similarity
- **Explains** → Shows *why* results matched (semantic, temporal, graph)
- **Deletes** → GDPR-compliant data removal with audit trail

**No vector database setup. No chunking strategies. No embedding models to manage.**

---

## Security: API Keys Are Server-Only

Your API key grants full account access. Keep it server-side.

**✅ Backend (environment variable):**
```python
mi = MemoryIntelligence.from_env()   # reads MI_API_KEY
```

**❌ Never hardcoded:**
```python
# Don't - visible in logs/code
mi = MemoryIntelligence(api_key='mi_sk_live_...')
```

**For web apps:** Use your API key in the backend, build your own endpoints with your auth, let your frontend call those.

---

## What Makes This Different

| Others | Memory Intelligence |
|--------|---------------------|
| Store text, embed, hope | Extract meaning first |
| "Here are similar chunks" | "Here's why this matched" |
| No audit trail | Cryptographic provenance |
| Your data = their model training | We never train on your data |

**Setting the standard for memory.**

---

## Core Operations

Eight verbs, mapped one-to-one onto the public API:

```python
note    = mi.capture(content, source="notes")   # POST   /v1/process
hits    = mi.ask(query, limit=5)                 # POST   /v1/memories/query
note    = mi.get(umo_id)                          # GET    /v1/memories/{id}
notes   = mi.list(limit=20)                       # GET    /v1/memories
proof   = mi.verify(umo_id)                        # GET    /v1/memories/{id}/proof
why     = mi.explain(umo_id)                        # GET    /v1/memories/{id}/explain
receipt = mi.forget(umo_id)                        # DELETE /v1/memories/{id}
notes   = mi.batch(["note one", "note two"])       # POST   /v1/batch
note    = mi.upload("meeting.mp3")                 # POST   /v1/upload
```

Results come back as small typed objects (`Memory`, `Match`, `Proof`, `Receipt`),
each with a `.raw` escape hatch and item access, so `note.id` when it is clean and
`note["quality_score"]` when you need a field we did not surface.

---

## Async Support

An async twin of the flat client (`AsyncMemoryIntelligence`) is on the roadmap.
Until then, the async surface is the older `AsyncMemoryClient` (the `mi.umo.*`
namespace, deprecated alongside `MemoryClient`):

```python
from memoryintelligence import AsyncMemoryClient

async with AsyncMemoryClient.from_env() as mi:
    results = await mi.umo.search(query, user_ulid="01ABC...")
```

---

## Error Handling

```python
from memoryintelligence import (
    MIError, AuthenticationError, NotFoundError, RateLimitError, ValidationError,
)

try:
    hits = mi.ask(query)
except AuthenticationError:
    ...                       # API key invalid or expired
except NotFoundError:
    ...                       # no memory with that id
except RateLimitError:
    ...                       # the client already retried with backoff
except ValidationError as e:
    ...                       # request shape was wrong
except MIError as e:
    print(e.status, e)        # any API error carries its status
```

---

## Typed Everywhere

Full Pydantic models. Type hints on every method. No `dict` soup.

```python
from memoryintelligence import Memory, Match, Proof
```

---

## Examples & Docs

- **[Getting Started Guide](https://github.com/memoryintelligence/memoryintelligence-python-sdk/tree/main/docs/GETTING-STARTED.md)** — Full walkthrough
- **[FastAPI Integration](https://github.com/memoryintelligence/memoryintelligence-python-sdk/tree/main/examples/fastapi_app.py)** — Complete example
- **[Advanced Usage](https://github.com/memoryintelligence/memoryintelligence-python-sdk/tree/main/docs/ADVANCED.md)** — Batch processing, retry logic, custom configs

---

## Support

- **Docs:** [memoryintelligence.io/docs](https://memoryintelligence.io/docs)
- **Issues:** [github.com/memoryintelligence/memoryintelligence-python-sdk/issues](https://github.com/memoryintelligence/memoryintelligence-python-sdk/issues)
- **Beta:** [memoryintelligence.io/beta](https://memoryintelligence.io/beta)

---

**Memory Intelligence™** — Setting the standard for memory.

Built by [somewhere](https://somewheremedia.com)
