Mnemexa — Python SDK

Official Python SDK for Mnemexa — the Intelligent Memory OS for AI.

pip install mnemexa

Quick start

import mnemexa

client = mnemexa.Client()  # reads MNEMEXA_API_KEY from the environment

# Store a memory
result = client.memory.store(text="The customer's name is Maya.")
print(result.memory_id)

# Retrieve relevant memories
recall = client.memory.retrieve(query="who is the customer?", top_k=3)
for memory in recall.memories:
    print(memory.score, memory.text)

# Check workspace memory health
health = client.optimize.health()
print(f"Quality: {health.quality_score}/100, total: {health.signals.total_memories}")

# Verify the connection / inspect workspace identity
status = client.status()
print(f"Connected to {status.workspace_name} ({status.workspace_status}) on {status.plan_name}")

Async

The same surface is mirrored under mnemexa.AsyncClient:

import asyncio
import mnemexa

async def main() -> None:
    async with mnemexa.AsyncClient() as client:
        result = await client.memory.store(text="The customer's name is Maya.")
        print(result.memory_id)

asyncio.run(main())

Configuration

All client kwargs are optional. Precedence is explicit kwarg > environment variable > default.

Setting	Constructor arg	Env var	Default
API key	api_key=	MNEMEXA_API_KEY (falls back to BIZX_API_KEY)	raises AuthenticationError
Base URL	base_url=	MNEMEXA_BASE_URL (falls back to BIZX_BASE_URL)	https://api.mnemexa.com
Timeout	timeout=	—	30.0 seconds
Max retries	max_retries=	—	2

client = mnemexa.Client(
    api_key="mnx_...",
    base_url="https://api.mnemexa.com",
    timeout=15.0,
    max_retries=3,
)

Endpoints

The SDK currently wraps four endpoints — full API documentation lives at docs.mnemexa.com.

Resource	Method	Returns
client.memory.store(text, meta)	POST /v1/memory/store	MemoryStoreResponse
client.memory.retrieve(query, top_k, min_score)	POST /v1/memory/retrieve	MemoryRetrieveResponse
client.optimize.health()	GET /v1/optimize/health	OptimizeHealthResponse
client.status()	GET /v1/status	StatusResponse

All response objects are Pydantic models with extra="allow" — future server-side fields surface automatically without breaking your code.

Error handling

Every error raised by the SDK inherits from mnemexa.MnemexaError. The hierarchy maps HTTP status codes to typed exceptions you can catch precisely:

import mnemexa

try:
    client.memory.store(text="...")
except mnemexa.AuthenticationError:    # 401 — invalid API key
    ...
except mnemexa.PermissionError:        # 403 — suspended workspace
    ...
except mnemexa.ValidationError:        # 422 — bad request body
    ...
except mnemexa.RateLimitError as e:    # 429 — back off and retry
    print(f"Retry after {e.retry_after}s")
except mnemexa.ServiceUnavailableError:  # 5xx — backend transient
    ...
except mnemexa.MnemexaError as e:      # catch-all
    print(e.request_id)  # always populated when available

Every error carries status_code, request_id, and the parsed response body for easy support escalation.

Retry policy

The SDK auto-retries with exponential backoff (capped at 8 seconds) on:

• Network errors and timeouts
• HTTP 502, 503, 504

The SDK never auto-retries 401, 403, 404, 422, or 429. For 429, inspect RateLimitError.retry_after and back off on your own schedule.

Logging

The SDK logs to a logger named mnemexa. By default no handler is attached — the host application's logging configuration is respected. Auth headers are always redacted from log lines.

import logging
logging.getLogger("mnemexa").setLevel(logging.DEBUG)

Links

• Homepage: mnemexa.com
• Documentation: docs.mnemexa.com
• Source: github.com/mnemexa/python
• Issues: github.com/mnemexa/python/issues
• Changelog: CHANGELOG.md

License

MIT