그래프 메모리 프록시(graph-memory proxy)가 어떻게 당신의 앱과 OpenAI API 사이에서 작동하며, LLM이 놓칠 수 있는 모든 것을 조용히 기억하는지에 대하여.

대규모 언어 모델(Large Language Model, LLM)과의 모든 대화는 제로 상태에서 시작됩니다. 탭을 닫거나 새로운 세션을 시작하면, 모델은 당신이 누구인지, 어제 무엇을 논의했는지, 혹은 지난주에 무엇을 결정했는지 전혀 알지 못합니다. 대부분의 도구들은 점점 더 많은 채팅 기록을 컨텍스트 윈도우(context window)에 밀어 넣는 방식으로 이를 해결하려 하지만, 이는 비용이 많이 들고 느리며 결국 엄격한 한계에 부딪히게 됩니다.

저는 이를 다르게 해결하기 위해 TokenMizer를 구축했습니다. 모든 것을 다시 읽음으로써 기억하는 대신, _그래프(graph)_를 구축함으로써 기억합니다.

핵심 아이디어: 플러그인이 아닌 프록시

TokenMizer는 모든 OpenAI 호환 API 앞에 프록시(proxy)로 위치합니다. 당신의 애플리케이션은 모델을 호출하는 방식을 변경할 필요가 없습니다. 단지 API 베이스 URL(API base URL)을 OpenAI로 직접 향하게 하는 대신 TokenMizer를 가리키기만 하면 됩니다. 모든 요청(request)과 응답(response)은 실제 모델로 전달되기 전에 통과되어 분석되고 저장됩니다.

이러한 설계 선택은 보기보다 훨씬 중요합니다. 이는 TokenMizer가 SDK 변경이나 통합 코드의 재작성 없이도, 이미 OpenAI API 형식을 사용하는 모든 프레임워크나 앱과 함께 작동할 수 있음을 의미합니다. 단 하나의 URL을 변경함으로써 기존 앱에 메모리를 추가할 수 있습니다.

메모리가 실제로 구축되는 방식

두 가지 시스템이 핵심적인 역할을 수행합니다.

**파일 인텔리전스(File Intelligence)**는 대화 중에 어떤 코드, 문서 또는 파일이 참조되는지 감시하고 그 주변의 컨텍스트를 구축합니다. 따라서 만약 당신이 세 번의 세션에 걸쳐 동일한 파일을 디버깅하고 있다면, TokenMizer는 해당 파일의 현재 내용뿐만 아니라 대화 속에서의 이력까지 이미 알고 있습니다.

**그래프 메모리 (Graph Memory)**는 더욱 흥미로운 부분입니다. TokenMizer는 대화 이력을 평면적인 로그 (flat log)로 저장하는 대신, 인물, 프로젝트, 결정 사항, 의존성 (dependencies)과 같은 엔티티 (entities)와 관계 (relationships)를 추출하여 SQLite 기반의 그래프 내 노드 (nodes)와 엣지 (edges)로 저장합니다. 새로운 메시지가 들어오면 TokenMizer는 오래된 대화 기록을 검색하는 대신, 그래프에서 관련 노드를 쿼리(query)하여 현재 주제와 연결된 정보만을 가져옵니다.

실질적인 차이점은 다음과 같습니다. 평면 로그 메모리 시스템은 검색해야 할 텍스트가 늘어남에 따라 이력이 쌓일수록 더 느려지고 비용이 많이 들게 됩니다. 반면, 그래프 메모리 시스템은 대화 기록을 스캔하는 것이 아니라 관계를 탐색(traversing)하기 때문에 빠른 속도를 유지합니다.

그래프 확인하기: D3.js 익스플로러 (D3.js Explorer)

데이터베이스 내부에만 존재하는 메모리 시스템은 시스템이 무엇을 하고 있는지 눈으로 볼 수 없기 때문에 신뢰하기 어렵습니다. TokenMizer는 D3.js를 기반으로 구축된 **그래프 익스플로러 (Graph Explorer)**를 함께 제공합니다. 이는 시스템이 학습한 모든 엔티티와 연결 관계를 시각적이고 인터랙티브하게 보여주는 지도입니다. 대화가 진행됨에 따라 새로운 노드가 나타나는 것을 관찰하거나, 엣지를 따라 소스(source)로 거슬러 올라가 모델이 왜 갑자기 세 번 전의 세션 내용을 "기억"해냈는지 추적할 수 있습니다.

이는 데모용보다 디버깅(debugging) 용도로 훨씬 유용하다는 것이 밝혀졌습니다. 메모리 검색(retrieval)이 잘못된 컨텍스트 (context)를 가져올 때, 그래프 뷰는 어떤 노드가 매칭되었는지, 그리고 어떤 관계를 통해 연결되었는지 정확히 보여줍니다.

두 가지 접근 방식: CLI 및 MCP

TokenMizer는 pip로 설치 가능한 라이브러리로 배포되므로, 기존 Python 환경에 직접 바로 적용할 수 있습니다. 일상적인 사용을 위해 코드를 작성하지 않고도 메모리 그래프를 조사, 쿼리 및 관리할 수 있는 CLI (Command Line Interface)가 제공됩니다.

두 번째 통합 경로는 MCP (Model Context Protocol) 서버 지원입니다. 이를 통해 Cursor와 같은 에디터를 포함하여 MCP 호환 클라이언트가 TokenMizer의 메모리를 도구 (tool)로 사용할 수 있습니다. 이는 의도적인 설계 결정이었습니다. 메모리가 하나의 앱에만 종속되어서는 안 되기 때문입니다. API를 직접 호출하든, CLI를 통해 스크립트를 작성하든, 혹은 AI 지원 에디터 내부에서 작업하든, 동일한 그래프가 그 모든 것의 배후에 존재합니다.

무엇이 고장 났으며, 수정 과정에서 무엇을 배웠는가

모든 API 호출을 가로채는 프록시 (proxy)를 구축하는 것은 신뢰성에 대한 요구치를 높입니다. 만약 TokenMizer가 실패하면, 사용자의 앱 내 LLM 호출도 함께 실패하기 때문입니다. 내부 감사 결과, 솔직하게 밝힐 가치가 있는 실제 문제들이 드러났습니다:

• 요청 처리 과정에서의 비동기 레이스 컨디션 (Async race conditions): 동시 호출이 메모리 상태를 순서에 어긋나게 읽거나 쓸 수 있는 문제.
• 12개 파일에서 반복된 조용한 충돌 패턴 (Silent crash patterns): 오류가 표면화되지 않고 조용히 실패하는 현상으로, 제 다른 프로젝트인 GitHub Autopilot에서 얻은 'fail-closed' 교훈과 맥락을 같이 합니다.
• 정규 표현식 (regex) 회귀: 리팩토링 이후 특정 입력 집합에 대해 개체 추출 (entity extraction) 기능이 작동하지 않는 문제.
• MCP 설치 프로그램의 데이터 파괴 버그: 설치 시 기존 메모리 데이터와 병합하는 대신 덮어쓰기가 발생할 수 있는 예외 상황.

확인된 9가지 이슈는 모두 수정 및 테스트를 완료했습니다. 특히 설치 프로그램 버그는 설치 스크립트를 바라보는 제 관점을 바꾸어 놓았습니다. 설치 시 사용자의 기존 데이터에 손을 대는 모든 작업은, 설령 확인 질문을 한 번 더 던지는 한이 있더라도 가장 안전한 동작을 기본값으로 설정해야 합니다.

Mem0나 Zep 대신 왜 이것을 만드는가

기존의 LLM용 메모리 레이어들은 대부분 잘 작동하지만, 대개 해당 서비스의 SDK와 저장 모델을 채택해야 한다는 것을 의미합니다. TokenMizer의 프록시 우선 (proxy-first) 설계는 모델 호출 방식을 재구조화할 필요 없이, 이미 사용 중인 도구들 아래에 위치할 수 있음을 의미합니다. 그래프 기반 검색 (graph-based retrieval) 또한 의도적인 선택입니다. 대화와 코드베이스가 성장함에 따라, 관계 기반 조회 (relationship-based lookup)는 평면적 검색 (flat retrieval)이 할 수 없는 방식으로 확장성을 제공합니다.

아직 초기 단계입니다. 이 프로젝트는 완성된 제품이 아니라 공개적으로 구축되고 있는 프로젝트입니다. 하지만 아키텍처는 이제 제대로 설명할 가치가 있을 만큼 충분히 안정적이며, 다른 개발자들이 자신의 워크플로우(workflow)에 적용해 볼 만한 가치가 있습니다.

_TokenMizer는 오픈 소스(open source)이며 pip로 설치할 수 있습니다. 코드, CLI 문서 및 Graph Explorer는 GitHub에서 확인할 수 있습니다: Shweta-Mishra-ai/tokenmizer.

저는 TechNova World에서 개발자 도구 및 AI 인프라 구축에 관한 글을 씁니다. 이와 같은 시스템을 구축하고 이를 팀이나 사용자에게 명확하게 설명할 수 있는 전문가가 필요하다면, 연락해 주세요.