이용 가이드

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

1빠른 시작

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

Claude.ai 웹 — 키가 필요 없습니다. 커넥터에 주소만 넣으면 Google 로그인으로 자동 연결돼요. 아래 A 그룹.
그 외 (ChatGPT·Codex·Claude Code·Grok) — 먼저 API 키를 발급한 뒤, 클라이언트에 Bearer hk_... 로 등록합니다. 아래 B 그룹.
연결한 AI 에게 자연어로 “이거 기억해줘” 라고 말하면 저장되고, 저장된 기억은 대시보드 탭에서 관리합니다.

2AI 클라이언트 연결

A. OAuth — 키 없이 연결

Claude.ai 웹

MCP · OAuth키 불필요

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

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

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

B. API 키(Bearer)로 연결

먼저 API 키 탭에서 클라이언트마다 키를 하나씩 발급해 두세요.

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

MCP · Streamable HTTP키 필요

원격 MCP 서버로 한 줄이면 등록됩니다. 터미널에서 (어느 폴더든):

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

스코프 — 기본은 --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   # 도구 9개 노출 확인

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

이렇게 쓰세요

“내 Heirmos 메모리에 뭐 있어?” → heirmos_list
“이 결정 Heirmos에 기억해줘” → heirmos_schema 로 분류 확인 후 heirmos_write
“전에 정한 배포 절차 찾아줘” → heirmos_search

잘 안 될 때

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

Codex CLI (0.133+)

MCP · CLI키 필요

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.

“Heirmos에서 메모리 목록 보여줘” → heirmos_list
“지금 결정한 거 Heirmos에 저장해” → heirmos_write
“Heirmos에서 ‘async pattern’ 검색” → heirmos_search

잘 안 될 때

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 → 재등록.
connection refused — curl -i https://mcp.heirmos.com/mcp 가 401(=서버 도달, 인증 거부)로 나오면 정상. 그 외면 네트워크 점검.
옛 /sse 등록 — codex mcp remove heirmos 후 위 /mcp 로 재등록.

ChatGPT (Custom GPT)

REST Action키 필요

Custom GPT → Configure → Create new Action
Authentication = API Key, Auth Type = Bearer, 값 = 발급한 hk_... 키
Schema → Import from URL: https://api.heirmos.com/openapi.json (또는 저장소 docs/openapi.json 붙여넣기)
(권장) Instructions 에 source="chatgpt" 로 저장 + path 자동 분류 규칙 추가

검증: 새 대화에서 “Heirmos health check 해줘” → GET /health 200.

xAI Grok

function-calling키 필요

MCP 가 아니라 직접 코드로 호출합니다. REST base https://api.heirmos.com + docs/onboarding/grok.json 의 함수 정의를 사용하고, tool_call 시 본인 코드가 Authorization: Bearer hk_... 부착 + source="grok" 로 저장.

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

3API 키 관리

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

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

4대시보드 사용법

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

5잘 저장하는 법

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

6자주 묻는 질문

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