Metadata-Version: 2.4
Name: hmc-memory
Version: 2.5.0
Summary: MemoryAI v2.0 — Living Brain for AI Agents. Emotion State Engine, Context Guard, DNA-protected memories, Multi-Agent Mesh, Hebbian learning, Ebbinghaus decay, Sleep consolidation, Personality synthesis, Causal reasoning.
License: MIT
Project-URL: Homepage, https://memoryai.dev
Project-URL: Documentation, https://memoryai.dev/docs
Project-URL: Repository, https://github.com/memoryai-dev/memoryai
Keywords: ai,memory,llm,context,embeddings
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.27.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"

# 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).

## Agent Loop — turn memory into a working brain

The SDK ships `MemoryAgent`, a small ReAct-style executor that wires the
memory primitives into a full operating loop:

```
bootstrap → [recall → pitfall_check → think → act → store/feedback]* → done
```

It is model-agnostic — you plug in any LLM and your own tools:

```python
from memoryai import MemoryAI, MemoryAgent

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

def my_llm(prompt: str, context: str) -> str:
    # Return a JSON decision string. Wire this to any model you like.
    # {"thought":..., "tool":..., "args":{...}, "done":false, "final":...}
    ...

tools = {
    "search_web": lambda q: "...",
    "run_tests":  lambda: "12 passed",
}

agent = MemoryAgent(mem, llm=my_llm, tools=tools)
result = agent.run("Fix the failing auth test")

print(result.final)
for step in result.steps:
    print(step.tool, step.observation)
```

What the loop does automatically:

- **Bootstrap** — loads DNA + recent activity so the agent starts informed.
- **Recall** — pulls memory relevant to the task before each decision.
- **Pitfall check** — queries known failures *before* acting, so the agent avoids repeating mistakes.
- **Feedback** — reports recall quality so the brain self-improves (helpful recalls get boosted, unhelpful ones fade).
- **Outcome storage** — successes become episodic memories; failures become DNA-protected pitfalls.
- **State persistence** — saves plan/cursor so a future session can resume.

The lower-level primitives are also available directly on the client:
`pitfall_check`, `procedure_check`, `feedback`, `predict`, `save_state`,
`restore_state` (sync and async).

## 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)
