memoryintelligence 0.1.0__tar.gz

memoryintelligence-0.1.0/CHANGELOG.md

@@ -0,0 +1,242 @@
+# Changelog
+
+## [2.0.1] - 2026-03-27
+
+### Fixed
+- Corrected all documentation and billing URLs from `memoryintelligence.dev` to `memoryintelligence.io`
+- Updated default API base URL from `api.memoryintelligence.dev` to `api.memoryintelligence.io`
+- Resolved dead links in error messages, edge client defaults, and PyPI package metadata
+
+
+All notable changes to the Memory Intelligence Python SDK.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [2.0.0] - 2026-02-27
+
+### Breaking Changes
+
+#### UMO Namespace Pattern
+- **Changed:** All UMO operations moved to `mi.umo.*` namespace
+  - `mi.process()` → `mi.umo.process()`
+  - `mi.search()` → `mi.umo.search()`
+  - `mi.match()` → `mi.umo.match()`
+  - `mi.explain()` → `mi.umo.explain()`
+  - `mi.delete()` → `mi.umo.delete()`
+
+#### Mandatory Encryption
+- **Changed:** Client-side AES-256-GCM encryption is now **mandatory**
+- **Removed:** `enable_encryption` parameter (previously optional in v1)
+- **Added:** Automatic encryption with ephemeral key if `MI_ENCRYPTION_KEY` not set
+- **Added:** Warning logged when using ephemeral keys in production
+
+#### User ID Format
+- **Changed:** `user_id` parameter renamed to `user_ulid`
+- **Changed:** Must use ULID format (26-character string: `01ABC...`)
+- **Migration:** Generate ULIDs: `str(ULID())`
+
+#### Dual Identity Pattern
+- **Changed:** `user_ulid` no longer defaults from client constructor
+- **Added:** `for_user(user_ulid)` method for scoped clients
+- **Usage:**
+  ```python
+  # v2.0
+  mi = MemoryClient()
+  user_client = mi.for_user("01USER12345678901234567890")
+  umo = user_client.umo.process("content")
+  ```
+
+#### Model Serialization
+- **Changed:** Models converted from dataclasses to Pydantic BaseModel
+- **Changed:** `asdict(umo)` → `umo.model_dump()`
+- **Changed:** `json.dumps(asdict(umo))` → `umo.model_dump_json()`
+- **Added:** Full Pydantic validation and serialization support
+
+#### Error Classes
+- **Renamed:** `AuthError` → `AuthenticationError`
+- **Added:** New exception classes:
+  - `LicenseError` - License validation and feature gating
+  - `PIIViolationError` - PII detection violations (HTTP 451)
+  - `PaymentRequiredError` - License required (HTTP 402)
+  - `ConflictError` - Resource conflicts (HTTP 409)
+
+### Added
+
+#### EdgeClient
+- **Added:** `EdgeClient` for on-premises deployment
+- **Features:**
+  - HIPAA mode (`hipaa_mode=True`)
+  - Air-gapped deployment (`air_gapped=True`)
+  - Federated aggregation (`aggregate()`)
+  - PHI handling verification (`verify_phi_handling()`)
+  - Audit log export (`export_audit_log()`)
+- **License Required:** ENTERPRISE tier only
+
+#### Async Support
+- **Added:** `AsyncMemoryClient` for non-blocking operations
+- **Features:**
+  - Full async/await support
+  - Connection pooling with `httpx.AsyncClient`
+  - Same API as sync client
+
+#### License System
+- **Added:** License tier enforcement (TRIAL, STARTER, PROFESSIONAL, ENTERPRISE)
+- **Added:** Feature gating:
+  - STARTER: `process()`, `search()` only
+  - PROFESSIONAL: All cloud features (`match()`, `explain()`)
+  - ENTERPRISE: All features including EdgeClient
+- **Added:** Grace periods:
+  - Cloud: 14 days
+  - Air-gapped: 30 days
+- **Added:** License caching with 24-hour TTL
+- **Added:** Background license revalidation
+
+#### Encryption Enhancements
+- **Added:** AES-256-GCM encryption with PBKDF2 (100,000 iterations)
+- **Added:** User ULID binding via associated data
+- **Added:** Key identification via SHA-256 hash
+- **Added:** `EncryptedPayload` model for inspection
+
+#### HTTP Transport
+- **Added:** `SyncTransport` and `AsyncTransport` with retry logic
+- **Added:** Exponential backoff with jitter
+- **Added:** Retry on: 408, 429, 500, 502, 503, 504
+- **Added:** ULID request IDs for tracing
+- **Added:** Automatic error mapping from HTTP status codes
+
+#### Models
+- **Added:** Pydantic models for all API responses:
+  - `MeaningObject`, `Entity`, `Topic`, `SVOTriple`
+  - `SearchResponse`, `SearchResult`, `MatchResult`
+  - `Explanation`, `HumanExplanation`, `AuditExplanation`
+  - `Provenance`, `PIIInfo`, `DeleteResult`
+- **Added:** Enum types:
+  - `Scope` (USER, CLIENT, ORGANIZATION)
+  - `PIIHandling` (EXTRACT_AND_REDACT, HASH, REJECT)
+  - `RetentionPolicy` (FULL, MEANING_ONLY, NO_STORAGE)
+  - `ProvenanceMode` (MINIMAL, STANDARD, AUDIT)
+  - `LicenseType` (TRIAL, STARTER, PROFESSIONAL, ENTERPRISE)
+  - `LicenseStatus` (ACTIVE, EXPIRED, REVOKED, SUSPENDED)
+
+### Changed
+
+#### Dependencies
+- **Added:** `httpx>=0.27.0` (was `requests` in v1)
+- **Added:** `pydantic>=2.5.0`
+- **Added:** `cryptography>=42.0.0`
+- **Added:** `python-ulid>=2.0.0`
+- **Removed:** `requests` dependency
+
+#### Configuration
+- **Changed:** `MI_API_KEY` environment variable now the primary auth method
+- **Changed:** `MI_ENCRYPTION_KEY` for persistent encryption keys
+- **Added:** Validation for API key format (`mi_sk_` prefix)
+
+#### Error Handling
+- **Changed:** All errors now include `code` attribute
+- **Changed:** `RateLimitError` includes `retry_after` seconds
+- **Changed:** `ServerError` includes `request_id` for debugging
+- **Changed:** `ValidationError` includes `field` for invalid parameters
+- **Changed:** `LicenseError` includes `days_expired` and `renew_url`
+
+### Removed
+
+- **Removed:** Direct method calls on `MemoryClient` (use `mi.umo.*`)
+- **Removed:** `enable_encryption` parameter (always enabled)
+- **Removed:** `user_id` parameter (use `user_ulid`)
+- **Removed:** `AuthError` exception (use `AuthenticationError`)
+
+### Security
+
+- **Added:** Mandatory client-side encryption for all content
+- **Added:** User ULID binding prevents cross-user decryption
+- **Added:** Authentication tags prevent tampering
+- **Added:** PII detection with configurable handling
+- **Added:** HIPAA mode for healthcare compliance
+- **Added:** Audit logging for compliance reviews
+- **Added:** Scope isolation (user/client/organization)
+
+### Documentation
+
+- **Added:** Quickstart guide (`docs/quickstart.md`)
+- **Added:** Authentication guide (`docs/authentication.md`)
+- **Added:** Encryption guide (`docs/encryption.md`)
+- **Added:** Licensing guide (`docs/licensing.md`)
+- **Added:** API reference (`docs/api_reference.md`)
+- **Added:** Enterprise guide (`docs/enterprise.md`)
+- **Added:** Migration guide (`docs/migration_v1_to_v2.md`)
+- **Added:** FAQ (`docs/faq.md`)
+- **Added:** OpenAPI specification (`docs/openapi.yaml`)
+
+### Testing
+
+- **Added:** Comprehensive test suite:
+  - `tests/test_client.py` - UMONamespace methods
+  - `tests/test_crypto.py` - Encryption/decryption
+  - `tests/test_license.py` - License validation
+  - `tests/test_edge_client.py` - EdgeClient functionality
+  - `tests/test_errors.py` - HTTP status mapping
+  - `tests/test_integration.py` - End-to-end workflows
+- **Added:** pytest fixtures with mocked transport
+- **Added:** Test coverage for all license tiers
+
+---
+
+## [1.0.1] - 2026-02-07
+
+### Fixed
+- Corrected `ProvenanceError` in `__all__` exports list (final typo fix)
+
+## [1.0.0] - 2026-02-07 [YANKED]
+
+### Added
+- **MemoryClient** with 6 core operations: process, search, match, explain, delete, verify_provenance
+- **EdgeClient** for on-premises HIPAA-compliant deployments
+- Privacy-first architecture with meaning-only retention (default)
+- Structured semantic extraction (entities, topics, SVO triples, key phrases)
+- Explainable search results with human + audit explanations
+- Cryptographic provenance tracking with hash chain verification
+- ULID-based identity firewall for cryptographic tenant isolation
+- Scope-based access control (user, team, client, organization)
+- PII detection and configurable handling (extract_and_redact, hash, reject)
+- Type-safe API with Pydantic models
+- Comprehensive error handling (7 exception types)
+- 30+ unit and integration tests
+
+### Known Limitations
+- Pagination not yet implemented (coming in v1.1.0)
+- Streaming search results not yet available
+- Temporal intelligence parameter present but not fully validated in tests
+
+### Fixed
+- Corrected `ProvenanceError` exception name (was misspelled as `ProvenenaceError`)
+
+---
+
+## Migration Guide
+
+See [docs/migration_v1_to_v2.md](docs/migration_v1_to_v2.md) for detailed migration instructions.
+
+### Quick Migration Checklist
+
+- [ ] Update imports to use `mi.umo.*` namespace
+- [ ] Rename `user_id` to `user_ulid` (use ULID format)
+- [ ] Set `MI_ENCRYPTION_KEY` environment variable
+- [ ] Update `asdict(umo)` to `umo.model_dump()`
+- [ ] Rename `AuthError` to `AuthenticationError`
+- [ ] Use `for_user()` for multi-user applications
+
+---
+
+## Support
+
+- **Documentation:** [docs.memoryintelligence.dev](https://docs.memoryintelligence.dev)
+- **Migration Help:** migration@memoryintelligence.dev
+- **Issues:** [github.com/memoryintelligence/sdk-python/issues](https://github.com/memoryintelligence/sdk-python/issues)
+- **Changelog:** This file
+
+[2.0.0]: https://github.com/memoryintelligence/sdk-python/releases/tag/v2.0.0
+[1.0.1]: https://github.com/memoryintelligence/sdk-python/releases/tag/v1.0.1
+[1.0.0]: https://github.com/memoryintelligence/sdk-python/releases/tag/v1.0.0
+[Unreleased]: https://github.com/memoryintelligence/sdk-python/compare/v2.0.0...HEAD

memoryintelligence-0.1.0/LICENSE

@@ -0,0 +1,31 @@
+MIT License with Attribution Requirement
+
+Copyright (c) 2026 Memory Intelligence
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+1. The above copyright notice and this permission notice shall be included in all
+   copies or substantial portions of the Software.
+
+2. Applications using this SDK MUST display "Powered by Memory Intelligence" 
+   attribution in their user interface or documentation.
+
+3. This SDK may only be used to interact with official Memory Intelligence API 
+   services. No reverse engineering of the API or unauthorized replication of 
+   the service is permitted.
+
+4. API access credentials (API keys) are non-transferable and may not be 
+   resold or sublicensed.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

memoryintelligence-0.1.0/MANIFEST.in

@@ -0,0 +1,21 @@
+# Include essential files
+include README.md
+include LICENSE
+include CHANGELOG.md
+
+# Include package data
+recursive-include memoryintelligence *.py
+
+# Exclude development files
+exclude .gitignore
+exclude .env*
+recursive-exclude tests *
+recursive-exclude demos *
+recursive-exclude examples *
+recursive-exclude .venv *
+recursive-exclude __pycache__ *
+recursive-exclude *.egg-info *
+global-exclude *.pyc
+global-exclude *.pyo
+global-exclude *~
+global-exclude .DS_Store

memoryintelligence-0.1.0/PKG-INFO

@@ -0,0 +1,220 @@
+Metadata-Version: 2.4
+Name: memoryintelligence
+Version: 0.1.0
+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
+Requires-Dist: python-ulid>=2.0.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)

memoryintelligence-0.1.0/README.md

@@ -0,0 +1,184 @@
+# 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)