mnemosyne-sdk

The official Python client for the Mnemosyne memory substrate. Synchronous and async APIs, container-scoped storage, hybrid BM25+vector recall, full type stubs. Talks to any Mnemosyne endpoint over HTTPS via httpx.

Mnemosyne gives any AI system persistent identity, episodic recall, contradiction resolution, metacognition, and a self-model that compounds across sessions. This SDK is the thin HTTP client that talks to a Mnemosyne Cloud or self-hosted Mnemosyne instance.

Install

pip install mnemosyne-sdk
# or
uv add mnemosyne-sdk
# or
poetry add mnemosyne-sdk

Quick start

from mnemosyne_sdk import Mnemosyne

mn = Mnemosyne(
    api_key="mn_...",  # from your Mnemosyne dashboard
    # base_url="https://api.mnemosyne.geasslabs.xyz",  # default
)

# Save a memory
memory = mn.add(
    "The dock-A camera lost calibration at 14:32 UTC",
    container_tag="fleet-ops",
    metadata={"severity": "high"},
)
print(memory.id)

# Search
results = mn.search("when did dock A fail?", container_tag="fleet-ops")
for r in results:
    print(f"{r.score:.3f}  {r.content}")

# Get / delete
one = mn.get(memory.id)
mn.delete(memory.id)

Async client

import asyncio
from mnemosyne_sdk import AsyncMnemosyne

async def main():
    async with AsyncMnemosyne(api_key="mn_...") as mn:
        await mn.add("...", container_tag="fleet-ops")
        results = await mn.search("query", container_tag="fleet-ops")

asyncio.run(main())

The async client shares the same httpx connection pool and is recommended for high-throughput agents.

Function-calling tools

from mnemosyne_sdk import TOOLS, execute_tool

# Pass TOOLS to any OpenAI-compatible function-calling API
response = client.chat.completions.create(
    model="gpt-4",
    messages=[...],
    tools=TOOLS,
)

# Execute a tool call from the model's response
for call in response.choices[0].message.tool_calls:
    result = execute_tool(
        call.function.name,
        call.function.arguments,
        base_url="https://api.mnemosyne.geasslabs.xyz",
        api_key="mn_...",
    )

Framework adapters

This package is the core client. For framework-specific integrations, install one of the dedicated adapter packages:

Or install everything: pip install mnemosyne-sdk[all].

Error handling

from mnemosyne_sdk import Mnemosyne, AuthenticationError, RateLimitError

mn = Mnemosyne(api_key="...")

try:
    mn.add("...")
except AuthenticationError:
    ...  # bad API key
except RateLimitError as e:
    time.sleep(e.retry_after or 1)
    ...  # back off

All errors inherit from MnemosyneError.

Configuration

Development

git clone https://github.com/synet-systems/mnemosyne
cd mnemosyne/packages/mnemosyne-sdk-python
uv sync --all-extras
uv run pytest

License

MIT © Geass Labs. The Mnemosyne engine this SDK talks to is licensed under the Mnemosyne Source-Available License v1.0. See NOTICE for the dual-license arrangement.

Links

• Homepage: https://mnemosyne.geasslabs.xyz
• Documentation: https://docs.geasslabs.xyz/mnemosyne-sdk
• Repository: https://github.com/synet-systems/mnemosyne
• Issues: https://github.com/synet-systems/mnemosyne/issues
• Changelog: CHANGELOG.md