AI 에이전트용 지식 베이스 「ContextMixer」를 만들고 운영하며 알게 된 것

세션이 끊기면 전부 사라진다

LLM을 사용한 개발에서 가장 아까운 점은, 세션이 끊길 때마다 컨텍스트 (Context)가 제로로 돌아가는 것이라고 생각한다.

지난 채팅에서 "Vue를 그만두고 HTMX로 바꾼다"라고 결정했다. 이유도, 검토한 선택지도 전부 이야기했다. 하지만 다음 세션에서 AI는 그것을 알지 못한다. 인간이 다시 한번 설명하거나, 과거 로그를 붙여넣거나, 아니면 포기하고 처음부터 다시 이야기해야 한다.

프로젝트가 하나라면 그나마 낫다. 나의 경우 개인 개발 프로젝트가 20개 이상 있고, 각각에 사양과 설계 판단, 진척도가 있다. 게다가 Claude Code, Codex, OpenCode 등 여러 에이전트 (Agent) 도구를 테스트하던 시기에는, 매번 "이 프로젝트는 이런 구성이고, 지난번에는 여기까지 했으며, 다음에는 이것을 하고 싶다"라고 설명하는 것이 상당히 고통스러웠다.

세션별, 에이전트 도구별로 정보를 공유할 수 있는 장소가 필요해서 기존 도구들을 여러 가지 시도해 보았다.

기존 도구로는 부족했다

처음에는 로컬 Markdown 파일로 관리했다. 프로젝트 문서를 Git으로 관리하는 일반적인 방식이라 어느 정도는 기능했지만, 프로젝트 간의 정보 참조가 어렵고 채팅 도구에서 액세스할 수 없다는 점이 불만이었다.

다음으로 Notion을 시도했다. MCP를 통해 채팅 도구에서도 액세스할 수 있고, 인간도 웹(Web)에서 읽고 쓸 수 있다. 구성 자체는 나쁘지 않았다. 다만 계속 사용하다 보니 MCP를 통해 가져올 때의 레이턴시 (Latency)나 토큰 (Token) 소비가 신경 쓰이기 시작했다. 특히 여러 페이지를 한꺼번에 업데이트하는 상황에서는 꽤 오래 기다려야 한다. Notion은 원래 인간이 읽고 쓰기 위해 설계된 도구이므로, AI의 액세스 효율성을 전제로 하지 않는 것은 어쩔 수 없는 일이다.

Obsidian도 검토했다. 로컬 Markdown 방식이라 도구 종속성 (Lock-in)이 없고 Claude Code에서는 액세스할 수 있지만, Claude.ai와 같은 채팅에서는 로컬 파일에 액세스할 수 없다. GitHub 리포지토리 + GitHub MCP는 당시 채팅 측에 커넥터 (Connector)가 없었다.

요컨대, 채팅 앱에서도 CLI의 에이전트에서도 액세스할 수 있고, AI에 적합한 가벼운 구조를 가진 것을 찾을 수 없었다. 어차피 나밖에 안 쓸 거라면 직접 만들자는 생각으로 만들기 시작한 것이 Context Mixer다. Hono on Cloudflare Workers + D1 (SQLite 호환) + R2라는 구성으로, Cloudflare의 무료 티어 내에서 동작하므로 런닝 코스트 (Running Cost)는 거의 제로다.

Karpathy의 LLM Wiki 패턴

만들기 시작하고 얼마 지나지 않아, Karpathy가 공개한 "LLM Wiki" 패턴을 알게 되었다. RAG처럼 매번 문서의 파편을 검색하는 것이 아니라, LLM이 소스를 읽고 구조화된 wiki를 스스로 구축 및 유지한다는 접근 방식으로, 공개 직후부터 큰 화제가 되었다고 한다.

내가 하려던 것을 깔끔하게 언어화해 준 느낌이었다. 다만 Karpathy의 패턴은 "로컬 Markdown 파일 + 코딩 에이전트"로 완결되는 설계라서, 개인 연구 노트에는 적합하지만 나의 유스케이스 (Use Case)와는 조금 차이가 있었다.

나의 경우는:

액세스 원이 채팅 (Claude.ai)과 CLI (Claude Code) 양쪽 모두임
프로젝트가 20개 이상 있음
쓰기의 8할은 AI가 담당하며, 인간도 웹 UI로 가끔 확인 및 편집함

LLM Wiki가 "읽은 것을 축적하는 도서관"이라면, 내게 필요했던 것은 "진행 중인 프로젝트를 AI와 함께 관리하는 작업장의 화이트보드" 같은 것이었다.

취득의 입도를 선택할 수 있도록 했다

ContextMixer의 설계에서 가장 먼저 생각한 것은, AI가 "어디까지 읽을지"를 선택할 수 있게 하는 것이었다.

Notion의 MCP라면 페이지를 지정했을 때 내용이 전부 반환된다. 하지만 AI가 가장 먼저 하고 싶은 것은 "이 문서가 지금 작업과 관련이 있는가?"를 판단하는 것이며, 그러기 위해서는 제목과 개요 정도의 수십 토큰이면 충분하다.

그래서 취득 모드를 4단계로 나누었다.

모드	반환 내용	토큰 기준
`meta`	제목 + 개요	수십
`outline`	헤더 구조	수백
`section`	지정된 섹션만	수백~수천
`full`	전문 (Full Text)	전체 양

실제 취득 흐름은 다음과 같다. 예를 들어 "인증 설계 방침을 확인해 줘"라고 지시했을 경우:

list_docs(collection_id) → 문서 목록 (각 meta 포함)
"spec"가 관련 있어 보임 → get_doc(doc_id, view=outline)
「인증」 섹션 발견 → get_doc(doc_id, view=section, section="인증")
...

Notion이라면 「spec 페이지 통째로 가져오기」라는 1단계로 끝나지만, 페이지가 길면 수천 토큰을 소비한다. ContextMixer라면 3번의 API 호출이 발생하지만, 합계 토큰은 수백 개로 끝난다.

엄밀하게 측정한 것은 아니지만, 전문(Full Text) 취득을 전제로 하는 Notion MCP와 비교하면 토큰 소비가 상당히 가벼워질 것이다. 대부분 meta → section의 2단계로 끝나는 케이스이므로, 읽는 양 자체도 상당히 작아진다. 소소한 메커니즘이지만 매일 사용하는 것이기에 이 차이가 서서히 효과를 발휘한다.

세션 인계(Session Handover) 구조: AI Cortex

취득의 입도(Granularity)를 나누었다면, 다음으로는 「무엇을 어떻게 저장할 것인가」에 대한 규칙을 생각해야 했다.

ContextMixer 자체는 컬렉션(Collection)과 문서(Document)라는 범용적인 그릇이며, 무엇을 어떻게 넣을지는 시스템이 결정하는 것이 아니라 사용하는 쪽에서 규칙으로 정한다. 본인이 만든 운영 규칙을 「AI Cortex」라고 부르고 있다.

구체적으로는 각 프로젝트의 컬렉션에 4개의 문서를 두는 규칙으로 정했다.

context — 현재 단계, 최근 작업, 미결 사항, 다음 세션으로의 인계 내용
spec — 목표, 요구사항, 기술 구성. 확정된 사항만 기록
decisions — 설계 판단의 이유와 경위. 기각된 선택지도 기록
notes — 라이브러리의 함정, 버그 회피책, 구현 팁(Tips)

이 4개의 문서를 만들고, CLAUDE.md나 skills에 「작업 시작 시에는 context를 읽고, 종료 시에는 업데이트하라」고 적어둔다. 다음 세션의 에이전트(Agent)는 그것을 읽고 이어서 작업을 시작한다.

가장 효과를 느끼는 것은 Claude Code를 이용한 개발로, 「지난번에 어디까지 했는지」를 인간이 설명할 필요가 없다. 에이전트가 context를 읽고 알아서 작업을 재개해 준다. decisions도 은근히 도움이 되는데, 「왜 Vue를 포기했는지」를 에이전트가 스스로 읽을 수 있기 때문에 동일한 논의가 반복되지 않게 되었다.

AI에게 쓰게 만드는 것의 어려움

다만, AI에게 쓰기(Write)를 맡기는 것에는 어려움도 있다.

방치하면 AI가 멋대로 판단을 decisions에 써넣어서, 확정된 사항과 검토 중인 이야기가 섞일 때가 있다. 「사용자 확인 없이 decisions를 작성하지 말 것」, 「spec에 검토 중인 내용을 쓰지 말 것」과 같은 규칙을 CLAUDE.md에 지정하여 대처하고 있지만, 완벽하지는 않다.

비슷한 테마의 문서가 중복되어 만들어지는 경우도 있다. 쓰기 전에 검색을 통해 중복 체크를 시키는 등 여러 가지를 시도하고 있지만 아직 시행착오 중이다. AI에게 지식 베이스(Knowledge Base)를 쓰게 하려면, 쓰기 권한보다 쓰기 규칙의 설계가 더 중요하다는 것이 현재까지의 체감이다.

해보면서 알게 된 것

이 메커니즘을 운영해 오면서, ContextMixer 고유의 이야기를 떠나서 말할 수 있는 것이 두 가지 있다.

AI에게는 전문이 아니라, 읽는 순서를 전달하는 것이 좋다

먼저, AI에 대한 정보 제공은 단계적으로 하는 것이 좋다. 매번 전문을 전달할 필요 없이, 개요를 보여주고 관련이 있어 보이면 심층적으로 파고들게 한다. 이 사고방식은 자체 지식 베이스뿐만 아니라, RAG의 청크(Chunk) 설계나 프롬프트 구성 방식에서도 사용할 수 있다.

세션 인계는 채팅 이력의 요약만으로는 부족하다

또 하나는, 세션 인계에는 채팅 이력의 요약만으로는 부족하다는 점이다. 「지난 판단의 이유」나 「다음에 해야 할 일」을 정확하게 전달하려면, 역할별로 구조화된 문서가 필요하다. 이 사고방식 자체는 Notion에서도 Obsidian에서도 사용할 수 있지만, AI가 가벼운 입도로 탐색할 수 있고, 채팅에서도 CLI에서도 동일한 장소에 접근할 수 있는 환경을 처음부터 전제로 설계한 것이 ContextMixer다.

ContextMixer는 OSS(Open Source Software)로 공개되어 있습니다.

내가 원했던 것은 AI에게 모든 것을 기억시키는 것이 아니라, AI가 필요할 때 스스로 읽으러 갈 수 있는 장소였다. 세션이 끊겨도, 에이전트가 바뀌어도 지식이 그곳에 있다. 현재로서는 그것이 가장 현실적인 「AI의 기억」을 만드는 방법이라고 생각한다.

Cloudflare의 무료 티어(Free Tier)에서 동작하므로 실행 비용(Running Cost)은 거의 제로에 가깝다. 세션 인계로 고민하고 있는 분들은 한번 시도해 보길 바란다.

링크

데모

프로젝트 상세 및 설계 경위