kioku-mesh #2 - kioku-mesh를 Claude Code 및 Codex CLI에 MCP로 연결하기

목표

uv tool install

으로부터 local 모드로 초기화

kioku-mesh mcp install

으로 Claude Code 및 Codex CLI에 MCP server로 등록

• Claude Code에서 저장한 기억을 Codex CLI 측에서 불러올 수 있는지 확인

별도의 머신은 필요하지 않으며, 1대의 기기에서 완결됩니다.

전제 조건

• Python 3.10+
• Linux (macOS는 미검증, Windows는 WSL2 권장)
• Claude Code 또는 Codex CLI 중 하나(가급적 둘 다)가 설치되어 있음

uv가 설치되어 있음 (미도입 시
curl -LsSf https://astral.sh/uv/install.sh | sh
)

설치 및 초기화

kioku-mesh는 kioku-mesh와 kioku-mesh-mcp라는 2개의 명령어를 제공하는 CLI 툴이므로, uv tool install을 통해 격리된 환경에 함께 설치하는 것이 다루기 쉽습니다.

uv tool install kioku-mesh
kioku-mesh init --mode local
kioku-mesh doctor

init --mode local은 ~/.config/kioku-mesh/config.yaml에 backend: local을 기록하여 SQLite만으로 동작하는 상태로 만듭니다. zenohd도 RocksDB도 필요하지 않습니다. doctor는 헬스 체크 (Health Check)를 수행합니다.

포함된 2개의 명령어는 다음과 같은 역할 분담을 가집니다.

kioku-mesh
: 인간용 CLI (유지보수 및 디버깅 시 가끔 사용)

kioku-mesh-mcp
: MCP 클라이언트로부터 기동되는 stdio MCP server. 실제 운용 시에는 이것만 사용합니다

Claude Code에 MCP로 등록하기

kioku-mesh mcp install이 클라이언트별 설정을 기록해 줍니다.

kioku-mesh mcp install --client claude-code

이 명령어는 내부적으로 다음 작업을 수행합니다.

• kioku-mesh-mcp의 절대 경로를 해결
• MESH_MEM_AGENT_FAMILY=claude / MESH_MEM_CLIENT_ID=claude-code를 기본값으로 설정 (관측의 작성자를 구분하기 위함)
• Claude Code의 MCP 설정에 엔트리(Entry)를 추가 (등록 명칭은 기본적으로 kioku_mesh)

내용만 확인하고 싶다면 --dry-run, 기존 등록을 덮어쓸 때는 --force, 추가 환경 변수를 넣고 싶을 때는 -e KEY=VALUE를 반복해서 지정할 수 있습니다.

# 실행하지 않고 내용만 확인
kioku-mesh mcp install --client claude-code --dry-run
# 기존 설정을 덮어쓰기
...

Codex CLI에도 추가하기

동일한 방식으로 Codex CLI에도 추가합니다.

kioku-mesh mcp install --client codex-cli

이 경우 MESH_MEM_AGENT_FAMILY=codex / MESH_MEM_CLIENT_ID=codex-cli가 기본값으로 설정됩니다. local 모드의 SQLite는 양쪽 모두 동일한 파일을 가리키므로, Claude Code가 저장한 관측 내용을 Codex CLI에서 읽을 수 있으며 그 반대도 가능합니다.

Claude Desktop / Gemini CLI / ChatGPT Desktop 등 기타 클라이언트는 docs/mcp-clients.md와 docs/multi-agent.md를 참조하십시오 (v0.3 시점에서 mcp install의 타겟은 Claude Code와 Codex CLI 두 가지입니다).

에이전트가 호출하는 MCP 툴

mcp install 이후, 에이전트로부터는 kioku-mesh가 제공하는 MCP tool이 일반적인 tool처럼 보이게 됩니다. 주로 사용하는 것은 다음 두 가지입니다.

• save_observation

• save_observation: 관측을 저장한다

• search_memory: 관측을 검색한다

저장 시의 카테고리(memory_type)는 다음 6가지 종류입니다. 에이전트에게 "decision으로 저장해줘"라고 지시할 때 사용하는 어휘가 되므로, 기억해 두면 편리합니다.

memory_type	용도
note	기본값. 잡다한 메모
decision	설계·방침 결정
bug	수정한 버그와 원인
pattern	코딩 규칙·명명법·구조 패턴
config	설정 변경과 그 이유
summary	세션 종료 시의 요약

importance (1~5), subject (짧은 주제), tags, source_files, references (PR/Issue 번호) 등도 MCP tool 인자로 전달할 수 있습니다. 에이전트가 문맥을 보고 적절한 값을 채워줄 것입니다.

동작 확인: 에이전트 간 저장 → 검색

local 모드의 SQLite를 Claude Code와 Codex CLI가 공유하고 있는 상태이므로, 한쪽에서 저장하고 다른 한쪽에서 검색하면 에이전트 간 교차 확인이 가능합니다.

• Claude Code 측에서 다음과 같이 요청합니다.
  "kioku-mesh에 '오늘은 kioku-mesh를 테스트 중이다'를 note로 저장해줘"

• Codex CLI 측에서 별도의 세션을 열고 다음과 같이 요청합니다.
  "kioku-mesh에서 'kioku-mesh'를 검색해줘"

• 저장한 엔트리가 검색 결과로 돌아오면 OK

결과가 잘 보이지 않을 때의 마지막 수단으로 CLI에서 직접 들여다볼 수도 있습니다.

kioku-mesh search "kioku-mesh"

여기까지로 "도구 간 교차 사용"은 달성

local 모드는 어디까지나 한 대의 기기에 국한된 SQLite입니다. 동일한 머신 상의 Claude Code / Codex CLI 간에는 memory가 공유되지만, 다른 머신으로는 전파되지 않습니다.

머신 간 공유를 원할 때는 hub / spoke 모드로 전환합니다. init --mode hub --force로 언제든지 전환할 수 있으므로, local 모드로 동작 감각을 익힌 뒤 다음 단계로 넘어가는 것이 안전합니다.

다음 예고

제3회에서는 메쉬 모드(mesh mode)의 이면에서 동작하는 Zenoh + RocksDB + SQLite index의 관계를 정리합니다. "Source of truth는 어디이며, 왜 SQLite가 읽기 캐시(read cache)인가", "zenohd는 무엇을 하고 있는가", "local에서 hub/spoke로 전환했을 때 기존에 저장된 데이터는 어떻게 되는가" 등을 다룹니다.

제4회에서 실제로 메쉬를 구성할 때 이해를 한 단계 더 깊게 만들어 줄 회차입니다.

참고 링크

• kioku-mesh (GitHub)
• docs/mcp-clients.md / docs/multi-agent.md (리포지토리 내)
• 연재 제1회: kioku-mesh란 무엇인가

Discussion