AI-translated from English; not yet reviewed by a fluent editor.

# Hy Memory 2.0 为智能体提供三种保留上下文的方式

> Tencent 的 Hy Memory 2.0.1 SDK 将聊天、工作和编程的记忆检索分开。其 MemHub 应用已有源代码，但尚无公开发布文件；集成仍需提供模型端点，并明确设置访问边界。

By BIG CHANGE Editorial

Published: 2026-10-16T14:13:14.740Z
Updated: 2026-10-16T14:13:14.740Z
Canonical: https://bigchange.ai/blog/hy-memory-2-sdk-chat-work-coding-context

![Conceptual charcoal illustration of a three-drawer cabinet: blank conversation slips, tool tokens and layered revision strips sit in separate drawers.](https://bigchange.ai/api/media/file/hy-memory-three-scopes-v1.png)
AI-generated conceptual illustration by BIG CHANGE; not a Hy Memory product interface or tested result.

Tencent 发布了 `hy-memory==2.0.1`，这是一套 Python SDK，用于保存和检索聊天、工作及编程会话的上下文。代码已公开；配套的 MemHub 应用仍处于源代码阶段，等待公开发布文件。评估共享记忆层的开发者现在就能使用 SDK，但必须提供模型和嵌入端点，并决定每个智能体可以读取哪些会话记录。

项目的[变更日志](https://github.com/Tencent-Hunyuan/Hy-Memory/blob/main/CHANGELOG.md)将 Hy Memory 2.0.1 的日期列为 2026 年 10 月 16 日。[PyPI](https://pypi.org/project/hy-memory/2.0.1/) 记录了 10 月 15 日的包上传，相关的[模型论文](https://arxiv.org/abs/2610.22196)也在当天提交。这些是不同的发布记录，不能据此证明桌面产品已经推出。

## 关键变化

- **改变了什么：**已发布的 SDK 通过 `add()` 和 `search()` 提供分开的聊天、工作和编程记忆路径，并提供集成应用可以使用的来源及工作区过滤条件。
- **如何运作：**聊天流程将对话整理成记忆层。工作流程从工具调用轨迹中提取一条会话事实，并在适当时提取可复用的经验。编程流程则为代码变更加入版本链。调用方负责提供源材料、身份标识、存储配置和模型服务。
- **为什么重要：**智能体宿主可以检索先前对话或任务决策的精简记录，而不必在每次新会话中传入全部历史。这份记录是否准确、获得授权并且有用，仍取决于宿主发送的内容，以及它允许哪些记忆重新进入提示词。

## 集成前先选择工作流程

SDK 的 [README](https://github.com/Tencent-Hunyuan/Hy-Memory) 列出了 `scene` 的三种取值。`chat` 接受纯文本或消息数组，随后返回 `profile`、`normal` 和 `proactive` 记忆检索通道。在 `lite` 模式下，它存储原始文本以用于嵌入搜索，不经过 LLM 提取。`pro` 加入提取与协调过程；`ultra` 则可以通过 `evolve()` 再运行一轮演化。

使用 `working` 时，输入必须包含工具调用轨迹。一个会话会产生一条关于任务、方法和结果的事实，以及零条或多条达到引擎价值门槛的可复用经验。`coding` 使用相同的两层结构，并为修改过的代码加入版本演化链。README 表示，如果设置了 `MEMORY_CODING_CHAIN_REPO_ROOT`，这条链可以使用本地 Git 差异，或者使用工具调用轨迹中的确定性替换操作。在 `lite` 模式下，SDK 会忽略工作与编程场景的区别，只存储原始记忆。

这些输出结构适用于不同的问题。对话中的偏好应放入 `chat`；带有工具结果的已完成任务应放入 `working`；早期修订版本可能重要的代码变更则应放入 `coding`。这是文档中记录的路由区分，并非 BIG CHANGE 的性能测试。

## 文档中记录的 SDK 使用路径

以下步骤依据[代码仓库快速入门](https://github.com/Tencent-Hunyuan/Hy-Memory)和 [MemHub 的 SDK 配置指南](https://github.com/Tencent-Hunyuan/Hy-Memory/blob/main/memhub/MEMORY.md)整理而成。BIG CHANGE 没有运行该包或调用模型。

使用 Python 3.9 或更新版本，并安装固定版本的 SDK：

```bash
pip install hy-memory==2.0.1
```

ChromaDB 和 Kuzu 属于核心依赖；Qdrant、FAISS、Neo4j、MySQL 缓存及本地重排器有单独的附加依赖。MemHub 源代码的开发环境不同：它要求 Node.js 24、pnpm 11、Python 3.12 和 uv。

初始化客户端之前，先配置 LLM 端点和嵌入端点。README 列出了 `MEMORY_LLM_API_KEY`、`MEMORY_LLM_BASE_URL`、`MEMORY_LLM_MODEL`，以及对应的 `MEMORY_EMBEDDER_*` 变量和 `MEMORY_EMBEDDING_DIMS`；也记录了 `OPENAI_API_KEY` 的默认用法。请提供自己的端点 URL、模型名称、密钥及相匹配的嵌入维度。这些是兼容 OpenAI 的接口，不代表必须使用 Tencent 另外发布的 Hy-Memory-30B 模型。不要把凭据放入将要存储的轨迹中。

以下聊天示例使用文档中的 `MemoryConfig.from_env()`、`HyMemoryClient`、`add()` 和 `search()` API。调用应用必须提供纯文本或 OpenAI 格式消息作为 `authorized_messages`，并提供稳定且获得授权的 `user_id` 以及 `query`。示例只显示返回值，没有声称得到任何特定结果：

```python
from hy_memory import HyMemoryClient, MemoryConfig

def write_and_recall(authorized_messages, user_id, query):
    config = MemoryConfig.from_env()  # Caller supplies LLM and embedding settings.
    client = HyMemoryClient(config=config, mode="pro")
    try:
        client.add(authorized_messages, user_id=user_id)
        return client.search(query, user_ids=[user_id], limit=10)
    finally:
        client.close()
```

使用工作或编程流程时，请传入包含工具调用或 `role="tool"` 条目的消息轨迹，并明确设置 `scene`。设置 `workspace_id` 以隔离项目材料；`branch` 必须搭配这一设置。当调用应用的边界重要时，写入时请设置 `source`，搜索时请设置 `include_sources` 或 `exclude_sources`。聊天搜索返回记忆通道；工作／编程搜索返回 `facts` 和 `experiences`，编程还会返回 `chain_block`。把返回的记录交给智能体宿主前，请先检查。`list_memories`、`get`、`update` 和 `delete` 可用于逐条管理记录。

成功的集成应有来自已授权输入的存储记录，以及范围受限、能回答预期记忆检索问题的搜索结果。README 记录了返回字段，但我们没有观察实际运行，因此无法声称提取或检索成功。如果工作／编程搜索为空，先确认写入内容包含工具结果，且使用了 `pro` 或 `ultra`，再检查是否使用相同的 `user_id`、`workspace_id`、`branch` 和来源过滤条件。如果更换嵌入模型或维度，[MemHub 配置指南](https://github.com/Tencent-Hunyuan/Hy-Memory/blob/main/memhub/MEMORY.md)提醒，现有集合不能直接改用不同的向量宽度。

## MemHub 和模型是分开的选择

MemHub 是规划中基于 SDK 构建的桌面与 CLI 产品。其 [README](https://github.com/Tencent-Hunyuan/Hy-Memory/blob/main/memhub/README.md) 描述了受管理的本地运行时、来源连接器和宿主集成。其[变更日志](https://github.com/Tencent-Hunyuan/Hy-Memory/blob/main/CHANGELOG.md)更具体地说明了可用状态：源代码版本 1.0.0 build 4 已存在，但 npm 发布和 GitHub 发布文件仍待完成。[安装指南](https://github.com/Tencent-Hunyuan/Hy-Memory/blob/main/memhub/docs/INSTALLATION.md)列出 Linux 和 macOS 为目标平台，并表示不支持 Windows；其中的 npm 安装步骤以相关文件已发布为前提。目前应把它视为规划中的安装路径。

本地存储也不意味着每个处理步骤都在本地完成。MemHub 的[隐私文档](https://github.com/Tencent-Hunyuan/Hy-Memory/blob/main/memhub/PRIVACY.md)区分了读取对话来源的许可、向所选第三方模型服务发送已授权材料的许可，以及智能体宿主检索记忆的许可。文档指出，原始来源证据保存在本地数据目录；如果选择外部模型服务，该服务会收到所选任务需要的已授权内容。直接使用 SDK 的集成者必须自行实现来源同意、模型访问和宿主记忆检索控制；MemHub 的[集成指南](https://github.com/Tencent-Hunyuan/Hy-Memory/blob/main/memhub/MEMORY.md)表示，产品桥接层会加入这些治理步骤，而不是只调用 SDK。

Tencent 也发布了 [Hy-Memory-30B-A3B](https://huggingface.co/tencent/Hy-Memory-30B-A3B)，这是一个为记忆写入而训练的模型，其[技术报告](https://arxiv.org/abs/2610.22196)于 10 月 15 日提交。报告声称，该模型在固定的基准测试子样本上领先于比较系统。这是供应商自行报告的模型评估，并非证明这套 SDK 或 MemHub 能改善已部署智能体回答的独立证据。SDK 也接受其他兼容的模型服务。

仓库当前的[许可证文件](https://github.com/Tencent-Hunyuan/Hy-Memory/blob/main/LICENSE)和项目元数据都标注 Apache-2.0。变更日志表示，这是在 2.0.1 上传后采用的；该次上传不可变更的 [PyPI 元数据](https://pypi.org/project/hy-memory/2.0.1/)仍标注 MIT。包可免费下载，但所选模型或嵌入服务可能按请求收费；发布文档没有记录通用的运行价格。因此，实际决策在于集成哪种记忆路径和授权边界，并在开发者自己的环境中衡量供应商费用与检索质量。

## 来源与延伸阅读

- [Hy-Memory 仓库与快速入门](https://github.com/Tencent-Hunyuan/Hy-Memory) — 当前 SDK 场景、API 示例、模式、存储选项和来源过滤条件。
- [发布变更日志](https://github.com/Tencent-Hunyuan/Hy-Memory/blob/main/CHANGELOG.md)和 [PyPI 2.0.1](https://pypi.org/project/hy-memory/2.0.1/) — SDK 不同的发布日期、包需求、MemHub 状态及许可证元数据差异。
- [MemHub README](https://github.com/Tencent-Hunyuan/Hy-Memory/blob/main/memhub/README.md)、[SDK 集成指南](https://github.com/Tencent-Hunyuan/Hy-Memory/blob/main/memhub/MEMORY.md)和[隐私文档](https://github.com/Tencent-Hunyuan/Hy-Memory/blob/main/memhub/PRIVACY.md) — 源代码阶段的产品架构、配置及授权边界。
- [MemHub 安装指南](https://github.com/Tencent-Hunyuan/Hy-Memory/blob/main/memhub/docs/INSTALLATION.md) — 目标平台及有条件的发布文件安装路径。
- [Hy-Memory-30B-A3B 报告](https://arxiv.org/abs/2610.22196) — 预印本及作者自行报告的模型评估；没有验证这项集成在实际环境中的效果。

## Sources

- [Hy-Memory 仓库与 README](https://github.com/Tencent-Hunyuan/Hy-Memory) — SDK 场景、模式、API 示例、存储和过滤条件；README 的发布公告只列了月份。
- [Hy-Memory 变更日志](https://github.com/Tencent-Hunyuan/Hy-Memory/blob/main/CHANGELOG.md) — 列出 SDK 2.0.1 的日期，说明 MemHub 尚无公开发布文件，并解释不可变更的 PyPI 许可证元数据。
- [PyPI 上的 hy-memory 2.0.1](https://pypi.org/project/hy-memory/2.0.1/) — 已发布的包、Python 要求、发布文件日期及上传时的 MIT 元数据。
- [MemHub README](https://github.com/Tencent-Hunyuan/Hy-Memory/blob/main/memhub/README.md) — 产品源代码架构与开发前提，不能证明应用已公开发布。
- [MemHub 记忆集成指南](https://github.com/Tencent-Hunyuan/Hy-Memory/blob/main/memhub/MEMORY.md) — SDK 配置、嵌入宽度和产品桥接层的边界。
- [MemHub 隐私文档](https://github.com/Tencent-Hunyuan/Hy-Memory/blob/main/memhub/PRIVACY.md) — 区分来源、模型处理和宿主记忆检索的许可。
- [MemHub 安装指南](https://github.com/Tencent-Hunyuan/Hy-Memory/blob/main/memhub/docs/INSTALLATION.md) — 有条件的包安装路径与目标平台。
- [Hy-Memory-30B-A3B 预印本](https://arxiv.org/abs/2610.22196) — 单独的模型、训练方法及供应商报告的基准测试；未经独立验证。
- [仓库当前的 LICENSE](https://github.com/Tencent-Hunyuan/Hy-Memory/blob/main/LICENSE) — 当前 Apache-2.0 源文本；PyPI 2.0.1 仍保留 MIT 元数据。