Hy-Memory README

项目的 README,来自 github.com/Tencent-Hunyuan/Hy-Memory。合并为一个 markdown 文件:README.md。

Tencent Hunyuan

Hy Memory

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

Latest News Papers Get Started System Architecture Support Hugging Face Model MemHub Website Discord Apache-2.0 License

English | 中文

Hy Memory (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 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.

MemHub Demo Video


Latest News


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 (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

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.4              # core (includes ChromaDB and Kuzu)
pip install "hy-memory[qdrant]==2.0.4"    # + Qdrant
pip install "hy-memory[faiss]==2.0.4"     # + FAISS
pip install "hy-memory[graph]==2.0.4"     # + Neo4j
pip install "hy-memory[mysql]==2.0.4"     # + MySQL cache
pip install "hy-memory[rerank]==2.0.4"    # + local multilingual cross-encoder rerank
pip install "hy-memory[all]==2.0.4"       # 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 for the full list.

Prompts ship in 11 languages (en, zh-Hans, zh-Hant, ja, es, de, pt, fr, ko, ru, id). By default the SDK picks Chinese or English from the input. Set MEMORY_LANGUAGE (or language= on add()) to choose one explicitly; memories are then written in that language. See Prompt language.

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,
    scene="coding",                              # or "working"
    user_id="user_123",
    workspace_id="github.com/example/service",   # optional: isolate by repository / project
    branch="fix/search-timeout",                 # optional: requires workspace_id
)

result = client.search(
    "Which timeout implementation was finally kept?",
    scene="coding",
    user_ids=["user_123"],
    workspace_id="github.com/example/service",
    branch="fix/search-timeout",
    limit=5,
)

result["facts"]          # fact layer
result["experiences"]    # experience layer
result["chain_block"]    # coding only: version-evolution context (empty unless MEMORY_CODING_CHAIN_BLOCK_ENABLED)

5. Routing, Source Isolation & Advanced APIs

For provider configuration, storage backends, scenes, and the complete API, see the Usage Guide.


System Architecture

Hy Memory architecture

Hy Memory provides three memory scenes (scene), one per kind of task. add() / search() go through the scene router first, then into the Chat or the Working / Coding pipeline (orange parts in the diagram are coding-only; without them the pipeline is Working):

scene Tasks Memory shape
chat Small talk, personal information, preferences, general Q&A Hierarchical memory (L0–L7)
working Productivity work: documents, spreadsheets, research, financial analysis, content creation, computer operation Two-layer memory: session facts + reusable experiences
coding Software engineering: coding, debugging, testing, builds, APIs/SDKs, scripts, SQL The same two-layer memory as working, plus a code version-evolution chain (diff chain)

1. Chat: Memory Hierarchy

For long-term personal memory. Raw conversations are abstracted layer by layer into facts, summaries, a profile, and higher-level cognitive structures:

Layer Name Content
L0 BASIC_INFO Basic information
L1 RAW Raw conversation (append-only)
L2 FACT Atomic facts (versioned, immutable records)
L3 SUMMARY Session summaries
L4 IDENTITY Reserved
L5 KNOWLEDGE Reserved
L6 SCHEMA Mental models (abstract narrative templates, graph layer)
L7 INTENTION Prospective intentions (with an expiry; demoted to ordinary facts once expired)

Modes

Mode What it does Graph DB Use case
lite Raw-only embedding writes and searches, no LLM calls; scene and layers are ignored No Vanilla vector RAG, fast ingestion, zero LLM cost
pro + LLM extraction + reconcile Optional (MEMORY_ENABLE_GRAPH, off by default) Standard workloads
ultra + System 2 schema induction + cross-domain sweeper (triggered by evolve()) Yes (always on) Full cognitive architecture

2. Working: Two-Layer Productivity Memory

For getting things done. One session with tool calls (a trace) produces both layers at once:

Layer What it records Per session Structure
Facts (WorkingFact) What this session did: the task, the approach, the result Exactly 1, no threshold statement, subject, files, details (verbatim source)
Experiences Approaches that can be reused next time a similar task comes up 0–N, must pass a value threshold task, search_keys, solution, boundary_envs, confidence

The fact layer guarantees that work which was done is remembered; the experience layer makes what was learned reusable. The two layers link to each other (fact.derived_experience_ids ↔ experience.source_fact_ids), and superseded facts stay traceable through a task-progress chain (fact_chain_summary).

3. Coding: Two-Layer Memory + Version-Evolution Chain

Coding reuses the same two-layer pipeline and data schema as Working. It differs in three ways:

Working Coding
Extraction spec Productivity-task spec Software-engineering spec: the subject must be code or a decision; record exact coordinates (file / function / branch) instead of pasting code
Storage coding_memory.db + *_coding_keys / *_working_facts collections coding_memory_cv.db + *_cv collections, fully isolated from working
Version-evolution chain None Yes: how many times the same code was changed, and what each change was

Why a version-evolution chain: fact extraction deliberately avoids pasting code (the budget goes to more informative coordinates), so a version that was later reverted never appears in a fact. That version is usually not in the working tree or at HEAD either, so it cannot be read back afterwards. The chain stores the real diff of every version with zero LLM calls, filling in exactly the information a summary inevitably drops.

Design highlights (hy_memory/coding/chain_store.py):


Support

Storage Backends

Documentation

License

Hy-Memory is licensed under Apache-2.0. See LICENSE; third-party components remain subject to their respective licenses and notices.

Hy-Memory (Tencent-Hunyuan/Hy-Memory)

正在搜索数据库…

这是什么?Hy Memory 是一个面向生产环境的双系统认知记忆引擎,也是用于自我进化 LLM 智能体的 Python SDK(hy-memory),并为聊天、工作和编程任务分别提供独立的记忆流水线。它还附带 MemHub,这是一款本地优先的桌面和命令行工具,可将 Claude Code、Cursor、Codex 等应用的记忆统一到一个受管理的本地存储中。
这是 Python 库还是独立应用?主要是一个 Python SDK(hy-memory),你可以把它导入到智能体代码中使用;MemHub 则是基于它构建的独立本地优先桌面和命令行产品,用于管理外部编程工具的记忆。
我该怎么安装和配置?安装 hy-memory 包(在 PyPI 上发布的版本为 hy-memory==2.0.3),然后配置一个 LLM 和一个嵌入(embedding)端点。任何兼容 OpenAI 的服务都可以,或者直接设置一个 OpenAI API 密钥作为默认配置。
使用它需要兼容 OpenAI 的 API 密钥吗?需要。pro 和 ultra 模式需要,因为它们会执行 LLM 抽取、记忆整合和模式归纳;lite 模式完全不调用 LLM,只做基于嵌入的原始写入和检索。
工作和编程记忆有什么限制?工作和编程场景的写入仅在 pro 或 ultra 模式下生效,且输入中必须包含工具调用轨迹;在 lite 模式下,场景路由会被忽略,所有内容都作为原始记忆存储。
MemHub 会把我的数据保存在本地吗?会。MemHub 采用本地优先的设计,将来自已授权应用的统一对话历史和编程轨迹存储在本机的托管运行时和本地数据目录中。
它处理哪三种记忆场景?聊天场景使用分层的长期记忆(L0 至 L7 层,从原始对话到意图);工作场景使用双层记忆,即事实加可复用经验,用于效率类任务;编程场景沿用这一双层模型,并增加了一个版本演进差异链,用于追踪代码变更。
它支持哪些存储后端?向量存储支持 ChromaDB(默认)、Qdrant 或 FAISS;ultra 模式额外增加图存储,默认为 Kuzu,也可以使用 Neo4j;工作和编程场景的元数据保存在本地 SQLite 中。
Coding 记忆中的版本演进差异链有什么用?它会存储记忆事实所涉及的每个代码版本的真实差异,包括从未进入事实摘要的已回滚版本,因此不会丢失任何关于过往代码变更的信息。
MemHub 可以统一哪些 AI 编程工具的记忆?MemHub 目前支持 Claude Code、Cursor、Codex、OpenCode 和 Qwen Code。
有哪些类似的项目?m_flow, MemOS, mem0, memvid, claude-mem, LongMemory, semantica, Agentlas-OS
大小
25 MB
星标
2.1K
时长
1个月
提交 · 90 天