OKF Agent Memory – AI 코딩 에이전트를 위한 Git 기반 영구 메모리

Who Should Read

CLAUDE.md·AGENTS.md가 계속 비대해져 에이전트가 지시를 놓쳐 고민인 코딩 에이전트 사용 개발자

Core Mechanics

• 메모리를 두 층으로 나눈다
  • 항상 로드하는 Push 층은 AGENTS.md에 400토큰 이내 규칙만 둔다.
  • 필요할 때만 꺼내는 Pull 층은 knowledge/ 폴더로 시스템 프롬프트 기본 토큰이 0이다.
• 기존 방식의 두 가지 실패를 지적한다
  • AGENTS.md/CLAUDE.md에 다 넣으면 컨텍스트가 부풀고 에이전트가 중요한 지시를 무시한다고 한다.
  • 규칙을 벡터 DB에 넣으면 에이전트가 포맷·보안 같은 제약을 의미 검색하지 않아 놓친다고 한다.
• 벡터 대신 메모리 내 BM25 검색
  • BM25는 키워드 기반 순위 검색으로, 임베딩 API와 외부 DB 없이 돈다.
  • README 표 기준 검색 지연은 300µs 미만이고 Mem0·Letta류는 150~800ms로 적혀 있다.
• Go 단일 바이너리에 MCP 서버 내장
  • okf mcp knowledge로 stdio MCP 서버를 띄워 Claude Code, Cursor 등에 연결한다.
  • 도구는 okf_search, okf_show, okf_create, okf_validate가 있다.
• 메모리는 전부 Git 관리 마크다운
  • knowledge/ 아래 OKF v0.2 형식 문서라서 git diff, git blame, 코드 리뷰로 검토한다.
  • 출처, 신뢰 등급(verified/generated), stale_after 같은 수명 메타데이터를 지원한다.

Community Reactions

• 벤치마크가 지연 시간뿐이라는 비판
  • 정확도(recall/precision) 없이 지연만 재는 건 LLM 호출 맥락에서 의미가 작다는 의견이 있었다.
  • 저장·검색 품질 벤치마크가 있는지 묻는 댓글도 따로 있었다.
• MCP 서버가 꼭 필요한가라는 의문
  • 스펙이 이렇게 단순한데 왜 MCP 서버가 필요하냐는 질문이 나왔다.
  • Codex처럼 내장 메모리 도구가 있는 환경에서 OKF를 따르게 할 수 있는지 궁금해하는 댓글도 있었다.
• 메모리 자체가 부담이라는 의견
  • 메모리는 skills처럼 컨텍스트를 낭비하므로 사람이 쓴 md 몇 개로 충분하다는 의견이 있었다.
• 엔터프라이즈 적용은 따로 시험해야 한다는 의견
  • 계획 세션과 구현 세션을 분리해 쓰는데 도메인 지식을 잘 유지하면 단위 기능 구현이 매끄러울 것이라는 기대가 있었다.
  • 실무 적용 위험이 있어 개인 프로젝트에서 먼저 시험하겠다고 했다.

How to Apply

• 지금 프로젝트의 AGENTS.md 용량부터 재기
  • 오늘 CLAUDE.md/AGENTS.md의 토큰 수를 세고 400토큰 넘는 부분을 표시하라.
  • 항상 지켜야 할 규칙과 가끔 찾아볼 지식으로 나눠라.
• 빈 프로젝트에 okf 설치해 부트스트랩 돌려보기
  • brew install okf-memory/tap/okf 후 okf bootstrap .을 실행하라.
  • 생성된 knowledge/와 AGENTS.md를 git diff로 확인하라.
• MCP 서버를 에이전트에 연결하기
  • Claude Code나 Cursor 설정에 command를 okf, args를 ["mcp", "프로젝트/knowledge"]로 등록하라.
  • 작업 전 okf_search를 부르는지 로그로 확인하라.
• 수정 전 제약 조회를 워크플로에 넣기
  • 중요한 결정 문서에 code_refs를 달아라.
  • 파일 수정 전에 okf search --for-path 경로 knowledge를 실행하게 하라.

Try It

# Claude Code나 ChatGPT에 붙여넣기 (OKF Agent Memory 방식의 간이 버전)

너는 코딩 에이전트다. 아래 AGENTS.md를 두 층으로 나눠라.

1) Push 층: 항상 지켜야 할 불변 규칙만 400토큰 이내로 압축한다.
2) Pull 층: 나머지는 주제별 마크다운 개념 문서로 쪼갠다. 각 문서는 제목, 한 줄 설명, 태그, 300토큰 이내 본문을 가진다. 그리고 index.md에 문서 목록과 한 줄 설명을 만든다.

[AGENTS.md]
{{AGENTS.md 내용}}

이어서 해 볼 것: 새 작업 {{작업 설명}}을 줄 때, 먼저 index.md만 읽고 필요한 개념 문서만 골라 쓰게 해 보라.

Terminology

관련 논문

• 같은 시뮬레이션, 다른 근거: 도구 출력을 파일로 넘기면 LLM 에이전트 정확도가 어디서 깎이나

  긴 툴 출력을 파일로 넘기자 GPT-5.1은 정확도 11.3%p 하락, 정식 출력 지정하니 회복

• 가짜 뉴스가 진짜 폭락을: LLM 트레이딩 에이전트 대상 정보 주입 공격

  가짜 헤드라인 한 줄로 LLM 트레이딩 에이전트 62%를 조종했다(프롬프트 주입은 14%)

• Harness Engineering 101: LLM은 뇌, harness는 몸

  에이전트는 JSON 배열을 관리하는 루프이고, 16개 챕터로 직접 만들어 본다

• Harness²: 에이전트 harness를 스스로 고쳐 쓰는 재귀 최적화 프레임워크

  모델은 고정하고 harness를 재귀로 고쳤더니 벤치마크 점수가 최대 11.8%p 올랐다

• 해고된 Savannah 경찰관, ICE 요원 남편에게 Flock 계정 공유

  경찰관이 Flock 계정을 남편(ICE 요원)에게 공유했고, 감사에서 983건 검색이 드러나 해고됐다

• tmux와 Claude Code: 세션, send-keys, 그리고 한계선

  tmux로 Claude Code 여러 개를 돌리면 편하지만 에이전트 4개쯤에서 한계가 온다

• Hybrid Reasoning Agents: 잠재 공간에서 생각하고 텍스트로 행동하는 LLM 에이전트

  잠재 공간 추론과 텍스트 도구 호출을 섞었더니 성능 10.4%↑, 토큰 최대 54.7%↓

Related Resources

• https://github.com/okf-memory/okf-agent-memory
• https://okf-memory.dev
• https://github.com/oak-invest/kiso
• https://github.com/fellowgeek/mcp-memory
• https://github.com/scaccogatto/okf-skills
• https://github.com/ucsandman/declick