semvec/pypi-packages huggingface dataset:
openengram 0.1.0
Python SDK for the Engram memory API
Requires Python: >=3.10
Keywords: agent, ai, context, engram, llm, memory

# openengram

Python SDK for the [Engram](https://openengram.ai) memory API — persistent memory for AI agents.

## Installation

```bash
pip install openengram
```

## Quick Start

```python
from openengram import Engram

engram = Engram(api_key="ek_...", user_id="user_beaux")

# Store a memory
memory = engram.remember("User prefers dark mode and uses vim")

# Search memories
results = engram.search("What editor does the user prefer?")
for m in results.memories:
    print(m.raw)

# Load context for a session
ctx = engram.context(max_tokens=2000)
print(ctx.context)

# Get a specific memory
memory = engram.get(memory.id)

# Update a memory
engram.update(memory.id, raw="User prefers dark mode and uses neovim")

# Delete a memory
engram.forget(memory.id)
```

## Configuration

| Parameter  | Env Var           | Default                       |
|------------|-------------------|-------------------------------|
| `api_key`  | `ENGRAM_API_KEY`  | —                             |
| `user_id`  | `ENGRAM_USER_ID`  | —                             |
| `base_url` | `ENGRAM_BASE_URL` | `https://api.openengram.ai`   |

```python
# Using environment variables
import os
os.environ["ENGRAM_API_KEY"] = "ek_..."
os.environ["ENGRAM_USER_ID"] = "user_beaux"

engram = Engram()  # picks up env vars automatically
```

## Async Support

```python
from openengram import AsyncEngram

async def main():
    async with AsyncEngram(api_key="ek_...") as engram:
        memory = await engram.remember("User likes async Python")
        results = await engram.search("async")
```

## Memory Layers

Memories are organized into layers:

- **SESSION** — Short-lived, conversation-scoped
- **PROJECT** — Project-specific context
- **IDENTITY** — Long-term user preferences and facts
- **TASK** — Task-specific context

```python
from openengram import MemoryLayer

engram.remember(
    "User's favorite color is blue",
    layer=MemoryLayer.IDENTITY,
)

results = engram.search("color", layers=[MemoryLayer.IDENTITY])
```

## Feedback

Help improve memory relevance with feedback signals:

```python
engram.mark_used(memory.id)      # implicit signal
engram.mark_helpful(memory.id)   # explicit signal
```

## Error Handling

```python
from openengram import NotFoundError, RateLimitError

try:
    memory = engram.get("nonexistent-id")
except NotFoundError:
    print("Memory not found")
except RateLimitError:
    print("Slow down!")
```

## License

Apache 2.0