0 Fork 0

Files

T

alvinfeiandClaude Opus 5.5 58f2fa884a build(memhub): pin hy-memory 2.0.14

2.0.14 accepts `statuses` on explicit L1_RAW search, which Core has
passed since #316. Covers the same files as the 2.0.13 pin (#285).

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

2026-11-04 19:32:11 +08:00

17 KiB

Raw Blame History

Hy Memory

工业级双系统认知记忆框架，为 LLM Agent 提供类人长期记忆能力。

English | 中文

Hy Memory（官网：memory.hunyuan.tencent.com）是面向自演化 LLM Agent 的工业级双系统认知记忆引擎与 Python SDK（hy-memory），针对三类任务场景提供专用记忆链路：面向日常对话的 Chat 多层认知记忆、面向生产力任务的 Working“会话事实 + 可复用经验”双层记忆，以及面向软件工程的 Coding 双层记忆与代码版本演进链（diff 链）。基于 Hy Memory 构建的 MemHub 是本地优先的桌面端与 CLI 产品，可将用户授权的多个 AI 应用（如 Claude Code、Cursor、Codex、OpenCode、Qwen Code 等）的历史对话与操作轨迹汇入统一的本地受管 Runtime 与数据目录，并向授权宿主提供受治理的跨应用记忆召回。

MemHub 演示视频

论文

欢迎了解 Hy Memory 记忆研究体系，涵盖对话认知记忆、长周期编程记忆以及强化学习记忆写入模型：

Memory Beyond Recall: A Dual-Process Cognitive Memory System for Self-Evolving LLM Agents （EMNLP 2026 已接收）
TL;DR: 提出面向 Chat 的双系统（System 1 + System 2）认知记忆架构，将个人长期记忆组织为 8 层认知结构（原始对话、原子事实、会话摘要、心智图式与前瞻意图等），支持冲突消解与跨域图式归纳。
📄 Paper: https://arxiv.org/abs/2606.09483

CMB: A Coding Memory Benchmark for Long-Horizon and Interleaved Coding Agents （ICLR 2027 已投稿）
TL;DR: 提出面向长周期与交错式 Coding Agent 的记忆评测基准与“双层记忆 + 代码版本演进链（diff 链）”方法，在保留可复用工程经验的同时完整追踪代码历次修改轨迹。
📄 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 （开源模型技术报告）
TL;DR: 提出面向长期记忆写入的归因强化学习（Attributed RL）训练框架，开源专门针对高精度记忆抽取与冲突消解优化的 30B-A3B MoE 模型。
📄 Paper: https://arxiv.org/abs/2610.22196 · Model: https://huggingface.co/tencent/Hy-Memory-30B-A3B

快速开始

1. 安装

pip install hy-memory==2.0.4              # 核心（含 ChromaDB 与 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 缓存
pip install "hy-memory[rerank]==2.0.4"    # + 本地多语言 cross-encoder rerank
pip install "hy-memory[all]==2.0.4"       # 全部

2. 配置

只需 LLM 和 Embedding 两组配置，支持任何兼容 OpenAI API 格式的服务：

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

或使用 OpenAI 默认配置（单个 key）：

export OPENAI_API_KEY="sk-your-key"

完整配置见环境变量参考。

提示词提供 11 种语言（en、zh-Hans、zh-Hant、ja、es、de、pt、fr、 ko、ru、id）。默认按输入自动在中文与英文之间选择；设置 MEMORY_LANGUAGE（或在 add() 上传 language=）可显式指定，记忆随之用该语言书写。详见提示词语言。

3. Chat 记忆

from hy_memory import HyMemoryClient

client = HyMemoryClient(mode="pro")

# 写入：纯文本或 OpenAI messages 格式
client.add("用户喜欢科幻电影，特别是《星际穿越》", user_id="user_1")
client.add([
    {"role": "user", "content": "推荐一部电影"},
    {"role": "assistant", "content": "推荐《星际穿越》，诺兰的经典科幻之作"},
], user_id="user_1")

# 检索：返回 profile / normal / proactive 三路
results = client.search("用户喜欢什么类型的电影？", user_ids=["user_1"], limit=10)
for mem in results["memories"]["normal"]:
    print(f"  [{mem['score']:.2f}] {mem['content']}")

client.close()

4. Working / Coding 记忆

写入需要包含工具调用轨迹（tool_calls 或 role="tool" 消息），且仅在 pro / ultra 模式下生效（lite 会忽略 scene，一律按原始记忆存取）：

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",                              # 或 "working"
    user_id="user_123",
    workspace_id="github.com/example/service",   # 可选：按仓库 / 项目隔离
    branch="fix/search-timeout",                 # 可选：需同时传 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"]          # 事实层
result["experiences"]    # 经验层
result["chain_block"]    # 仅 coding：版本演进上下文（默认空；需 MEMORY_CODING_CHAIN_BLOCK_ENABLED）

5. 自动路由、来源过滤与进阶 API

自动场景路由：不传 scene 时，不含工具调用的写入直接走 chat（零 LLM 开销），含工具调用的写入用一次 LLM 在 chat / working / coding 间分类；检索在 search_mode="default" 下固定走 chat（零 LLM），search_mode="agentic" 下自动完成场景分类、query 改写和时间范围解析。详见 Working/Coding Scene。
按来源区分记忆：写入时传入 source="openclaw" | "cursor" | "codex"，检索时通过 include_sources / exclude_sources 过滤，实现与 agent_id 正交的宿主应用隔离。
常用管理与演进 API：client.get(id)、client.update(id, text)、client.delete(id)、client.list_memories(user_id=...)，以及在 ultra 模式下显式触发 System 2 认知加工的 client.evolve(user_id=...)。
Per-call Embedding 端点覆盖：支持在 add() / search() 中传 embed_override={"base_url": ..., "api_key": ...}，或使用并发安全的 with embed_endpoint_override(...): 上下文管理器。

服务商配置、存储后端、场景与完整 API 见使用指南。

架构设计

Hy Memory 按任务类型提供三种记忆场景（scene）。add() / search() 先经过 scene 路由，再进入 Chat 或 Working / Coding 链路（图中橙色部分为 Coding 独有，去掉后即为 Working）：

`scene`	面向的任务	记忆形态
`chat`	闲聊、个人信息、偏好、一般问答	记忆分层（L0–L7）
`working`	文档、表格、研究、财经分析、内容创作、电脑操作等生产力任务	双层记忆：会话事实 + 可复用经验
`coding`	编码、调试、测试、构建、API/SDK、脚本、SQL 等软件工程任务	与 working 相同的双层记忆，外加代码版本演进链（diff 链）

1. Chat：记忆分层

面向个人长期记忆。原始对话逐层抽象成事实、摘要、画像和更高层的认知结构：

层	名称	内容
L0	`BASIC_INFO`	基础信息
L1	`RAW`	原始对话（append-only）
L2	`FACT`	原子事实（版本化，不可变记录）
L3	`SUMMARY`	会话摘要
L4	`IDENTITY`	保留
L5	`KNOWLEDGE`	保留
L6	`SCHEMA`	心智模型（抽象叙事模板，图层）
L7	`INTENTION`	前瞻意图（带有效期，过期后转为普通事实）

处理模式

模式	功能	图数据库	适用场景
`lite`	只对原始记忆做 embedding 写入与检索，不调 LLM；忽略 `scene` 和 `layers`	否	纯向量 RAG，快速写入，零 LLM 开销
`pro`	+ LLM 提取 + reconcile 冲突处理	可选（`MEMORY_ENABLE_GRAPH`，默认关）	标准场景
`ultra`	+ System 2 图式归纳 + 跨域 sweeper（通过 `evolve()` 触发）	是（自动开启）	完整认知架构

2. Working：双层生产力记忆

面向"做事"的场景。一次带工具调用的会话（trace）会同时产出两层记忆：

层	记录什么	每次会话产出	结构
事实层（`WorkingFact`）	这次会话做了什么：任务、做法、结果	恰好 1 条，不设门槛	`statement`、`subject`、`files`、`details`（原文留存）
经验层（`Experience`）	下次遇到类似任务可以直接复用的做法	0–N 条，需通过价值门槛	`task`、`search_keys`、`solution`、`boundary_envs`、`confidence`

事实层保证"做过的事一定记得"，经验层负责"学到的东西能复用"。两层互相链接（fact.derived_experience_ids ↔ experience.source_fact_ids），旧事实被覆盖时以 superseded 状态保留并通过任务进展链（fact_chain_summary）回溯演化过程。

3. Coding：双层记忆 + 版本演进链

Coding 与 Working 复用同一套双层 pipeline 和数据 schema，区别有三点：

	Working	Coding
抽取规范	生产力任务规范	软件工程规范：主语必须是代码或决策，记录精确坐标（文件 / 函数 / 分支）而不是粘贴代码
存储	`coding_memory.db` + `_coding_keys` / `_working_facts` 向量集合	`coding_memory_cv.db` + `*_cv` 向量集合，与 working 完全隔离
版本演进链	无	有：记录同一处代码被改了几次、每次改了什么

为什么需要版本演进链：事实层的抽取刻意不粘贴代码（预算留给更有信息量的坐标），所以被撤掉的那一版代码不会出现在事实里。而那一版往往不在工作区、也不在 HEAD，事后读不回来。版本演进链零 LLM 地把每一版的真实 diff 存下来，补上摘要必然丢掉的这类信息。

设计要点（hy_memory/coding/chain_store.py）：

装饰器而非检索器：向量层决定返回哪几条事实；演进链只负责在每条事实下面挂上它所涉及代码的全部改动版本（每版的用户原话 + 真实 diff）。
修改来源：本地 Git diff（设置 MEMORY_CODING_CHAIN_REPO_ROOT），或工具轨迹中带 path / old / new 的确定性替换动作。
分链粒度与隔离：一条 thread 对应“某分支、某文件、某函数的某一块”，由 user_id 与 workspace_id 共同隔离。

支持

存储后端

向量库：ChromaDB（默认）、Qdrant、FAISS
图库（ultra 模式）：Kuzu（默认）、Neo4j
Working / Coding 的元数据使用本地 SQLite

文档

使用指南 — 完整配置参考、API 详情、部署模式
环境变量参考 — 配置说明与默认值
Search 与 Reader 指南 — Reader 选择、Schema 配额、Rerank 与返回通道
Working/Coding Scene — 生产力记忆路由、返回结构与 Coding 链行为
Graph 记忆设计 — 图投影、重排、关系路径与部署限制
环境变量模板 — 可直接复制的配置模板
MemHub 说明文档 — 本地优先桌面端与 CLI 产品总览、Runtime 命令与隐私边界
Hermes 原生记忆 Provider — 显式用户与 Agent 隔离，独立 HTTP 服务，自动记录与召回默认关闭。
OpenClaw 插件 — Agent 集成见 plugins/（总览：plugins/README.md）

License

Hy-Memory 使用 Apache-2.0，详见 LICENSE。第三方组件仍受各自许可证与声明约束。

17 KiB Raw Blame History Unescape Escape