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

Method	Endpoint	Notes
`health()`	`GET /api/v1/health`	Exempt from auth.
`metrics()`	`GET /api/v1/metrics`	Prometheus text format.
`store(...)`	`POST /api/v1/memories`	Upsert on `(title, namespace)`.
`bulk_store([...])`	`POST /api/v1/memories/bulk`	Up to 1000 per call.
`get(id)`	`GET /api/v1/memories/{id}`	Returns `Memory`.
`update(id, UpdateMemory)`	`PUT /api/v1/memories/{id}`	Partial update.
`delete(id)`	`DELETE /api/v1/memories/{id}`
`promote(id)`	`POST /api/v1/memories/{id}/promote`	Tier -> `long`.
`list(...)`	`GET /api/v1/memories`	Filters: namespace, tier, tags, agent_id.
`search(q, ...)`	`GET /api/v1/search`	FTS AND search.
`recall(context, ...)`	`POST /api/v1/recall`	Hybrid semantic + FTS.
`forget(...)`	`POST /api/v1/forget`	Bulk delete by pattern.
`link(a, b, relation)`	`POST /api/v1/links`	`related_to`, `supersedes`, `contradicts`, `derived_from`.
`get_links(id)`	`GET /api/v1/links/{id}`
`stats()`	`GET /api/v1/stats`
`namespaces()`	`GET /api/v1/namespaces`
`gc()`	`POST /api/v1/gc`
`export()` / `import_()`	`GET` / `POST /api/v1/export	import`
`subscribe(req)` / `unsubscribe(id)` / `subscriptions()`	`/api/v1/subscriptions`	Webhook mgmt.
`notify(req)` / `inbox(...)`	`/api/v1/notify`, `/api/v1/inbox`	Agent-to-agent messaging.
`grant(id, agent)` / `revoke(id, agent)`	`/api/v1/memories/{id}/grant	revoke`
`cluster(req)`	`POST /api/v1/cluster`	Peer management.
`agents()` / `register_agent(...)`	`/api/v1/agents`	NHI registry.

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:

Exception	HTTP
`ValidationError`	400
`AuthError`	401
`ForbiddenError`	403
`NotFoundError`	404
`ConflictError`	409
`RateLimitError`	429
`ServerError`	5xx
`TransportError`	network failure

License

Apache-2.0, see LICENSE.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

ai_memory_mcp-0.8.1.tar.gz (20.9 kB view details)

Uploaded Jun 29, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

ai_memory_mcp-0.8.1-py3-none-any.whl (21.2 kB view details)

Uploaded Jun 29, 2026 Python 3

File details

Details for the file ai_memory_mcp-0.8.1.tar.gz.

File metadata

Download URL: ai_memory_mcp-0.8.1.tar.gz
Upload date: Jun 29, 2026
Size: 20.9 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for ai_memory_mcp-0.8.1.tar.gz
Algorithm	Hash digest
SHA256	`f9cb2268aaf5f24a66866e947f57da3d8c5c58d4dc97538cbe6208cd7177af4d`
MD5	`7b8a4a6cc10c350b30e1955190190da8`
BLAKE2b-256	`8f7dd192cb63aa5ffd2a7060613bfbee82bc696d3331bd141c502bbbc81fb74d`

See more details on using hashes here.

Provenance

The following attestation bundles were made for ai_memory_mcp-0.8.1.tar.gz:

Publisher: publish-sdks.yml on alphaonedev/ai-memory-mcp

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: ai_memory_mcp-0.8.1.tar.gz
- Subject digest: f9cb2268aaf5f24a66866e947f57da3d8c5c58d4dc97538cbe6208cd7177af4d
- Sigstore transparency entry: 2012576349
- Sigstore integration time: Jun 29, 2026
Source repository:
- Permalink: alphaonedev/ai-memory-mcp@08f4e2500eb1eb865c6c8960df9e57783b23c506
- Branch / Tag: refs/heads/release/v0.8.1
- Owner: https://github.com/alphaonedev
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: publish-sdks.yml@08f4e2500eb1eb865c6c8960df9e57783b23c506
- Trigger Event: workflow_dispatch

File details

Details for the file ai_memory_mcp-0.8.1-py3-none-any.whl.

File metadata

Download URL: ai_memory_mcp-0.8.1-py3-none-any.whl
Upload date: Jun 29, 2026
Size: 21.2 kB
Tags: Python 3
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for ai_memory_mcp-0.8.1-py3-none-any.whl
Algorithm	Hash digest
SHA256	`1c64fa8037059cfc6eae324731fddf788a0c96d92996415a50a9b0b4119e5538`
MD5	`4c5376e58c688243fefbdd538ef0699e`
BLAKE2b-256	`827beaeeeddcac198148fbce73de8d7ff26d7ed29cb2a4d3c27da5d9b716a660`

See more details on using hashes here.

Provenance

The following attestation bundles were made for ai_memory_mcp-0.8.1-py3-none-any.whl:

Publisher: publish-sdks.yml on alphaonedev/ai-memory-mcp

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: ai_memory_mcp-0.8.1-py3-none-any.whl
- Subject digest: 1c64fa8037059cfc6eae324731fddf788a0c96d92996415a50a9b0b4119e5538
- Sigstore transparency entry: 2012576367
- Sigstore integration time: Jun 29, 2026
Source repository:
- Permalink: alphaonedev/ai-memory-mcp@08f4e2500eb1eb865c6c8960df9e57783b23c506
- Branch / Tag: refs/heads/release/v0.8.1
- Owner: https://github.com/alphaonedev
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: publish-sdks.yml@08f4e2500eb1eb865c6c8960df9e57783b23c506
- Trigger Event: workflow_dispatch

Release history Release notifications | RSS feed

0.10.0

Jul 12, 2026

0.9.0.post1

Jul 8, 2026

This release

0.8.1

Jun 29, 2026

0.8.0

Jun 25, 2026

0.7.1

Jun 15, 2026

0.7.0

May 15, 2026

0.6.4

May 5, 2026

ai-memory-mcp 0.8.1

ai-memory — Python SDK

Install

Quickstart

Async

Authentication

API key

mTLS

Agent identity (NHI)

All methods

Webhook verification

Errors

License

Project links

Key dates

1 maintainer

Credits

GitHub Statistics

License

Requires

Provides Extra

Tags

Classifiers

Download files

Source Distribution

Built Distribution

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

Release history Release notifications | RSS feed