codex-lcm

OpenAI Codex CLI를 위한 로컬, 무손실 컨텍스트 관리.

codex-lcm은 Codex 대화 이벤트를 SQLite에 캡처하고, 이전 컨텍스트를 소스 메시지를 삭제하지 않고 요약 계층 구조로 압축하며, 세션 시작 시 관련 컨텍스트를 복원하고, 로컬 MCP 서버를 통해 어휘 검색(lexical recall)을 제공합니다.

"무손실"의 의미: 소스 콘텐츠는 구성된 비밀값 편집(redaction) 이후에도 유지됩니다. 검색 가능한 도구 미리보기는 제한되지만, 완전한 편집된 도구 입력 및 출력은 페이지 단위 확장을 통해 계속 사용할 수 있습니다.

상태 및 플랫폼

codex-lcm은 macOS용 베타 소프트웨어입니다. Codex 훅과 POSIX flock에 의존하며, Windows와 Linux는 현재 지원되지 않거나 주장되지 않습니다.

Related MCP server: ClaudeX

기능

• 실시간 캡처: 사용자 프롬프트, 어시스턴트 응답, 도구 활동이 Codex 훅을 통해 캡처됩니다.

• 영구 로컬 저장소: WAL 모드의 SQLite가 원시 메시지, 구조화된 메시지 부분, 요약, FTS5 인덱스를 저장합니다.

• 계층적 압축: 오래된 메시지는 리프 요약(leaf summary)이 되고, 적격한 요약 실행은 더 깊은 DAG 노드로 응축될 수 있습니다. 소스 행은 자동으로 삭제되지 않습니다.

• 컨텍스트 복원: 활성 요약과 가장 최근의 미요약 메시지가 엄격한 크기 제한 내에서 세션 시작 시 주입됩니다.

• 로컬 검색: 6개의 stdio MCP 도구가 어휘 검색, 최근 세션 조회, 메타데이터 검사, 페이지 단위 소스 확장을 제공합니다.

• 실패 시 개방형 훅(fail-open hooks): 캡처 또는 압축 실패가 Codex 턴을 차단하지 않습니다.

• 안전 제어: 비밀값 편집, 세션별 압축 잠금, 원자적 메시지/FTS 쓰기, 공급자 호출 예약, 진행 상황 검사, 기본 비공개 파일 권한.

저장소 체크아웃에서 설치

python3 -m venv ~/.codex-lcm/venv
~/.codex-lcm/venv/bin/python -m pip install .
~/.codex-lcm/venv/bin/codex-lcm install
~/.codex-lcm/venv/bin/codex-lcm doctor

설치 후 Codex를 다시 시작하세요. Codex에서 /hooks를 사용하여 설치된 훅을 검사하고 신뢰하세요.

설치 프로그램은 codex-lcm 항목을 ~/.codex/hooks.json 및 ~/.codex/config.toml에 병합합니다. 기존 파일을 변경하기 전에 타임스탬프가 있는 백업을 생성합니다. 설치 프로그램을 다시 실행하는 것은 멱등적입니다.

소스 체크아웃에는 동일한 격리 설치 및 검증을 수행하는 scripts/install.sh도 포함되어 있습니다.

선택적 LLM 요약

Python 3.11 이상에서 핵심 패키지에는 타사 런타임 종속성이 없습니다. Python 3.10은 안전한 TOML 구성 처리를 위해 tomli 호환성 백포트를 설치합니다. LLM 클라이언트가 없으면 압축은 결정적 head/tail 잘라내기를 사용합니다.

OpenAI 호환 요약을 활성화하려면 선택적 추가 기능을 설치하고 자격 증명을 구성하세요:

~/.codex-lcm/venv/bin/python -m pip install ".[llm]"
export CODEX_LCM_API_KEY="..."

OPENAI_API_KEY도 인식됩니다. OpenAI 호환 엔드포인트에는 CODEX_LCM_BASE_URL 또는 OPENAI_BASE_URL을 사용하세요. CODEX_LCM_* 공급자 설정은 쌍으로 처리되며 쌍으로 우선 적용되므로 전역 키가 범위가 지정된 엔드포인트로 전송되지 않습니다. CODEX_LCM_BASE_URL이 설정된 경우 CODEX_LCM_API_KEY도 구성하세요.

CLI

codex-lcm install                       Wire hooks and the MCP server into Codex
codex-lcm uninstall                     Remove codex-lcm wiring and keep stored data
codex-lcm status                        Show database statistics
codex-lcm doctor                        Verify package, database, hooks, and MCP wiring
codex-lcm compact --session <id>        Compact one session synchronously
codex-lcm compact --all                 Compact every recorded session synchronously

제거해도 ~/.codex-lcm/ 또는 해당 데이터베이스는 삭제되지 않습니다.

MCP 도구

검색은 의미론적이 아닌 어휘적입니다. 이 릴리스에는 임베딩이나 벡터 유사성 주장이 없습니다.

구성

구성은 환경 변수에서 읽습니다.

기본 데이터 디렉터리는 모드 0700입니다. 데이터베이스, WAL 사이드카, 잠금 파일, 압축 로그는 POSIX 시스템에서 모드 0600입니다.

데이터 및 보안 경계

• 알려진 API 키, 토큰, 인증 헤더, 비밀번호/비밀 할당, JWT, PEM 개인 키에 대해 지속 전에 편집이 발생합니다.

• 자격 증명이 포함된 Git 원격 URL은 사용자 정보, 쿼리 매개변수, 프래그먼트 없이 저장됩니다.

• 편집은 모든 가능한 비밀 형식이 인식된다는 보장이 아니라 심층 방어입니다.

• 완전한 편집된 도구 페이로드에는 여전히 개인 대화 또는 프로젝트 데이터가 포함될 수 있습니다. 로컬 계정과 데이터베이스 백업을 그에 따라 보호하세요.

• 선택적 클라이언트가 설치되고 공급자 자격 증명 또는 기본 URL이 구성되지 않는 한 LLM 공급자에게 데이터가 전송되지 않습니다.

• 자동 보존 및 삭제는 의도적으로 없습니다. 애플리케이션은 소스 기록을 조용히 폐기하지 않습니다.

개발

프로젝트 로컬 환경을 사용하세요. 테스트는 라이브 Codex 프로필이나 데이터베이스가 필요하지 않습니다.

python3 -m venv .venv
.venv/bin/python -m pip install -e ".[dev]"
.venv/bin/python -m pytest -q
.venv/bin/python tests/smoke_test.py
.venv/bin/python tests/reliability_test.py
.venv/bin/python tests/package_test.py
.venv/bin/ruff check .
.venv/bin/bandit -q -r codex_lcm

패키지 테스트는 임시 홈 디렉터리와 가상 환경에 빌드 및 설치됩니다. 스모크 및 안정성 스크립트도 임시 데이터베이스를 사용합니다.

저장 모델, 불변 조건, 훅 흐름, 실패 동작은 DESIGN.md를 참조하세요.

라이선스

MIT