Tencent-Hunyuan/Hy-Memory

Tencent-Hunyuan/Hy-Memory

Language: Python

License: NOASSERTION

Stars: 442

Forks: 40

Open issues: 10

Created: 2026-10-15T13:06:56Z

Pushed: 2026-10-17T05:37:04Z

Default branch: main

Fork: no

Archived: no

README:

Hy Memory

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

English | [中文](README.zh.md)

[Hy Memory](https://memory.hunyuan.tencent.com/) (Official Website) is a production-grade dual-system cognitive memory engine and Python SDK (hy-memory) for self-evolving LLM agents, providing specialized memory pipelines across three task scenes: hierarchical long-term cognitive memory for Chat, two-layer fact and reusable-experience memory for Working, and version-evolution diff-chain tracking for Coding. Built on top of Hy Memory, [MemHub](memhub/README.md) is a local-first desktop and CLI product that unifies conversation history and coding traces from user-authorized AI applications (such as Claude Code, Cursor, Codex, OpenCode, and Qwen Code) into a single managed runtime and local data directory, enabling governed cross-application memory recall.

---

Latest News

• *[new]* 🔥🔥🔥 [2026-10]: 🚀 Released Hy Memory 2.0 (`hy-memory==2.0.2`) on PyPI and open-sourced the Hy-Memory monorepo together with [MemHub](memhub/README.md)!
• *[new]* 🔥🔥🔥 [2026-10]: 🚀 Open-sourced [Hy-Memory-30B-A3B](https://huggingface.co/tencent/Hy-Memory-30B-A3B) on Hugging Face along with its technical report on attributed reinforcement learning for long-term memory writing!
• *[new]* 🔥🔥 [2026-09]: 📊 Released [CMB: A Coding Memory Benchmark for Long-Horizon and Interleaved Coding Agents](docs/papers/CMB_A_Coding_Memory_Benchmark_for_Long_Horizon_and_Interleaved_Coding_Agents.pdf) (submitted to ICLR 2027).
• *[new]* 🔥🔥 [2026-08]: 🎉 Accepted at EMNLP 2026: [Memory Beyond Recall: A Dual-Process Cognitive Memory System for Self-Evolving LLM Agents](https://arxiv.org/abs/2606.09483)!
• 🔥 [2026-05]: 🌟 Initial Release Released [Hy Memory 1.0](https://mp.weixin.qq.com/s/dH5PGpxqArFZkSq3-QxWYA), our first-generation dual-system cognitive memory framework for self-evolving LLM agents.

---

Papers

Welcome to the Hy Memory Research Family, covering cognitive chat memory, long-horizon coding memory, and RL-trained memory writing models:

> **Memory Beyond Recall: A Dual-Process Cognitive Memory System for Self-Evolving LLM Agents** *(Accepted at EMNLP 2026)* > TL;DR: Proposes the dual-process (System 1 + System 2) cognitive memory architecture for Chat, organizing personal memory into an 8-layer hierarchy (raw dialogues, atomic facts, summaries, schemas, and prospective intentions) with conflict reconciliation and cross-domain schema induction. > 📄 Paper: https://arxiv.org/abs/2606.09483

> [CMB: A Coding Memory Benchmark for Long-Horizon and Interleaved Coding Agents](docs/papers/CMB_A_Coding_Memory_Benchmark_for_Long_Horizon_and_Interleaved_Coding_Agents.pdf) *(Submitted to ICLR 2027)* > TL;DR: Introduces a benchmark and two-layer + version-evolution diff-chain memory method for long-horizon Coding agents, preserving both reusable engineering experiences and exact code revision trajectories across interleaved tasks. > 📄 Paper: [docs/papers/CMB_A_Coding_Memory_Benchmark_for_Long_Horizon_and_Interleaved_Coding_Agents.pdf](docs/papers/CMB_A_Coding_Memory_Benchmark_for_Long_Horizon_and_Interleaved_Coding_Agents.pdf)

> **Hy-Memory-30B-A3B: Attributed Reinforcement Learning for Long-Term Memory Writing** *(Open Model Technical Report)* > TL;DR: Trains a 30B-A3B MoE model via attributed reinforcement learning specifically for high-precision long-term memory extraction and conflict reconciliation. > 📄 Paper: https://arxiv.org/abs/2610.22196 · Model: https://huggingface.co/tencent/Hy-Memory-30B-A3B

---

Quick Start

1. Installation

pip install hy-memory==2.0.2 # core (includes ChromaDB and Kuzu)
pip install "hy-memory[qdrant]==2.0.2" # + Qdrant
pip install "hy-memory[faiss]==2.0.2" # + FAISS
pip install "hy-memory[graph]==2.0.2" # + Neo4j
pip install "hy-memory[mysql]==2.0.2" # + MySQL cache
pip install "hy-memory[rerank]==2.0.2" # + local multilingual cross-encoder rerank
pip install "hy-memory[all]==2.0.2" # everything

2. Configuration

Only an LLM and an embedding endpoint are needed; any OpenAI-compatible service works:

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 the OpenAI defaults with a single key:

export OPENAI_API_KEY="sk-your-key"

See the [Environment Variable Reference](docs/env_reference.md) for the full list.

3. Chat Memory

from hy_memory import HyMemoryClient

client = HyMemoryClient(mode="pro")

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

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

client.close()

4. Working & Coding Memory

Writes must include a tool-call trace (tool_calls or role="tool" messages) and take effect in pro / ultra mode only (lite ignores scene and stores everything as raw memory):

messages = [
{"role": "user", "content": "Fix the timeout in the search client."},
{"role": "assistant", "content": "", "tool_calls": [{
"id": "call_1", "type": "function",
"function": {"name": "apply_patch", "arguments": '{"path":"src/search.py"}'},
}]},
{"role": "tool", "tool_call_id": "call_1", "name": "apply_patch",
"content": "Patch applied successfully"},
]

client.add(
messages,...