Mnemoverse Python SDK

Hosted AI agent memory that learns from outcomes, from Python. mnemoverse is a sync and async client for the Mnemoverse REST API: write memories, search them with a natural-language query, and report whether a recalled memory helped or misled, which re-ranks what comes back next. graph() reads the association edges around given concepts. Shared rooms (beta) use the same calls: pass a room's xroom: address as domain to write to it or read it.

The SDK does not create, invite to or join rooms. Those are tools of the Mnemoverse MCP server, which also connects Claude, Cursor and ChatGPT to the same memory.

Installation

pip install mnemoverse

Quick Start

export MNEMOVERSE_API_KEY=mk_live_YOUR_KEY

Check the key in one command. It reads the same variable the client reads (in PowerShell, write $env:MNEMOVERSE_API_KEY and type curl.exe):

curl -s -H "X-Api-Key: $MNEMOVERSE_API_KEY" https://core.mnemoverse.com/api/v1/memory/stats

from mnemoverse import MnemoClient

client = MnemoClient()
# or pass it explicitly — an explicit api_key always wins over the environment:
# 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"]
)

# Search by natural-language query
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
)

Closing the client

MnemoClient holds a background event loop and a pooled HTTP connection, so close it when a script is done. Use it as a context manager, with MnemoClient() as client:, to close automatically on exit, or call client.close() directly. A client left unclosed closes itself at interpreter exit, which is a fallback rather than something to rely on.

Async Client

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

Every method exists on both MnemoClient (sync) and AsyncMnemoClient (async).

Search or feed?

read() answers what do I know about X and ranks by relevance. recent() answers what happened lately and is complete within one scope by construction — nothing is skipped, which a ranked search cannot promise. Reach for recent() to resume after a break or to catch up on a shared room.

from mnemoverse import MnemoClient

client = MnemoClient(api_key="mk_live_...")

# Catch up on a shared room. Rooms are SEPARATE stores: pass the address as
# `domain`, or an unscoped feed will not cover them.
page = client.recent(domain="xroom:room_01ABC", since="2026-08-01T00:00:00Z", limit=20)
for item in page.items:
    print(item.created_at, item.content)

if page.next_cursor:
    page = client.recent(domain="xroom:room_01ABC", cursor=page.next_cursor)

Read items carry created_at and provenance (who wrote it, where from).

Documentation

• Getting Started
• API Reference
• Python SDK Docs

License

MIT