Hy Memory 2.0·MemHub 사용법: Codex·Claude Code 기억 공유 가이드
AI 코딩 도구를 바꿀 때마다 “이 저장소에서는 pnpm을 쓴다”, “마이그레이션 파일은 직접 고치지 않는다” 같은 규칙을 다시 설명해야 하는 경우가 많습니다. Tencent Hunyuan이 2026년 10월 16일 공개한 Hy Memory 2.0과 MemHub는 이 문제를 모델 자체가 아니라 별도의 기억 계층으로 풀려는 오픈소스 프로젝트입니다. Codex와 Claude Code의 대화 기록을 사용자가 허용한 범위에서 로컬 기억으로 정리하고, 필요한 도구가 MCP를 통해 다시 조회하게 만드는 방식입니다.
이 글은 벤치마크 순위를 홍보하기보다, 지금 공개된 구성요소 중 무엇을 선택해야 하는지, MemHub를 설치하기 전에 어떤 버전과 권한을 확인해야 하는지, Codex·Claude Code 연결이 실제로 어떤 파일을 바꾸는지를 중심으로 설명합니다. 확인일은 2026년 10월 20일입니다.
먼저 알아둘 핵심
- MemHub는 일반 사용자가 여러 AI 도구의 기억을 한곳에서 관리하는 로컬 우선 앱입니다.
- Hy Memory SDK는 개발자가 자신의 에이전트에 채팅·업무·코딩 기억을 넣을 때 사용하는 Python 계층입니다.
- Hy-Memory-30B-A3B는 기억 추출·갱신용 오픈 모델입니다. MemHub를 써보기 위해 이 30B 모델을 직접 실행할 필요는 없습니다.
- 공개 v1.0.4 자산은 macOS Apple Silicon DMG와 Linux x64/arm64 Runtime입니다. Windows와 Intel Mac용 공개 설치 파일은 확인되지 않았습니다.
- Codex와 Claude Code 연결은 자동으로 모든 기억을 프롬프트에 넣는 방식이 아닙니다. 기본적으로 Skill이 조회 시점을 안내하고 모델이 MCP 도구를 호출합니다.
세 계층 중 무엇을 선택할까
| 선택 | 적합한 사용자 | 직접 관리할 것 |
|---|---|---|
| MemHub | Codex·Claude Code·Cursor 등 기존 도구 사이에서 기억을 이어 쓰고 싶은 사용자 | 연결할 앱, 동기화·조회 권한, 모델 제공자, 로컬 데이터 |
| Hy Memory SDK | 자체 에이전트나 사내 서비스에 기억 API를 붙이는 개발자 | LLM·임베딩 엔드포인트, 저장소, scene과 mode, 데이터 수명주기 |
| 30B-A3B 모델 | 기존 기억 프레임워크의 추출·정리 모델을 교체하거나 연구하려는 팀 | 모델 호스팅 자원, 추론 서버, 평가와 안전 정책 |
개인 개발자가 “도구를 바꿔도 프로젝트 규칙을 이어가고 싶다”는 목적이라면 MemHub부터 보는 편이 자연스럽습니다. 반대로 제품 안에 기억 기능을 넣으려면 SDK가 맞습니다. SDK의 chat, working, coding scene은 각각 개인 대화, 업무 진행·재사용 경험, 코드 변경 이유와 버전 흐름을 다르게 다룹니다.
설치 전에 확인할 네 가지
1. 운영체제와 실제 릴리스 자산
공식 문서는 macOS 13 이상, Linux x64/arm64를 목표로 설명하지만, 설치 가능 여부는 문서의 목표가 아니라 GitHub Releases에 실제로 올라온 파일과 release-manifest.json으로 판단해야 합니다. 10월 20일 확인한 v1.0.4에는 Apple Silicon용 DMG, macOS arm64 Runtime, Linux x64·arm64 Runtime이 있습니다. Windows 파일과 macOS x64 파일은 없었습니다.
2. CLI와 Runtime 버전 일치
npm의 memhub-cli 최신 표시는 1.0.5였지만, 공개 GitHub Release는 v1.0.4였습니다. 설치기는 CLI와 정확히 맞는 Runtime manifest를 확인하도록 설계됐으므로, 최신이라는 이유로 버전이 다른 조합을 강제로 섞지 않는 것이 안전합니다. 현재 공개 자산을 기준으로 시험한다면 먼저 다음처럼 버전을 확인하고, 공개 Runtime과 같은 1.0.4를 명시하는 방법이 보수적입니다.
node -v
npm view memhub-cli versions --json
npm install -g memhub-cli@1.0.4
memhub installmemhub install은 확인 없이 바로 설치하는 명령이 아니라 먼저 계획을 보여주는 흐름입니다. manifest의 플랫폼·아키텍처·파일 크기·SHA-256·프로토콜 범위를 확인한 뒤 계속하려면 memhub install --yes를 사용합니다. 공개 CLI는 Node.js 24 이상을 요구합니다.
3. 기억에 보낼 모델 제공자
MemHub는 로컬 우선이지만, 사용자가 제3자 모델 서비스를 선택하면 기억 추출에 필요한 허용된 내용이 그 서비스로 전송될 수 있습니다. “로컬 앱”이라는 말이 곧 “모든 처리가 오프라인”이라는 뜻은 아닙니다. 모델 제공자, 전송 범위, API 키 저장 위치를 확인한 뒤 실제 업무 대화를 가져오세요.
4. 백업과 삭제 경계
기본 데이터 디렉터리는 ~/.one-memory입니다. npm uninstall -g memhub-cli는 Bootstrap CLI만 지우며 Runtime과 기억을 삭제하지 않습니다. memhub uninstall도 기본적으로 기억을 보존합니다. 기억 삭제는 Runtime을 멈춘 뒤 정확한 경로를 재확인하는 memhub delete-data에서만 수행됩니다. 처음에는 테스트 저장소와 비민감 대화로 시작하고, 백업 정책을 정한 뒤 범위를 넓히는 편이 좋습니다.
설치와 정상 동작 확인 순서
- 릴리스 확인: GitHub v1.0.4의 자산 목록에서 자신의 OS·CPU와
release-manifest.json을 확인합니다. - Bootstrap CLI 설치: 위와 같이 대응 버전을 고정합니다. npm 설치만으로 Runtime 다운로드나 서비스 등록이 자동 실행되지는 않습니다.
- 설치 계획 검토:
memhub install결과의 다운로드 출처, 설치 위치, 데이터 위치를 읽습니다. - Runtime 설치: 계획이 맞으면
memhub install --yes를 실행합니다. Linux 백그라운드 서비스에는 systemd user session이 필요합니다. - 초기화와 진단:
memhub init,memhub status,memhub doctor순서로 상태를 확인합니다.
memhub init
memhub status
memhub doctormacOS Apple Silicon 사용자는 같은 v1.0.4 Release의 공증된 DMG를 이용할 수도 있습니다. GUI와 CLI는 같은 Runtime과 데이터 디렉터리를 공유합니다. 앱 창을 닫아도 LaunchAgent가 관리하는 Runtime은 계속 동작할 수 있으므로, 단순히 창을 닫은 것을 서비스 중지로 오해하지 않아야 합니다.
Codex와 Claude Code를 연결하면 바뀌는 것
MemHub의 “한 번에 연결”은 단순 로그인 버튼이 아닙니다. Codex에는 ~/.codex/config.toml의 MCP 설정, ~/.codex/skills/memhub-recall/SKILL.md, UserPromptSubmit·Stop Capture Hook이 추가됩니다. Claude Code에는 ~/.claude.json의 MCP, Skill, 그리고 UserPromptSubmit·Stop·SubagentStop Hook이 들어갑니다.
여기서 조회와 동기화는 별도 스위치입니다. 연결만 켜고 동기화를 끄면 도구는 기존 기억을 조회할 수 있지만 새 대화는 MemHub에 들어가지 않습니다. 반대로 연결을 끄고 동기화만 켜면 MemHub는 새 기록을 읽을 수 있어도 Codex나 Claude Code에 기억 조회 도구가 노출되지 않습니다. 양쪽을 모두 켜야 입력과 조회가 이어집니다.
설정 파일을 쓰고 난 뒤 실행 중인 Codex·Claude Code가 이를 즉시 다시 읽는다는 보장은 없습니다. 완전히 종료한 뒤 새 세션을 시작하고, MCP 도구 목록과 Skill이 보이는지 확인하세요. 기존 설정을 사용자가 수정한 경우 제거 과정이 강제로 덮어쓰지 않고 수동 확인을 요구할 수 있습니다.
실용적인 활용 예시 3가지
저장소 규칙 이어받기
첫 세션에서 패키지 관리자, 테스트 명령, 변경 금지 파일, 리뷰 기준을 확정합니다. 다음 도구에서는 “이 저장소의 빌드·테스트 규칙과 금지 사항을 기억에서 찾아 요약한 뒤 작업 계획을 제시해 달라”고 요청합니다. 산출물은 코드가 아니라 먼저 규칙 목록이어야 하며, 현재 저장소의 README와 실제 설정 파일로 다시 검증해야 합니다.
장기 마이그레이션의 결정 기록
프레임워크 업그레이드를 여러 날 진행할 때, 선택한 버전과 보류한 대안, 실패 원인, 남은 작업을 세션별로 남깁니다. 새 세션은 관련 기억을 조회해 “이미 기각한 방법을 반복하지 않는지”, “현재 브랜치와 기억의 경로가 일치하는지”를 확인한 뒤 다음 단계를 제안하게 합니다. 기억은 근거를 찾는 출발점이지 Git 기록이나 이슈 트래커를 대체하지 않습니다.
도구를 바꾼 인수인계
Claude Code에서 조사와 설계를 하고 Codex에서 구현하는 흐름이라면, 구현 전에 설계의 목표·제약·완료 기준만 조회하게 할 수 있습니다. 비밀 값, 고객 데이터, 전체 대화 원문은 공유 범위에서 제외하고, 필요한 프로젝트 규칙만 승인하는 방식이 안전합니다.
개인정보와 문제 해결 체크리스트
- 디버그 로그: 기본 info 로그는 대화 본문과 키를 기록하지 않도록 설계됐지만, debug 모드는 전체 모델 prompt/response를 로컬 로그에 남길 수 있습니다. 문제 해결이 끝나면 info로 되돌리고 기존 debug 파일도 별도로 검토하세요.
- 진단 공유: 로그를 이슈에 올릴 때 API 키, 실제 대화, 사용자 경로를 제거합니다.
- 연결이 안 보일 때: Runtime 상태, Credential 승인, 동기화 스위치, 호스트 재시작 순서로 확인합니다.
- 새 대화가 쌓이지 않을 때: 조회 연결과 동기화는 다른 기능입니다. Core가 source scan과 Hook Capture를 허용하는지 확인합니다.
- 설치가 중단될 때: CLI와 Release 버전, OS·CPU 자산, Node 24+, Linux systemd user session, 프록시의 GitHub 접근을 차례로 확인합니다. 해시가 맞지 않으면 검증을 우회하지 말고 파일을 다시 받습니다.
정리
Hy Memory 2.0의 실용적인 변화는 “더 큰 기억 모델”보다 기억을 모델과 도구에서 분리해 사용자가 관리할 수 있게 한 것에 있습니다. 다만 MemHub는 Preview 단계이고 플랫폼별 공개 자산과 npm 버전이 빠르게 바뀌고 있습니다. 지금 시험한다면 v1.0.4처럼 manifest와 Runtime이 실제로 함께 공개된 버전을 고정하고, 비민감 프로젝트에서 조회·동기화 권한을 나눠 검증하는 것이 좋습니다.
공식 자료: Hy Memory 2.0 발표, Hy-Memory 저장소, MemHub Releases, MemHub 개인정보 문서, Codex 연결 문서, Claude Code 연결 문서. 자료 확인일: 2026-10-20.
댓글
댓글 쓰기