Metadata-Version: 2.4
Name: engrammemory-ai
Version: 0.1.3
Summary: Memory infrastructure for AI agents. Your Qdrant, your hardware, our intelligence.
Project-URL: Homepage, https://engrammemory.ai
Project-URL: Documentation, https://engrammemory.ai/docs
Project-URL: Repository, https://github.com/EngramMemory/engrammemory-python
Project-URL: Issues, https://github.com/EngramMemory/engrammemory-python/issues
Author-email: Engram Memory <hello@engrammemory.ai>
License: MIT
Keywords: agents,ai,embeddings,llm,mcp,memory,openclaw,qdrant,rag
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.9
Requires-Dist: httpx>=0.25.0
Provides-Extra: async
Requires-Dist: httpx[http2]>=0.25.0; extra == 'async'
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Description-Content-Type: text/markdown

<div align="center">

<img src="https://raw.githubusercontent.com/EngramMemory/engram-memory-community/main/assets/logo.svg" alt="Engram Memory" width="360" />

**Memory infrastructure for AI agents. Your Qdrant, your hardware, our intelligence.**

[npm](https://www.npmjs.com/package/engrammemory-ai) · [Dashboard](https://app.engrammemory.ai) · [API Docs](https://api.engrammemory.ai/docs) · [Community Edition](https://github.com/EngramMemory/engram-memory-community)

![pypi](https://img.shields.io/pypi/v/engrammemory-ai?label=pypi&color=10b981&style=flat-square)
![npm](https://img.shields.io/npm/v/engrammemory-ai?label=npm&color=10b981&style=flat-square)
![license](https://img.shields.io/badge/license-MIT-green?style=flat-square)

</div>

```bash
pip install engrammemory-ai
```

## Quick Start

```python
from engrammemory import Engram

client = Engram(
    api_key="eng_live_xxx",
    qdrant_url="http://localhost:6333"
)

# Store — embedded & deduplicated by Engram, stored in YOUR Qdrant
client.store("User prefers TypeScript and dark mode", category="preference")

# Search — three-tier recall (hot → hash → vector)
results = client.search("What does the user prefer?")
for r in results:
    print(f"[{r.tier}] {r.content} ({r.score:.2f})")

# Forget
client.forget("mem_abc123")
```

## Why Engram?

| | **Engram** | Mem0 | Supermemory | Zep |
|---|---|---|---|---|
| Data ownership | Your Qdrant, your hardware | Their cloud | Their cloud | Their cloud |
| Three-tier recall | Hot → Hash → Vector | Single-tier | Single-tier | Two-tier |
| Stateless intelligence | Embeds + classifies, never stores | Stores everything | Stores everything | Stores everything |
| Edge/fleet support | Per-device agents, zone isolation | No | No | Limited |
| Local-first + overflow | Store locally, overflow to cloud | Cloud only | Cloud only | Cloud only |
| Open community edition | OpenClaw skill, full recall engine | No | Partial | No |

## Three-Tier Recall

Every search flows through three tiers automatically:

```python
results = client.search("database config")
for r in results:
    print(f"[{r.tier}] {r.content} ({r.score:.2f})")
    # [hot]    PostgreSQL 15 with read replicas (0.94)   — sub-ms, cached
    # [hash]   Migrated from MongoDB last quarter (0.81)  — O(1) LSH lookup
    # [vector] Old DB credentials in vault (0.67)         — full ANN fallback
```

## Auto-Recall for Agent Prompts

```python
# Inject relevant memories into your agent's system prompt
memories = client.recall("User is asking about their database setup")
system_prompt = f"You know: {', '.join(m.content for m in memories)}"
```

## Async

```python
from engrammemory import AsyncEngram

async with AsyncEngram(api_key="eng_live_xxx") as client:
    await client.store("User prefers TypeScript")
    results = await client.search("language preferences")
```

## Multi-Agent / Fleet

```python
# Each agent gets its own namespace
client = Engram(api_key="eng_live_xxx", project="icu-floor-3")

# Store with agent tracking
client.store("Patient allergic to penicillin", category="fact", agent="tablet-icu-3a")

# Search scoped to project
results = client.search("allergies", agent="tablet-icu-3a")
```

## API Reference

### Constructor

```python
Engram(
    api_key: str,                          # Your Engram API key
    qdrant_url: str = "http://localhost:6333",  # Your Qdrant instance
    base_url: str = "https://api.engrammemory.ai",
    collection: str = "agent-memory",
    project: str | None = None,            # Memory isolation namespace
    max_retries: int = 3,
    timeout: float = 30.0,
)
```

### Methods

| Method | Description |
|---|---|
| `store(content, category?, importance?, metadata?, agent?)` | Store a memory (embedded + deduplicated + compressed) |
| `search(query, limit?, min_score?, category?, agent?)` | Three-tier recall: hot → hash → vector |
| `recall(context, top_k?, agent?)` | Auto-inject relevant memories for agent prompts |
| `get(memory_id)` | Get a specific memory by ID |
| `forget(memory_id)` | Remove from all three tiers |
| `forget_by_query(query)` | Forget memories matching a search |
| `list(limit?, offset?, category?, agent?)` | List memories with filtering |
| `health()` | Check Engram + Qdrant connectivity |

### Models

```python
from engrammemory import Memory, SearchResult, StoreResult, HealthStatus
```

| Model | Fields |
|---|---|
| `Memory` | `id`, `content`, `category`, `metadata`, `created_at`, `access_count` |
| `SearchResult` | `memory`, `score`, `tier` (`"hot"`, `"hash"`, `"vector"`) |
| `StoreResult` | `id`, `stored`, `deduplicated` |
| `HealthStatus` | `status`, `qdrant_connected`, `version` |

### Exceptions

```python
from engrammemory import EngramError, AuthenticationError, RateLimitError, NotFoundError, ValidationError
```

| Exception | HTTP Code | When |
|---|---|---|
| `AuthenticationError` | 401 | Invalid or missing API key |
| `RateLimitError` | 429 | Too many requests (auto-retries with Retry-After) |
| `NotFoundError` | 404 | Memory ID doesn't exist |
| `ValidationError` | 400/422 | Invalid request body |
| `EngramError` | Other | Base class for all errors |

## Community Edition

Don't need cloud? The [community edition](https://github.com/EngramMemory/engram-memory-community) runs the full three-tier recall engine locally as an OpenClaw skill with no API dependency.

## Links

- [Node SDK](https://www.npmjs.com/package/engrammemory-ai) — `npm install engrammemory-ai`
- [Dashboard](https://app.engrammemory.ai)
- [API Docs](https://api.engrammemory.ai/docs)
- [GitHub](https://github.com/EngramMemory)
- [Community Edition](https://github.com/EngramMemory/engram-memory-community)
