Honcho × OpenAI Codex — lifecycle hooks 기반 영속 메모리 통합

codex-honcho는 Codex의 세션 시작·프롬프트·도구 사용·턴 종료 hook을 Honcho의 hosted MCP와 로컬 append-only 큐에 연결해, 프로젝트·브랜치·대화 단위의 장기 메모리를 제공하는 TypeScript 플러그인이다.[1][3] 패키지는 Honcho SDK와 MCP SDK를 의존성으로 사용한다.[4]

한눈에 보기

대상: OpenAI Codex CLI에 Honcho 메모리를 붙이는 @honcho-ai/codex-honcho 플러그인이다. 문서가 요구하는 최소 Codex 버전은 0.136.0, 설치기와 hook 실행에는 PATH의 Node가 필요하다.[1][3]
패키지 경계: 조사한 저장소 snapshot은 c8d35e6943ac120b8b11487701c0835715cf3700(chore: codex plugin (#13))이며, package.json의 버전은 0.1.1, 라이선스는 MIT다.[2][4]
설치 표면: ~/.honcho/config.json의 키를 읽어 ~/.codex/hooks.json, ~/.codex/config.toml, ~/.codex/skills/honcho-memory/에 필요한 hook·MCP·skill을 등록한다.[1][6][7]
핵심 설계: 세션 시작에는 가벼운 context snapshot을 주입하고, 대화 중에는 로컬 JSONL 큐에 관찰·전사 delta를 쌓은 뒤 Stop/PreCompact에서 Honcho로 flush한다.[3][8][12]
검증 경계: 이 환경에서는 소스 manifest, TypeScript typecheck/build, 78개 Bun 테스트, dummy-key 기반 install/status/remove smoke를 실행했지만 실제 Honcho API 인증·실제 Codex 세션·외부 메모리 품질은 실행하지 않았다.[unverified]

무엇을 해결하는가

Honcho 공식 문서는 Codex가 context reset·세션 재시작·새 대화 뒤에도 작업 중인 내용, 선호, 결정을 이어가도록 하는 integration으로 설명한다.[1] codex-honcho README도 이를 Codex lifecycle에 hook을 걸어 세션을 Honcho에 저장하고 다음 세션 시작에 관련 context를 되돌려주는 구조로 설명한다.[3]

이것은 Codex 자체의 로컬 대화 로그를 단순히 다시 붙이는 기능이라기보다, Codex hook → Honcho session/peer → MCP recall이라는 외부 메모리 경로를 추가하는 방식이다.[6][7] 프로젝트는 TypeScript CLI이며 Honcho SDK와 MCP SDK를 의존성으로 사용한다.[4] npm bundle은 plain Node로 실행되는 dist/codex-honcho.mjs를 제공한다.[17]

설치 흐름

Honcho API key를 ~/.honcho/config.json에 저장한다. 공식 문서는 honcho init 또는 직접 JSON 작성 경로를 제시하지만, 이 위키에는 키 값을 보존하지 않았다.[1][13]
npm install -g @honcho-ai/codex-honcho 뒤 codex-honcho install을 실행한다. 설치 명령은 hook·MCP·skill을 ~/.codex 아래에 등록한다.[1][3]
Codex를 재시작하거나 새 세션을 시작해야 [features].hooks와 hooks.json을 다시 읽는다.[1][3]
선택적으로 ~/.codex/AGENTS.md에 Honcho MCP의 search, chat, create_conclusions를 적극 활용하라는 지침을 추가할 수 있다.[1][3]

키가 없으면 구현은 hook과 memory skill은 설치하지만 MCP 등록을 건너뛰고, honcho init 후 다시 install하라는 안내를 출력한다.[17] 키를 rotate한 경우에도 install을 다시 실행해 Codex의 MCP header를 갱신하는 흐름이다.[1][7]

Lifecycle hook 구조

플러그인은 네 가지 handler verb를 다섯 Codex event에 매핑한다. SessionStart, UserPromptSubmit, PostToolUse, Stop, PreCompact를 등록하며, 기존 사용자의 다른 hook은 보존하고 자기 명령만 재설치 시 교체한다.[6]

Codex event	handler	동작
`SessionStart` (`startup\|resume\|clear\|compact`)	`recall`	Honcho session/peer를 materialize하고 representation·peer card 일부를 `<honcho-memory>` context로 주입한다. 10분 cache와 Honcho GUI deep link도 사용한다.[6][14]
`UserPromptSubmit`	`prompt`	`injectPerPrompt=true`일 때만 cached context를 추가한다. 기본값은 꺼져 있고, trivial prompt와 동일한 반복 주입은 건너뛴다.[5][15]
`PostToolUse`	`observe`	의미 있는 shell·patch·도구 사용을 한 줄 요약해 로컬 큐에 넣는다. `ls`, `pwd`, `git status` 같은 읽기 위주 명령과 Honcho 자신의 MCP 호출은 필터링한다.[8][11]
`Stop`	`writeback`	Codex rollout JSONL에서 아직 보존하지 않은 user/assistant turn만 cursor 이후 delta로 추출하고, 큐를 Honcho로 flush한다.[9][10][12]
`PreCompact` (`manual\|auto`)	`writeback`	compaction 전에 같은 writeback 경로를 실행해 버려질 대화 tail을 먼저 capture한다.[6][10][12]

Codex rollout parser는 response_item의 user/assistant message만 읽고 reasoning·function call·Codex가 주입한 environment_context, user_instructions 등의 system-like turn은 저장 대상에서 제외한다.[9] 이 필터는 사용자의 말과 Codex 실행 환경을 한 Honcho memory stream에 그대로 섞지 않기 위한 경계다.[9]

Local-first capture와 flush

공식 README는 capture를 먼저 로컬에 append하고 업로드를 뒤로 미뤄 대화 중 네트워크가 turn을 막지 않는다고 설명한다.[3] 실제 구현의 큐는 ~/.honcho/codex/queue/<key>.jsonl에 human-readable JSONL을 append하고 .sent high-water mark로 이미 전송된 entry 수를 기록한다.[8]

observe는 네트워크 없이 큐에 한 줄을 넣고, writeback은 rollout delta를 큐에 추가한 뒤 flush를 inline으로 호출한다.[11][12] 따라서 “background upload”라는 제품 설명은 capture가 비차단·local-first라는 뜻으로 읽어야 하며, 현재 Stop/PreCompact의 실제 upload는 hook 프로세스 안에서 수행된다.[12]

flush 구현에는 다음 안전장치가 있다.[10]

한 메시지는 약 24,000자 이하로 분할하고, 한 SDK 호출은 최대 100개 메시지로 제한한다.[10]
세션별 lock으로 동시 flush의 중복 전송을 막고, 죽은 process의 lock은 회수한다.[10]
부분 upload가 실패하면 성공한 high-water mark까지만 전진하고 나머지는 다음 turn에 재시도한다.[10]
user·assistant는 각각 Honcho peer로 보내고, tool observation은 [tool] prefix와 metadata를 붙인다.[10]

세션·workspace 설정

설정은 다른 Honcho integration과 공유하는 ~/.honcho/config.json에 두고, Codex 전용 값은 hosts.codex 아래에 둔다. host block이 없으면 root field로 fallback하며, HONCHO_API_KEY, HONCHO_PEER_NAME, HONCHO_CONFIG_DIR 환경변수도 지원한다.[1][5]

{
  "apiKey": "[REDACTED]",
  "peerName": "alice",
  "hosts": {
    "codex": {
      "workspace": "codex",
      "sessionStrategy": "per-directory",
      "injectPerPrompt": false,
      "saveMessages": true
    }
  }
}

세션 이름 전략은 세 가지다.[1][5]

전략	예시	용도
`per-directory` (기본)	`my-app`	프로젝트 디렉터리별로 메모리를 누적
`git-branch`	`my-app-main`	feature branch별 context 분리
`chat-instance`	`my-app-019ea7df`	대화마다 새 memory session

sessions[cwd] 명시 매핑은 전략보다 우선하며, peerName은 같은 workspace를 쓰는 팀원들을 구분한다.[1][5] saveMessages=false는 memory read는 허용하되 새 메시지 write를 끈다. injectPerPrompt=false는 매 turn context를 자동으로 되풀이하지 않고 MCP active recall을 쓰게 한다.[1][5][15]

MCP 연결면

설치기는 Codex의 ~/.codex/config.toml에 [mcp_servers.honcho] native HTTP block을 추가하고 https://mcp.honcho.dev를 등록한다.[1][7] 인증은 environment variable을 요구하는 대신 ~/.honcho/config.json의 resolved key를 Authorization bearer header로 복사하고, X-Honcho-User-Name 및 선택적 workspace/assistant header를 함께 쓴다.[7]

Codex가 호출할 수 있는 도구는 session message semantic search, 사용자에 대해 질문하는 chat, peer context/representation 조회, durable conclusion 생성·목록·검색·삭제다.[1] 즉 hook은 자동 capture/recall의 기본 경로이고, MCP는 “지금 필요한 과거 맥락을 더 찾아보기”와 “새 결론을 명시적으로 저장하기”를 위한 능동 경로다.[1][7]

설치·제거가 실제로 바꾸는 파일

경로	구현상 변경
`~/.codex/honcho/`	npm/npx cache eviction에 영향을 받지 않도록 bundle과 skill asset을 stable copy로 stage한다.[1][17]
`~/.codex/hooks.json`	네 개 handler가 다섯 event에 연결된다. 기존 foreign hook은 유지된다.[1][6]
`~/.codex/config.toml`	`[features].hooks = true`를 보장하고, fenced `[mcp_servers.honcho]` block을 추가한다.[6][7]
`~/.codex/skills/honcho-memory/`	모델이 언제 Honcho를 recall/save할지 안내하는 `SKILL.md`를 복사한다.[1][16]
`~/.honcho/config.json`	resolved `apiKey`와 `peerName`을 merge하며 다른 root field와 `hosts.*` block은 보존한다.[1][5][17]

codex-honcho remove는 자기 hook·MCP block·skill을 제거하고 사용자의 foreign hook/config 내용을 보존하도록 구현돼 있다.[6][7][16] CLI entrypoint는 staged bundle도 제거한다.[17] 문서는 설치 변경을 정확히 되돌린다고 설명한다.[1] 다만 이번 source inspection 및 dummy-key smoke에서 remove 뒤 ~/.codex/config.toml의 [features].hooks = true는 남았다.[unverified] 따라서 제거 시 plugin-owned registration은 걷어내지만 feature flag까지 원상 복구된다고 가정하면 안 된다.[unverified]

보안·운영 경계

보안 정책은 Codex session content가 Honcho API로 전송되어 memory storage에 쓰인다고 명시하고, ~/.honcho/config.json의 키와 ~/.codex/config.toml의 Authorization header를 비공개로 유지하라고 안내한다.[13] 따라서 회사 코드, 비공개 문서, 개인 선호를 저장하기 전에 Honcho의 privacy/security posture와 workspace 권한을 별도로 검토해야 한다.[13]

이 integration은 로컬-first이지만 local-only는 아니다. 큐가 flush되면 대화 내용이 hosted Honcho service로 전송되고, search·chat·peer context 호출도 외부 MCP endpoint를 사용한다.[7][10][13] 현재 조사에서는 실제 key를 사용하지 않았고 Honcho API·MCP의 authenticated response나 실제 memory representation 품질을 검증하지 않았다.[unverified]

이 환경에서 실행한 검증

고정 plugin checkout의 선택 파일 19개를 commit-pinned raw URL로 다시 내려받아 HTTP 200·바이트 수·SHA-256을 대조했으며 모두 일치했다.[unverified]
npm ci --ignore-scripts, npm run typecheck, npm run build가 성공했고, Node용 dist/codex-honcho.mjs가 생성됐다. npm audit은 5 vulnerabilities (1 low, 1 moderate, 3 high)를 보고했다.[unverified]
npx --yes bun test는 11개 test file, 78 pass, 0 fail이었다. cursor·queue·config·rollout parser·hook·connector 경로를 포함한다.[unverified]
임시 CODEX_HOME/HONCHO_CONFIG_DIR에서 dummy key로 install → status → remove를 실행했다. hook event, MCP URL/header 생성, skill/bundle stage, pending queue 표시, foreign 설정 보존 경로를 확인했지만 실제 Honcho 네트워크 호출은 하지 않았다.[unverified]
실제 Codex 0.136.0+ 세션에서 hook payload가 주입되고, 외부 API가 memory를 생성·검색하는 end-to-end 품질은 검증하지 않았다.[unverified]

판단

codex-honcho의 흥미로운 점은 메모리를 모델 prompt에 매 turn 무조건 붙이는 대신 세션 시작의 작은 snapshot + 필요할 때 MCP active recall + 턴 종료의 durable writeback으로 나눈다는 데 있다.[1][3][14] 매 turn context 주입은 별도 옵션으로 남겨 둔다.[15] 프로젝트·branch·chat-instance를 Honcho session으로 명시적으로 모델링하고, 로컬 큐·cursor·lock·재시도를 둔 것은 장기 실행 코딩 도구에서 memory capture가 본 작업을 방해하지 않게 하려는 설계다.[5][8][10]

반면 서비스 경계가 분명하다. API key와 session content를 외부 서비스에 보내며, 현재 snapshot의 remove는 feature flag를 남기는 작은 운영 불일치가 있다.[6][7][13] 따라서 개인 프로젝트에서 Codex의 반복 설명을 줄이는 용도에는 매력적이지만, 민감한 저장소에는 saveMessages=false, 별도 workspace/peer, 보존·삭제 정책, 네트워크·서비스 장애 시 fallback을 먼저 결정해야 한다.[1][5][13]

Sources

description	codex-honcho가 OpenAI Codex의 lifecycle hook·MCP·로컬 큐·세션 전략으로 Honcho 메모리를 연결하는 구조와 검증 경계.
tags	ai-agents, ai-coding, typescript, codex, openai, open-source, cli, privacy
aliases	codex-honcho, Honcho Codex, Honcho Codex integration

LLM Wiki

탐색기