Metadata-Version: 2.4
Name: hy-memory
Version: 1.0.0
Summary: HY Memory - Intelligent hierarchical memory system for LLM agents
Author: alvinfei
License: MIT
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pydantic
Requires-Dist: numpy
Requires-Dist: openai
Requires-Dist: python-dotenv
Requires-Dist: pyyaml
Requires-Dist: chromadb
Requires-Dist: langdetect
Provides-Extra: qdrant
Requires-Dist: qdrant-client; extra == "qdrant"
Provides-Extra: faiss
Requires-Dist: faiss-cpu; extra == "faiss"
Provides-Extra: graph
Requires-Dist: neo4j; extra == "graph"
Requires-Dist: kuzu; extra == "graph"
Provides-Extra: redis
Requires-Dist: redis; extra == "redis"
Provides-Extra: anthropic
Requires-Dist: anthropic; extra == "anthropic"
Provides-Extra: ml
Requires-Dist: scikit-learn; extra == "ml"
Provides-Extra: all
Requires-Dist: chromadb; extra == "all"
Requires-Dist: qdrant-client; extra == "all"
Requires-Dist: faiss-cpu; extra == "all"
Requires-Dist: kuzu; extra == "all"
Requires-Dist: neo4j; extra == "all"
Requires-Dist: redis; extra == "all"
Requires-Dist: anthropic; extra == "all"
Requires-Dist: scikit-learn; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-asyncio; extra == "dev"
Requires-Dist: httpx; extra == "dev"
Dynamic: license-file

# HY Memory

**Intelligent hierarchical memory system for LLM agents.**

HY Memory provides a production-grade memory layer for AI agents with LLM-driven extraction, semantic search, multi-layer knowledge representation, and graph-based schema inference.

## Features

- **7-Layer Memory Architecture** — From raw facts (L1) to behavioral schemas (L6) and intentions (L7)
- **LLM-Driven Extraction** — Automatically extracts structured memories from conversations
- **Semantic Search** — Vector similarity search across all memory layers
- **Graph Knowledge** — Neo4j/Kuzu graph store for schema and intention inference (System 2)
- **Evolution Chains** — Tracks how memories evolve over time via supersedes links
- **Multiple Backends** — Qdrant, ChromaDB, FAISS for vectors; Neo4j, Kuzu for graphs
- **OpenAI-Compatible** — Works with any LLM that supports the OpenAI API format (DeepSeek, Qwen, Claude, etc.)

## Quick Start

```bash
pip install hy-memory
```

```python
from hy_memory import HyMemoryClient

client = HyMemoryClient(mode="lite")

# Write
client.add("I love sci-fi movies, especially Interstellar", user_id="user_1")

# Search
results = client.search("What movies does the user like?", user_id="user_1")
for mem in results["memories"]:
    print(f"  [{mem['score']:.2f}] {mem['content']}")

client.close()
```

## Configuration

HY Memory is configured via environment variables. Minimal setup:

```bash
export MEMORY_LLM_API_KEY="sk-your-key"
export MEMORY_LLM_BASE_URL="https://api.deepseek.com"   # or any OpenAI-compatible endpoint
export MEMORY_LLM_MODEL="deepseek-chat"

export MEMORY_EMBEDDER_API_KEY="sk-your-key"
export MEMORY_EMBEDDER_BASE_URL="https://api.openai.com/v1"
export MEMORY_EMBEDDER_MODEL="text-embedding-3-small"
```

Or copy `.env.example` and fill in your values:

```bash
cp .env.example .env
```

See [docs/env_reference.md](docs/env_reference.md) for all available options.

## Modes

| Mode | Layers | Graph | Best For |
|------|--------|-------|----------|
| **lite** | L0-L4 (facts + identity) | No | Simple chatbots, quick setup |
| **pro** | L0-L5 (+ knowledge) | Optional | Knowledge-heavy applications |
| **ultra** | L0-L7 (+ schema + intention) | Yes | Full cognitive architecture |

## Vector Store Backends

| Backend | Install | Config |
|---------|---------|--------|
| **ChromaDB** (default) | included | `MEMORY_VECTOR_STORE=chroma` |
| **Qdrant** | `pip install hy-memory[qdrant]` | `MEMORY_VECTOR_STORE=qdrant` |
| **FAISS** | `pip install hy-memory[faiss]` | `MEMORY_VECTOR_STORE=faiss` |

## Graph Store Backends (Ultra mode)

| Backend | Install | Config |
|---------|---------|--------|
| **Kuzu** (default) | included | `MEMORY_GRAPH_PROVIDER=kuzu` |
| **Neo4j** | `pip install hy-memory[graph]` | `MEMORY_GRAPH_PROVIDER=neo4j` |

## Documentation

- [Usage Guide](docs/usage.md) — Detailed API documentation and examples
- [Environment Reference](docs/env_reference.md) — All configuration options
- [Contributing](CONTRIBUTING.md) — How to contribute

## License

MIT License. See [LICENSE](LICENSE) for details.
