# Magic Context: 세션을 끊지 않고 프로젝트 지식을 쌓는 코딩 에이전트용 메모리 플러그인

**URL:** <https://discuss.pytorch.kr/t/magic-context/11645>\
**Category:** 읽을거리&정보공유\
**Tags:** agent-memory, context-engineering, cortexkit, magic-context, mit-license, coding-agent, opencode\
**Created:** [8월 18, 2026, 9:30오후 UTC](https://discuss.pytorch.kr/t/magic-context/11645 "2026-08-18T21:30:43Z")\
**Posts on this page:** 1\
**Page:** 1

<div class="post-metadata">

**Author:** ![9bow](https://discuss.pytorch.kr/user_avatar/discuss.pytorch.kr/9bow/32/16301_2.png) [@9bow](https://discuss.pytorch.kr/u/9bow)\
**Post date:** [8월 18, 2026, 9:30오후 UTC](https://discuss.pytorch.kr/t/magic-context/11645/1 "2026-08-18T21:30:43Z")

</div>

![Magic Context: 세션을 끊지 않고 프로젝트 지식을 쌓는 코딩 에이전트용 메모리 플러그인](https://discuss.pytorch.kr/uploads/default/original/3X/7/9/79e9a390409eb7b8c010b8fecbfffbf77fcacc54.jpeg)

## Magic Context 소개

코딩 에이전트와 오래 작업하면 두 번 손해를 봅니다. 대화가 길어져 컨텍스트 창이 차면 에이전트는 지금까지의 기록을 압축(compaction)하려고 작업을 멈추고, 압축이 끝난 뒤에는 알고 있던 것 일부가 조용히 사라집니다. 그리고 세션을 닫으면 남는 것이 없어서, 다음 작업은 이 프로젝트를 처음 보는 사람으로 다시 시작합니다. Magic Context의 저자는 이 상태를 _"anterograde amnesia"_, 즉 새 기억을 만들지 못하는 전향성 기억상실에 빗대면서, 좋은 개발자를 버그 하나 고칠 때마다 새로 뽑고 내보내지는 않는다고 지적합니다.

Magic Context는 이 두 손해를 배경 작업으로 함께 해결하려는 플러그인입니다. 프로젝트는 스스로를 코딩 에이전트의 **해마(hippocampus)**, 곧 기억을 만들고 정리하고 다시 꺼내는 부위라고 소개하며, 두 가지를 약속합니다. 에이전트가 컨텍스트를 관리하려고 멈추는 일이 없고, 알게 된 것을 잊지 않는다는 것입니다. 압축을 걷어내는 방식이 아니라, 압축을 호스트에서 가져와 배경에서 조금씩 처리하는 방식이라는 점이 핵심입니다. 그래서 설치 마법사는 호스트의 내장 압축 기능을 먼저 끕니다.

Magic Context는 TypeScript로 작성된 플러그인이고, 지원 대상은 [OpenCode](https://github.com/sst/opencode)와 Pi, Oh My Pi(OMP) 세 가지 호스트입니다. 모든 지속 상태는 로컬 SQLite 데이터베이스 한 개에 담기며, 프로젝트는 이것을 CortexKit라는 더 큰 계획의 한 조각으로 두고 있습니다. 한국어 [README](https://github.com/cortexkit/magic-context/blob/master/README.ko.md)가 저장소에 함께 들어 있어서 원문을 한국어로 바로 읽을 수도 있습니다.

## Magic Context가 컨텍스트를 다루는 방식

Magic Context가 압축 대기를 걷어내는 방법은 압축을 **뒤로 미루고 잘게 쪼개는** 것입니다. 배경에서 도는 사관(historian)이 오래된 원본 기록을 계층화된 구획(tiered compartment)으로 압축하는데, 각 구획은 시간순 요약이면서 중요도 점수를 함께 갖습니다. 요약 작업에는 주 모델의 코딩 능력이 필요하지 않으므로, 프로젝트는 사관을 값싼 모델이나 완전한 로컬 모델로 실행하면서 주 에이전트는 최상급 모델로 유지하라고 권합니다.

구획을 실제로 프롬프트에 넣을 때는 감쇠 렌더링(decay rendering)을 씁니다. LLM을 쓰지 않는 결정적(deterministic) 규칙이 모델의 컨텍스트 창 크기에 맞춰 스스로 조정되면서, 오래된 기록이 어느 순간 뚝 떨어지는 대신 서서히 흐려지게 만듭니다. 규칙이 결정적이라 같은 기록은 언제 렌더링해도 같은 결과가 나옵니다.

프롬프트 캐시를 지키는 설계도 함께 들어 있습니다. 에이전트가 `ctx_reduce`로 낡은 도구 출력이나 긴 메시지를 지울 대상으로 표시하면, 삭제는 곧바로 반영되지 않고 **큐에 쌓여 캐시가 안전한 시점에만** 적용됩니다. 배경 작업이 프롬프트의 캐시된 앞부분을 무효화하지 않도록 전체 배치를 잡아 두었기 때문에, 프로젝트는 캐시 단가가 적용되는 제공자에서 세션을 몇 달 유지해도 비용이 낮게 유지된다고 설명합니다. 에이전트가 컨텍스트 관리에 아예 관여하지 않게 하려면 이 기능을 끌 수 있고, 그때는 낡은 출력이 나이에 따라 자동으로 정리됩니다.

## Magic Context의 기억은 세 단계로 만들어집니다

프로젝트는 기억을 포착, 통합, 회상 세 단계로 나눠 설명합니다.

**포착(Capture)** 은 압축 과정에 얹혀 갑니다. 사관은 기록을 압축하려면 어차피 전부 읽어야 하므로, 같은 작업에서 오래 남길 가치가 있는 것들을 함께 들어 올려 프로젝트 기억으로 승격시킵니다. 결정 사항, 제약, 관례, 설정값이 그 대상이고, 분류는 `PROJECT_RULES`, `ARCHITECTURE`, `CONSTRAINTS`, `CONFIG_VALUES`, `NAMING` 다섯 가지입니다. 에이전트가 `ctx_memory`로 직접 적을 수도 있지만 대부분은 자동으로 포착됩니다.

**통합(Consolidate)** 은 선택 기능인 몽상가(dreamer) 에이전트가 유휴 시간에 하는 일입니다. 기억을 그것을 뒷받침하는 프로젝트 파일에 연결해 두고, 코드베이스와 대조해 낡은 사실을 고치거나 지우고, 중복을 합치고 표현을 다듬으며, 중요도와 범위를 점수화합니다. 사용자가 반복해서 바로잡아 준 순간에서 교훈을 정리해 남기는 회고 작업과 `ARCHITECTURE.md`, `STRUCTURE.md`를 최신 상태로 유지하는 작업도 목록에 있습니다. 아무도 기다리지 않는 시간에 돌기 때문에 프로젝트는 몽상가를 느린 로컬 모델과 함께 쓰기 좋다고 안내하며, `/ctx-dream`으로 직접 실행할 수도 있습니다.

**회상(Recall)** 은 매 턴 자동으로 일어납니다. 활성 프로젝트 기억과 압축된 세션 기록이 캐시를 깨지 않는 방식으로 주입되고, 에이전트가 필요할 때 직접 찾아볼 수도 있습니다. 회상은 세션을 넘어서고 호스트도 넘어서므로, OpenCode에서 적은 기억을 Pi나 OMP에서 꺼낼 수 있습니다.

에이전트가 직접 호출하는 도구는 다섯 가지입니다:

 ![Magic Context가 코딩 에이전트에 더하는 다섯 가지 도구를 정리한 표](https://discuss.pytorch.kr/uploads/default/original/3X/9/e/9e9b09a7fb1d656a86878f7b60bdc24af8861613.jpeg)

이 중 `ctx_search`는 프로젝트 기억과 원본 대화 기록, 색인된 git 커밋, 보류해 둔 메모, 승격된 프라이머를 한 번의 질의로 훑습니다. 검색은 임베딩 기반 의미 검색을 쓰고 전문 검색으로 대체(fallback)되며, 임베딩을 끄면 의미 검색만 사라지고 키워드 검색과 컨텍스트 관리는 계속 동작합니다.

## Magic Context 설치 및 설정

설치는 대화형 마법사가 담당합니다. 어떤 호스트가 깔려 있는지 자동으로 찾아 플러그인을 추가하고, 내장 압축을 끄고, 사관과 몽상가, 조수(sidekick)에 쓸 모델을 고르게 하고, 다른 컨텍스트 관리 플러그인과의 충돌을 정리합니다:

```bash
# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/cortexkit/magic-context/master/scripts/install.sh | bash

# 또는 운영체제와 무관하게
npx @cortexkit/magic-context@latest setup

```

호스트를 지정하려면 `--harness opencode`, `--harness pi`, `--harness omp`를 붙입니다. Pi는 `0.74.0` 이상, OMP는 `17.1.7` 이상이 필요합니다. 마법사를 쓸 수 없는 환경이라면 `opencode.jsonc`에 플러그인을 직접 추가하고 `compaction`의 `auto`와 `prune`을 끈 다음, `magic-context.jsonc`에 사관 모델을 지정하면 됩니다. 설정 항목 전체는 [`CONFIGURATION.md`](https://github.com/cortexkit/magic-context/blob/master/CONFIGURATION.md)에 정리되어 있습니다. `historian.model`은 실제로 존재하는 `provider/model-id`여야 하며, 이 값이 없으면 플러그인은 올라오지만 사관 실행이 실패해 오래된 기록이 요약되지 않습니다.

문제가 생기면 `npx @cortexkit/magic-context@latest doctor`가 호스트를 자동으로 찾아 충돌과 플러그인 등록, 데이터베이스 상태를 점검하고 고칠 수 있는 것은 고칩니다. 설치 시점을 기준으로 동작한다는 점은 미리 알아 둘 만합니다. 새 프로젝트든 오래된 프로젝트든 같게 동작하지만, **설치 이전의 세션을 소급해서 채워 넣지는 않습니다.**

지속 상태는 `~/.local/share/cortexkit/magic-context/context.db` 한 파일에 모입니다. 기억은 저장소에서 끌어낸 안정적인 프로젝트 신원(project identity)에 묶이므로 worktree나 복제, 포크를 따라다니며, 디렉토리 경로에 매이지 않습니다. 로컬 임베딩을 쓰면 약 90MB 크기의 `Xenova/all-MiniLM-L6-v2` 모델이 처음 사용할 때 내려받아 캐시되는데, Docker나 CI처럼 사라지는 환경에서는 이 디렉토리를 지속 볼륨에 연결하라는 안내가 있습니다.

## Magic Context를 켜면 꺼야 하는 것들

Magic Context는 컨텍스트 관리를 처음부터 끝까지 자기가 맡기 때문에, 같은 일을 하는 다른 플러그인이 이미 있으면 **스스로 꺼집니다.** 두 개가 동시에 돌면 기록을 두 번 압축하고 프롬프트 캐시를 망가뜨리기 때문입니다. 시작할 때 아래 항목들을 점검하고, 정리되지 않는 동안에는 안전한 쪽으로 꺼진 상태를 유지하며 이유를 알려 줍니다:

| 충돌하는 기능 | 왜 함께 쓸 수 없는가 |
| --- | --- |
| OpenCode 내장 압축(`compaction.auto` / `compaction.prune`) | Magic Context가 대체하는 기능입니다 |
| OMP 기본 압축(`compaction.enabled`) | 같은 이유로 대체되며, 설치가 트랜잭션으로 끕니다 |
| OMP 자동 메모리(`memory.backend`) | 메모리 주입이 두 벌이 되어 회상과 보존이 중복됩니다 |
| DCP(`opencode-dcp`) | 별도의 컨텍스트 정리 플러그인이라 함께 돌 수 없습니다 |
| [oh-my-opencode](https://discuss.pytorch.kr/t/oh-my-opencode-subagent-opencode-all-in-one/8586)의 세 가지 훅 | 선제 압축과 사용량 경고, 긴급 압축이 사관과 겹칩니다 |

목록의 마지막 항목처럼, 이미 쓰던 플러그인의 일부 기능만 끄고 나머지는 유지하는 경우도 있습니다. 설치 마법사가 어떤 훅을 끌지 물어보므로 전체를 걷어낼 필요는 없습니다.

## Magic Context와 다른 기억 도구의 차이

에이전트에 기억을 붙이는 프로젝트는 이미 여러 갈래로 나와 있습니다. PyTorchKR에 소개된 것만 봐도 코딩 에이전트에 4단계 기억 구조를 더하는 [agentmemory](https://discuss.pytorch.kr/t/agentmemory-4/11460), 도구를 바꿔도 메모리와 스킬을 유지하는 [agentic-stack](https://discuss.pytorch.kr/t/agentic-stack/10829), 장기 기억을 압축해 토큰을 줄이는 [SimpleMem](https://discuss.pytorch.kr/t/simplemem-llm-30/11501), 지식 그래프(Knowledge Graph)와 벡터 검색을 결합한 [Cognee](https://discuss.pytorch.kr/t/cognee-ai/9852)가 있습니다.

Magic Context의 자리는 이 중 **컨텍스트 관리와 기억을 한 몸으로 묶은** 쪽입니다. 별도의 메모리 서버나 저장소를 두고 에이전트가 그것을 조회하는 형태가 아니라, 호스트의 압축 기능을 대체하면서 그 압축 과정에서 기억을 만들어 냅니다. 기억이 공짜로 생긴다고 프로젝트가 말하는 근거가 여기에 있고, 동시에 같은 일을 하는 다른 플러그인과 공존할 수 없는 이유도 여기에 있습니다.

프로젝트는 스스로를 CortexKit라는 묶음의 한 조각으로 두고 있습니다. Magic Context가 해마와 내측두엽을 맡고, 코드 구조를 인식하고 정확히 조작하는 [AFT](https://github.com/cortexkit/aft)가 감각운동 피질을, 계획과 분해를 맡을 Alfonso가 전두전야를 맡는다는 구성입니다. 다만 Alfonso는 아직 공개 예정 상태이므로, 지금 설치할 수 있는 것은 앞의 두 개입니다.

## Magic Context는 누구에게 유용한가

OpenCode나 Pi, OMP로 한 프로젝트를 길게 붙들고 작업하는 사람에게 가장 잘 맞습니다. 압축 대기가 실제로 흐름을 끊고 있고 같은 배경 설명을 매 세션 다시 하고 있다면, 이 도구가 겨냥하는 상황이 바로 그것입니다. 사관을 값싼 모델이나 로컬 모델로 돌릴 수 있어서 비용 부담도 조절할 수 있습니다.

반대로 Claude Code나 Codex를 주로 쓴다면 지금은 대상이 아닙니다. 지원 호스트가 위 세 가지로 한정되어 있기 때문입니다. 세션 하나로 끝나는 짧은 작업이 대부분이라면 얻을 것이 적고, 이미 다른 컨텍스트 관리 플러그인을 쓰고 있다면 둘 중 하나를 포기해야 합니다. 설치 이전 기록을 소급해 채우지 않으므로, 오래 이어 온 세션의 과거를 되살리려는 목적에도 맞지 않습니다.

## Magic Context의 라이선스

Magic Context는 [MIT 라이선스](https://github.com/cortexkit/magic-context/blob/master/LICENSE)로 공개되어 있어 개인 및 상업적 목적으로 자유롭게 사용할 수 있습니다.

## 📚 Magic Context 문서 사이트

> **[Magic Context](https://docs.cortexkit.io/magic-context/)**
>
> Persistent memory and self-managing context for OpenCode and Pi coding agents.

## :github: Magic Context 프로젝트 GitHub 저장소

> **[GitHub - cortexkit/magic-context: Unbounded context. Memory that manages itself. One...](https://github.com/cortexkit/magic-context)**
>
> Unbounded context. Memory that manages itself. One session, for life. The hippocampus for coding agents, part of CortexKit.

## 더 읽어보기

- [agentmemory: 코딩 에이전트에 4단계 기억 구조를 붙이는 오픈소스 메모리 서버](https://discuss.pytorch.kr/t/agentmemory-4/11460)

- [agentic-stack: 코딩 에이전트 도구를 바꿔도 메모리와 스킬을 유지하는 이식형 브레인](https://discuss.pytorch.kr/t/agentic-stack/10829)

- [SimpleMem: LLM 에이전트의 장기 기억을 압축해 토큰을 최대 30배 줄이는 메모리 프레임워크](https://discuss.pytorch.kr/t/simplemem-llm-30/11501)

- [Cognee: 지식 그래프와 벡터 검색을 결합하여 AI 에이전트에 장기 기억을 부여하는 오픈소스 지식 엔진](https://discuss.pytorch.kr/t/cognee-ai/9852)

- [Opencode: 다양한 LLM을 사용할 수 있는, 터미널 기반의 오픈소스 AI 코딩 에이전트](https://discuss.pytorch.kr/t/opencode-llm-ai/7579)

- [Oh My OpenCode: 다수의 SubAgent 및 도구들을 활용하는, OpenCode를 위한 All-in-One 플러그인](https://discuss.pytorch.kr/t/oh-my-opencode-subagent-opencode-all-in-one/8586)

- [Prime Intellect, 컨텍스트를 변수로 다루는 자기개선형 코딩 에이전트 Prime Agent 공개](https://discuss.pytorch.kr/t/prime-intellect-prime-agent/11544)

* * *

_이 글은 GPT 모델로 정리한 초안을 바탕으로 한 것으로, 원문의 내용 또는 의도와 다르게 정리된 내용이 있을 수 있습니다. 관심있는 내용이시라면 원문도 함께 참고해주세요! 읽으시면서 어색하거나 잘못된 내용을 발견하시면 댓글로 알려주시기를 부탁드립니다._ 🤗

이 도구를 직접 설치해 사용해보셨다면, [:pytorch:파이토치 한국 사용자 모임🇰🇷](https://pytorch.kr/) 회원들을 위해 경험이나 팁을 댓글로 남겨주세요! 🙏