AI 코딩 에이전트를 쓰다 보면 매번 같은 벽에 부딪힌다. 대화 세션이 끝나거나 컨텍스트 창이 가득 차면 그동안 쌓은 맥락이 사라진다. 아키텍처를 왜 이렇게 설계했는지, 특정 도메인 규칙이 무엇인지, 운영상 주의할 점이 무엇인지 같은 값진 판단들이 세션과 함께 증발한다. 다음 세션에서 에이전트는 다시 백지 상태로 돌아가고, 사람은 같은 설명을 반복해야 한다. OKF Agent Memory는 바로 이 문제를 겨냥해 만들어진 지속 메모리 계층으로, 구글이 제안한 Open Knowledge Format(OKF) v0.2 명세를 구현한 오픈소스 프로젝트다.
마크다운과 벡터 DB 사이의 빈자리
지금까지 에이전트의 기억을 다루는 방식은 크게 두 갈래였다. 하나는 CLAUDE.md나 AGENTS.md 같은 자유 형식 마크다운 파일에 규칙을 적어두는 방법이다. 단순하지만 구조가 없어 규모가 커지면 관리가 어렵고, 필요 없는 내용까지 통째로 프롬프트에 밀어 넣게 된다. 다른 하나는 벡터 데이터베이스에 임베딩을 저장하는 방법이다. 검색은 유연하지만 별도 인프라가 필요하고 내부 동작이 불투명한 블랙박스가 되기 쉽다. OKF Agent Memory는 이 두 극단 사이를 메우겠다는 위치 설정을 분명히 한다.
구조는 의외로 단순하다. 지식은 저장소 안의 knowledge/ 디렉터리에 YAML 프런트매터가 붙은 평범한 마크다운 파일로 쌓인다. 즉 기억이 코드와 같은 깃 저장소 안에 텍스트로 존재한다. 이 방식의 장점은 실무자에게 직관적이다. 기억의 변경 이력이 깃 커밋으로 남아 누가 언제 어떤 사실을 추가·수정했는지 추적할 수 있고, 코드 리뷰와 동일한 흐름으로 지식을 검토할 수 있다. 특정 벤더나 에이전트 플랫폼에 묶이지 않는 벤더 중립성도 이 텍스트 기반 설계에서 나온다.
성능을 앞세운 설계
기술적으로 이 프로젝트가 강조하는 지점은 속도와 토큰 절감이다. 구현은 외부 의존성이 없는 Go로 작성됐고, 에이전트가 도구를 빠르게 반복 호출하는 루프를 견디도록 설계됐다고 설명한다. 검색은 벡터 대신 인메모리 BM25 방식을 쓰며 300마이크로초 미만의 응답을 표방한다. BM25는 키워드 기반 랭킹 알고리즘으로, 임베딩 모델을 돌릴 필요가 없어 가볍고 결과를 예측하기 쉽다는 특성이 있다. 여기에 필요한 정보만 단계적으로 꺼내 보여주는 프로그레시브 디스클로저(progressive disclosure)를 결합해 토큰 사용량을 80%까지 줄인다고 주장한다.
이 수치들은 검증 수단과 함께 제시된다는 점이 눈에 띈다. 프로젝트는 순수 Go로 작성된 자동 벤치마크 러너를 제공해, 사용자가 자기 하드웨어에서 첫 토큰까지의 시간(TTFT) 개선과 토큰 절감폭을 직접 재현하도록 한다. LM Studio나 Ollama에서 Gemma, Qwen, Llama 같은 로컬 LLM을 물려 make benchmark로 돌려볼 수 있다. 성능 주장을 광고로만 남기지 않고 재현 가능한 형태로 내놓았다는 점은, 도입을 검토하는 팀 입장에서 신뢰를 가늠할 근거가 된다.
실무 도입의 접점과 한계
연동 측면에서는 Model Context Protocol(MCP) 서버를 stdio 위에서 기본 탑재한다. 이를 통해 Claude Code, Cursor, Codex 등 MCP를 지원하는 에이전트 플랫폼과 붙일 수 있다. 사용 흐름도 단순하다. 저장소를 클론해 컴파일하면 bin/okf라는 독립 실행 파일이 나오고, 이 명령 하나로 새 저장소든 기존 저장소든 OKF 메모리 구조를 스캐폴딩할 수 있다. 별도 서비스를 띄우거나 계정을 만들 필요 없이 바이너리와 파일만으로 동작한다는 점은 로컬·온프레미스 환경을 중시하는 팀에 매력적이다.
다만 냉정하게 볼 지점도 있다. BM25는 키워드 매칭에 강하지만 의미 기반 검색에서는 벡터 방식보다 불리할 수 있어, 기억의 표현과 질의 어휘가 어긋나면 원하는 항목을 놓칠 여지가 있다. 80% 토큰 절감이나 마이크로초 단위 검색 같은 수치도 지식 규모, 질의 패턴, 로컬 모델 종류에 따라 달라지므로 자사 환경에서 직접 벤치마크를 돌려보는 편이 안전하다. 또한 기억을 저장소에 텍스트로 남기는 방식은 투명성과 이력 관리의 장점이 있는 반면, 민감한 도메인 지식이 코드 저장소에 그대로 커밋된다는 뜻이기도 하므로 접근 권한과 공개 범위를 함께 고려해야 한다. 그럼에도 에이전트의 기억을 익숙한 깃 워크플로 안으로 끌어들였다는 발상 자체는, 늘어나는 AI 코딩 도구를 팀 차원에서 길들이려는 이들에게 검토할 만한 선택지다.