# Hy Memory

> Dual-system cognitive memory engine and Python SDK for LLM agents covering chat, working, and coding scenes.

Hy Memory is a memory engine and Python SDK (`hy-memory`) from Tencent Hunyuan for self-evolving LLM agents. It provides separate memory pipelines for chat, productivity work, and software engineering. The repository also includes MemHub, a local-first desktop and CLI product built on top of it.

## What It Is

Hy Memory is a library that agents call to write and search long-term memory. It needs only an LLM endpoint and an embedding endpoint, and any OpenAI-compatible service works. Users call `add()` with plain text or OpenAI-format messages and `search()` to retrieve memories, with CRUD operations and an `evolve()` call also available.

## Three Memory Scenes

The `chat` scene organizes personal memory into a hierarchy from raw conversation through atomic facts, session summaries, schemas, and prospective intentions. The `working` scene records a session's facts plus reusable experiences, based on a tool-call trace. The `coding` scene uses the same two layers and adds a version-evolution chain that stores the real diff of each code revision, sourced from local Git diffs or replace actions in the tool trace. When `scene` is omitted, automatic routing classifies writes that include tool calls.

## Modes and Storage

The `lite` mode does raw embedding writes and searches with no LLM calls. The `pro` mode adds LLM extraction and reconciliation. The `ultra` mode adds System 2 schema induction and a cross-domain sweeper triggered by `evolve()`. Vector stores include ChromaDB, Qdrant, and FAISS, and graph stores include Kuzu and Neo4j. Working and coding metadata live in local SQLite.

## MemHub and Integrations

MemHub unifies conversation history and coding traces from user-authorized AI applications such as Claude Code, Cursor, Codex, OpenCode, and Qwen Code into one local data directory for governed cross-application recall. The repository also lists an OpenClaw plugin and an open model, Hy-Memory-30B-A3B, on Hugging Face.

## Features
- Hierarchical long-term chat memory (L0–L7)
- Two-layer working memory of facts and reusable experiences
- Coding memory with version-evolution diff chain
- Automatic scene routing
- Source isolation via include/exclude filters
- Lite, pro, and ultra modes
- System 2 schema induction via evolve()
- Workspace and branch isolation
- Per-call embedding endpoint override
- MemHub local-first desktop and CLI for cross-application memory

## Integrations
ChromaDB, Qdrant, FAISS, Kuzu, Neo4j, MySQL, OpenAI-compatible APIs, Claude Code, Cursor, Codex, OpenCode, Qwen Code, OpenClaw, Hugging Face

## Platforms
WINDOWS, MACOS, LINUX, API, DEVELOPER_SDK, CLI

## Pricing
Open Source

## Version
2.0.3

## Links
- Website: https://github.com/Tencent-Hunyuan/Hy-Memory
- Documentation: https://github.com/Tencent-Hunyuan/Hy-Memory/blob/main/docs/usage.md
- Repository: https://github.com/Tencent-Hunyuan/Hy-Memory
- EveryDev.ai: https://www.everydev.ai/tools/hy-memory