# Hy Memory 2.0 gives agents three ways to keep context

> Tencent's Hy Memory 2.0.1 SDK separates chat, work and coding recall. Its MemHub app has source but no public release artifacts; integrations still need model endpoints and explicit access boundaries.

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 published `hy-memory==2.0.1`, a Python SDK for retaining and retrieving context from chat, work and coding sessions. The code is public; its companion MemHub app is still source code awaiting public release artifacts. Developers evaluating a shared memory layer can use the SDK now, but need to supply model and embedding endpoints and decide which session records each agent may read.

The [project changelog](https://github.com/Tencent-Hunyuan/Hy-Memory/blob/main/CHANGELOG.md) dates Hy Memory 2.0.1 to October 16, 2026. [PyPI](https://pypi.org/project/hy-memory/2.0.1/) records the package upload on October 15, and the related [model paper](https://arxiv.org/abs/2610.22196) was submitted that day. Those are distinct publication records, rather than proof that the desktop product shipped.

## The big change

- **What changed:** The published SDK exposes separate chat, working and coding memory paths through `add()` and `search()`, with source and workspace filters that an integrating application can use.
- **How it works:** Chat organizes conversations into memory layers. Working extracts a session fact and, when warranted, reusable experiences from a tool trace. Coding adds a version chain for code changes. The caller supplies the source material, identities, storage configuration and model services.
- **Why it matters:** An agent host can retrieve a compact record of prior conversations or task decisions instead of passing an entire history into every new session. Whether that record is accurate, authorized and useful still depends on what the host sends and which memories it allows back into the prompt.

## Choose the workflow before integrating

The [SDK README](https://github.com/Tencent-Hunyuan/Hy-Memory) describes three `scene` values. `chat` accepts plain text or message arrays, then returns `profile`, `normal` and `proactive` recall channels. In `lite` mode, it stores raw text for embedding search without LLM extraction. `pro` adds extraction and reconciliation; `ultra` can run a further evolution pass through `evolve()`.

For `working`, the input must contain a tool-call trace. A session produces one fact about the task, approach and result, plus zero or more reusable experiences that pass the engine's value threshold. `coding` uses the same two layers and adds a version-evolution chain for the code touched. The README says the chain can use local Git diffs if `MEMORY_CODING_CHAIN_REPO_ROOT` is set, or deterministic replace actions in the tool trace. In `lite`, the SDK ignores the working/coding scene distinction and stores raw memory.

These output shapes serve different questions. A conversation preference belongs in `chat`; a completed task with tool results belongs in `working`; a code change whose earlier revision may matter belongs in `coding`. This is a documented routing distinction, not a BIG CHANGE performance test.

## A documented SDK path

The following sequence is based on the [repository quick start](https://github.com/Tencent-Hunyuan/Hy-Memory) and [MemHub's SDK configuration guide](https://github.com/Tencent-Hunyuan/Hy-Memory/blob/main/memhub/MEMORY.md). BIG CHANGE did not run the package or make model calls.

Use Python 3.9 or newer and install the pinned SDK:

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

ChromaDB and Kuzu are in the core dependency set; Qdrant, FAISS, Neo4j, MySQL cache and a local reranker have separate extras. The MemHub source development environment is different: it calls for Node.js 24, pnpm 11, Python 3.12 and uv.

Configure both an LLM endpoint and an embedding endpoint before initializing the client. The README lists `MEMORY_LLM_API_KEY`, `MEMORY_LLM_BASE_URL`, `MEMORY_LLM_MODEL`, and the corresponding `MEMORY_EMBEDDER_*` variables plus `MEMORY_EMBEDDING_DIMS`; it also documents an `OPENAI_API_KEY` default. Supply your own endpoint URLs, model names, keys and matching embedding dimensions. These are OpenAI-compatible interfaces, not a requirement to use Tencent's separate Hy-Memory-30B model. Keep credentials out of the traces being stored.

The following chat example uses the documented `MemoryConfig.from_env()`, `HyMemoryClient`, `add()` and `search()` APIs. The calling application must supply `authorized_messages` as plain text or OpenAI-format messages, a stable authorized `user_id`, and the `query`. It shows the return value without claiming a particular result:

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

For working or coding, pass a message trace containing a tool call or `role="tool"` entry and set `scene` explicitly. Set `workspace_id` to isolate project material; `branch` requires it. Set `source` on writes and `include_sources` or `exclude_sources` on searches when caller application boundaries matter. Chat search returns memory channels; working/coding search returns `facts` and `experiences`, with `chain_block` for coding. Inspect the returned records before handing them to the agent host. `list_memories`, `get`, `update` and `delete` provide record-level management.

A successful integration would have a saved record from an authorized input and a scoped search result that answers the intended recall question. The README documents return fields, but we have no observed run to claim that extraction or recall succeeded. If a working/coding search is empty, first confirm that the write included tool results and used `pro` or `ultra`, then check the same `user_id`, `workspace_id`, `branch` and source filters. If changing an embedding model or dimensions, [MemHub's configuration guide](https://github.com/Tencent-Hunyuan/Hy-Memory/blob/main/memhub/MEMORY.md) warns that an existing collection cannot simply be reused with a different vector width.

## MemHub and the model are separate choices

MemHub is the proposed desktop and CLI product built on the SDK. Its [README](https://github.com/Tencent-Hunyuan/Hy-Memory/blob/main/memhub/README.md) describes a managed local runtime, source connectors and host integrations. Its [changelog](https://github.com/Tencent-Hunyuan/Hy-Memory/blob/main/CHANGELOG.md) is more specific about availability: source version 1.0.0 build 4 exists, but the npm publication and GitHub release artifacts remain pending. The [installation guide](https://github.com/Tencent-Hunyuan/Hy-Memory/blob/main/memhub/docs/INSTALLATION.md) gives Linux and macOS release targets and says Windows is unsupported; its npm install sequence is conditional on those artifacts being published. Treat that sequence as a planned installation path today.

Local storage also does not mean every processing step stays local. MemHub's [privacy document](https://github.com/Tencent-Hunyuan/Hy-Memory/blob/main/memhub/PRIVACY.md) separates permission to read a conversation source, permission to send authorized material to a selected third-party model service, and permission for an agent host to retrieve memory. It says raw source evidence is stored in the local data directory and that an external model service receives the authorized content needed for the chosen task when selected. An integrator using the SDK directly must implement its own source consent, model access and host recall controls; MemHub's [integration guide](https://github.com/Tencent-Hunyuan/Hy-Memory/blob/main/memhub/MEMORY.md) says its product bridge adds those governance steps rather than calling the SDK alone.

Tencent also released [Hy-Memory-30B-A3B](https://huggingface.co/tencent/Hy-Memory-30B-A3B), a model trained for memory writing, with a [technical report](https://arxiv.org/abs/2610.22196) submitted October 15. The report claims a lead over comparison systems on fixed benchmark subsamples. That is a vendor-reported evaluation of the model, not independent evidence that this SDK or MemHub improves a deployed agent's answers. The SDK accepts other compatible model services.

The repository's current [license file](https://github.com/Tencent-Hunyuan/Hy-Memory/blob/main/LICENSE) and project metadata say Apache-2.0. The changelog says this was adopted after the 2.0.1 upload, whose immutable [PyPI metadata](https://pypi.org/project/hy-memory/2.0.1/) still says MIT. The package is free to download, but a chosen model or embedding service can charge for requests; the release documents no universal operating price. The practical decision is therefore which memory path and authorization boundary to integrate, with provider charges and recall quality measured in the developer's own setup.

## Sources & further reading

- [Hy-Memory repository and quick start](https://github.com/Tencent-Hunyuan/Hy-Memory) — current SDK scenes, API examples, modes, storage options and source filters.
- [Release changelog](https://github.com/Tencent-Hunyuan/Hy-Memory/blob/main/CHANGELOG.md) and [PyPI 2.0.1](https://pypi.org/project/hy-memory/2.0.1/) — separate SDK release dates, package requirements, MemHub status and license metadata discrepancy.
- [MemHub README](https://github.com/Tencent-Hunyuan/Hy-Memory/blob/main/memhub/README.md), [SDK integration guide](https://github.com/Tencent-Hunyuan/Hy-Memory/blob/main/memhub/MEMORY.md) and [privacy document](https://github.com/Tencent-Hunyuan/Hy-Memory/blob/main/memhub/PRIVACY.md) — source-stage product architecture, configuration and authorization boundaries.
- [MemHub installation guide](https://github.com/Tencent-Hunyuan/Hy-Memory/blob/main/memhub/docs/INSTALLATION.md) — intended platforms and conditional release artifact path.
- [Hy-Memory-30B-A3B report](https://arxiv.org/abs/2610.22196) — preprint and author-reported model evaluation; it does not validate this integration in the field.

## Sources

- [Hy-Memory repository and README](https://github.com/Tencent-Hunyuan/Hy-Memory) — SDK scenes, modes, API examples, storage and filters; month only in README release notice.
- [Hy-Memory changelog](https://github.com/Tencent-Hunyuan/Hy-Memory/blob/main/CHANGELOG.md) — Dates SDK 2.0.1 and states MemHub lacks public release artifacts; explains immutable PyPI license metadata.
- [hy-memory 2.0.1 on PyPI](https://pypi.org/project/hy-memory/2.0.1/) — Published package, Python requirement, release file dates and MIT upload metadata.
- [MemHub README](https://github.com/Tencent-Hunyuan/Hy-Memory/blob/main/memhub/README.md) — Product source architecture and development prerequisites, not proof of public app release.
- [MemHub memory integration guide](https://github.com/Tencent-Hunyuan/Hy-Memory/blob/main/memhub/MEMORY.md) — SDK configuration, embedding width and product bridge boundaries.
- [MemHub privacy document](https://github.com/Tencent-Hunyuan/Hy-Memory/blob/main/memhub/PRIVACY.md) — Separate source, model processing and host-recall permissions.
- [MemHub installation guide](https://github.com/Tencent-Hunyuan/Hy-Memory/blob/main/memhub/docs/INSTALLATION.md) — Conditional package installation path and platform targets.
- [Hy-Memory-30B-A3B preprint](https://arxiv.org/abs/2610.22196) — Separate model, training approach and vendor-reported benchmark; not independently validated.
- [Current repository LICENSE](https://github.com/Tencent-Hunyuan/Hy-Memory/blob/main/LICENSE) — Current Apache-2.0 source text; PyPI 2.0.1 retains MIT metadata.