이용 가이드

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대시보드 사용법

대시보드 — Google Drive 식 폴더 브라우저. 폴더를 열어 탐색하고 파일을 누르면 마크다운 미리보기. 상단 검색창은 의미(시맨틱) + 키워드 하이브리드 검색입니다.
작성·이동·업로드 — 우클릭 메뉴/툴바로 새 메모리·새 폴더 작성, .md 업로드/다운로드, 드래그 또는 이동 다이얼로그로 폴더 이동.
검토 필요 — AI 가 신뢰도가 낮거나 충돌한다고 본 기억이 모입니다. 맞아요 / 틀렸어요 피드백을 주면 이후 자동 분류에 반영됩니다.
삭제 = 보관(soft delete) — 실제로 사라지지 않으며 복구 가능합니다.

6잘 저장하는 법

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

7자주 묻는 질문

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