> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mengram.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Async Client

> Non-blocking Python client built on httpx for async/await workflows.

## Installation

```bash theme={null}
pip install mengram-ai[async]
```

This installs `httpx` for non-blocking HTTP.

## Initialize

```python theme={null}
from mengram import AsyncMengram

m = AsyncMengram(api_key="om-your-key")

# Or use environment variable
m = AsyncMengram()
```

## Context Manager

```python theme={null}
async with AsyncMengram() as m:
    results = await m.search("deployment")
    profile = await m.get_profile()
# Client automatically closed
```

## All Methods

Every method is async and must be `await`-ed:

```python theme={null}
import asyncio
from mengram import AsyncMengram

async def main():
    m = AsyncMengram()

    # Add memories
    result = await m.add([
        {"role": "user", "content": "Deployed on Railway with PostgreSQL"},
    ])

    # Upload a file (PDF, DOCX, TXT, MD)
    await m.add_file("meeting-notes.pdf")

    # Search
    results = await m.search("deployment")

    # Unified search
    all_results = await m.search_all("issues")

    # Profile
    profile = await m.get_profile()

    # Episodes & procedures
    events = await m.episodes(query="deployment")
    procs = await m.procedures(query="deploy")

    # Feedback
    await m.procedure_feedback(proc_id, success=True)

    # Graph & timeline
    graph = await m.graph()
    facts = await m.timeline(after="2026-01-01")

    # Agents & insights
    await m.run_agents()
    await m.reflect()
    insights = await m.insights()

    # Memory management
    await m.dedup()
    await m.merge("source", "target")
    await m.archive_fact("Entity", "old fact")

    # Triggers
    triggers = await m.get_triggers()

    # Webhooks
    await m.create_webhook(url="https://example.com/hook")
    hooks = await m.get_webhooks()

    # Jobs
    status = await m.job_status("job-abc")
    result = await m.wait_for_job("job-abc")

    # Close when done
    await m.close()

asyncio.run(main())
```

## Available Methods

| Method | Description |
| - | - |
| `add(messages, ...)` | Add memories from conversation |
| `add_text(text, ...)` | Add memories from plain text |
| `add_file(file_path, ...)` | Upload file (PDF, DOCX, TXT, MD) |
| `search(query, ...)` | Semantic search |
| `search_all(query, ...)` | Unified search (all 3 types) |
| `get_all(...)` | List all entities |
| `get(name, ...)` | Get specific entity |
| `delete(name, ...)` | Delete entity |
| `stats(...)` | Usage statistics |
| `get_profile(...)` | Cognitive Profile |
| `episodes(...)` | Episodic memories |
| `procedures(...)` | Procedural memories |
| `procedure_feedback(id, ...)` | Record success/failure |
| `graph(...)` | Knowledge graph |
| `timeline(...)` | Temporal search |
| `run_agents(...)` | Run memory agents |
| `reflect(...)` | Trigger reflection |
| `insights(...)` | Get AI insights |
| `dedup(...)` | Deduplicate entities |
| `merge(src, target, ...)` | Merge entities |
| `archive_fact(entity, fact, ...)` | Archive a fact |
| `get_triggers(...)` | Get smart triggers |
| `create_webhook(url, ...)` | Create webhook |
| `get_webhooks()` | List webhooks |
| `job_status(id)` | Check job status |
| `wait_for_job(id, ...)` | Poll until job completes |

## Retry & Error Handling

The async client automatically retries on transient errors (429, 502, 503, 504) and network failures, with exponential backoff up to 3 attempts. **402 (quota exceeded) is never retried** — it raises `QuotaExceededError` immediately.

```python theme={null}
from mengram import AsyncMengram
from mengram.cloud.async_client import QuotaExceededError

async def safe_add(m, messages):
    try:
        return await m.add(messages)
    except QuotaExceededError as e:
        print(f"Quota hit: {e.action} {e.current}/{e.limit} ({e.plan})")
        # e.action = "add" | "search" | "add_file"
        # e.plan = "free" | "starter" | "pro"
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.