Skip to content

README.ko.md

Latest commit

 

History

History
307 lines (222 loc) · 12.5 KB

README.ko.md

File metadata and controls

307 lines (222 loc) · 12.5 KB

🌐 English · 한국어

Hermes Memory Stack 한국어

Hermes Memory Stack 한국어 개요 인포그래픽

Hermes Agent를 위한 선택형 한방 메모리·지식 부트스트랩입니다.

라이선스: MIT GitHub stars 마지막 커밋

Hermes Memory Stack은 새 Hermes 설치에 계층형 memory/knowledge 환경을 붙여주는 선택형 설치 팩입니다. skills, Axiom Perception MCP, llmwiki 모드, Hindsight routing helper, 선택형 NotebookLM 연동, 선택형 source-pack 자동화, 선택형 코드/로그 helper를 비밀 값 없이 설치할 수 있게 돕습니다.

Important

API 키, OAuth 토큰, Google 쿠키, 개인 memory, 개인 config는 포함하지 않습니다. 설치 중 사용자가 직접 선택하고, 비밀 값은 ~/.hermes/.env에만 둡니다.

한눈에 보기

Layer 추가되는 것
Skills Hermes memory-stack 작업을 위한 반복 절차
Axiom Perception MCP 반복 UI/workflow용 실행 패턴 캐시
llmwiki API-free, extraction, local/OAuth bridge, hybrid knowledge 모드
Hindsight routing 선택형 durable-memory provider routing helper
NotebookLM 선택형 외부 source-grounded workspace와 inventory sync
Source packs 공개 docs를 NotebookLM source로 묶고 갱신하는 선택형 workflow
semble_rs 선택형 codebase 탐색 및 log digest helper

빠른 설치

검토 후 설치:

git clone https://github.com/yelixir-dev/hermes-memory-stack
cd hermes-memory-stack
./install.sh

한방 설치:

curl -fsSL https://raw.githubusercontent.com/yelixir-dev/hermes-memory-stack/main/install.sh | bash

설치 후 30초 확인:

hermes skills list | grep -E 'yorha-hermes-memory-stack|notebooklm|native-mcp'
test -f ~/.hermes/config.yaml && echo "Hermes config present"

예상 결과: memory-stack skill 또는 integration route가 하나 이상 보이고, backup/patch 이후에도 Hermes config 파일이 유지됩니다.

설치 가능한 구성

  • Hermes memory stack skills
  • Axiom Perception MCP 실행 패턴 캐시
  • llmwiki: API-free / extraction / local bridge / hybrid embedding 모드
  • Hindsight/Hermes memory 라우팅 helper
  • 선택형 semble_rs 코드 탐색/로그 압축 CLI
  • 선택형 NotebookLM CLI
  • 선택형 NotebookLM → llmwiki inventory sync
  • 선택형 NotebookLM source-pack helper (공개 docs root 대상, nlm-pack와 수동 NotebookLM 인증 필요)
  • 선택형 Hermes auxiliary model routing template

설계 원칙

  1. 선택 우선 — 외부 API를 강제하지 않습니다.
  2. API-free 모드 제공 — 로컬/프라이버시 중심 사용자도 사용 가능합니다.
  3. NotebookLM은 선택형 — Google 로그인과 외부 서비스 사용은 필수가 아닙니다.
  4. 비밀 값은 로컬에만 — 실제 키는 .env에 두고 커밋하지 않습니다.
  5. config 백업 — 수정 전 ~/.hermes/config.yaml을 백업합니다.
  6. 역할 분리:
    • Hermes memory / Hindsight: 개인화 기억
    • session_search: 과거 대화 회상
    • skills: 반복 절차
    • Axiom: 실행 패턴
    • llmwiki: 공유 지식베이스
    • NotebookLM: 선택형 외부 source workspace
    • semble_rs: 선택형 코드/로그 helper

설치 프로필

Minimal

  • skills
  • Axiom Perception MCP
  • 외부 API 없음
  • NotebookLM 없음

API-free

  • skills
  • Axiom Perception MCP
  • llmwiki markdown/wiki 모드
  • 선택형 semble_rs
  • 외부 API 불필요

Full / Selectable

  • Hindsight routing wizard
  • llmwiki mode wizard
  • Axiom
  • 선택형 semble_rs
  • 선택형 NotebookLM
  • 선택형 auxiliary routing

NotebookLM

NotebookLM은 기본 설치가 아니라 옵션입니다.

선택한 경우 CLI와 브라우저 dependency만 설치하고, 로그인은 사용자가 직접 합니다.

notebooklm login
notebooklm auth check --test --json
notebooklm list --json

Google cookie, storage_state.json, 계정 credential은 절대 배포하거나 복사하지 않습니다.

NotebookLM 인증이 끝난 경우 선택형 inventory sync를 켤 수 있습니다. 이 sync는 노트북 이름, ID, source 제목/URL/status, 짧은 요약만 저장합니다.

~/wiki/_meta/notebooklm-inventory.md

이 파일은 에이전트가 “어떤 NotebookLM 노트북을 참고할지” 판단하는 라우팅 지도입니다. Google cookie, storage state, full source body는 저장하지 않습니다.

NotebookLM source-pack 자동화

NotebookLM source-pack 자동화는 기본 설치가 아니라 NotebookLM 지원을 선택한 뒤 다시 고르는 2단계 opt-in 경로입니다. 사용자가 직접 인증한 뒤, 공개 문서 루트를 크롤링/정리해 bundled Markdown source로 만들고 manifest/hash 기반으로 갱신하는 helper를 켤 수 있습니다.

Memory Stack은 crawler/bundler 자체를 구현하지 않고, 독립 Source Pack Builder를 GitHub 기준으로 설치/갱신합니다.

uv tool install "git+https://github.com/yelixir-dev/notebooklm-source-pack-builder.git@main" --force

GitHub 갱신 후 사용하는 안전한 CLI 연결면은 다음입니다.

nlm-pack sync <pack-name> --config <config.yaml> --no-upload --json
nlm-pack refresh <pack-name> --config <config.yaml> --versioned --upload --json

배포 파일:

config/notebooklm-source-pack.example.yaml
scripts/install-notebooklm-source-pack-sync.sh

NotebookLM 설치 단계에서 선택하면 다음 위치로 복사됩니다.

~/.hermes/notebooklm-source-packs/examples/notebooklm-source-pack.example.yaml
~/.hermes/scripts/install_notebooklm_source_pack_sync.sh

cron/upload 활성화 전에는 GitHub 기준 builder 설치/갱신 단계가 성공해야 하고, notebooklm.notebook_id를 사용자가 config에 직접 적어야 하며, 수동 인증 확인이 성공해야 합니다.

notebooklm login
notebooklm auth check --test --json

상세 계획은 NOTEBOOKLM_SOURCE_PACKS.md에 둡니다. 핵심 경계는 다음과 같습니다.

  • 기본값은 공개 docs/source root만 대상으로 합니다.
  • Google cookie, storage_state.json, OAuth token, private browser profile, source body는 repo에 넣지 않습니다.
  • Hermes script-only cron은 변경이 없으면 조용히 종료합니다.
  • deploy/refresh 후에는 compact NotebookLM inventory를 llmwiki로 sync합니다.
  • NotebookLM Automation / Source Pack Builder 구현과 테스트는 독립 project/board로 유지합니다.

Hindsight / Memory 선택지

설치기는 다음 중 선택하게 합니다.

  • 기존 설정 유지
  • 기본 Hermes provider가 GPT OAuth(openai-codex)인 경우, 현재 로컬 GPT OAuth bearer token을 Hindsight local-embedded LLM 호출에 재사용할지 질문하고 연결
  • 연결된 Hermes OAuth/provider/bridge 재사용 의도 설정
  • 외부 OpenAI-compatible endpoint 설정
  • 건너뛰기

GPT OAuth 재사용은 opt-in이며 로컬에서만 수행됩니다. 설치기는 ~/.hermes/auth.json의 현재 OAuth access token을 로컬 Hindsight/Hermes env 파일에 복사해 Hindsight embedded daemon이 같은 GPT endpoint를 호출할 수 있게 합니다. 토큰은 배포물에 포함하거나 커밋하지 않습니다. OAuth 토큰이 만료되거나 Hermes 인증을 다시 한 경우 설치기를 다시 실행하거나 Hindsight env를 갱신하세요. 그 외 provider/OAuth 직접 재사용은 provider마다 다르므로, 필요하면 OpenAI-compatible bridge나 LiteLLM proxy를 통해 연결합니다.

llmwiki 선택지

  • 건너뛰기
  • API-free markdown/wiki 모드
  • 외부 API extraction
  • 로컬/OAuth bridge extraction
  • extraction + embedding hybrid

embedding은 필수가 아닙니다. 사용자가 외부 embedding, 로컬 embedding, embedding 없음 중 선택합니다.

저장소 구조

NOTEBOOKLM_SOURCE_PACKS.md
install.sh
uninstall.sh
scripts/
  patch-config.py
  write-llmwiki-env-shim.py
  sync-notebooklm-inventory.py
  install-notebooklm-inventory-sync.sh
  install-notebooklm-source-pack-sync.sh
config/
  env.template
  notebooklm-source-pack.example.yaml
  profiles/
skills/
  hermes-memory-stack/
  llm-wiki/
  axiom-perception/
  semble-rs/
  notebooklm/

삭제 / 복구

한방 설치를 지우거나 config를 이전 백업으로 되돌리고 싶으면 삭제/복구 helper를 실행하세요.

한방 삭제/복구:

curl -fsSL https://raw.githubusercontent.com/yelixir-dev/hermes-memory-stack/main/uninstall.sh | bash

검토 후 실행:

git clone https://github.com/yelixir-dev/hermes-memory-stack
cd hermes-memory-stack
./uninstall.sh

삭제 스크립트도 선택형입니다. 다음을 처리할 수 있습니다.

  • ~/.hermes/skills에 복사된 stack skill 제거
  • ~/.hermes/scripts의 helper script 제거
  • stack-owned NotebookLM inventory/source-pack cron job 제거
  • 선택적으로 ~/wiki/_meta/notebooklm-inventory.md 제거
  • perception MCP 등록 제거
  • 선택적으로 최신 ~/.hermes/config.yaml.bak.* 복구
  • 선택적으로 notebooklm-py, semble_rs, llm-wiki-compiler uninstall

Hermes Agent 본체, 개인 memory, session, auth file, Google cookie, 무관한 사용자 config는 삭제하지 않습니다.

문제 해결

curl | bash에서 선택을 못 하고 자동으로 진행됨

정상적인 터미널에서는 선택지가 떠야 합니다. installer는 stdin으로 script가 pipe되어도 /dev/tty에서 wizard 입력을 읽습니다.

curl -fsSL https://raw.githubusercontent.com/yelixir-dev/hermes-memory-stack/main/install.sh | bash

만약 실행 환경에 interactive TTY가 전혀 없으면 안전한 기본값으로 진행하고 경고를 출력합니다. 특이한 터미널에서는 clone mode를 쓰면 됩니다.

git clone https://github.com/yelixir-dev/hermes-memory-stack
cd hermes-memory-stack
./install.sh

Axiom Perception MCP에서 No such file or directory: 'uvx axiom-perception-mcp'

Hermes MCP 등록은 command와 args를 분리해야 합니다.

hermes mcp add perception --command uvx --args axiom-perception-mcp

installer도 이 분리 형식을 사용합니다. uvx 자체가 없다면 먼저 uv를 설치한 뒤 MCP add 명령을 다시 실행하세요.

보안

이 저장소는 secrets, OAuth token, browser storage, 개인 memory, 개인 Hermes config를 배포물에 포함하지 않는 것을 원칙으로 합니다. 신고 정책과 보안 경계는 SECURITY.md를 참고하세요. 비공개 보안 제보는 GitHub Security Advisory form(https://github.com/yelixir-dev/hermes-memory-stack/security/advisories/new)을 사용하거나 yelixir.dev@gmail.com으로 연락하세요.

기여

Issue와 pull request를 환영합니다. 단, stack 경계를 지켜주세요: credential 커밋 금지, private source body 금지, Google cookie/browser state 금지, 외부 API 강제 의존 금지.

감사 및 참고 프로젝트

이 integration pack은 다음 upstream 프로젝트를 참고하거나 선택적으로 설치합니다.

자세한 내용은 ACKNOWLEDGEMENTS.md를 참고하세요. 이 repo는 integration/bootstrap layer이며, upstream 프로젝트의 license와 저작권은 각 프로젝트에 귀속됩니다.