Python SDK

The official Python client for Mnemexa. Sync and async clients, Pydantic-typed responses, automatic retries with exponential backoff, Python 3.9 through 3.13.

Install

pip install mnemexa

Latest published version: mnemexa==0.1.1.

Quick example

import mnemexa

# Reads MNEMEXA_API_KEY from environment if not passed explicitly
client = mnemexa.Client()

# 1. Verify connection
status = client.status()
print(f"Connected to {status.workspace_name} ({status.workspace_status})")

# 2. Store a memory
result = client.memory.store(
    text="Client prefers async standups on Tuesdays at 9am IST.",
    meta={"source": "kickoff_meeting"},
)
print(f"stored: id={result.memory_id} importance={result.importance}")

# 3. Retrieve relevant memories
hits = client.memory.retrieve(query="communication preferences", top_k=5)
for m in hits.memories:
    print(f"[{m.score:.3f}] {m.text}")

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

The four methods

The Python SDK mirrors the Core API endpoint-for-endpoint:

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

Configuration

All Client(...) arguments are optional. The precedence chain is explicit kwarg → env var → default:

client = mnemexa.Client(
    api_key="mnx_ws_…",
    timeout=60.0,
    max_retries=3,
)

Async client

AsyncClient mirrors Client exactly — same constructor args, same methods, same response types. Every call is awaitable.

import asyncio
import mnemexa

async def main():
    async with mnemexa.AsyncClient() as client:
        result = await client.memory.store(text="Async memory.")
        hits = await client.memory.retrieve(query="memory", top_k=3)
        print(result.memory_id, len(hits.memories))

asyncio.run(main())

Context managers

Both clients support context-manager use to release the underlying HTTP connection pool cleanly:

with mnemexa.Client() as client:
    client.memory.store(text="…")

async with mnemexa.AsyncClient() as client:
    await client.memory.store(text="…")

Errors

Every error raised by the SDK inherits from mnemexa.MnemexaError:

import mnemexa

try:
    client.memory.store(text="…")
except mnemexa.AuthenticationError:     # 401 — invalid or missing API key
    ...
except mnemexa.PermissionError:         # 403 — workspace suspended or deleted
    ...
except mnemexa.NotFoundError:           # 404
    ...
except mnemexa.ValidationError:         # 422 — backend rejected the payload
    ...
except mnemexa.RateLimitError as exc:   # 429 — back off
    print(f"retry after {exc.retry_after} seconds")
except mnemexa.ServiceUnavailableError: # 502/503/504 — temporary backend issue
    ...
except mnemexa.MnemexaError as exc:     # any other API failure
    print(exc.status_code, exc.request_id, exc.body)

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

Retry behaviour

By default the SDK retries 502, 503, 504, and network errors up to max_retries=2 times (3 total attempts) with exponential backoff plus jitter. It never retries:

• 401 (auth) — your key won’t suddenly become valid.
• 403 (permission) — same reason.
• 404 (not found).
• 422 (validation) — your payload is malformed; retrying won’t fix it.
• 429 (rate limit) — the SDK raises RateLimitError with retry_after set, so your code can decide what to do.

Telemetry

Logs emit on the "mnemexa" logger:

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

The Authorization header is always redacted in log lines.

Resources

• Repository: github.com/mnemexa/python
• Issues: github.com/mnemexa/python/issues
• Changelog: Changelog
• PyPI: pypi.org/project/mnemexa