Kumiho 설정

Kumiho는 Revka의 공식 영구 메모리 저장소입니다. 런타임은 메모리를 직접 저장하지 않으며, 내부 에이전트를 제외한 모든 에이전트에 Kumiho MCP 사이드카를 주입합니다. 이 사이드카가 Model Context Protocol을 통해 그래프 기반 메모리 백엔드를 읽고 씁니다. 이 페이지에서는 사이드카 설치, [kumiho] 구성 블록, 호스팅 방식인 Kumiho Cloud와 직접 운영하는 Community Edition (CE) 백엔드 선택, 인증 토큰 제공, 그리고 revka doctor로 연결 상태를 검증하는 방법을 다룹니다.

메모리가 로컬 데이터베이스가 아닌 Kumiho에 저장되는 이유에 대한 개념적 설명은 먼저 메모리 개요를 읽어보세요. 사이드카 설치 및 연결이 완료된 후, 에이전트 측 사용 패턴은 Kumiho 그래프 메모리에서 확인할 수 있습니다.

참고

여기서 설치하는 Kumiho MCP 서버는 클라이언트 스텁이며 백엔드가 아닙니다. 그래프 백엔드는 Kumiho Cloud(호스팅) 또는 직접 운영하는 Community Edition 서버입니다. 사이드카는 [kumiho].api_url을 통해 HTTP로 백엔드를 검색합니다.

Kumiho MCP 사이드카 설치

Revka는 Kumiho 런처가 ~/.revka/kumiho/run_kumiho_mcp.py에 위치하고, ~/.revka/kumiho/venv/에 Python 가상환경이 구성되어 있다고 가정합니다. 런처는 해당 가상환경에서 python -m kumiho.mcp_server를 실행하는 얇은 shim입니다.

사전 요구사항

• PATH에 Python 3.11+ 설치.
• PyPI 네트워크 접근 가능 — 설치 스크립트가 pip install 'kumiho[mcp]>=0.9.20'를 실행합니다. [mcp] 확장은 mcp>=1.0.0 및 httpx>=0.27.0을 함께 설치합니다.
• 접근 가능한 Kumiho 백엔드 URL과, 클라우드의 경우 서비스 토큰(revka onboard가 수집하여 ~/.revka/.env에 저장). 이 값이 없어도 MCP 프로세스는 시작되지만 상태 비저장(stateless) 모드로 동작합니다.

자동 설치

With the revka binary

revka가 이미 PATH에 있는 경우:

revka install --sidecars-only

이 명령은 크로스플랫폼이며 멱등적으로 동작합니다 — 여러 번 실행해도 안전합니다. 기존 config.toml, .env, 또는 사용자가 작성한 런처를 덮어쓰지 않습니다. 유용한 플래그:

플래그	효과
--sidecars-only	Python MCP 사이드카만 설치합니다(바이너리 작업 없음).
--skip-kumiho	Kumiho 사이드카를 건너뜁니다(Operator만 설치).
--skip-operator	Operator 사이드카를 건너뜁니다(Kumiho만 설치).
--dry-run	실제 변경 없이 실행 계획을 출력합니다.
--with-session-manager	Node.js 라이브 실행 세션 매니저도 함께 설치합니다.
--python <path>	특정 Python 인터프리터를 지정합니다.

From a source checkout

revka 바이너리 없이 소스에서 실행:

# POSIX (macOS / Linux / WSL)
./scripts/install-sidecars.sh

# Windows
scripts\install-sidecars.bat

동일한 로직이 ./install.sh 및 setup.bat에서도 자동으로 실행됩니다. ./install.sh --skip-sidecars로 비활성화할 수 있습니다.

수동 설치

mkdir -p ~/.revka/kumiho
python3 -m venv ~/.revka/kumiho/venv
~/.revka/kumiho/venv/bin/pip install --upgrade pip
~/.revka/kumiho/venv/bin/pip install "kumiho[mcp]>=0.9.20"

cat > ~/.revka/kumiho/run_kumiho_mcp.py <<'PY'
#!/usr/bin/env python3
import os, pathlib, sys
HERE = pathlib.Path(__file__).resolve().parent
VENV_PY = HERE / "venv" / "bin" / "python3"
if not VENV_PY.exists():
    VENV_PY = HERE / "venv" / "Scripts" / "python.exe"
os.execv(str(VENV_PY), [str(VENV_PY), "-m", "kumiho.mcp_server", *sys.argv[1:]])
PY
chmod +x ~/.revka/kumiho/run_kumiho_mcp.py

팁

Kumiho 사이드카는 두 개의 레이어로 구성됩니다. 기본 kumiho[mcp] 패키지는 부트스트랩 메모리 도구를 제공하고, 동반 패키지인 kumiho_memory는 고수준 리플렉스(engage, reflect, recall, consolidate, dream_state)를 추가합니다. kumiho_memory가 없으면 런타임은 자동으로 경량 부트스트랩 프롬프트로 대체됩니다 — 감지 및 수정 방법은 아래 doctor 검사를 참조하세요.

Operator MCP 사이드카(멀티 에이전트 워크플로 오케스트레이션)는 동일한 스크립트로 Kumiho와 함께 설치됩니다. 자세한 내용은 Python MCP 사이드카 설치를 참조하세요.

[kumiho] 구성 블록

[kumiho]는 ~/.revka/config.toml에 위치하며, 사이드카 주입, 통신할 백엔드, 네임스페이스 범위를 제어합니다. 대표적인 구성 블록:

[kumiho]
enabled = true
mode = "cloud"                                  # or "local_ce"
mcp_path = "~/.revka/kumiho/run_kumiho_mcp.py"
api_url = "https://api.kumiho.cloud"            # cloud default
space_prefix = "Revka"
memory_project = "CognitiveMemory"
harness_project = "Revka"
memory_retrieval_limit = 3

키	타입	기본값	설명
enabled	bool	true	내부 에이전트를 제외한 에이전트에 Kumiho MCP 사이드카를 주입합니다. 테스트 또는 에어갭 배포 시 비활성화하면 에이전트가 영구 메모리 없이 실행됩니다.
mode	string	"cloud"	백엔드 선택자: "cloud"(호스팅, 토큰 기반) 또는 "local_ce"(자체 호스팅, 토큰 없음, 루프백 전용).
mcp_path	string	~/.revka/kumiho/run_kumiho_mcp.py	런처 shim 경로. ~ 확장을 지원합니다.
api_url	string	https://api.kumiho.cloud	Kumiho REST API의 기본 URL. local_ce의 경우 루프백 CE 서버(http://127.0.0.1:9190)를 지정합니다.
space_prefix	string	"Revka"	에이전트 메모리의 범위를 지정하는 접두사. 메모리는 <space_prefix>/<context> 형태로 저장됩니다.
memory_project	string	"CognitiveMemory"	사용자 메모리, 세션, 압축을 위한 Kumiho 프로젝트.
harness_project	string	"Revka"	스킬, 운영 데이터, ClawHub 설치를 위한 Kumiho 프로젝트.
memory_retrieval_limit	int	3	recall/engage 호출당 반환되는 최대 메모리 수.

mcp_path는 다음 순서로 확인됩니다: 구성 값이 비어있지 않으면 해당 값을, 그렇지 않으면 기본 설치 경로인 ~/.revka/kumiho/run_kumiho_mcp.py를 사용합니다.

참고

[kumiho].mode는 [memory].backend와 별개입니다. [memory].backend는 Kumiho 경로의 활성화 여부만 전환합니다("kumiho" 또는 "none" 수락). [kumiho].mode는 어떤 Kumiho와 통신할지를 선택합니다. 개요의 백엔드 선택을 참조하세요.

Cloud vs Community Edition

Kumiho Cloud (default)

호스팅, 관리형, 멀티 디바이스, 계정/토큰 기반. revka onboard를 실행할 때의 기본 경로이자 권장 방식입니다.

[kumiho]
enabled = true
mode = "cloud"
api_url = "https://api.kumiho.cloud"

클라우드 방식은 환경에 서비스 토큰이 필요합니다(인증 토큰 참조). 온보딩 중 메모리 단계에서 Kumiho Cloud 계정을 생성하거나 로그인하여 토큰을 발급받거나, 기존 토큰을 직접 붙여넣을 수 있습니다. 토큰은 ~/.revka/.env에 KUMIHO_SERVICE_TOKEN으로 저장됩니다.

Community Edition (local_ce)

자체 호스팅 Community Edition 서버: 토큰 없음, 루프백 전용(127.0.0.1), 단일 사용자, 무료. CE는 컨트롤 플레인이 없으며 인증은 토큰이 아닌 네트워크 위치 기반입니다.

[kumiho]
enabled = true
mode = "local_ce"
api_url = "http://127.0.0.1:9190"   # CE default port

mode = "local_ce" 설정 시, Revka는 api_url에서 파생된 KUMIHO_LOCAL_SERVER_ENDPOINT(기본값 127.0.0.1:9190)를 통해 메모리 MCP를 루프백 서버로 지정하며 KUMIHO_AUTH_TOKEN / KUMIHO_SERVICE_TOKEN을 전달하지 않습니다. CE 자동 감지는 kumiho[mcp] >= 0.10.0이 필요합니다.

CE 실행에 필요한 구성 요소

구성 요소	주소	비고
CE 서버	127.0.0.1:9190	Kumiho CE REST/gRPC 엔드포인트.
Neo4j 5.x	127.0.0.1:7687 (Bolt), 7474 (HTTP)	필수 — 그래프 저장소.
Redis	127.0.0.1:6379	선택 사항이지만 권장; 이벤트 스트림 및 고수준 메모리 쓰기 경로를 활성화합니다.

고수준 메모리 레이어(kumiho_memory)는 세션을 Redis에 버퍼링합니다. CE는 Upstash URL을 검색할 컨트롤 플레인이 없으므로, Revka는 CE 온보딩이 프로비저닝한 루프백 Redis를 가리킵니다. Redis에 연결할 수 없으면 reflect 쓰기가 “No credentials available for memory proxy.” 오류와 함께 실패합니다. KUMIHO_UPSTASH_REDIS_URL(또는 UPSTASH_REDIS_URL)을 내보내어 URL을 재정의할 수 있으며, 기본값은 redis://127.0.0.1:6379입니다.

설정 방법

CE 설정은 마법사 방식으로 진행됩니다. revka onboard → 메모리 단계 → Local Community Edition을 선택하면, Docker/Podman이 있을 경우 kumiho-neo4j(및 선택적으로 kumiho-redis) 컨테이너를 시작하고 공식 Kumiho CE 설치 프로그램으로 안내합니다.

주의

Kumiho CE는 Kumiho CE EULA의 적용을 받습니다. 설치 프로그램이 EULA를 검토하고 accept를 입력하도록 요청한 후 서버가 실행됩니다. 마법사는 사용자가 제공한 비밀번호로 Neo4j를 프로비저닝하며, 기존 kumiho-neo4j 컨테이너를 재사용할 경우 원래 비밀번호가 유지됩니다.

컨테이너 런타임이 없으면 Kumiho 설정 마법사를 완료하기 전에 직접 Neo4j를 시작하세요:

docker run -d \
  -p 127.0.0.1:7687:7687 -p 127.0.0.1:7474:7474 \
  -e NEO4J_AUTH=neo4j/<password> \
  neo4j:5

CE는 반드시 루프백 전용으로 유지해야 합니다. api_url을 루프백 이외의 호스트로 지정하는 것은 CE 범위를 벗어나며 암호화되지 않은 통신이 발생합니다.

인증 토큰

클라우드 Kumiho는 대시보드에서 발급한 서비스 토큰으로 인증합니다. Revka는 revka onboard가 작업 공간의 ~/.revka/.env에 저장하는 두 환경 변수에서 토큰을 읽습니다.

변수	사용처	비고
KUMIHO_SERVICE_TOKEN	Revka 게이트웨이 / CLI 코드 (FastAPI 호출)	온보딩이 저장하는 값. 우선 적용됩니다.
KUMIHO_AUTH_TOKEN	사이드카 내부의 Kumiho Python SDK	KUMIHO_SERVICE_TOKEN이 설정되지 않은 경우 폴백.

우선순위: KUMIHO_SERVICE_TOKEN이 KUMIHO_AUTH_TOKEN보다 우선합니다. 생성된 MCP에 전달할 때 Revka는 서비스 토큰(온보딩된 값)을 사용하여 다른 계정의 쉘 수준 KUMIHO_AUTH_TOKEN에 의해 재정의되지 않도록 합니다. 최종 확인된 토큰은 사이드카에 KUMIHO_AUTH_TOKEN(SDK가 읽는 값)으로 전달됩니다.

두 변수 모두 설정되지 않은 경우, Revka는 ~/.kumiho/kumiho_authentication.json(kumiho login이 작성하는 파일)에서 Kumiho CLI의 인증 파일을 읽고, 토큰이 만료되지 않은 경우 control_plane_token을 읽어 KUMIHO_SERVICE_TOKEN에 설정합니다.

주의

Kumiho Cloud → Service Tokens에서 생성한 Kumiho 서비스 토큰을 정확히 하나만 붙여넣으세요. Firebase/Auth JWT를 KUMIHO_SERVICE_TOKEN으로 사용하면 Kumiho 401 오류가 발생합니다. CE 모드는 토큰이 필요 없으며 local_ce 사용 시 이 변수들을 설정하지 마세요.

Revka는 임의의 쉘 .env 파일을 자동으로 로드하지 않지만, 시작 시 작업 공간의 ~/.revka/.env를 로드하여 KUMIHO_SERVICE_TOKEN을 사용 가능하게 합니다. KUMIHO_CONTROL_PLANE_URL을 설정하여 사이드카에 전달되는 컨트롤 플레인 URL을 재정의할 수도 있습니다.

revka doctor로 검증

revka doctor는 구조화된 진단을 실행합니다. Kumiho와 관련된 두 가지 카테고리가 있습니다:

revka doctor

sidecars 카테고리 — Kumiho 가상환경 및 패키지 확인:

• kumiho.mcp_path에서 가상환경을 확인합니다(<dir>/venv/bin/python 또는 Windows의 경우 venv\Scripts\python.exe).

• 가상환경 Python이 없으면 경고 — scripts/install-sidecars.sh(또는 .bat 동등물)를 실행하여 수정합니다.

• kumiho를 임포트할 수 없으면 오류 발생(손상된 가상환경).

• kumiho_memory가 없으면 경고 — 런타임이 경량 부트스트랩 프롬프트로 동작 중이며 고급 리플렉스를 사용할 수 없습니다. 출력되는 수정 명령:

  ~/.revka/kumiho/venv/bin/python -m pip install 'kumiho_memory>=0.5.0'

kumiho.enabled = false이면 사이드카 확인을 건너뜁니다.

kumiho 카테고리 — 백엔드 확인:

• Cloud: backend: cloud (<api_url>)을 보고합니다(정적 참고 사항 — 라이브 프로브는 서비스 토큰이 필요합니다).
• Community Edition: GET /api/_live(deployment_mode=self_hosted_ce 확인) 및 GET /api/_health로 루프백 서버를 프로브하며, Neo4j, Redis 이벤트 스트림, 임베딩의 구성 요소별 준비 상태를 보고합니다. 서버에 연결할 수 없으면 경고를 표시하고 kumiho_server onboard 완료(EULA 수락, 서버 시작, Neo4j 실행 확인)를 안내한 후 revka doctor를 다시 실행하도록 안내합니다.

심각도는 세 수준으로 표시됩니다: ok, warn, error. 사이드카를 직접 스모크 테스트할 수도 있습니다:

# Package import smoke test
~/.revka/kumiho/venv/bin/python3 -c 'import kumiho; print(kumiho.__version__)'

# Confirm the MCP tools loaded: open the gateway tools panel and look for kumiho_memory_*
revka gateway
# then visit http://127.0.0.1:42617/tools

전체 진단 항목은 revka doctor, status & self-test를 참조하세요.

문제 해결

증상	해결 방법
로그: Kumiho MCP script not found: ~/.revka/kumiho/run_kumiho_mcp.py	revka install --sidecars-only(또는 scripts/install-sidecars.sh)를 실행하세요.
ModuleNotFoundError: kumiho.mcp_server 또는 ModuleNotFoundError: mcp	[mcp] 확장으로 재설치: ~/.revka/kumiho/venv/bin/pip install -U 'kumiho[mcp]'.
도구 패널에 kumiho_memory_* 도구가 없음	토큰이 없거나 백엔드에 연결할 수 없습니다. ~/.revka/.env에 KUMIHO_SERVICE_TOKEN이 있는지 확인하고, ~/.revka/logs/에서 사이드카 stderr를 확인하세요.
Cloud 401 오류	토큰이 Kumiho 서비스 토큰이 아닙니다(예: Firebase JWT). Kumiho Cloud → Service Tokens에서 새 토큰을 생성하세요.
CE: reflect가 저장 성공을 보고하지만 실제로 저장되지 않음	Redis에 연결할 수 없습니다 — kumiho-redis를 시작하거나 KUMIHO_UPSTASH_REDIS_URL을 설정하세요.
CE: doctor가 127.0.0.1:9190에서 연결 불가를 보고	kumiho_server onboard를 완료하고, 서버를 시작하고, Neo4j(7687)가 실행 중인지 확인하세요.
백엔드가 자동으로 비활성화됨(영구 저장 없음)	api_url에 연결할 수 없습니다 — [kumiho].api_url이 실행 중인 엔드포인트를 가리키는지 확인하세요.

관련 페이지

메모리 개요 Kumiho가 공식 저장소인 이유, NoneMemory 바인딩, 백엔드 선택 방법.

Kumiho 그래프 메모리 에이전트를 Kumiho에 연결하는 engage/reflect 두 단계 리플렉스 패턴.

Python MCP 사이드카 설치 Kumiho와 Operator MCP 사이드카를 함께 설치합니다.

구성: 게이트웨이, 메모리, 보안 및 플랫폼 전체 [kumiho] 및 [memory] 구성 스키마 참조.

revka doctor, status & self-test 사이드카 및 Kumiho 검사를 포함한 전체 진단 항목.

revka memory & estop CLI에서 Kumiho 기반 메모리를 검사하고 관리합니다.