Metadata-Version: 2.4
Name: hmc-memory
Version: 2.1.0
Summary: Long-term memory for AI agents. Your AI never forgets.
Author-email: MemoryAI <hello@memoryai.dev>
License: MIT
Project-URL: Homepage, https://memoryai.dev
Project-URL: Documentation, https://memoryai.dev/docs.html
Project-URL: Repository, https://github.com/memoryai/memoryai-python
Keywords: ai,memory,llm,agent,persistent-memory,context
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# MemoryAI — Long-term Memory for AI Agents

> Your AI never forgets. Preferences, decisions, context — remembered forever.

## Install

```bash
pip install memoryai
```

## Quick Start

```python
from memoryai import MemoryAI

mem = MemoryAI(api_key="hm_sk_your_key")

# Store a memory
mem.store("User prefers dark mode", memory_type="preference")

# Recall
results = mem.recall("what does user prefer")
for r in results:
    print(f"[{r['score']:.0%}] {r['content']}")

# Bootstrap (start of session)
context = mem.bootstrap("working on payment feature")
# → Returns ~800 token context block with identity + mood + goals

# Save (end of session)
mem.save("Built payment API with Stripe. User decided on webhook approach.")

# Profile
profile = mem.profile()
print(profile["persona"])
print(profile["mood"])
```

## API

### `MemoryAI(api_key, endpoint, timeout, graceful)`

| Param | Default | Description |
|-------|---------|-------------|
| `api_key` | required | Your API key (`hm_sk_...`) |
| `endpoint` | `https://memoryai.dev` | API endpoint |
| `timeout` | `30` | Request timeout (seconds) |
| `graceful` | `False` | Never raise errors, return empty instead |

### Methods

| Method | Description |
|--------|-------------|
| `store(content, memory_type, tags)` | Store a memory |
| `recall(query, limit, depth, since)` | Search memories |
| `bootstrap(task, mode)` | Wake up with context (session start) |
| `save(content)` | Save session summary (session end) |
| `profile()` | Get cognitive profile (persona, mood, goals) |
| `health()` | Check memory stats |
| `guard_check(tokens, max_tokens)` | Check context pressure |

### Memory Types

| Type | Lifespan | Use for |
|------|----------|---------|
| `preference` | Forever | User likes/dislikes |
| `decision` | Forever | Choices made |
| `identity` | Forever | Who the user is |
| `procedure` | Forever | How to do things |
| `fact` | Decays | General knowledge |
| `goal` | Until done | Active objectives |

## Zero Dependencies

Pure Python stdlib (`urllib`). No `requests`, no `httpx`, no `aiohttp`. Works everywhere Python runs.

## Links

- [Documentation](https://memoryai.dev/docs.html)
- [Setup Guide](https://memoryai.dev/setup.html)
- [Get API Key](https://memoryai.dev)
