# MemoryAI — Python SDK

[![PyPI](https://img.shields.io/pypi/v/hmc-memory)](https://pypi.org/project/hmc-memory/)
[![Python](https://img.shields.io/pypi/pyversions/hmc-memory)](https://pypi.org/project/hmc-memory/)

A brain for your AI agent. Store, recall, and manage context across sessions — memories persist and strengthen with use, just like the human mind.

## Install

```bash
pip install hmc-memory
```

## Quick Start

```python
from memoryai import MemoryAI

mem = MemoryAI(api_key="hm_sk_...", base_url="https://memoryai.dev")

# Bootstrap — load context at session start
ctx = mem.bootstrap(task_description="Fix auth bug", project_name="my-app")
print(ctx["context_block"])

# Store — save what you learn
mem.store("User prefers dark mode", tags=["preferences"], priority="hot")

# Recall — search memory
for r in mem.recall("user preferences"):
    print(f"[{r.score:.0%}] {r.content}")

# Learn — store action + result + lesson
mem.learn(action="Fixed N+1 query", result="Response time 2s → 50ms", lesson="Always check ORM queries")

# Compact — consolidate session into key memories
mem.compact("Session transcript...", task_context="Refactoring auth")

mem.close()
```

## Async

```python
from memoryai import AsyncMemoryAI

async with AsyncMemoryAI(api_key="hm_sk_...", base_url="https://memoryai.dev") as mem:
    await mem.store("Important context", tags=["project"])
    results = await mem.recall("project context")
```

## IDE Integration (MCP)

Works with Cursor, VS Code, Claude Desktop, Windsurf, Kiro, and OpenClaw via MCP server. See [Integration Guide](https://github.com/memoryai-dev/memoryai/blob/main/INTEGRATION-GUIDE.md).

## How Your Agent's Brain Works

Memories are processed through 4 stages — just like the human brain:

| | Stage | What it does | Like... |
|---|---|---|---|
| ⚡ | **Instant Recall** | What's on the tip of your tongue. Always ready, zero delay. | Remembering your own name |
| 🔍 | **Deep Search** | Scans long-term memory, finds matches by meaning — not just keywords. | "Where did I put that...?" |
| 🧠 | **Reasoning** | Reads multiple memories, connects the dots, synthesizes a precise answer. *(Pro)* | Thinking hard about it |
| 📦 | **Archive** | Compressed long-term storage. Memories age naturally, but nothing is truly forgotten. | That thing from 6 months ago |

The more you recall a memory, the stronger it gets. Unused memories gently fade to deeper storage — but deeper recall can always bring them back.

## Features

- **🔥 Hot / 🌤️ Warm / ❄️ Cold** — Priority levels mirror how the brain stores memories
- **Associative connections** — Related memories link automatically, like neurons forming pathways
- **Entity tracking** — Recognizes files, people, packages, and URLs in your context
- **Session recovery** — Pick up exactly where you left off, every time
- **Collective knowledge** — Shared intelligence pool across users (anonymized, opt-in)
- **Smart deduplication** — Same knowledge stored once, no matter how many times you mention it
- **Contradiction detection** — Outdated info is flagged when newer facts arrive

## Legacy Imports

Backward compatible — these still work:

```python
from cortexmemory import MemoryAI      # OK
from hybridmemory import HybridMemory  # OK — alias for MemoryAI
```

## Get an API Key

```bash
curl -X POST https://memoryai.dev/v1/admin/provision \
  -H "Content-Type: application/json" \
  -d '{"name": "my-agent", "tos_accepted": true}'
```

Or visit https://memoryai.dev to create one instantly.

## Links

- PyPI: https://pypi.org/project/hmc-memory/
- Website: https://memoryai.dev
- Integration Guide: [INTEGRATION-GUIDE.md](https://github.com/memoryai-dev/memoryai/blob/main/INTEGRATION-GUIDE.md)
