Markdown 버전

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`일 때는 입력에 도구 호출 추적이 포함돼야 한다. 한 세션은 작업·접근법·결과에 관한 사실 하나와, 엔진의 가치 임계값을 넘는 재사용 가능한 경험을 0개 이상 생성한다. `coding`은 같은 두 계층을 사용하며, 수정한 코드의 버전 진화 체인을 추가한다. README에 따르면 이 체인은 `MEMORY_CODING_CHAIN_REPO_ROOT` 설정이 있을 때 로컬 Git diff를 사용하거나 도구 추적의 결정적 치환 작업을 사용할 수 있다. `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를 사용해야 한다는 뜻은 아니다. 저장하는 추적에 자격 증명이 포함되지 않게 한다.

다음 채팅 예제는 문서화된 API인 `MemoryConfig.from_env()`, `HyMemoryClient`, `add()` 및 `search()`를 사용한다. 호출하는 애플리케이션은 `authorized_messages`를 일반 텍스트나 OpenAI 형식 메시지로 제공하고, 안정적이며 사용 권한이 확인된 `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 빌드 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 메타데이터를 유지한다.