hy-memory 1.1.0

HY Memory - Industrial-grade dual-system cognitive memory framework

HY Memory

Production-grade dual-system cognitive memory for LLM agents.

English | 中文

Quick Start

pip install hy-memory-internal

from hy_memory import HyMemoryClient

client = HyMemoryClient(mode="pro")

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

# Write — conversation messages (OpenAI format)
client.add([
    {"role": "user", "content": "Recommend a movie"},
    {"role": "assistant", "content": "Try Interstellar — a sci-fi masterpiece by Nolan"},
], user_id="user_1")

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

client.close()

Features

• 7-Layer Memory Architecture — L0 (basic info) through L7 (intentions), progressively abstracted
• LLM-Driven Extraction — Automatically extracts facts, identity traits, and behavioral patterns
• Three Processing Modes — lite (embedding only), pro (+ LLM extraction), ultra (+ graph inference)
• Semantic Search — Vector similarity with profile/normal/proactive channel separation
• Evolution Chains — Tracks how memories update over time via supersedes links
• Graph Knowledge (ultra mode) — Schema inference and cross-domain pattern detection
• Multiple Backends — ChromaDB, Qdrant, FAISS for vectors; Neo4j, Kuzu for graphs
• OpenAI-Compatible — Works with any LLM/embedding service that supports the OpenAI API format

Configuration

Minimal setup — just two API keys:

export MEMORY_LLM_API_KEY="sk-your-key"
export MEMORY_LLM_BASE_URL="https://api.deepseek.com"
export MEMORY_LLM_MODEL="deepseek-chat"

export MEMORY_EMBEDDER_API_KEY="sk-your-key"
export MEMORY_EMBEDDER_BASE_URL="https://dashscope.aliyuncs.com/compatible-mode/v1"
export MEMORY_EMBEDDER_MODEL="text-embedding-v3"
export MEMORY_EMBEDDING_DIMS=1024

Or use OpenAI defaults with a single key:

export OPENAI_API_KEY="sk-your-key"

Modes

Mode	What it does	Graph	Best for
lite	Embedding-only write, no LLM	No	Fast ingestion, zero LLM cost
pro	+ LLM extraction + reconciliation	No	Standard use case
ultra	+ System 2 schema inference + sweeper	Yes	Full cognitive architecture

Install Options

pip install hy-memory-internal            # Core (ChromaDB included)
pip install hy-memory-internal[qdrant]    # + Qdrant
pip install hy-memory-internal[faiss]     # + FAISS
pip install hy-memory-internal[graph]     # + Neo4j + Kuzu
pip install hy-memory-internal[redis]     # + Redis cache
pip install hy-memory-internal[all]       # Everything

API Overview

from hy_memory import HyMemoryClient

client = HyMemoryClient(mode="pro")

# Write memory
client.add("User likes basketball", user_id="u1")
client.add([
    {"role": "user", "content": "Recommend a movie"},
    {"role": "assistant", "content": "Try Interstellar"},
], user_id="u1")

# Search (returns profile/normal/proactive channels)
results = client.search("hobbies", user_ids=["u1"], limit=10)

# CRUD
client.get("memory_id")
client.update("memory_id", "Updated content")
client.delete("memory_id")
client.list_memories(user_id="u1")

# Ultra mode: check System 2 completion
status = client.get_write_status("request_id")

client.close()

Documentation

• Usage Guide — Full configuration reference, API details, deployment patterns
• Environment Variables — All available env vars with defaults

License

MIT