원문 캡처 · github.com
원문 캡처 · github.com

Mnemonic Proxy는 코딩 에이전트와 로컬 모델 사이에서 대화 기록을 관리하는 HTTP 프록시다. 에이전트가 보내는 전체 기록은 디스크에 원문 그대로 보관하고, 오래된 내용을 모델의 프롬프트에서 가린 뒤 필요할 때 recall 도구로 찾아 돌려준다. 제작자 측 AgentLongBench 실험에서 32K 창으로 100문제 중 86문제를 맞혀, 같은 모델이 만든 요약을 넣었을 때의 47문제와 전체 기록을 더 큰 창에 넣었을 때의 69문제를 앞섰다. 다만 한 모델·엔진·시드와 100문제에 한정된 단일 실험이다.

  • 대상: OpenAI 호환 엔진을 쓰는 코딩 에이전트. OpenAI Chat Completions, Anthropic Messages, OpenAI Responses를 지원한다.
  • 조건: Python 3.10 이상, 엔진 창 최소 16K 토큰이며 32K 이상을 권장한다. 모델이 저장 상태를 지원하지 않아도 기본 기능은 쓸 수 있지만, 대화 상태를 디스크에 저장하고 복원하는 기능은 지원 엔진에서만 가능하다.
  • 설치 전 에이전트 자체의 자동 요약·압축 기능을 꺼야 한다. 두 기록 관리 기능이 동시에 작동하면 같은 대화를 따로 줄일 수 있다.

설치자는 가상 환경에서 pip install mnemonic-proxy를 실행한 뒤 mnemonic-proxy demo로 모델 없이 아카이브·마스킹·회수 동작을 확인할 수 있다. 데모는 긴 로그에서 값을 가린 뒤 요청이 오면 원문과 바이트 단위로 비교하며, 성공하면 PASS를 출력한다. 이는 프록시 자체의 로직만 확인하며 실제 모델의 도구 호출이나 엔진 상태 저장을 검증하지 않는다.

실제 엔진 연결 전에는 다음처럼 점검하고 프록시를 시작한다. 여기서 --upstream은 엔진 주소이며, 점검이 READY와 종료 코드 0을 반환해야 한다. --live를 추가하면 실제 생성, 도구 호출, 저장·복원까지 확인한다. 이후 에이전트의 주소를 엔진 대신 프록시 포트로 바꾼다.

text
mnemonic-proxy check --upstream http://127.0.0.1:8095 --port 8096 --data ./data --config config.json
mnemonic-proxy --upstream http://127.0.0.1:8095 --port 8096 --data ./data --config config.json

엔진에 따라 설정이 다르다. llama-server는 최소 16K, 권장 32K 이상의 창으로 시작하고 저장 기능을 쓰려면 --slot-save-path를 지정한다. 예를 들어 llama-server -m model.gguf -c 32768 --parallel 1 --jinja --slot-save-path ./slots --port 8095로 실행할 수 있다. 설정의 slot_dir은 같은 저장 폴더를 가리켜야 한다. Strata는 저장 상태 기능에 0.1.40 이상과 --slot-save-path DIR이 필요하다. ds4-server는 자체적으로 KV 상태를 관리하므로 프록시가 별도로 저장하지 않는다. Ollama·LM Studio는 엔진 창을 32768로 설정하는 것을 권하며, 프록시가 실행 중인 모델의 창을 읽는다. 다른 호환 엔진은 창을 자동으로 읽지 못할 수 있으므로 설정에 실제 창 크기를 적어야 한다. 엔진 창이 16384보다 작거나 설정 창이 실제 엔진 창보다 크면 시작을 거부한다.

Ollama와 LM Studio의 기본 창은 테스트 환경에서 각각 4096, 8192였다. 이 상태에서 두 엔진은 긴 입력 일부를 알리지 않고 버린 채 HTTP 200을 반환했다. Ollama는 오래된 메시지를, LM Studio는 가운데 내용을 버렸다. 32K로 설정한 0.3.8 테스트에서는 프록시가 29,473토큰을 보내고 엔진이 전부 읽었으며, 12개 파일을 다루는 대화에서 21개 요청이 모두 200, 유효한 도구 호출 19건, 회수 1건, 잘린 입력 0건으로 기록됐다. 이는 특정 Linux 환경과 테스트 조합의 결과다.

프록시는 오래된 도구 출력과 추론을 요약하지 않고 일정한 블록으로 가린 뒤 한 줄짜리 식별 영수증으로 바꾼다. 원문은 중복 제거된 아카이브에 저장하며, recall은 파일의 최초 내용과 수정 이력, 명령과 출력 등을 찾아 메시지 번호와 구간 정보를 붙여 반환한다. 이 호출은 프록시가 처리해 클라이언트에는 보이지 않는다. 가린 기록도 감당하기 어려워지면 모델이 다음 구간을 위한 메모를 작성하고 새 구간을 시작한다. !! 또는 📌로 표시한 줄은 구간이 바뀌어도 유지되고, 🗑 또는 ~로 시작하는 줄은 답변 뒤 버릴 수 있다. 도구 정의는 필요한 때 이름으로 불러오도록 줄이며, 제작자 측 예시에서는 요청당 25.6K에서 6.2K 토큰으로 감소했다.

지원 엔진에서는 KV 상태를 디스크에 저장해 재시작 뒤 대화를 처음부터 다시 읽지 않고 이어갈 수 있다. 제작자 측 12GB RTX 4070 Ti 세션에서는 3시간 15분 동안 430개 요청에 오류가 없었고, 기록 448K 토큰 중 프롬프트에 들어간 최대치는 105K였다. 110K 토큰 대화 복원은 1.4초였으며, 다시 읽는 데는 약 50초가 걸렸다. 이 수치는 단일 하드웨어와 실행에서 나온 결과다. 저장 상태가 없는 온라인 API나 vLLM 같은 엔진은 기본 모드로 동작하며 저장·복원은 제공하지 않는다.

벤치마크와 검증 범위

AgentLongBench 실험은 Qwen3.8 Flash Next IQ3_XXS, Strata 0.1.40, RTX 4070 Ti 12GB, 시드 1로 진행했다. 64K 기록과 128K 기록에서 각각 50문항을 냈다. 전체 창 방식은 69/100, 프록시는 86/100, 같은 모델이 작성한 최대 2,048토큰 요약은 47/100, 단순 절단은 49/100이었다. 프록시와 요약을 비교한 100문항에서는 프록시만 맞힌 문제가 44개, 요약만 맞힌 문제가 5개였고, 정확 McNemar 검정의 p값은 7.6e-9였다. 질문을 명확히 고친 뒤 얻은 결과이며, 처음의 모호한 질문에서는 각 방식의 점수가 51·52·56·44로 우연 수준에 가까웠다. 프록시 처리 시간은 문항당 중앙값 136초(64K), 286초(128K)로, 전체 창 방식의 70초와 102초보다 길었다. 전체 기록을 프록시를 거쳐 다시 전달하는 시간이 주된 이유였다.

회수 검색 시험은 과거 세션에 관한 71개 질문으로 진행했다. 증거를 5회 이내에 찾은 비율은 키워드 검색 90%, 구조화된 회수 100%였고 질문당 반환 토큰은 각각 5,940과 2,737이었다. 아카이브에 답이 없는 경우를 알아맞힌 결과는 1/4와 4/4였다. 개발 과정에서 이 시험을 사용했으므로 독립적인 성능 점수로 볼 수 없으며, 시험 자료는 비공개 세션 기록이다.

실제 모델을 사용한 CPU 안내는 Ubuntu 24.04 컨테이너에서 Qwen3-4B-Instruct-2507 Q4_K_M과 llama.cpp b11430, pi 1.0.3으로 시험했다. 4B 모델은 CPU에서 느리고 실제 작업용이 아니라 기능 확인용이라고 명시한다. 32K 시험에서 마스킹과 엔진 재시작 뒤 복원은 작동했지만, 모델은 가린 로그의 값을 묻는 단계에서 recall을 호출하지 않고 모른다고 답했다. 8K 시험에서도 회수를 안정적으로 쓰지 못했다. 현재 프록시는 16K 미만 창을 거부하며, 작은 창에서 회수가 통과한 시험은 한 차례뿐이라 더 많은 반복 검증 전까지 지원 범위에서 제외했다.

또한 모델이 448K 기록 전체를 한꺼번에 읽는 것은 아니다. 모델은 한 번에 엔진 창 안의 내용만 보며 나머지는 회수할 수 있을 뿐이다. 제작자 측 한계 공개에는 3시간 세션의 첫 시간에 관한 질문 6개 중 4개는 정확했고 2개는 일부만 맞았다는 결과, 구간 전환에 12GB GPU에서 약 2분이 든다는 내용이 포함된다. 검색은 의미 검색이 아니라 FTS5와 구조를 이용한 어휘 검색이라 공통 단어가 없는 바꿔 말하기는 놓칠 수 있다. 수치는 대체로 한 기기·한 종류의 작업에서 한 번씩 측정했으므로 참고값으로 봐야 한다.

보안과 자료

아카이브는 평문 SQLite 데이터베이스다. 에이전트가 본 파일 내용, 명령 출력, 추론과 비밀 정보가 data/archive.sqlite에 저장되고, data/journal.jsonl에는 요청 정보와 회수 검색어가 남는다. live_dump를 켜면 마지막 전체 프롬프트도 저장된다. 프록시는 기본적으로 127.0.0.1에 인증 없이 바인딩하므로 공유 네트워크에 노출하지 말아야 한다. 제작자는 data와 엔진 상태 폴더의 접근 권한을 제한하도록 안내한다. 삭제 명령은 아직 없으며, 대화 삭제에는 데이터베이스 행·상태 파일·아카이브 색인 등을 직접 정리해야 한다.

프로젝트 설치, 엔진별 설정, 에이전트 연결 절차와 시험 보고서는 Mnemonic Proxy 저장소에서 확인할 수 있다. 제작자는 Maurizio Verde(LastReload)이며 MIT 라이선스로 공개했다. 프로젝트는 Strata와 호환되지만 Strata의 일부가 아니고, llama-server·ds4-server 및 다른 OpenAI 호환 백엔드도 지원한다.