---
title: "에이전트의 기억을 git diff로 읽는다, OKF Agent Memory"
original_title: "OKF Agent Memory: 벡터 DB 없이 Git 저장소의 마크다운으로 AI 코딩 에이전트 기억을 관리하는 도구"
source: "https://discuss.pytorch.kr/t/okf-agent-memory-db-git-ai/11884"
source_author: "PyTorchKR 9bow(박정환), 2026-09-13"
project_site: "https://okf-memory.dev/"
repository: "https://github.com/okf-memory/okf-agent-memory"
tool_license: "MIT"
curated_by: "다비(davi.kr) https://davi.kr/"
curated_at: "2026-09-14"
tags: [OKF_Agent_Memory, Open_Knowledge_Format, agent_memory, progressive_disclosure, BM25, MCP, Claude_Code, Cursor, Go]
---

원문 URL
- https://discuss.pytorch.kr/t/okf-agent-memory-db-git-ai/11884
- https://okf-memory.dev/
- https://github.com/okf-memory/okf-agent-memory
- https://github.com/okf-memory/okf-agent-memory/blob/main/docs/GETTING_STARTED.md

문서의 목적
PyTorchKR에 소개된 OKF Agent Memory를 중학생도 이해할 수 있는 말로 요약하고, 바로 써 볼 수 있는 절차와 도입 여부를 판단할 근거를 제공합니다. 원문의 주장은 GitHub 저장소 코드, 릴리스 노트, 공식 홈페이지로 교차 확인했습니다.

## 쉬운 설명

Claude Code나 Cursor 같은 AI 코딩 에이전트는 대화 창이 닫히면 그동안 정한 규칙과 결정을 잊습니다. 흔한 대책은 CLAUDE.md 같은 파일에 규칙을 계속 적어 두는 것인데, 이 파일은 갈수록 커지고 매 요청마다 통째로 AI에게 전달되어 토큰(AI가 읽는 글자 단위, 곧 비용)을 낭비합니다. 반대로 벡터 DB(문장을 숫자로 바꿔 저장하는 검색 전용 저장소)에 넣는 방식은 사람이 읽거나 검토할 수 없습니다.

OKF Agent Memory는 그 중간을 노립니다. 기억을 저장소 안 knowledge/ 폴더에 평범한 마크다운 파일로 저장하되, Google이 공개한 Open Knowledge Format(OKF) v0.2 규격을 따라 파일마다 출처와 신뢰 등급(AI 추측은 generated, 사람 확인은 verified)을 붙입니다. AI는 기억 전체 대신 질문과 관련된 개념 파일만 검색해 꺼내 쓰고(점진적 공개), 검색은 외부 API 없이 프로그램 안에서 BM25(단어 빈도로 관련 문서를 찾는 고전 검색 방식)로 처리합니다. 순수 Go로 만든 실행 파일 하나가 명령줄 도구이자 MCP 서버라서 Claude Code나 Cursor에 바로 연결됩니다. 개발팀 벤치마크에서 입력 토큰은 3,034개에서 603개로 약 80% 줄었고, 첫 글자가 나오기까지의 지연은 모델별로 1.1배에서 5.2배 빨라졌습니다. MIT 라이선스입니다.

## 활용 방법

가장 쉬운 경로는 실행 파일 하나를 설치하고 bootstrap 명령 한 번으로 프로젝트에 기억 구조를 깔아 두는 것입니다.

1. 설치하세요. macOS와 Linux는 `brew install okf-memory/tap/okf` 또는 `curl -fsSL https://okf-memory.dev/install.sh | sh`를 실행합니다. Go가 있으면 `go install github.com/okf-memory/okf-agent-memory/cmd/okf@v0.2.0`, 소스 빌드는 Go 1.22 이상에서 `make build`입니다. Windows는 릴리스 페이지의 바이너리 목록을 확인하거나 Go로 빌드하세요. 설치 후 `okf version`으로 확인합니다.
2. 프로젝트에 기억 구조를 설치하세요. 프로젝트 폴더에서 `okf bootstrap . --name "My Project"`를 실행하면 knowledge/ 번들, .agents/skills/okf-memory/ 스킬, AGENTS.md, Makefile이 생성됩니다. `okf validate knowledge --strict`로 형식을 검증하세요.
3. 에이전트에 연결하세요. Claude Code는 .claude.json(또는 claude_desktop_config.json)에 아래 설정을 추가합니다. Cursor와 Windsurf는 MCP 설정에서 type stdio, command okf, args mcp knowledge로 등록합니다. 연결되면 okf_search, okf_show, okf_create, okf_update, okf_relate, okf_validate 6개 도구가 에이전트에 노출됩니다.

```json
{
  "mcpServers": {
    "okf-memory": {
      "command": "okf",
      "args": ["mcp", "knowledge"]
    }
  }
}
```

4. 매 세션을 같은 루프로 돌리세요. 작업 전에는 `okf search "<키워드>" knowledge`로 기존 결정을 확인합니다. 작업 후 새 결정은 `okf create <id> knowledge --type Decision --title "..." --desc "..."`로 기록합니다. 세션을 닫기 전에는 `okf validate knowledge --strict --drift`를 실행합니다. 대화 로그가 아니라 아키텍처 결정, 스키마, 업무 규칙만 저장하세요.
5. 한국어 팀은 규칙을 하나 정하세요. 검색기가 영문자와 숫자만 인식하므로 개념의 ID, 제목, 태그는 영문으로 쓰고 본문만 한글로 작성하세요. 이 규칙 없이는 `okf search "인증 흐름"` 같은 한글 질의가 빈 결과를 돌려줍니다.
6. MCP 교육 자료로 활용하세요. 계정이나 API 키 없이 로컬 실행 파일 하나로 MCP 서버를 띄우고 도구 6개가 에이전트에 노출되는 과정을 보여줄 수 있어 MCP 개념 실습에 적합합니다.

## 전체 내용에 대한 전문가 의견(사실 기반)

### 강점(확인된 사실)
- 의존성이 없습니다. go.mod에 외부 require가 없고 결과물은 단일 실행 파일이라 별도 DB나 Python 런타임을 세울 필요가 없습니다.
- 기억이 저장소 안 마크다운이라 git diff, git blame, 풀 리퀘스트 리뷰가 그대로 적용됩니다. OKF v0.2 프런트매터의 sources, generated/verified, status, stale_after 항목이 출처와 신뢰 구분을 형식으로 강제합니다.
- 2026-09-12 v0.2.0에서 governance 3단계(constraint, hold, context), 개념과 코드 경로를 묶는 code_refs, 편집 전 관련 규칙을 조회하는 `okf search --for-path`가 추가됐습니다. code_refs의 경로 탈출(CWE-22) 검증도 포함됐습니다.
- 벤치마크 실행기가 저장소에 들어 있어 `make benchmark`로 자기 하드웨어와 모델에서 재현할 수 있습니다.
- MIT 라이선스이며, 2026-09-14 기준 GitHub 별 약 627개, 포크 44개입니다(조회 시점별 편차 있음).

### 한계와 주의점(확인된 사실)
- 한글 검색이 동작하지 않습니다. pkg/okf/search.go의 tokenize 함수는 a-z, A-Z, 0-9 이외의 문자를 모두 구분자로 버리고 한 글자 토큰도 제외합니다. 한글만으로 된 질의는 토큰이 0개라 nil을 반환하고, 한글 본문은 색인에 기여하지 않습니다. 원문의 지적을 코드로 직접 확인했습니다.
- BM25라고 부르지만 코드는 문서 길이 정규화(k1, b)가 없는 필드 가중 TF에 BM25식 IDF를 곱한 단순 점수이며 접두 일치(HasPrefix)를 포함합니다. 개념 수십 개 규모에서는 충분하지만, 동의어나 의미 유사도는 잡지 못하는 어휘 검색입니다.
- 벤치마크는 개발팀 자체 측정입니다. Apple M2 Pro 1대, 과제 1개, 11.5KB 문서 묶음 기준이며, 토큰 80% 절감은 문서 전체를 통째로 넣는 방식과의 비교입니다. 클라우드 API(gpt-5.6-sol)에서는 첫 토큰 지연이 9,227ms에서 8,682ms로 약 6% 줄어드는 데 그쳤고, 정책 준수 검사는 두 방식 모두 4/4로 같아 결과 품질이 좋아졌다는 근거는 없습니다.
- 마케팅 수치가 문서마다 다릅니다. v0.1.0 릴리스 노트는 "최대 94% 절감", v0.2.0과 홈페이지는 "80%"를 쓰고, 홈페이지 FAQ의 "6초 이상에서 50ms 미만으로" 문구는 공개 벤치마크 표(1.1~5.2배)와 맞지 않습니다. 홈페이지 비교표의 Mem0/Letta 지연 150~800ms 같은 수치는 개발팀 주장이며 독립 검증이 없습니다. "zero hallucinations" 문구도 근거 자료가 없습니다.
- 신생 프로젝트입니다. v0.1.0이 2026-09-05, v0.2.0이 2026-09-12에 나왔고 주 개발자 1인(sknr, Stephan Knauer)에 외부 기여자 소수가 참여하는 단계입니다. 개발은 develop 브랜치에서 진행되고 main은 태그 릴리스 전용입니다.
- OKF Cloud(다중 저장소 통합 검색, PR 거버넌스 봇) 베타 대기 신청을 받고 있어 상용화 로드맵이 있습니다. 오픈소스 CLI는 MIT지만 교차 저장소 기능은 클라우드 전용으로 예고돼 있습니다.
- Google OKF v0.2 규격을 따를 뿐 Google 공식 제품이 아닙니다(홈페이지 FAQ 명시). governance 3단계 설계는 MemContinuum(krakozavr) 프로젝트에서 착안했다고 릴리스 노트가 밝히고 있습니다.
- PyTorchKR 원문은 GPT 초안을 바탕으로 정리했다고 고지하고 있습니다. 이 문서는 명령 9개, MCP 도구 6개, 벤치마크 수치, 토크나이저 동작을 저장소 코드와 문서로 교차 확인했습니다.

### 도입 판단 기준
- 도입 권장: ADR(아키텍처 결정 기록)을 이미 저장소에서 관리하고 Claude Code, Cursor, Windsurf 중 하나를 쓰며, 개념 제목과 태그를 영문으로 쓰는 데 거부감이 없는 팀. 외부 DB 운영을 피하고 싶은 팀.
- 보류: 한글 위주 문서화 팀에서 영문 키 규칙을 세우기 어려운 경우. 자연어 질의나 동의어 검색이 필요한 경우. 저장소 여러 개를 한 번에 검색해야 하는 경우(OKF Cloud 예고 단계).
- 배제: 세션 대화 자체를 자동으로 요약해 쌓으려는 목적. 이 도구는 사람이 골라 기록하는 결정 기록용이며, 자동 세션 기록은 Magic Context 같은 다른 계열의 도구가 맡습니다.

### 관련 항목
- 트렌드 T 기존 항목 "Magic Context: 압축이 곧 기억이 되는 코딩 에이전트 메모리 플러그인"(2026-08-18)은 호스트의 컨텍스트 압축 과정에서 자동으로 기억을 만드는 접근이라, 사람이 결정을 골라 기록하는 OKF Agent Memory와 반대 방향입니다.
- 원문이 언급한 인접 프로젝트: OptMem(로그와 이진 트리 기반), memsearch(다중 에이전트 공유 기억), MegaMemory, lat.md(Agent Lattice), llm-wiki(Karpathy 방법론).

## Bottom Line

ADR을 이미 저장소에서 관리하고 Claude Code나 Cursor를 쓰는 팀이라면 실행 파일 하나와 `okf bootstrap` 한 번으로 오늘 시험할 수 있습니다. 벤치마크 수치는 참고만 하고 `make benchmark`로 자기 환경에서 다시 재보십시오. 한국어 팀은 ID, 제목, 태그를 영문으로 쓰는 규칙 한 줄만 먼저 정하십시오. 지금 당장 시작하십시오.

## 검증 현황과 자체 평가

- 직접 확인: PyTorchKR 원문, GitHub README, GETTING_STARTED.md, pkg/okf/search.go 소스, v0.1.0과 v0.2.0 릴리스 노트, okf-memory.dev 홈페이지와 FAQ.
- 확인하지 못한 것: benchmarks/results/의 원본 로그 파일 내용(원문과 홈페이지의 표로만 확인), go.mod 파일 자체(원문과 README의 "zero external dependencies" 서술로 확인), Windows 공식 바이너리 제공 여부.
- 자체 평가: 92/100. 감점 사유는 벤치마크 원본 로그 미열람(-4), GitHub 별 수치가 캐시 편차로 확정 불가(-2), Windows 설치 경로 미확인(-2).

정리: 다비(davi.kr) https://davi.kr/