Eve MCP 클라이언트

eve-client는 지원되는 AI 도구를 호스팅된 Eve 메모리 서비스에 연결하기 위한 로컬 설치 프로그램이자 통합 CLI입니다.

이 도구는 로컬 도구를 감지하고, MCP를 구성하며, 지원되는 경우 Eve가 관리하는 프롬프트 및 후크 파일을 설치하고, 인증을 관리하며, 나중에 통합을 확인, 복구 또는 제거할 수 있습니다. 또한 지원되는 클라이언트에서 로컬 기록을 가져올 수도 있습니다.

Eve 작동 방식

eve install을 실행하면 Eve는 자동으로 실행되는 4개의 수명 주기 후크를 구성합니다. 세션 중에 별도의 명령이 필요하지 않습니다.

수명 주기 후크는 Claude Code 및 Gemini CLI에서 사용할 수 있습니다. Eve는 또한 프롬프트 시딩을 사용하여 Codex CLI 및 기타 MCP 호환 클라이언트에 연결하므로 모든 도구에서 메모리를 사용할 수 있습니다.

Related MCP server: Sovereign Universal Memory MCP

빠른 시작 — 5분

1. Eve 워크스페이스 확보

evemem.com에서 액세스를 요청하세요. 프로비저닝 후 로그인하여 evemem.com/app/overview에서 API 키를 생성하세요.

2. 클라이언트 설치

uv tool install git+https://github.com/sherifkozman/eve-mcp.git

uv가 없나요? 다음을 사용하세요:

pipx install git+https://github.com/sherifkozman/eve-mcp.git

확인: eve version

3. Claude Code 연결 (Gemini CLI의 경우 --tool gemini-cli로 변경)

eve connect --tool claude-code --api-key <your-eve-api-key>

이 명령은 인증, 설치 및 확인을 결합합니다. 단계별 안내는 아래의 API 키 흐름을 참조하세요.

예상 출력:

✓ MCP config written
✓ CLAUDE.md companion updated
✓ Lifecycle hooks configured — Eve auto-injects memory context on every session
✓ Eve memory is connected and responding

방금 무슨 일이 일어났나요? Eve가 4개의 수명 주기 후크를 설치했습니다. 이제부터 모든 Claude Code 세션은 메모리 컨텍스트가 미리 로드된 상태로 시작되고, 새로운 학습 내용이 캡처된 상태로 종료됩니다. Claude에게 Eve를 사용하라고 요청할 필요가 전혀 없습니다.

eve connect가 실패하면 eve doctor --tool claude-code를 실행하고 진단 출력을 확인하세요. github.com/sherifkozman/eve-mcp에 이슈를 제기하세요.

4. 세션 간 메모리 테스트

Claude Code에서 Claude에게 다음과 같이 말하세요:

"내가 PostgreSQL을 사용하고 users 테이블(email 및 created_at 컬럼)이 있다는 것을 기억해 줘."

새로운 Claude Code 세션을 시작하고 다음과 같이 물어보세요:

"내가 언급한 데이터베이스 설정이 뭐야?"

Claude가 Eve를 통해 이를 기억해 낼 것입니다. ✓

수동 MCP 구성 스니펫(설치 프로그램 불필요)은 examples/를 참조하세요.

설치

클라이언트를 설치하기 전에 Eve 워크스페이스를 확보하세요:

• 액세스 요청: https://evemem.com

• 워크스페이스가 프로비저닝된 후 Eve 대시보드에 로그인하세요:

  • https://evemem.com/app/overview

• API 키 인증을 사용할 계획이라면 클라이언트를 연결하기 전에 Eve 관리자/사용자 설정 흐름에서 테넌트 키를 생성하거나 교체하세요.

GitHub에서 바로 설치

권장:

uv tool install git+https://github.com/sherifkozman/eve-mcp.git

대안:

pipx install git+https://github.com/sherifkozman/eve-mcp.git

또는 독립형 bash 설치 프로그램 사용:

curl -fsSL https://raw.githubusercontent.com/sherifkozman/eve-mcp/main/install.sh | bash

그런 다음 확인:

eve version
eve --help

수동 구성 (설치 프로그램 없음)

Claude Code, Gemini CLI 및 Codex CLI용으로 바로 붙여넣을 수 있는 MCP 구성 스니펫은 examples/를 참조하세요.

향후 PyPI에서 설치

패키지가 게시되면 설치 명령은 다음과 같습니다:

uv tool install eve-client

또는:

pipx install eve-client

Eve 클라이언트의 기능

• 지원되는 로컬 AI 클라이언트 감지

• 파일 변경 전 설치 계획 표시

• Eve 관리 MCP 구성 작성

• 지원되는 경우 프롬프트/컴패니언 파일 설치

• 모든 세션에서 메모리 컨텍스트를 자동 주입하는 4개의 수명 주기 후크 설치 (SessionStart, UserPromptSubmit, PreCompact, Stop)

• 파일 기반 자격 증명 저장소를 사용하여 로컬에 인증 정보 저장

• 직접적인 메모리 액세스를 위한 eve memory search 및 eve memory status 명령 제공

• Eve 관리 변경 사항 확인, 복구, 롤백 및 제거

• 지원되는 클라이언트에서 로컬 대화 기록을 Eve로 가져오기

로컬 기록 가져오기

현재 지원되는 가져오기 소스:

• Claude Code

• Codex CLI

• Gemini CLI

핵심 명령:

eve import scan --source claude-code
eve import preview --source claude-code --path <session_file>
eve import jobs                              # list scan jobs
eve auth login --tool claude-code
eve import upload --job <scan_job_id> --use-auth-from claude-code
eve import runs                              # list upload runs
eve import resume --run <run_id>
eve import cleanup --days 30
eve import cleanup --days 30 --apply

작동 방식:

• 머신의 로컬 기록 파싱

• 관리형 Eve 서비스로 정규화된 배치 업로드

• 스캔 작업, 업로드 실행, 재생 및 재개를 위한 로컬 SQLite 원장 유지

• 기본적으로 오래된 완료된 로컬 가져오기 실행에 대한 드라이런 정리 지원

가져오기 유지 관리:

• eve import cleanup은 일반적인 로컬 원장 유지 관리 명령이며, 클라이언트별 가져오기 소스 기능이 아닙니다.

인증 참고:

• 가능하면 명령줄에 직접 비밀 정보를 전달하지 마세요.

• 먼저 eve auth login ...을 수행한 다음 API 키를 반복하지 않고 가져오기 명령을 실행하는 것을 선호합니다.

• 대화형 셸에서 eve auth login --tool claude-code를 실행하면 키를 안전하게 입력하라는 메시지가 표시됩니다.

현재 롤아웃 참고:

• 정확성과 재개 기능은 안정적입니다.

• 매우 큰 가져오기, 특히 Claude 관련 데이터가 많은 경우 배치 기본값이 계속 조정됨에 따라 이상적인 것보다 느릴 수 있습니다.

지원되는 클라이언트

Claude Code

현재 지원:

• MCP 구성

• CLAUDE.md 컴패니언 파일

• 패키지 관리 후크

• 가져오기 지원: scan, preview, upload, resume

현재 주요 인증 경로:

• Eve API 키

Gemini CLI

현재 지원:

• MCP 구성

• GEMINI.md 컴패니언 파일

• 패키지 관리 후크

• 가져오기 지원: scan, preview, upload, resume

현재 주요 인증 경로:

• Eve API 키

Codex CLI

현재 지원:

• MCP 구성

• Eve 소유 OAuth 로그인

• 런타임 베어러 토큰 주입

• 가져오기 지원: scan, preview, upload, resume

현재 주요 인증 경로:

• Eve OAuth

중요:

• 네이티브 Codex MCP 로그인은 지원되는 Eve 경로가 아닙니다.

Claude Desktop

호스팅된 Eve에 대해 로컬에서 자동 구성되지 않습니다.

인증 요구 사항

Eve 워크스페이스와 다음 중 하나가 필요합니다:

• Eve API 키, 또는

• 지원되는 흐름에 대한 Eve OAuth 액세스

현재 인증 기대치:

• Claude Code: API 키

• Gemini CLI: API 키

• Codex CLI: Eve OAuth

더 많은 클라이언트를 위한 OAuth 브라우저 흐름이 존재하지만, Codex 경로 외에서는 여전히 실험적이며 기본 프로덕션 설치 프로그램 흐름으로 간주해서는 안 됩니다.

기본 사용법

첫 실행

eve quickstart
eve connect --tool claude-code
eve verify --tool claude-code

API 키 흐름

eve auth login --tool claude-code --api-key <eve-key>
eve install --tool claude-code --apply --yes  # --apply writes config, --yes skips confirmation
eve verify --tool claude-code

Codex OAuth 흐름

eve auth login --tool codex-cli --auth-mode oauth
eve install --tool codex-cli --auth-mode oauth --apply --yes
eve verify --tool codex-cli --auth-mode oauth

메모리 명령

eve memory search "what database do we use" --context naya
eve memory search "auth patterns" --limit 5 --json
eve memory status
eve memory status --json

공통 명령

eve quickstart
eve connect
eve install --dry-run
eve install --apply --yes --tool claude-code
eve status
eve doctor
eve verify
eve repair --tool gemini-cli --apply --yes
eve uninstall --tool claude-code --yes
eve run --tool codex-cli -- exec "Use Eve memory to search for my latest preference."

수동 MCP 구성

설치 프로그램이 클라이언트 구성을 편집하지 않기를 원하는 경우, 호스팅된 Eve MCP 서버를 수동으로 추가하세요.

공유 호스팅 MCP 엔드포인트

https://mcp.evemem.com/mcp

Claude Code / Gemini CLI (API 키)

Eve 관리자 패널의 테넌트 API 키를 사용하세요.

{
  "eve-memory": {
    "type": "http",
    "url": "https://mcp.evemem.com/mcp",
    "headers": {
      "X-API-Key": "eve_<tenant>_...",
      "X-Source-Agent": "claude_code"
    }
  }
}

Gemini의 경우 동일한 형태를 유지하고 다음을 변경하세요:

X-Source-Agent = gemini_cli

Codex CLI (OAuth)

Codex는 네이티브 codex mcp login이 아닌 Eve 소유 베어러 토큰을 사용해야 합니다.

[mcp_servers.eve-memory]
url = "https://mcp.evemem.com/mcp"
bearer_token_env_var = "EVE_CODEX_BEARER_TOKEN"
startup_timeout_sec = 60

[mcp_servers.eve-memory.headers]
X-Source-Agent = "codex_cli"

OAuth 리소스:

https://mcp.evemem.com/mcp

Codex 프롬프트 시딩은 활성 프로젝트 AGENTS.md에 속합니다. Eve는 병렬 사이드카 파일을 만드는 대신 해당 파일 내의 자체 표시 블록을 관리합니다.

기타 MCP 클라이언트

다른 원격 MCP 클라이언트의 경우 최소 작동 설정은 다음과 같습니다:

1. MCP URL:

https://mcp.evemem.com/mcp

2. 하나의 소스 에이전트 헤더:

X-Source-Agent: your_client_name

3. 하나의 인증 스타일 선택:

• API 키:

X-API-Key: eve_<tenant>_...

• OAuth 베어러:

Authorization: Bearer <token>

4. OAuth 지원 클라이언트의 경우 이 리소스 식별자를 사용하세요:

https://mcp.evemem.com/mcp

5. 필수 범위:

memory.read
memory.write

클라이언트가 컴패니언 지침 파일을 지원하는 경우, 두 번째 병렬 파일을 만드는 대신 해당 도구의 활성 지침 파일을 가리키세요.

사용할 인증 경로

• Claude Code: API 키

• Gemini CLI: API 키

• Codex CLI: Eve OAuth

Eve가 구성, 프롬프트, 후크 및 확인을 관리하도록 하려면 파일을 수동으로 편집하는 대신 eve connect를 사용하세요.

안전 모델

• 자동 셸 프로필 변경 없음

• 문서화되지 않은 후크 없음

• 사용자가 작성한 지침 파일 덮어쓰기 없음

• 변경 전 백업 및 매니페스트 추적

• 명시적 롤백 및 제거 지원

• 제거 시 Eve 관리 자격 증명 및 도구 항목이 삭제되며, 사용자가 수정한 Eve 소유 파일에 수동 검토가 필요한 경우 경고 표시

개발

테스트 실행:

uv run pytest --cov=eve_client --cov-report=term-missing -q tests

Python 아티팩트 빌드:

uv build .

빌드 아티팩트 확인:

uvx twine check dist/*

독립형 릴리스 아티팩트 빌드:

bash scripts/build-eve-client-release.sh

라이선스

Apache-2.0. LICENSE를 참조하세요.