Metadata-Version: 2.4
Name: anansi-memory
Version: 0.1.0
Summary: The memory layer for AI apps — persistent, synthesized context for any LLM application
Project-URL: Homepage, https://zazzy.app
Project-URL: Repository, https://github.com/JibrilSul/zazzy
Author-email: Anansi <hello@zazzy.app>
License: MIT
Keywords: ai,anansi,context,llm,memory,rag,vector
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: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# anansi-memory

The memory layer for AI apps. Give any LLM application persistent, synthesized memory in two API calls.

```bash
pip install anansi-memory
```

## Usage

```python
from anansi_memory import AnansiMemory

memory = AnansiMemory(api_key="zzy_...")

# Store a conversation turn
memory.ingest(
    user_id="user_123",
    content="User is building a voice agent. Prefers TypeScript. Team of 4.",
    source_type="conversation",
)

# Before your next LLM call — inject synthesized context into system prompt
ctx = memory.context(user_id="user_123", q="what is the user building?")
system_prompt = f"You are a helpful assistant.\n\n{ctx.format_for_prompt()}"
```

## API

### `AnansiMemory(api_key, base_url=None)`

| Param | Type | Description |
|---|---|---|
| `api_key` | `str` | Your API key (`zzy_...`) |
| `base_url` | `str` | Override API base URL (default: `https://api.zazzy.app`) |

### `memory.ingest(user_id, content, source_type=None, source_id=None, metadata=None)`

Store content in a user's memory. Returns `IngestResult(id, queued=True)`.

| Param | Type | Required | Description |
|---|---|---|---|
| `user_id` | `str` | ✓ | Your internal user ID |
| `content` | `str` | ✓ | Text to remember, max 100 KB |
| `source_type` | `str` | | `"conversation"`, `"document"`, `"note"`, `"meeting"`, `"custom"` |
| `source_id` | `str` | | Idempotency key — re-ingesting the same ID is a no-op |
| `metadata` | `dict` | | `title`, `author`, `timestamp`, any custom fields |

### `memory.context(user_id, q=None)`

Retrieve synthesized memory for a user. Returns `ContextResult(static, dynamic, relevant)`.

| Param | Type | Required | Description |
|---|---|---|---|
| `user_id` | `str` | ✓ | Your internal user ID |
| `q` | `str` | | Optional query to retrieve relevant chunks |

### `ctx.format_for_prompt()`

Format a context result into a ready-to-inject system prompt block (string).

## Error handling

```python
from anansi_memory import AnansiMemory, AnansiError

try:
    memory.ingest(user_id=user_id, content=content)
except AnansiError as e:
    print(e.status_code, e.args[0])
    # 401 — invalid API key
    # 402 — monthly quota exceeded
    # 413 — content too large
    # 429 — rate limit (retry after 60s)
```

## Requirements

Python 3.9+. No external dependencies — uses stdlib `urllib` only.

## Links

- [Developer Portal](https://api.zazzy.app/portal)
- [API Docs](https://api.zazzy.app/docs)
- [GitHub](https://github.com/JibrilSul/zazzy)
