mnemoverse 0.1.0__tar.gz

mnemoverse-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+dist/
+build/
+.eggs/
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.venv/
+*.so

mnemoverse-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mnemoverse
+
+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:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+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.

mnemoverse-0.1.0/PKG-INFO

@@ -0,0 +1,104 @@
+Metadata-Version: 2.4
+Name: mnemoverse
+Version: 0.1.0
+Summary: Python SDK for Mnemoverse Memory API — persistent memory for AI agents
+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: Issues, https://github.com/mnemoverse/mnemoverse-sdk-python/issues
+Author-email: Edward Izgorodin <helloworld@uinside.org>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,ai,cognitive,hebbian,llm,mcp,memory
+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: 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
+
+# Mnemoverse Python SDK
+
+Persistent memory for AI agents. Not vector search — statistical learning.
+
+## 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)` | Query with Hebbian expansion |
+| `feedback(atom_ids, outcome)` | Report success/failure |
+| `stats()` | Memory statistics |
+| `health()` | API health check |
+
+## 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

mnemoverse-0.1.0/README.md

@@ -0,0 +1,71 @@
+# Mnemoverse Python SDK
+
+Persistent memory for AI agents. Not vector search — statistical learning.
+
+## 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)` | Query with Hebbian expansion |
+| `feedback(atom_ids, outcome)` | Report success/failure |
+| `stats()` | Memory statistics |
+| `health()` | API health check |
+
+## 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

mnemoverse-0.1.0/mnemoverse/__init__.py

@@ -0,0 +1,34 @@
+"""Mnemoverse Python SDK — persistent memory for AI agents."""
+
+from mnemoverse.client import MnemoClient
+from mnemoverse._async_client import AsyncMnemoClient
+from mnemoverse.errors import MnemoError, MnemoAuthError, MnemoRateLimitError, MnemoUnavailableError
+from mnemoverse.types import (
+    WriteResponse,
+    WriteBatchResponse,
+    WriteBatchItemResult,
+    ReadResponse,
+    MemoryItem,
+    FeedbackResponse,
+    StatsResponse,
+    HealthResponse,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "MnemoClient",
+    "AsyncMnemoClient",
+    "MnemoError",
+    "MnemoAuthError",
+    "MnemoRateLimitError",
+    "MnemoUnavailableError",
+    "WriteResponse",
+    "WriteBatchResponse",
+    "WriteBatchItemResult",
+    "ReadResponse",
+    "MemoryItem",
+    "FeedbackResponse",
+    "StatsResponse",
+    "HealthResponse",
+]

mnemoverse-0.1.0/mnemoverse/_async_client.py

@@ -0,0 +1,237 @@
+"""Async Mnemoverse client using httpx."""
+
+from __future__ import annotations
+
+from typing import Any
+from uuid import UUID
+
+import httpx
+
+from mnemoverse._retry import CircuitBreaker, retry_with_backoff
+from mnemoverse.errors import (
+    MnemoAuthError,
+    MnemoError,
+    MnemoRateLimitError,
+    MnemoUnavailableError,
+)
+from mnemoverse.types import (
+    FeedbackResponse,
+    HealthResponse,
+    ReadResponse,
+    StatsResponse,
+    WriteBatchResponse,
+    WriteResponse,
+)
+
+_DEFAULT_BASE_URL = "https://api.mnemoverse.com"
+
+
+class AsyncMnemoClient:
+    """Async client for the Mnemoverse Memory API.
+
+    Features:
+    - Circuit breaker (5 failures → open → 30s half-open)
+    - Timeout (10s default)
+    - Retry with exponential backoff (3 attempts, rate-limit-aware)
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = _DEFAULT_BASE_URL,
+        timeout: float = 10.0,
+        max_retries: int = 3,
+    ) -> None:
+        self._api_key = api_key
+        self._base_url = base_url.rstrip("/")
+        self._timeout = timeout
+        self._max_retries = max_retries
+        self._cb = CircuitBreaker(failure_threshold=5, reset_timeout=30.0)
+        self._client: httpx.AsyncClient | None = None
+
+    def _get_client(self) -> httpx.AsyncClient:
+        if self._client is None or self._client.is_closed:
+            self._client = httpx.AsyncClient(
+                base_url=self._base_url,
+                headers={
+                    "X-Api-Key": self._api_key,
+                    "Content-Type": "application/json",
+                    "Accept": "application/json",
+                },
+                timeout=self._timeout,
+            )
+        return self._client
+
+    async def close(self) -> None:
+        if self._client and not self._client.is_closed:
+            await self._client.aclose()
+
+    async def __aenter__(self) -> AsyncMnemoClient:
+        return self
+
+    async def __aexit__(self, *args: Any) -> None:
+        await self.close()
+
+    # --- Public API ---
+
+    async def write(
+        self,
+        content: str,
+        *,
+        concepts: list[str] | None = None,
+        domain: str = "general",
+        metadata: dict[str, Any] | None = None,
+        external_ref: str | None = None,
+    ) -> WriteResponse:
+        """Store a single memory atom."""
+        body: dict[str, Any] = {"content": content, "domain": domain}
+        if concepts:
+            body["concepts"] = concepts
+        if metadata:
+            body["metadata"] = metadata
+        if external_ref:
+            body["external_ref"] = external_ref
+        data = await self._request("POST", "/api/v1/memory/write", json=body)
+        return WriteResponse.model_validate(data)
+
+    async def write_batch(
+        self,
+        items: list[dict[str, Any]],
+    ) -> WriteBatchResponse:
+        """Store up to 500 atoms in one request."""
+        data = await self._request("POST", "/api/v1/memory/write-batch", json={"items": items})
+        return WriteBatchResponse.model_validate(data)
+
+    async def read(
+        self,
+        query: str,
+        *,
+        top_k: int = 10,
+        domain: str | None = None,
+        min_relevance: float = 0.3,
+        include_associations: bool = True,
+        concepts: list[str] | None = None,
+    ) -> ReadResponse:
+        """Query memory with semantic search + Hebbian expansion."""
+        body: dict[str, Any] = {
+            "query": query,
+            "top_k": top_k,
+            "min_relevance": min_relevance,
+            "include_associations": include_associations,
+        }
+        if domain:
+            body["domain"] = domain
+        if concepts:
+            body["concepts"] = concepts
+        data = await self._request("POST", "/api/v1/memory/read", json=body)
+        return ReadResponse.model_validate(data)
+
+    async def feedback(
+        self,
+        atom_ids: list[UUID | str],
+        outcome: float,
+        *,
+        concepts: list[str] | None = None,
+        query_concepts: list[str] | None = None,
+        domain: str = "general",
+    ) -> FeedbackResponse:
+        """Report outcome (success/failure) for memories."""
+        body: dict[str, Any] = {
+            "atom_ids": [str(aid) for aid in atom_ids],
+            "outcome": outcome,
+            "domain": domain,
+        }
+        if concepts:
+            body["concepts"] = concepts
+        if query_concepts:
+            body["query_concepts"] = query_concepts
+        data = await self._request("POST", "/api/v1/memory/feedback", json=body)
+        return FeedbackResponse.model_validate(data)
+
+    async def stats(self) -> StatsResponse:
+        """Get memory statistics."""
+        data = await self._request("GET", "/api/v1/memory/stats")
+        return StatsResponse.model_validate(data)
+
+    async def health(self) -> HealthResponse:
+        """Check API health."""
+        data = await self._request("GET", "/api/v1/health")
+        return HealthResponse.model_validate(data)
+
+    # --- Internal ---
+
+    async def _request(
+        self,
+        method: str,
+        path: str,
+        json: dict[str, Any] | None = None,
+    ) -> Any:
+        if not self._cb.can_execute():
+            raise MnemoUnavailableError(
+                f"Circuit breaker open (state: {self._cb.state})"
+            )
+
+        def is_retryable(e: Exception) -> bool:
+            if isinstance(e, MnemoRateLimitError):
+                return True
+            if isinstance(e, MnemoError) and e.status and e.status >= 500:
+                return True
+            if isinstance(e, (httpx.ConnectError, httpx.TimeoutException)):
+                return True
+            return False
+
+        async def attempt() -> Any:
+            return await self._single_request(method, path, json)
+
+        try:
+            result = await retry_with_backoff(
+                attempt,
+                max_retries=self._max_retries,
+                retryable_check=is_retryable,
+            )
+            self._cb.on_success()
+            return result
+        except (MnemoAuthError, MnemoError) as e:
+            if isinstance(e, MnemoAuthError):
+                raise
+            self._cb.on_failure()
+            raise
+
+    async def _single_request(
+        self,
+        method: str,
+        path: str,
+        json: dict[str, Any] | None = None,
+    ) -> Any:
+        client = self._get_client()
+        try:
+            response = await client.request(method, path, json=json)
+        except httpx.TimeoutException as e:
+            raise MnemoUnavailableError(f"Request timeout after {self._timeout}s", e)
+        except httpx.ConnectError as e:
+            raise MnemoUnavailableError(f"Connection error: {e}", e)
+
+        if response.status_code == 401 or response.status_code == 403:
+            raise MnemoAuthError(self._extract_detail(response))
+
+        if response.status_code == 429:
+            retry_after = response.headers.get("Retry-After")
+            raise MnemoRateLimitError(
+                self._extract_detail(response),
+                retry_after=float(retry_after) if retry_after else None,
+            )
+
+        if response.status_code >= 400:
+            raise MnemoError(self._extract_detail(response), status=response.status_code)
+
+        return response.json()
+
+    @staticmethod
+    def _extract_detail(response: httpx.Response) -> str:
+        try:
+            data = response.json()
+            if isinstance(data, dict):
+                return str(data.get("detail") or data.get("message") or data)
+            return str(data)
+        except Exception:
+            return f"HTTP {response.status_code}"

mnemoverse-0.1.0/mnemoverse/_retry.py

@@ -0,0 +1,74 @@
+"""Retry with exponential backoff and circuit breaker."""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from typing import Any
+
+
+class CircuitBreaker:
+    """Simple circuit breaker: closed → open (after N failures) → half-open (after timeout)."""
+
+    def __init__(self, failure_threshold: int = 5, reset_timeout: float = 30.0) -> None:
+        self._failure_threshold = failure_threshold
+        self._reset_timeout = reset_timeout
+        self._failures = 0
+        self._last_failure_time = 0.0
+        self._state: str = "closed"  # closed | open | half-open
+
+    @property
+    def state(self) -> str:
+        return self._state
+
+    def can_execute(self) -> bool:
+        if self._state == "closed":
+            return True
+        if self._state == "open":
+            if time.monotonic() - self._last_failure_time >= self._reset_timeout:
+                self._state = "half-open"
+                return True
+            return False
+        return False  # half-open: block until probe completes
+
+    def on_success(self) -> None:
+        self._failures = 0
+        self._state = "closed"
+
+    def on_failure(self) -> None:
+        self._failures += 1
+        self._last_failure_time = time.monotonic()
+        if self._failures >= self._failure_threshold:
+            self._state = "open"
+
+
+async def retry_with_backoff(
+    coro_factory: Any,
+    max_retries: int = 3,
+    base_delay: float = 0.1,
+    max_delay: float = 2.0,
+    retryable_check: Any = None,
+) -> Any:
+    """Execute an async callable with exponential backoff.
+
+    Args:
+        coro_factory: Async callable (called each attempt).
+        max_retries: Max retry attempts (total attempts = max_retries + 1).
+        base_delay: Initial backoff delay in seconds.
+        max_delay: Maximum backoff delay in seconds.
+        retryable_check: Optional callable(exception) -> bool.
+    """
+    last_error: Exception | None = None
+
+    for attempt in range(max_retries + 1):
+        try:
+            return await coro_factory()
+        except Exception as e:
+            last_error = e
+            if retryable_check and not retryable_check(e):
+                raise
+            if attempt < max_retries:
+                delay = min(base_delay * (2 ** attempt), max_delay)
+                await asyncio.sleep(delay)
+
+    raise last_error  # type: ignore[misc]

mnemoverse-0.1.0/mnemoverse/client.py

@@ -0,0 +1,128 @@
+"""Synchronous Mnemoverse client — wraps AsyncMnemoClient with asyncio.run()."""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Any
+from uuid import UUID
+
+from mnemoverse._async_client import AsyncMnemoClient
+from mnemoverse.types import (
+    FeedbackResponse,
+    HealthResponse,
+    ReadResponse,
+    StatsResponse,
+    WriteBatchResponse,
+    WriteResponse,
+)
+
+
+class MnemoClient:
+    """Synchronous client for the Mnemoverse Memory API.
+
+    Wraps AsyncMnemoClient for use in scripts, notebooks, and sync applications.
+    For async applications (FastAPI, Discord bots), use AsyncMnemoClient directly.
+
+    Usage:
+        client = MnemoClient(api_key="mk_live_...")
+        result = client.write("Caching reduces latency", concepts=["caching"])
+        memories = client.read("how to reduce latency?")
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = "https://api.mnemoverse.com",
+        timeout: float = 10.0,
+        max_retries: int = 3,
+    ) -> None:
+        self._async_client = AsyncMnemoClient(
+            api_key=api_key,
+            base_url=base_url,
+            timeout=timeout,
+            max_retries=max_retries,
+        )
+
+    def _run(self, coro: Any) -> Any:
+        try:
+            loop = asyncio.get_running_loop()
+        except RuntimeError:
+            loop = None
+
+        if loop and loop.is_running():
+            # Inside an existing event loop (e.g., Jupyter notebook)
+            import concurrent.futures
+            with concurrent.futures.ThreadPoolExecutor(max_workers=1) as pool:
+                return pool.submit(asyncio.run, coro).result()
+        else:
+            return asyncio.run(coro)
+
+    def write(
+        self,
+        content: str,
+        *,
+        concepts: list[str] | None = None,
+        domain: str = "general",
+        metadata: dict[str, Any] | None = None,
+        external_ref: str | None = None,
+    ) -> WriteResponse:
+        """Store a single memory atom."""
+        return self._run(
+            self._async_client.write(
+                content, concepts=concepts, domain=domain,
+                metadata=metadata, external_ref=external_ref,
+            )
+        )
+
+    def write_batch(self, items: list[dict[str, Any]]) -> WriteBatchResponse:
+        """Store up to 500 atoms in one request."""
+        return self._run(self._async_client.write_batch(items))
+
+    def read(
+        self,
+        query: str,
+        *,
+        top_k: int = 10,
+        domain: str | None = None,
+        min_relevance: float = 0.3,
+        include_associations: bool = True,
+        concepts: list[str] | None = None,
+    ) -> ReadResponse:
+        """Query memory with semantic search + Hebbian expansion."""
+        return self._run(
+            self._async_client.read(
+                query, top_k=top_k, domain=domain,
+                min_relevance=min_relevance,
+                include_associations=include_associations,
+                concepts=concepts,
+            )
+        )
+
+    def feedback(
+        self,
+        atom_ids: list[UUID | str],
+        outcome: float,
+        *,
+        concepts: list[str] | None = None,
+        query_concepts: list[str] | None = None,
+        domain: str = "general",
+    ) -> FeedbackResponse:
+        """Report outcome (success/failure) for memories."""
+        return self._run(
+            self._async_client.feedback(
+                atom_ids, outcome, concepts=concepts,
+                query_concepts=query_concepts, domain=domain,
+            )
+        )
+
+    def stats(self) -> StatsResponse:
+        """Get memory statistics."""
+        return self._run(self._async_client.stats())
+
+    def health(self) -> HealthResponse:
+        """Check API health."""
+        return self._run(self._async_client.health())
+
+    def close(self) -> None:
+        """Close the underlying HTTP client."""
+        self._run(self._async_client.close())

mnemoverse-0.1.0/mnemoverse/errors.py

@@ -0,0 +1,35 @@
+"""Mnemoverse SDK error types."""
+
+from __future__ import annotations
+
+
+class MnemoError(Exception):
+    """Base error for all Mnemoverse API errors."""
+
+    def __init__(self, message: str, status: int | None = None) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status = status
+
+
+class MnemoAuthError(MnemoError):
+    """Invalid or missing API key (401/403)."""
+
+    def __init__(self, message: str = "Invalid or missing API key") -> None:
+        super().__init__(message, status=401)
+
+
+class MnemoRateLimitError(MnemoError):
+    """Rate limit exceeded (429)."""
+
+    def __init__(self, message: str = "Rate limit exceeded", retry_after: float | None = None) -> None:
+        super().__init__(message, status=429)
+        self.retry_after = retry_after
+
+
+class MnemoUnavailableError(MnemoError):
+    """Service unreachable — circuit breaker open, network error, or timeout."""
+
+    def __init__(self, message: str, cause: Exception | None = None) -> None:
+        super().__init__(message, status=None)
+        self.__cause__ = cause

mnemoverse-0.1.0/mnemoverse/types.py

@@ -0,0 +1,92 @@
+"""Pydantic models matching mnemoverse-core REST API schemas.
+
+Source of truth: mnemoverse-core/src/mnemo/api/schemas.py
+"""
+
+from __future__ import annotations
+
+from typing import Any
+from uuid import UUID
+
+from pydantic import BaseModel
+
+
+# --- Write ---
+
+
+class WriteResponse(BaseModel):
+    stored: bool
+    atom_id: UUID | None = None
+    importance: float = 0.0
+    reason: str = ""
+
+
+class WriteBatchItemResult(BaseModel):
+    index: int
+    stored: bool
+    atom_id: UUID | None = None
+    importance: float = 0.0
+    error: str | None = None
+
+
+class WriteBatchResponse(BaseModel):
+    total_count: int
+    stored_count: int
+    results: list[WriteBatchItemResult]
+
+
+# --- Read ---
+
+
+class MemoryItem(BaseModel):
+    atom_id: UUID
+    content: str
+    relevance: float
+    similarity: float
+    valence: float
+    importance: float
+    source: str
+    concepts: list[str]
+    domain: str
+    metadata: dict[str, Any] = {}
+
+
+class ReadResponse(BaseModel):
+    items: list[MemoryItem]
+    episodic_hit: bool
+    query_concepts: list[str]
+    expanded_concepts: list[str]
+    search_time_ms: float
+
+
+# --- Feedback ---
+
+
+class FeedbackResponse(BaseModel):
+    updated_count: int
+    avg_valence: float
+    coactivation_edges: int = 0
+
+
+# --- Stats ---
+
+
+class StatsResponse(BaseModel):
+    total_atoms: int
+    episodes: int
+    prototypes: int
+    singletons: int
+    hebbian_edges: int
+    episodic_fingerprints: int
+    domains: list[str]
+    avg_valence: float
+    avg_importance: float
+
+
+# --- Health ---
+
+
+class HealthResponse(BaseModel):
+    status: str
+    database: bool
+    version: str

mnemoverse-0.1.0/pyproject.toml

@@ -0,0 +1,57 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "mnemoverse"
+version = "0.1.0"
+description = "Python SDK for Mnemoverse Memory API — persistent memory for AI agents"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [
+    { name = "Edward Izgorodin", email = "helloworld@uinside.org" },
+]
+keywords = ["ai", "memory", "agents", "llm", "mcp", "hebbian", "cognitive"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Typing :: Typed",
+]
+dependencies = [
+    "httpx>=0.25.0",
+    "pydantic>=2.0.0",
+]
+
+[project.urls]
+Homepage = "https://mnemoverse.com"
+Documentation = "https://mnemoverse.com/docs/api/python-sdk"
+Repository = "https://github.com/mnemoverse/mnemoverse-sdk-python"
+Issues = "https://github.com/mnemoverse/mnemoverse-sdk-python/issues"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.24",
+    "pytest-httpx>=0.30",
+    "ruff>=0.4",
+    "mypy>=1.10",
+]
+
+[tool.ruff]
+target-version = "py310"
+line-length = 100
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"

mnemoverse-0.1.0/tests/test_client.py

@@ -0,0 +1,143 @@
+"""Tests for MnemoClient and AsyncMnemoClient."""
+
+from __future__ import annotations
+
+import pytest
+import httpx
+from pytest_httpx import HTTPXMock
+
+from mnemoverse import AsyncMnemoClient, MnemoAuthError, MnemoRateLimitError
+
+
+@pytest.fixture
+def client():
+    return AsyncMnemoClient(
+        api_key="mk_test_abc123",
+        base_url="https://test.api.mnemoverse.com",
+        timeout=5.0,
+        max_retries=0,  # no retries in tests
+    )
+
+
+async def test_write(client: AsyncMnemoClient, httpx_mock: HTTPXMock):
+    httpx_mock.add_response(
+        url="https://test.api.mnemoverse.com/api/v1/memory/write",
+        json={
+            "stored": True,
+            "atom_id": "550e8400-e29b-41d4-a716-446655440000",
+            "importance": 0.85,
+            "reason": "novel insight",
+        },
+    )
+
+    result = await client.write("test memory", concepts=["test"])
+
+    assert result.stored is True
+    assert str(result.atom_id) == "550e8400-e29b-41d4-a716-446655440000"
+    assert result.importance == 0.85
+
+
+async def test_read(client: AsyncMnemoClient, httpx_mock: HTTPXMock):
+    httpx_mock.add_response(
+        url="https://test.api.mnemoverse.com/api/v1/memory/read",
+        json={
+            "items": [
+                {
+                    "atom_id": "550e8400-e29b-41d4-a716-446655440000",
+                    "content": "test memory",
+                    "relevance": 0.92,
+                    "similarity": 0.87,
+                    "valence": 0.5,
+                    "importance": 0.85,
+                    "source": "semantic",
+                    "concepts": ["test"],
+                    "domain": "general",
+                    "metadata": {},
+                }
+            ],
+            "episodic_hit": False,
+            "query_concepts": ["test"],
+            "expanded_concepts": ["test"],
+            "search_time_ms": 12.5,
+        },
+    )
+
+    result = await client.read("test query")
+
+    assert len(result.items) == 1
+    assert result.items[0].content == "test memory"
+    assert result.search_time_ms == 12.5
+
+
+async def test_feedback(client: AsyncMnemoClient, httpx_mock: HTTPXMock):
+    httpx_mock.add_response(
+        url="https://test.api.mnemoverse.com/api/v1/memory/feedback",
+        json={"updated_count": 1, "avg_valence": 0.8, "coactivation_edges": 3},
+    )
+
+    result = await client.feedback(
+        atom_ids=["550e8400-e29b-41d4-a716-446655440000"],
+        outcome=1.0,
+    )
+
+    assert result.updated_count == 1
+    assert result.avg_valence == 0.8
+
+
+async def test_stats(client: AsyncMnemoClient, httpx_mock: HTTPXMock):
+    httpx_mock.add_response(
+        url="https://test.api.mnemoverse.com/api/v1/memory/stats",
+        json={
+            "total_atoms": 100,
+            "episodes": 80,
+            "prototypes": 15,
+            "singletons": 5,
+            "hebbian_edges": 250,
+            "episodic_fingerprints": 10,
+            "domains": ["general", "engineering"],
+            "avg_valence": 0.3,
+            "avg_importance": 0.6,
+        },
+    )
+
+    result = await client.stats()
+
+    assert result.total_atoms == 100
+    assert "engineering" in result.domains
+
+
+async def test_health(client: AsyncMnemoClient, httpx_mock: HTTPXMock):
+    httpx_mock.add_response(
+        url="https://test.api.mnemoverse.com/api/v1/health",
+        json={"status": "ok", "database": True, "version": "1.0.0"},
+    )
+
+    result = await client.health()
+
+    assert result.status == "ok"
+    assert result.database is True
+
+
+async def test_auth_error(client: AsyncMnemoClient, httpx_mock: HTTPXMock):
+    httpx_mock.add_response(
+        url="https://test.api.mnemoverse.com/api/v1/memory/read",
+        status_code=401,
+        json={"detail": "Invalid API key"},
+    )
+
+    with pytest.raises(MnemoAuthError):
+        await client.read("test")
+
+
+async def test_rate_limit_error(client: AsyncMnemoClient, httpx_mock: HTTPXMock):
+    httpx_mock.add_response(
+        url="https://test.api.mnemoverse.com/api/v1/memory/read",
+        status_code=429,
+        json={"detail": "Rate limit exceeded"},
+        headers={"Retry-After": "60"},
+    )
+
+    with pytest.raises(MnemoRateLimitError) as exc_info:
+        await client.read("test")
+
+    assert exc_info.value.retry_after == 60.0