ai-memory — Python SDK

Typed Python client for the ai-memory HTTP API. Wraps the daemon's /api/v1/ surface with sync and async clients, Pydantic v2 models that mirror the Rust structs, and HMAC-SHA256 webhook verification.

Status: 0.6.0-alpha.0 — scaffolding, unpublished. API may change before GA.

Install

# Not yet published; install from a local checkout:
pip install -e ./sdk/python

Requires Python 3.10+.

Quickstart

from ai_memory import AiMemoryClient, Tier

with AiMemoryClient(base_url="http://localhost:9077") as client:
    created = client.store(
        title="BIND9 build notes",
        content="Use --with-openssl=/opt/openssl, disable DoH for the lab.",
        tier=Tier.LONG,
        tags=["dns", "bind9"],
    )
    print(created["id"])

    hits = client.recall(context="how do I build BIND9?")
    for memory in hits.memories:
        print(memory.title, memory.confidence)

Async

import asyncio
from ai_memory import AsyncAiMemoryClient

async def main() -> None:
    async with AsyncAiMemoryClient(base_url="http://localhost:9077") as client:
        resp = await client.recall(context="hello")
        for memory in resp.memories:
            print(memory.title)

asyncio.run(main())

Authentication

API key

AiMemoryClient(base_url="https://memory.example.com", api_key="sk-...")

The key is sent as the X-API-Key header on every request. The server exempts /api/v1/health from auth.

mTLS

AiMemoryClient(
    base_url="https://memory.example.com",
    verify="/etc/ssl/certs/server-ca.pem",
    cert=("/etc/ssl/client/client.pem", "/etc/ssl/client/client.key"),
)

Agent identity (NHI)

Set agent_id to stamp the X-Agent-Id header on every request. The server writes metadata.agent_id accordingly (see CLAUDE.md §Agent Identity).

AiMemoryClient(base_url="http://localhost:9077", agent_id="ai:claude-opus-4.7@host")

All methods

Webhook verification

from ai_memory import verify_webhook_signature

def handle(request) -> None:
    sig = request.headers["X-AI-Memory-Signature"]
    if not verify_webhook_signature(request.body, sig, secret="..."):
        raise PermissionError("bad signature")
    ...

body must be the raw bytes as received — do not re-encode a parsed JSON payload; whitespace differences will break the HMAC.

Errors

All SDK errors derive from AiMemoryError:

License

Apache-2.0, see LICENSE.