hy-memory 1.0.0

HY Memory - Intelligent hierarchical memory system for LLM agents

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

pip install hy-memory

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:

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:

cp .env.example .env

See 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 — Detailed API documentation and examples
• Environment Reference — All configuration options
• Contributing — How to contribute

License

MIT License. See LICENSE for details.