Tencent는 hy-memory==2.0.1을 공개했다. 채팅·작업·코딩 세션의 맥락을 보관하고 검색하는 Python SDK다. 코드는 공개돼 있지만, 함께 제공되는 MemHub 앱은 아직 공개 배포 산출물을 기다리는 소스 코드 단계다. 공유 메모리 계층을 검토하는 개발자는 지금 SDK를 사용할 수 있지만, 모델 및 임베딩 엔드포인트를 제공하고 각 에이전트가 어떤 세션 기록을 읽을 수 있는지 결정해야 한다.

이 프로젝트 변경 기록은 Hy Memory 2.0.1의 날짜를 2026년 10월 16일로 명시한다. PyPI에는 패키지가 10월 15일 업로드된 것으로 기록돼 있으며, 관련 모델 논문은 같은 날 제출됐다. 이는 서로 다른 공개 기록이며 데스크톱 제품이 출시됐다는 증거는 아니다.

큰 변화

  • 달라진 점: 공개된 SDK는 add() 및 search()를 통해 채팅·작업·코딩 메모리 경로를 별도로 제공하며, 통합 애플리케이션에서 사용할 수 있는 소스 및 워크스페이스 필터도 제공한다.
  • 작동 방식: 채팅은 대화를 메모리 계층으로 구성한다. 작업은 도구 추적에서 세션에 관한 사실 하나를 추출하고, 가치가 있다고 판단되면 재사용할 수 있는 경험도 추출한다. 코딩은 코드 변경의 버전 체인을 추가한다. 호출자는 원본 자료, 식별자, 저장소 설정, 모델 서비스를 제공한다.
  • 의미: 에이전트 호스트는 새 세션마다 전체 이력을 전달하는 대신 이전 대화나 작업 결정의 간결한 기록을 검색할 수 있다. 그 기록이 정확하고 접근이 허가됐으며 유용한지는 여전히 호스트가 무엇을 보내고 어떤 기억을 프롬프트에 다시 포함하도록 허용하는지에 달려 있다.

통합 전에 워크플로 선택하기

이 SDK README는 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 사용 경로

다음 순서는 저장소의 빠른 시작 안내와 MemHub의 SDK 설정 가이드에 근거한다. BIG CHANGE는 패키지를 실행하거나 모델을 호출하지 않았다.

Python 3.9 이상을 사용하고 버전을 고정한 SDK를 설치한다.

Terminal
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의 설정 가이드는 기존 컬렉션을 다른 벡터 너비로 그대로 재사용할 수 없다고 경고한다.

MemHub와 모델은 별개의 선택

MemHub는 SDK를 기반으로 제안된 데스크톱·CLI 제품이다. 해당 README는 관리형 로컬 런타임, 소스 커넥터, 호스트 통합을 설명한다. 해당 변경 기록은 가용성을 더 구체적으로 설명한다. 소스 버전 1.0.0 빌드 4는 있지만 npm 게시와 GitHub 배포 산출물은 아직 준비 중이다. 설치 가이드는 Linux와 macOS를 배포 대상으로 제시하고 Windows는 지원하지 않는다고 명시한다. npm 설치 순서는 해당 산출물이 게시돼야 사용할 수 있다. 현재로서는 예정된 설치 경로로 보아야 한다.

로컬에 저장한다고 해서 모든 처리 단계가 로컬에서 이루어지는 것도 아니다. MemHub의 개인정보 보호 문서는 대화 소스를 읽을 권한, 허가된 자료를 선택한 외부 모델 서비스에 보낼 권한, 에이전트 호스트가 기억을 검색할 권한을 구분한다. 원시 소스 증거는 로컬 데이터 디렉터리에 저장되며, 외부 모델 서비스를 선택하면 선택한 작업에 필요한 허가된 내용이 그 서비스에 전달된다고 설명한다. SDK를 직접 사용하는 통합 개발자는 소스 동의, 모델 접근, 호스트의 기억 검색 제어를 직접 구현해야 한다. MemHub의 통합 가이드는 자사 제품 브리지가 SDK만 호출하는 대신 이러한 거버넌스 단계를 추가한다고 설명한다.

Tencent는 Hy-Memory-30B-A3B도 공개했다. 기억 작성을 학습한 모델이며 관련 기술 보고서는 10월 15일 제출됐다. 보고서는 고정된 벤치마크 하위 표본에서 비교 시스템보다 앞선다고 주장한다. 이는 공급업체가 보고한 모델 평가이며, 이 SDK나 MemHub가 실제 배포된 에이전트의 답변을 개선한다는 독립적인 증거는 아니다. SDK는 다른 호환 모델 서비스도 허용한다.

저장소의 현재 라이선스 파일과 프로젝트 메타데이터에는 Apache-2.0이 명시돼 있다. 변경 기록에 따르면 이는 2.0.1 업로드 이후 채택됐으며, 당시 업로드의 변경 불가능한 PyPI 메타데이터에는 아직 MIT가 명시돼 있다. 패키지는 무료로 내려받을 수 있지만 선택한 모델 또는 임베딩 서비스가 요청에 요금을 부과할 수 있다. 배포 자료에는 공통으로 적용되는 운영 가격이 명시돼 있지 않다. 따라서 실제 선택은 어떤 메모리 경로와 권한 경계를 통합할지 결정하고, 개발자 자신의 환경에서 공급업체 요금과 기억 검색 품질을 측정하는 것이다.

출처와 더 읽을거리