한눈에 보기
- 한 줄 정의: Claude Code, Cursor 등 AI 코딩 에이전트가 방대한 도구 출력(Log, Snapshot) 때문에 컨텍스트 윈도우를 낭비하지 않도록 제어하는 로컬 미들웨어(Middleware) 도구
- 핵심 아키텍처: MCP 도구 호출 가로채기(Intercept) → 서브프로세스 샌드박스 실행 → 대용량 출력 로컬 DB(SQLite) 저장 → 요약/검색 결과만 LLMd에 반환
- 서비스 가치: LLM 컨텍스트 사용량을 최대 96~98% 절감(공식 벤치마크 기준)해서 토큰 비용과 컨텍스트 망각(Context Forgetting) 현상을 방지
- 현재 상태: 2026년 5월 3일 기준 main 브랜치, 기준 커밋 78b2428, 최신 릴리스 v1.0.104
- 도입 전 체크리스트 (운영 리스크): 플랫폼 별 훅(Hook) 지원 편차 존재 (14개 플랫폼을 지원하지만 동작 상이함), better-sqlite3 네이티브 빌드 의존성, ELv2 라이선스 제약
서론: LLM 컨텍스트 윈도우 한계 극복을 위한 로컬 프록시
AI 코딩 도구를 활용한 세션이 길어지면 에이전트가 최근 수정한 파일이나 작업 지시를 잊어버리는 현상이 발생한다. 이건 모델의 성능이 떨어져서가 아니라, 도구 실행 결과물(브라우저 스냅샷, 대형 로그, 검색 결과 등)이 컨텍스트 윈도우를 꽉 채워버렸기 때문이다.
mksglu/context-mode는 이 "컨텍스트 고갈 문제"를 해결하기 위해 만들어진 MCP(Model Context Protocol) 기반의 로컬 인프라 계층이다. 원문 출력(Raw Output)은 로컬 환경에 따로 보관하고, LLM에는 요약과 검색 단서(Index)만 넘겨서 토큰 소비를 극단적으로 줄이는 '검색 가능한 생략(Searchable Omission)' 전략을 쓴다. 이 글에서는 저장소의 핵심 TypeScript 코드를 바탕으로 아키텍처와 엔지니어링 리스크를 분석해 본다.
1. 핵심 기술 용어 및 스택 정리
| 용어 (Term) | 기술적 정의 (Description) |
| MCP (Model Context Protocol) | LLM 클라이언트가 외부 시스템의 데이터와 도구에 안전하게 접근하기 위한 표준 인터페이스 사양. |
| SQLite FTS5 & BM25 | 대용량 텍스트의 Full-Text Search를 지원하는 SQLite 확장 모듈과, 문서의 관련성을 평가하는 검색 알고리즘. |
| 서브프로세스 샌드박스 | 코드를 격리 실행하기 위한 래퍼(Wrapper). 단, Docker 같은 컨테이너 격리가 아니라 환경변수 통제 수준의 논리적 격리라는 점을 주의해야 한다. |
| PreCompact 훅 | 에이전트가 컨텍스트 한계에 도달해 과거 대화를 압축(Summarization)하기 직전에 실행되어 세션 상태를 스냅샷으로 저장하는 트리거. |
| SSRF (Server-Side Request Forgery) | 서버가 공격자에 의해 변조된 내부 인트라넷 API나 메타데이터 서버로 요청을 보내게 만드는 취약점. |
2. 아키텍처 흐름 및 핵심 모듈 분석 (Hotspots)
context-mode의 전체 흐름은 "AI가 도구를 부르기 전과 후를 가로채는 구조"로 이해하면 쉽다. 사용자가 코딩 에이전트에게 일을 시키면, 에이전트는 파일 읽기, 명령 실행, 웹 요청, 검색 같은 도구를 호출한다. context-mode는 이 출력이 그대로 대화창에 쌓이지 않도록 샌드박스와 로컬 DB 사이에 완충지대를 만든다.
- 사용자 요청: Claude Code, Codex CLI, Cursor 같은 AI 도구에서 작업 시작
- MCP 서버: src/server.ts가 도구 호출을 받고 실행 경로를 결정
- 샌드박스 실행: src/executor.ts가 JavaScript, Python, Shell 등 코드를 임시 환경에서 실행
- 출력 판단: 짧은 결과는 요약하고, 큰 결과는 로컬 저장소에 넣은 뒤 참조만 반환
- 검색 저장소: src/store.ts가 SQLite FTS5로 문서와 로그 조각을 검색 가능하게 보관
- 세션 DB: src/session 모듈이 파일 변경, 에러, 결정, 작업 상태를 기록
- 플랫폼 어댑터: src/adapters가 Claude Code, Codex, Cursor 등 도구별 설정 경로를 맞춤
- 보안 가드: src/security.ts와 서버 내부 검사가 위험 명령, 비밀값, 위험 URL을 줄임
A. src/server.ts: MCP 도구 라우터 및 API 게이트웨이
11개의 MCP 도구를 등록하고 라우팅을 처리하는 엔트리포인트다.
- 설계 특징: ctx_execute 호출 시 출력 크기 임계치를 평가해서, 기준을 넘으면 자동 인덱싱(ctx_index) 기반 검색으로 우회시킨다.
- 배치 및 동시성(v1.0.104 개선): ctx_batch_execute, ctx_fetch_and_index에 동시성(Concurrency) 파라미터를 도입해서 외부 API나 다중 스크립트 실행 시 생기는 I/O 블로킹과 왕복 지연 시간(RTT)을 최소화했다.
흥미로운 점은 서버가 단순 명령 실행기가 아니라는 것이다. ctx_execute는 코드를 실행한 뒤 출력 크기를 보고, 필요하면 자동 인덱싱이나 의도 기반 검색으로 방향을 바꿔준다. ctx_search는 검색 호출이 반복되면 결과 수를 줄이거나 배치 실행을 요구한다. 이는 AI가 같은 질문을 여러 번 던지며 컨텍스트를 낭비하는 패턴을 줄이려는 장치이기 때문이다.
B. src/executor.ts: 서브프로세스 기반 다국어 런타임
JavaScript, Python, Shell 등 다양한 언어를 임시 환경에서 실행한다. LLM이 직접 엄청난 양의 데이터를 파싱하는 대신, 로컬 스크립트를 돌려서 계산된 통계나 요약만 반환받도록 유도한다.
- 보안 설계: BASH_ENV, NODE_OPTIONS, LD_PRELOAD, GIT_ASKPASS 등 사용자 셸 환경에 의도치 않은 사이드 이펙트를 유발할 수 있는 민감한 환경변수를 강제로 지워버린다(Sanitization).
- 엔지니어링 리스크: 이건 단순한 프로세스 래핑일 뿐, 컨테이너 기반의 완벽한 샌드박싱이 아니다. 프로덕션 망에 적용하려면 파일 시스템 쓰기 권한 통제 같은 추가적인 호스트 보안 레이어가 필요하다.
코드를 보면 출력 크기 상한, 프로세스 종료, 백그라운드 실행, Windows 경로 처리, Git Bash 변환 같은 운영 세부가 들어 있다. 특히 BASH_ENV, NODE_OPTIONS, PYTHONSTARTUP, LD_PRELOAD, GIT_ASKPASS 같은 민감한 환경변수를 제거하는 로직은 중요하다. 이런 값이 남아 있으면 사용자의 셸 설정이나 인증 헬퍼가 의도치 않게 실행될 수 있기 때문이다.
context-mode의 샌드박스는 AI 출력과 로컬 실행을 다루기 위한 안전장치에 가깝다. 완전한 격리 실행 환경, 예를 들어 컨테이너나 가상머신과 같은 보안 경계는 아니다. 기업 환경에서는 허용 명령, 네트워크 접근, 비밀값 노출, 작업 디렉터리 권한을 별도로 설계해야 한다.
C. src/store.ts: 로컬 지식 저장소 (FTS5 엔진)
원문 출력을 버리지 않고 검색 가능한 단위(Chunks)로 쪼개서 SQLite에 저장한다.
- 검색 최적화: 단순 문자열 매칭을 넘어서, FTS5의 BM25 스코어링과 Proximity Rerank(검색어 간 근접도 평가)를 적용해 검색 품질을 보정한다. 토큰 절감의 핵심인 '압축 후 재검색'을 가능하게 하는 코어 모듈이다.
이 계층은 컨텍스트 절감의 균형추로 역할을 한다. 단순히 출력을 줄이기만 하면 AI가 근거를 잃고, 반대로 원문을 모두 넣으면 컨텍스트가 너무 많아진다. context-mode는 원문을 검색 가능한 DB로 빼두고, 필요할 때 ctx_search로 다시 찾게 한다. 그래서 이 저장소의 핵심은 압축이 아니라 검색 가능한 생략이 된다.
D. src/session: 세션 복구 및 상태 동기화
LM 코딩 도구가 긴 대화 후 컨텍스트를 압축(Compact)할 때 날아가는 작업 상태(수정 파일, 의사결정 내역, 에러)를 추적한다.
- 동작 원리: 도구의 입력/출력 스트림에서 AST 훅을 통해 상태 변화 신호를 추출(extract.ts)하고, 세션 DB에 기록(db.ts)한다. 압축 이벤트가 발생하면, 원문이 아니라 목차와 인덱스 형태의 복구 스냅샷(snapshot.ts)만 주입해서 컨텍스트 폭발을 막는다.
- 역할: 파일 작업, 에러, Git 작업, 사용자 결정, 작업 상태를 세션 이벤트로 저장
- 입력 -> 출력: 도구 실행 흔적과 훅 이벤트 -> SQLite 세션 DB와 복구 스냅샷
- 중요한 규칙: 원문 전체를 다시 주입하지 않고 검색 가능한 안내와 요약을 제공
- 실패 가능성: 플랫폼 훅이 없거나 제한적이면 복구 품질이 떨어짐
- 서비스 의미: 긴 AI 코딩 작업에서 "어디까지 했는지"를 보존하는 운영 메모리
E. src/security.ts: SSRF 방어 및 프롬프트 인젝션 방어
설정 파일의 Deny Rule을 평가하는 보안 인터셉터다.
- 명령어 검증: &&나 | 등으로 체이닝된(Chained) 명령어를 분해해서 개별 검증하고, Tool Input 로그에서 Secret Value를 마스킹한다.
- 네트워크 통제: ctx_fetch_and_index 실행 시 대상 URL의 DNS 레코드를 조회해서 Link-local, Multicast, Reserved IP(예: AWS IMDS 169.254.169.254)로의 라우팅을 차단해 SSRF 공격을 방어한다. (CTX_FETCH_STRICT=1 플래그로 더 강력하게 통제 가능)
3. 실행 및 연동 파이프라인 가이드
1) 글로벌 CLI 설치 및 환경 진단
NPM 네이티브 빌드 종속성(better-sqlite3)을 확인하기 위해 설치 직후 진단 도구를 실행한다.
npm install -g context-mode
context-mode doctor
- 목적: 로컬 Node 환경과 context-mode 설치 상태 확인
- 기대 결과: 플랫폼 감지, 설정 파일, 런타임, DB 경로 관련 진단 출력
- 흔한 실패 지점: Node 버전, 전역 NPM 경로, better-sqlite3 네이티브 빌드
- 운영 메모: 일반 테스트는 Node 20 기반 CI가 보이고, OpenClaw E2E는 Node 22를 사용
2) Claude Code 플러그인 모드 연동
Claude Code 내부에서 MCP 서버 및 세션 훅을 주입하는 표준 방식이다.
/plugin marketplace add mksglu/context-mode
/plugin install context-mode@context-mode
/context-mode:ctx-doctor
- 목적: Claude Code 안에서 context-mode MCP 도구와 훅을 함께 사용
- 기대 결과: ctx_doctor 진단과 세션 훅 설정 확인
- 흔한 실패 지점: 플러그인 경로, Claude Code 재시작, 기존 MCP 설정 충돌
- 운영 메모: 팀 표준 환경에서는 개인 설정과 프로젝트 설정이 섞이지 않게 관리 필요
MCP 서버만 직접 붙이는 방식
플러그인 설치가 부담스럽다면 MCP 서버를 직접 등록하는 접근도 가능하고, Claude Code 예시로 쓰면 다음과 같은 형태이다.
claude mcp add context-mode -- npx -y context-mode
- 목적: context-mode를 MCP 서버로만 연결
- 기대 결과: AI 도구에서 ctx_execute, ctx_search, ctx_batch_execute 같은 도구 호출 가능
- 흔한 실패 지점: MCP stdio 통신, npx 캐시, 패키지 버전 고정 문제
- 운영 메모: 재현 가능한 팀 환경은 npx보다 버전 고정 설치가 더 안전
3) 실전 유즈케이스: 대용량 로그 파일 분석(토큰 절감)
로그 원문을 컨텍스트에 냅다 붓는(Dump) 대신, 스크립트 실행으로 통계 메타데이터만 뽑아내는 ctx_execute 패턴이다.
await ctx_execute({
language: "javascript",
intent: "최근 에러 유형과 빈도를 요약",
code: `
const fs = require("fs");
const text = fs.readFileSync("logs/app.log", "utf8");
const counts = {};
for (const line of text.split("\\n")) {
const match = line.match(/ERROR\\s+([A-Z_]+)/);
if (match) counts[match[1]] = (counts[match[1]] || 0) + 1;
}
console.log(JSON.stringify(counts, null, 2));
`
});
- 목적: 긴 로그 원문 대신 에러 유형과 빈도만 AI에게 전달
- 기대 결과: 출력이 작으면 요약 형태로 반환, 크면 로컬 저장 후 검색 단서 제공
- 흔한 실패 지점: 로그 경로, 파일 권한, timeout, 출력 상한
- 해석 메모: 원문 로그는 필요할 때 ctx_search로 다시 찾는 구조가 적합
실전 예제: 여러 요청을 한 번에 묶기
v1.0.104 릴리스는 배치 실행과 URL 수집의 동시성 개선을 강조한다. 여러 API나 문서를 한 번에 확인할 때는 ctx_batch_execute 또는 ctx_fetch_and_index가 유용한 방향이 된다.
await ctx_batch_execute({
concurrency: 4,
commands: [
{
language: "shell",
code: "gh issue list --limit 20",
intent: "최근 GitHub 이슈 목록 요약"
},
{
language: "shell",
code: "git log --oneline -20",
intent: "최근 커밋 흐름 요약"
}
],
queries: [
"최근 버그 리포트",
"성능 개선 커밋"
]
});
- 목적: 반복 MCP 호출을 줄이고 한 번의 배치로 조사 결과를 정리
- 기대 결과: 각 명령 출력은 필요시 인덱싱되고, 검색 질의는 짧은 결과로 반환
- 흔한 실패 지점: GitHub CLI 인증, 외부 API rate limit, 동시성 과다
- 운영 메모: CI나 사내망에서는 concurrency를 낮춰 실패 원인을 분리하는 편이 안전
한계 확인 예제: 위험 URL과 플랫폼 훅 점검
웹 수집 기능을 쓴다면 보안 가드를 먼저 확인해야 합니다. 특히 내부망 접근이 막히는지 보는 테스트가 필요하다.
CTX_FETCH_STRICT=1 context-mode doctor
await ctx_fetch_and_index({
concurrency: 2,
requests: [
{
url: "https://example.com",
intent: "외부 문서 수집 테스트"
}
]
});
- 목적: 네트워크 수집 기능과 strict fetch 정책 확인
- 기대 결과: 안전한 외부 URL은 수집되고, 위험한 내부 주소는 차단
- 흔한 실패 지점: 프록시, 인증 URL, 내부 DNS, 사내 SSL 인증서
- 해석 메모: context-mode의 가드는 보조 방어선이며, 네트워크 정책을 대체하지 않음
4. 프로덕션 도입 시 고려사항 및 리스크
context-mode는 문제 해결 방향이 아주 명확하고 훌륭한 인프라 도구지만, 엔터프라이즈 환경에 도입할 땐 다음 리스크를 반드시 따져봐야 한다.
- 플랫폼 어댑터 파편화 (Documentation Drift):
- README는 14개의 플랫폼 지원을 명시하지만, docs/platform-support.md에는 12개로 적혀 있는 등 파편화가 있다. 또, Cursor의 세션 복구 훅 제약, Zed의 훅 미지원 등 플랫폼 간 기능 편차가 커서 주력 IDE/Agent 툴에 대한 파일럿 테스트(Smoke Test)가 필수적이다.
- OS 의존성 및 C++ 네이티브 빌드 이슈:
- SQLite를 돌리기 위해 better-sqlite3를 쓰다 보니, Windows/macOS/Linux 환경별로 C++ 빌드 체인이 필요할 수 있다. 팀 내 개발 환경이 제각각이라면 CI/CD 환경 구성에 각별히 유의해야 한다.
- 가짜 샌드박싱 (Pseudo-Sandboxing) 오해:
- src/executor.ts는 환경변수를 소거할 뿐, 커널 레벨의 네임스페이스 격리를 제공하진 않는다. rm -rf / 같은 악의적이거나 할루시네이션(Hallucination)에 의한 파괴적 명령을 완벽하게 막을 수 없으니, 권한 통제 모델(Allowlist)을 꼭 병행해야 한다.
- 라이선스 제약 (Elastic License 2.0):
- 흔한 MIT/Apache 라이선스가 아니라 ELv2 라이선스를 쓰고 있다. 사내망에서 내부 도구로 쓰는 건 자유롭지만, 이걸 래핑(Wrapping)해서 상용 SaaS(관리형 서비스) 형태로 외부에 제공하는 건 라이선스 위반 소지가 있으니 법무 검토가 필요하다.
5. 서비스로서의 의미
서비스 관점에서 context-mode의 핵심 고객은 "AI를 쓰는 모든 사람"이 아니라. 더 정확한 고객은 AI 코딩 도구를 매일 쓰고, 긴 세션과 큰 저장소 때문에 컨텍스트 비용을 체감하는 개발자와 플랫폼팀이 될 것이다.
- 누가 쓰는가: Claude Code, Codex CLI, Cursor, OpenCode 같은 AI 개발 도구를 업무에 붙인 개발팀
- 줄이는 비용: 토큰, 재시작 시간, 같은 설명 반복, 긴 로그 복붙, 세션 압축 후 복구 시간
- 대체하는가: AI 모델이나 IDE를 대체하지 않고, 기존 에이전트 앞단을 보완
- 돈을 낼 가치: 팀 표준 에이전트 환경, 사내 개발자 포털, 보안형 로컬 컨텍스트 관리
- 운영 비용: 플랫폼별 훅 유지, SQLite DB 관리, 네이티브 패키지 설치, 문서 동기화
- 통합 장벽: 기존 MCP 설정, 권한 정책, 네트워크 정책, AI 도구별 플러그인 정책
- 신뢰 조건: 원문이 로컬에 남고, 비밀값이 가려지며, 실패 시 복구 경로가 명확해야 함
결론
결론적으로, context-mode는 "모델 윈도우가 크면 다 해결될 것"이라는 맹신을 깨고, 시스템 엔지니어링 관점에서 토큰 비용과 I/O 레이턴시를 최적화한 실용적인 미들웨어다. 철저한 망 분리와 샌드박스 보안 설계만 제대로 뒷받침된다면 팀 단위의 AI 코딩 생산성을 극대화할 수 있는 강력한 무기가 될 것이다.
