이용 가이드

Heirmos 는 여러 AI 가 공유하는 하나의 영구 기억입니다. Claude·ChatGPT·Codex·Grok 중 어디서 저장하든 다른 AI 가 같은 기억을 읽고 씁니다. AI 가 알아서 폴더를 분류하고, 원문은 손실 없이 보존됩니다.

아래 카드를 눌러 펼치세요. 필요한 항목만 열어 보면 됩니다. 명령어·주소·예시 문장은 클릭하면 복사됩니다.

1빠른 시작여기부터

연결할 AI 에 따라 길이 둘로 갈립니다.

Claude.ai · ChatGPT (브라우저 앱) — 키 없이 OAuth(링크 로그인). 커넥터에 주소만 넣으면 Google 로그인으로 자동 연결 (아래 2. AI 연결 → A).
Claude Code · Codex · Grok (CLI·기타) — Claude Code · Codex 는 키 없이 OAuth 도 가능. Grok·직접 API 는 API 키 발급 후 Bearer hk_... (아래 2. AI 연결 → B). API 키는 MCP 외 직접 REST 호출·스크립트에도 씁니다.
연결한 AI 에게 자연어로 “이거 기억해줘” 라고 말하면 저장되고, 저장된 기억은 메모장(홈)에서 읽고 고칩니다.

2AI 클라이언트 연결본인 클라이언트만 펼치세요

A. OAuth — 키 없이 연결

Claude.ai 웹

MCP · OAuth키 불필요

Claude.ai → Settings → Connectors → Add custom connector
Remote MCP server URL 에 입력 (Client ID/Secret 은 비움)
Connect → Heirmos 로그인 페이지로 이동 → Google 로그인·동의 → 완료
도구 11개(heirmos_schema / list / read / search / write / update / archive / relations / restore / surface / whoami)가 보이면 연결 성공

이미 이 대시보드에 로그인돼 있으면 Google 동의 화면이 안 뜨고 바로 연결됩니다(정상). 이 연결은 API 키 탭에 oauth:... 라는 이름의 키로 남고, 그 키를 폐기하면 Claude 연결이 끊깁니다.

예전에 /sse 주소로 등록했다면 위 /mcp 로 다시 등록하세요 (구형 SSE 전송은 은퇴했습니다).

ChatGPT (개발자 모드 커넥터)

MCP · OAuth키 불필요

Mac 데스크탑 앱에는 커넥터 메뉴가 없습니다 — 브라우저(chatgpt.com) 또는 Windows 데스크탑 앱에서 추가하세요(앱의 “앱 연결”은 MCP가 아닌 다른 기능). 추가한 커넥터는 계정에 묶여 어느 기기(Mac 앱 포함)에서나 사용됩니다. Plus·Pro·Business·Enterprise·Edu 플랜.

chatgpt.com → 좌측 하단 프로필 → 설정(Settings) → 커넥터(Connectors / Apps)
고급(Advanced) → 개발자 모드(Developer mode) 토글 ON → 커넥터 목록 위 만들기(Create) 버튼 생성
이름 Heirmos · MCP server URL (placeholder 의 /sse 무시 — Heirmos 는 Streamable HTTP) · 인증 OAuth · 신뢰 확인 체크
만들기 → URL 의 OAuth 메타데이터 자동 탐지(DCR) → Heirmos 로그인 팝업 → Google 로그인·동의 → 연결 완료, 도구 목록 표시

“고급 OAuth 설정”은 건드리지 마세요 — URL 만 넣으면 서버 설정을 자동 탐지합니다. 연결 후 새 대화에서 “내 Heirmos 메모리 목록 보여줘” 로 도구 호출 확인. (예전 “Custom GPT + Action + OpenAPI 스키마” 방식은 더 이상 필요 없습니다.)

B. CLI · 직접 연결 (OAuth 또는 API 키)

Claude Code · Codex 는 키 없이 OAuth 가 가장 간편합니다(각 카드 방법 1). Grok·직접 API 는 3. API 키 에서 키를 발급해 쓰세요 — API 키는 MCP 외 직접 REST 호출·스크립트 용도로도 씁니다.

Claude Code (CLI / 데스크탑 / IDE)

MCP · OAuth키 없이 가능

방법 1 (권장) — OAuth, 키 없이

헤더 없이 추가하면 OAuth 로 붙습니다 (Claude.ai 와 동일한 로그인):

claude mcp add --transport http heirmos https://mcp.heirmos.com/mcp

새 세션 claude 실행 → /mcp → heirmos → Authenticate → 브라우저에서 Google 로그인
claude mcp list 가 ✓ Connected 면 완료 — 키 입력 0

방법 2 — API 키(Bearer)

키로 붙이려면 (3. API 키 에서 발급 후) — 전체를 한 줄로:

claude mcp add --transport http heirmos https://mcp.heirmos.com/mcp --header "Authorization: Bearer hk_여기에_평문_키" --scope local

Windows PowerShell 주의 — 위 명령을 여러 줄로 붙여넣으면 Missing expression after unary operator '--' 에러가 납니다(PowerShell 이 줄 앞 --header 의 -- 를 연산자로 오해). 반드시 한 줄로 입력하거나, 줄을 나누려면 bash 의 \ 가 아니라 PowerShell 백틱 ` 을 줄 끝에 쓰세요. 헤더 인식이 이상하면 큰따옴표를 작은따옴표 '…' 로 바꿔 보세요.

스코프 — 기본은 --scope local(나만, 현재 폴더). 개인 키는 이게 안전합니다(키가 git 에 안 올라감). 모든 프로젝트에서 쓰려면 --scope user, 팀과 파일로 공유하려면 --scope project(.mcp.json 이 커밋됨 — 키 노출 주의).

또는 .mcp.json(프로젝트 루트) / ~/.claude.json 에 직접:

{
  "mcpServers": {
    "heirmos": {
      "type": "http",
      "url": "https://mcp.heirmos.com/mcp",
      "headers": { "Authorization": "Bearer hk_여기에_평문_키" }
    }
  }
}

연결 확인:

claude mcp list          # heirmos … ✓ Connected
claude mcp get heirmos   # 도구 11개 노출 확인

실행 중인 세션 안에서는 /mcp 를 입력해 heirmos 상태·도구 목록을 볼 수 있습니다.

잘 안 될 때

도구가 안 보임 — claude mcp get heirmos 로 상태 확인 후 Claude Code 재시작. ✓ Connected 가 아니면 URL·헤더를 다시 보세요.
401 — 키 오타·폐기. 대시보드에서 새 키 발급 후 등록 명령을 다시 실행(claude mcp remove heirmos → 재추가).
첫 저장이 느리거나 끊김 — 저장은 임베딩+분류로 수 초 걸립니다. MCP_TIMEOUT=60000 claude 로 타임아웃을 늘려 재시작하세요.

Codex CLI (0.133+)

MCP · OAuth키 없이 가능

방법 1 (권장) — OAuth, 키 없이

토큰 없이 추가하면 Codex 가 OAuth 지원을 자동 탐지합니다 — codex mcp login 으로 로그인:

codex mcp add heirmos --url https://mcp.heirmos.com/mcp
codex mcp login heirmos        # 브라우저 열림 → Google 로그인(team.pneumora)
codex mcp list                 # 등록·상태 확인

codex mcp login 이 브라우저 OAuth 창을 엽니다. Heirmos 는 DCR(동적 클라이언트 등록)을 지원하므로 client_id/secret 없이 URL 만으로 연결됩니다 — 키 입력 0.

방법 2 — API 키(Bearer)

1) 키를 환경변수로 분리 — 설정파일에 평문이 박히지 않게 합니다.

Windows PowerShell:

[Environment]::SetEnvironmentVariable("HEIRMOS_API_KEY","hk_...","User")

bash / zsh:

export HEIRMOS_API_KEY="hk_..."   # ~/.bashrc 또는 ~/.zshrc 에 추가

2) 새 셸을 열고(변수 적용) 등록 — 키는 --bearer-token-env-var 로 변수명만 넘깁니다:

codex mcp add heirmos \
  --url https://mcp.heirmos.com/mcp \
  --bearer-token-env-var HEIRMOS_API_KEY

codex mcp list           # 등록 목록
codex mcp get heirmos    # 상세 확인

3) 사용 — codex 로 세션을 열고 자연어로 부르면 됩니다. 도구 호출 confirm 이 뜨면 y.

잘 안 될 때

401 / Authentication required — --bearer-token-env-var 누락 또는 변수 미설정. echo $env:HEIRMOS_API_KEY(PS) / echo $HEIRMOS_API_KEY(bash) 로 값 확인.
도구가 안 보임 — npm i -g @openai/codex@latest 로 업그레이드 후 codex mcp remove heirmos → 재등록.
옛 /sse 등록 — codex mcp remove heirmos 후 위 /mcp 로 재등록.

xAI Grok

개발자용키 필요

Grok 은 MCP 커넥터가 없어 직접 API 호출이 필요합니다. REST 주소 에 발급한 키를 Authorization: Bearer hk_... 헤더로 붙여 호출하면 됩니다.

함수(툴) 정의 JSON·요청 예제 등 전체 코드는 docs/onboarding/grok.md 에 정리돼 있습니다. (코드를 다룰 줄 아는 분 대상의 고급 경로예요.)

각 클라이언트의 전체 가이드(스크린샷·트러블슈팅)는 docs/onboarding 에 있습니다.

3이렇게 말해보세요눌러서 복사 → 바로 사용

도구 이름을 외울 필요가 없습니다. 연결한 AI 에게 평소처럼 말하면 저장·검색·발굴이 알아서 일어납니다. 아래 문장을 눌러 복사한 뒤 그대로 붙여넣어 보세요.

저장 — 결정·사실·선호 남기기

회상 — 과거 기억 꺼내기

발굴 — 잊고 있던 연결 떠올리기

확인 — 지금 어느 계정에 저장되나

한국어로 말하면 한국어 그대로 저장됩니다(번역하지 않음). 원문은 손실 없이 보존되고, AI 는 폴더·요약 같은 메타데이터만 덧붙입니다.

4API 키 관리

발급 — 상단 API 키 탭에서 이름(예: chatgpt, codex)을 적고 발급. 평문 hk_... 키는 딱 한 번만 보이니 복사해 두세요.
폐기 — 활성 키 목록의 폐기 버튼. 폐기 즉시 해당 키는 401 처리됩니다. 클라이언트마다 키를 따로 쓰면 특정 AI 만 골라서 끊기 편합니다.
OAuth 키 — Claude.ai OAuth 연결은 oauth:... 키를 자동으로 만듭니다. 그 키를 폐기하면 Claude 연결이 해제됩니다.

키는 서버에 평문으로 저장되지 않습니다(해시만 보관). 비밀번호·카드번호·타인의 사적 정보는 메모리 본문에 저장하지 마세요.

5화면 사용법

메모장(홈) — 기억을 읽고 쓰는 기본 화면. 왼쪽은 폴더 트리, 가운데는 블록 편집기(문단을 클릭하면 바로 고쳐지고 1.4초 뒤 자동 저장), 오른쪽은 회상 레일 — 오래 안 꺼낸 기억·이 메모에 연결된 기억·아직 안 풀린 질문을 옆에 계속 띄웁니다. 메모를 우클릭하면 파일명 바꾸기·이동·삭제.
성좌 — 기억이 별로, 연결이 선으로 보이는 지도. 금빛 큰 별이 여러 생각의 뿌리이고, 밝을수록 최근에 떠올린 기억입니다. 오른쪽 오늘의 회상 데스크에서 가라앉는 기억을 바로 열거나 이어 쓸 수 있습니다.
폴더 브라우저 — 메모장 왼쪽 아래 폴더 브라우저 → 로 들어가는 Drive 식 화면. .md 업로드/다운로드, 드래그로 폴더 이동, 여러 개 골라 한 번에 처리할 때 씁니다.
검토 필요 — AI 가 신뢰도가 낮거나 충돌한다고 본 기억이 모입니다. 맞아요 / 틀렸어요 피드백을 주면 이후 자동 분류에 반영됩니다.
삭제 = 보관(soft delete) — 실제로 사라지지 않으며 복구 가능합니다.

6잘 저장하는 법

자연어로 말하면 됩니다 — “이거 기억해줘”, “내 트레이딩 룰 알아?”. AI 가 알아서 저장·검색합니다.
무엇을 저장? 영구적인 사실·선호·방법론·진행 상황. 이번 주 할 일 같은 일시적 정보는 저장하지 않는 게 좋습니다.
자동 분류 — path 를 직접 안 줘도 AI 가 projects/<프로젝트>/<주제>.md 식으로 추론합니다. 한 메모리 = 한 토픽이 좋습니다.
무손실 + 원어 보존 — 저장한 원문은 그대로 보존되고, AI 는 요약·분류 메타데이터만 덧붙입니다. 한국어로 저장하면 한국어 그대로 들어갑니다(번역하지 않음).

7대화 가져오기ChatGPT · Claude 내보내기 → 기억

연결 직후 기억이 1~2개면 검색할 것도 이을 것도 없습니다. 기존 대화를 통째로 가져오면 오래가는 사실·결정·취향만 기억으로 추출되고, 1분 뒤 첫 리포트를 받습니다.

ChatGPT: 설정 → 데이터 제어 → 데이터 내보내기 / Claude: 설정 → 개인정보 → 데이터 내보내기. 메일로 받은 zip 안의 conversations.json 을 준비합니다.
메모장 사이드바 하단 “ChatGPT · Claude 대화 가져오기 →”(/import)에 파일을 놓습니다. 파일은 브라우저에서만 읽히고, 목록에서 뺀 대화는 서버로 가지 않습니다(기본 전체 선택).
“가져오기 시작”을 누르면 서버가 청크마다 AI 로 추출합니다 — 한 번에 300청크까지, 최근 대화부터. 탭을 닫아도 계속됩니다.
완료되면 “당신의 기억 지도”로 이동합니다: 생긴 기억·폴더, 원래 대화가 있었던 달로 되돌린 시간축, 반복해서 돌아오는 주제, 아직 답하지 않은 질문, 그리고 다른 AI 에서 바로 물어볼 문장.

가져온 기억은 출처가 chatgpt/claude 로 남고 원래 시각을 갖습니다. 리포트가 준 문장을 연결된 다른 AI 에 그대로 물어보세요 — 기억이 AI 를 넘나드는 순간입니다.

비밀번호·카드번호 같은 민감 정보는 추출 단계에서 걸러지지만, 확실히 빼고 싶은 대화는 목록에서 해제하세요.

8코딩 에이전트 자동 기억Claude Code · Codex · Cursor — 훅으로 저장·회상 자동화

Claude Code·Codex 같은 코딩 에이전트에서는 “기억해줘” 라고 말하지 않아도 됩니다. 세션이 시작될 때 이 저장소의 최근 기억과 지금 맥락에 닿는 잊힌 기억이 브리핑으로 주입되고, 컴팩트·종료 시점에 대화의 사람이 읽는 부분만 캡처돼 오래가는 결정·선호만 기억이 됩니다. 한 에이전트가 남긴 결정을 다른 에이전트가 다음 세션에서 읽습니다.

CLI 설치: 저장소 체크아웃에서 uv tool install .(또는 pipx install .; PyPI 발행 전) → heirmos whoami 로 확인.
API 키: API 키 탭(/account)에서 발급해 HEIRMOS_API_KEY 환경변수로 넣습니다. 키가 없으면 훅은 조용히 아무것도 하지 않습니다 — 세션을 막지 않습니다.
Claude Code: /plugin marketplace add team-pneumora/pneumora-plugins → /plugin install heirmos@pneumora-plugins. Codex: codex mcp add heirmos … + AGENTS.md 스니펫(선택: hooks.json). Cursor: 규칙 파일 + MCP. 스니펫은 저장소 integrations/ 에 있습니다.

캡처는 내 프롬프트와 어시스턴트의 글만 보냅니다 — 도구 호출·파일 내용·사고 과정은 제외되고, 키·토큰·전화번호 같은 문자열은 보내기 전에 가려집니다. 브리핑은 회상으로 기록되지 않고, 에이전트가 실제로 기억을 읽을 때만 기록됩니다.

9자주 묻는 질문

지금 어느 계정에 연결됐는지 어떻게 확인해요?: AI 에게 “내 Heirmos 계정 뭐야?” 라고 물으면 됩니다 — heirmos_whoami 도구가 연결된 계정 이메일을 답해줍니다. 여러 구글 계정을 쓸 때 지금 어느 메모리에 저장/검색되는지 확인하는 용도예요.
Claude 연결할 때 Google 로그인 화면이 안 떴어요.: 정상입니다. 이미 이 대시보드에 로그인된 상태라 인증을 건너뛰고 바로 연결된 것입니다.
저장이 5~10초쯤 걸려요.: 저장은 임베딩 + 자동 분류 + 요약을 거쳐서 읽기보다 느립니다. 정상이며, 잠시 기다리면 저장됩니다.
예전 /sse 주소로 등록한 게 안 돼요.: 전송 방식이 /mcp(Streamable HTTP)로 바뀌었습니다. 커넥터 주소를 로 다시 등록하세요.
401 Unauthorized 가 떠요.: 키가 없거나 오타이거나 폐기된 키입니다. Authorization: Bearer hk_... 형식과 키가 활성 상태인지 확인하세요.
키를 잃어버렸어요.: 평문 키는 복구할 수 없습니다. 기존 키를 폐기하고 새로 발급한 뒤, 클라이언트의 키 값만 교체하세요(재등록 불필요).