cortexkit/magic-context

Magic Context – 코딩 에이전트를 위한 자가 관리 장기 메모리

개요 – CortexKit 제품군의 플러그인으로, AI 기반 코딩 에이전트에 '해마'를 부여합니다. 프로젝트 채팅 기록에서 유용한 지식을 자동으로 추출하고, 백그라운드에서 통합하며, 세션과 도구(OpenCode, Pi, Oh‑My‑Pi) 전반에 걸쳐 검색 가능하게 합니다. 목표는 에이전트가 작업 중에 학습한 내용을 잊어버리게 만드는 기존의 압축 중단을 없애는 것입니다.

주요 기능

• 캡처 – 에이전트가 작업하는 동안 히스토리언이 대화를 스캔하여 지속적인 사실(설계 결정, 제약 조건, 구성 값, 명명 규칙)을 추출하고 프로젝트 메모리로 저장합니다.
• 통합 – 선택적 드리머가 (보통 밤에) 실행되어 메모리를 현재 코드베이스와 대조 검증하고, 중복을 병합하며, 오래된 항목을 정리하고, 문서를 최신 상태로 유지합니다.
• 리콜 – 매 턴마다 시스템이 가장 관련성 높은 메모리를 프롬프트에 주입합니다. 개발자는 ctx_search, ctx_expand, ctx_note 등을 호출하여 메모리를 검색·편집하거나, git 커밋을 검색하거나, 메모를 연기할 수 있습니다.
• 컨텍스트 창 관리 – 히스토리언이 계층화된 구획을 만들어 중요도 점수와 함께 오래된 메시지를 요약함으로써, 활성 프롬프트를 작게 유지하면서 전체 스레드를 보존합니다. 캐시 인식 감소로 모델의 프롬프트 캐시가 무효화되지 않도록 합니다.
• 크로스 하네스 지원 – 주요 3가지 CortexKit 하네스(OpenCode, Pi, Oh‑My‑Pi)에서 작동하며, 경쟁하는 컨텍스트 관리 플러그인을 자동으로 비활성화합니다.

설치 및 설정

# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/cortexkit/magic-context/master/scripts/install.sh | bash
# Windows PowerShell
irm https://raw.githubusercontent.com/cortexkit/magic-context/master/scripts/install.ps1 | iex
# 또는 모든 OS에서 npx 사용
npx @cortexkit/magic-context@latest setup

마법사가 사용 중인 하네스를 감지하고, 적절한 플러그인(@cortexkit/opencode-magic-context, @cortexkit/pi-magic-context 등)을 추가하며, 호스트의 내장 압축을 비활성화하고, 히스토리언, 드리머, 사이드킥용 모델을 선택하도록 도와줍니다.

구성 – JSONC 파일(magic-context.jsonc)에서 하네스별로 히스토리언(필수) 및 선택적으로 드리머와 사이드킥의 모델 ID를 지정할 수 있습니다. 또한 임베딩, 시간 인식, 자동 검색 힌트를 활성화/비활성화할 수 있습니다.

일반적인 워크플로

1. 설정 마법사를 실행합니다(또는 플러그인을 하네스 구성에 수동으로 추가).
2. 히스토리언이 채팅 기록 요약을 시작하고 지속적인 사실을 프로젝트 메모리로 승격합니다.
3. 선택적으로 드리머(/ctx-dream)를 활성화하여 야간 유지 관리를 실행합니다.
4. 세션 중에 에이전트가 관련 메모리를 자동으로 받습니다. ctx_search로 쿼리하거나 ctx_memory로 편집할 수도 있습니다.

사용할 명령

명령	설명
/ctx-status	현재 메모리 통계, 보류 중인 드롭, 히스토리언 진행 상황 등을 표시합니다.
/ctx-flush	대기 중인 모든 축소/압축을 즉시 강제 실행합니다.
/ctx-recomp	원시 기록에서 구획을 재구축합니다(상태가 손상된 경우 유용).
/ctx-dream	드리머의 유지 관리 주기를 온디맨드로 트리거합니다.
/ctx-search(도구)	메모리, 채팅, git 커밋, 메모를 대상으로 의미론적/키워드 검색을 수행합니다.
/ctx-note	드리머가 나중에 표면화할 수 있는 연기 메모를 생성합니다.

중요성 – Magic Context가 없으면 각 코딩 에이전트 세션은 빈 상태에서 시작하고 주기적인 '압축'으로 인한 컨텍스트 중단을 겪습니다. Magic Context를 사용하면 단일 세션을 수주에서 수개월 동안 지속할 수 있으며, 프로젝트 지식을 보존하면서 토큰 비용을 줄이고 에이전트의 프롬프트 캐시를 안정적으로 유지합니다.

더 알아보기 – 전체 문서는 https://docs.cortexkit.io/magic-context 에 있으며, Discord 커뮤니티는 README에 링크되어 있습니다.