에이전트 메모리는 파일로 간다 — Karpathy의 LLM 위키에서 Google OKF 0.2까지, 사양에 있는 것과 없는 것

1. 핵심 요약

용어를 정합니다. 프런트매터(frontmatter)는 마크다운 파일 맨 위에 ---로 감싼 YAML 메타데이터 블록입니다. 번들(bundle)은 OKF 파일이 든 디렉터리 트리이며, git 저장소나 압축 파일로 배포합니다. 생산자(producer)는 파일을 쓰는 쪽(사람·에이전트·내보내기 파이프라인), 소비자(consumer)는 파일을 읽는 쪽(에이전트·UI·검색 색인)을 가리키는 사양의 용어입니다. 개념(concept)은 파일 하나가 설명하는 단위로, 테이블·지표·API·플레이북·런북 무엇이든 될 수 있습니다. LLM 위키는 Karpathy가 이름 붙인 패턴으로, 에이전트가 원본 자료를 읽고 상호 연결된 마크다운 페이지를 스스로 만들고 고쳐 나가는 방식입니다. 벡터 검색은 문장을 숫자 벡터로 바꿔 의미가 비슷한 것을 찾는 방식이고, BM25는 단어 일치 기반의 전통적인 전문 검색 점수입니다.

이 글의 사양 인용은 GoogleCloudPlatform/open-knowledge-format 저장소의 SPEC.md(v0.2) 원문이며, 도구의 성능 수치는 각 저장소 README의 주장입니다. 별 수는 2026-09-21 GitHub API 값입니다.

2. 여섯 달의 흐름 — gist에서 사양, 도구까지

세 갈래가 같은 방향을 가리킵니다. Karpathy는 에이전트가 위키를 직접 작성하는 운영 방식을 제안했고, Google Cloud는 그 위키를 파일로 표현하는 규약을 정했으며, 독립 개발자들은 그 규약에 검색 기능과 MCP 서버를 붙였습니다. 이 블로그가 6월에 정리한 GBrain은 이 중 세 번째 층, 즉 제품 층에 해당합니다. 이 글은 그 아래의 형식 층을 다룹니다.

3. OKF 사양이 실제로 정한 것 — 필수 필드는 하나

사양 첫 문단이 성격을 요약합니다. "형식은 의도적으로 최소입니다. YAML 프런트매터가 붙은 마크다운 파일의 디렉터리입니다. 스키마 레지스트리도, 중앙 권위도, 필수 도구도 없습니다. cat할 수 있으면 읽을 수 있고, git clone할 수 있으면 배포할 수 있습니다" [1].

표의 마지막 두 줄이 핵심입니다. 적합성 규칙은 거의 전부 "거부하지 말라"이고, 사양이 다루지 않는 항목에는 검색과 제공 방식이 포함됩니다. OKF는 읽고 쓰는 쪽이 지켜야 할 최소 규약이지, 기억을 꺼내는 방법이 아닙니다. 그래서 같은 번들을 Obsidian으로 보든, ripgrep으로 찾든, 임베딩 색인을 얹든 사양 위반이 아닙니다. 발표 글의 예시는 데이터 카탈로그입니다. sales/ 아래 datasets/, tables/, metrics/ 디렉터리에 개념 파일을 두고 [customers](/tables/customers.md)처럼 잇습니다 [2]. 코딩 에이전트의 프로젝트 메모리에 같은 틀을 쓰는 것은 사양이 아니라 도구들의 선택입니다.

4. v0.2의 다섯 가지 신뢰 신호와 3단계 신뢰 등급

v0.2의 동기는 사양 §1에 있습니다. "지식 말뭉치는 점점 에이전트가 계속 쓰고 유지합니다. 대부분의 개념이 기계 생성일 때, 파일을 읽는 쪽은 마크다운 본문과 프런트매터만으로는 판단하기 어려운 질문을 마주하게 됩니다. 무엇으로부터 만들어졌고 어떻게 검증됐는가, 얼마나 믿을 수 있는가, 아직 사실인가, 현재 버전인가, 그 숫자는 정해진 방식으로 계산됐는가" [1]. 발표 글은 이 다섯 질문에 답하는 장치를 다섯 가지 신뢰 신호라고 부릅니다 [3]. 출처(Provenance), 신뢰(Trust & Verification), 유효기한(Freshness), 수명(Lifecycle), 증명(Attested Computations)입니다. 앞의 넷은 프런트매터 필드이고, 마지막 하나는 새 개념 타입입니다.

출처 [1] §5·§10·§13, [3]. 행 이름은 사양 §1의 다섯 질문, 괄호는 발표 글의 분류를 따랐습니다.

신뢰 등급은 verified에서 유도합니다. 키가 없으면 미검증, human:이 아닌 주체만 확인했으면 기계 확인, human:<id>가 확인했으면 사람 검토입니다. 사양은 이것이 "접근 제어가 아니라 권고 신호"라고 못 박지만, 발표 글은 쓰임새를 이렇게 적었습니다. "경영진 대시보드에는 사람이 검토한 지표만 올려라"를 프런트매터 필터 하나로 표현할 수 있다 [3]. 이 블로그가 이틀 전 정리한 에이전트의 "검토 완료" 과장과 맞닿는 지점입니다. 에이전트가 쓴 문서에 사람의 확인 기록이 별도 필드로 남으면, "에이전트가 확인했다고 말한 것"과 "사람이 확인한 것"이 파일 수준에서 갈립니다.

호환성은 명시적입니다. "v0.1 번들은 바꾸지 않아도 그대로 들어간다." 이름이 바뀐 것은 둘뿐이고(timestamp → generated.at, # Citations → sources), v0.2 소비자는 옛 형태로 대체 읽기를 해도 됩니다 [1][3].

5. 세 접근의 차이 — LLM 위키, memoryfield, OKF

"파일로 기억한다"는 같은 문장 아래 세 제안은 서로 다른 층을 다룹니다.

출처 [4][5][1]. memoryfield의 수치는 에세이에 적힌 값이고, 에세이는 OKF를 언급하지 않습니다.

Paterson의 에세이가 기존 메모리 시스템을 비판하는 지점은 셋입니다. 플랫폼 사업으로 가면서 생기는 종속, pgvector·Neo4j·전용 모델이 필요한 복잡성, 그리고 지식 그래프를 걸어가며 여러 번 도구를 부르는 느림입니다. 그가 내놓은 답은 "마크다운에 간단한 임베딩" 하나입니다 [5]. HN에서 가장 많이 나온 반응은 그것을 한 줄로 줄인 것이었습니다. "'그냥 텍스트를 써라'를 길게 말한 글"(thm), "AI 진보의 절반은 '모델에게 영어로 알려 주기'를 다르게 말하는 방법 찾기"(andyfilms1). 반대편에는 "자동으로 관리되는 메모리가 늘 문제였다. 하네스가 관리하는 메모리는 쓸모없다"(JohnMakin)처럼 누가 기억을 쓰느냐를 문제 삼는 의견과, 잘못된 과거 탐색이 의미 검색에서 높게 뜬다는 품질 우려가 있었습니다 [7].

6. 도구와 그 주장 — 검증된 것은 아직 없습니다

출처 [8][6][1]. 별 수는 2026-09-21 GitHub API. 두 도구 모두 2026-08~09에 만들어져 운영 이력이 한 달 남짓입니다.

OKF Agent Memory의 HN 토론에서 값진 것은 도구의 수치가 아니라 검색 방식 논쟁이었습니다. 한 사용자(vshulcz)는 개인 말뭉치에서 BM25가 61%, 의미 검색이 37%의 성공률을 보였다며 "진짜 절벽은 재순위화와 낡음이다. 벡터 검색에는 '대체된 정보'라는 개념이 없다"고 적었습니다. 다른 사용자(langs)는 "아무도 근처에도 못 간 문제는 유지와 출처다. 무엇을 기억에 넣고, 무엇이 참이며, 낡은 기억을 어떻게 무효화하는가"라고 했습니다 [10]. 둘 다 한 사람의 경험담이지만, 두 번째 지적은 정확히 v0.2가 필드로 만든 것입니다. 형식이 답을 주지는 않지만 답을 적을 자리는 생겼습니다.

채택 신호는 아직 주변부입니다. GitBook은 "이미 그렇게 동작한다"며 자사를 "OKF-ready"로 표현했지만 내보내기 기능을 명시하지는 않았습니다 [11]. 그 밖에는 위키 도구(nexwiki)의 v0.2 지원 PR, 정적 발행 엔진(Kiso), Obsidian류 플러그인이 HN에 몇 점씩 올라온 정도입니다. 이 글 작성 시점에 OKF를 메모리 형식으로 채택했다고 밝힌 주요 에이전트 프레임워크나 코딩 에이전트는 확인하지 못했습니다.

7. 오늘 적용할 체크리스트

아래는 사양과 세 제안에서 이 글이 끌어낸 운영 권고입니다. 어느 항목도 통제된 측정으로 효과가 검증된 것은 아닙니다.

• 메모리를 폴더로 시작합니다. 프로젝트 안에 knowledge/ 같은 디렉터리를 두고, 파일마다 프런트매터에 type을 적습니다. 이것만으로 OKF 적합 번들이며, OKF를 읽는 도구라면 거부하지 않아야 합니다. 도구마다 추가 규약은 있을 수 있습니다.
• 에이전트가 쓴 파일에는 generated를, 사람이 확인한 파일에는 verified를 적습니다. 둘을 분리하는 것이 v0.2의 핵심입니다. 에이전트 프롬프트에 "새 개념 파일을 만들 때 generated: { by: <agent/version>, at: <ISO 8601> }를 넣고 verified는 비워 두라"고 지시하면, 사람 검토 여부가 파일에 남습니다.
• 낡을 것이 뻔한 사실에는 stale_after를 절대 시각으로 적습니다. 가격, 모델명, API 한도가 그렇습니다. 소비 쪽에서는 now >= stale_after인 파일을 컨텍스트에 넣기 전에 경고합니다.
• index.md로 점진적 공개를 합니다. 디렉터리마다 한 줄 설명이 달린 목록을 두면, 프롬프트와 도구가 전체를 읽지 않고 필요한 파일만 열도록 만들기 쉬워집니다. Karpathy의 스키마 파일(CLAUDE.md·AGENTS.md)에는 이 목록을 어떻게 쓰는지만 적습니다.
• lint를 정기 작업으로 둡니다. 모순·낡은 주장·끊긴 링크를 에이전트가 점검하게 하고, 결과를 log.md에 날짜순으로 기록합니다. 형식은 낡은 기억을 표시할 자리만 주고, 실제로 찾아내는 것은 이 작업이며, 무효화 여부는 별도의 정책으로 정해 적용해야 합니다.
• 검색은 색인이지 원본이 아닙니다. BM25든 임베딩이든 파일에서 다시 만들 수 있는 것으로 두고, 파일을 git에 넣습니다. 도구를 바꿔도 기억은 남습니다.
• "토큰 80% 절감" 같은 수치는 자기 저장소에서 잽니다. 같은 작업을 폴더 없이, 폴더만, 폴더 + 검색 도구로 돌려 입력 토큰과 결과를 비교합니다. 이 글이 읽은 어떤 자료에도 그 비교는 없습니다.
• 사람이 검토한 것만 쓰는 경로를 하나 만듭니다. 배포 판단, 고객 응대처럼 오류 비용이 큰 업무에는 verified에 human:이 있는 파일만 넣습니다. 발표 글이 든 대시보드 예시와 같은 구조입니다.

8. 아직 결론이 아닌 것

• 자체 실측이 없습니다. 이 글은 사양·발표 글·gist·에세이·저장소 README와 HN 토론을 대조한 정리입니다. 파일 기반 메모리가 벡터 DB 기반보다 낫다는 통제된 비교는 이 글이 읽은 자료 어디에도 없습니다.
• OKF는 0.2입니다. 사양 스스로 "출발점이지 완성된 표준이 아니다"라고 했고, 실행 프로토콜·증명자 ABI·샌드박싱·캐싱·의미 계층 템플릿을 "고려했으나 미룸"으로 남겼습니다. 1.0 전에 필드가 더 바뀔 수 있습니다.
• 출발점은 데이터 카탈로그입니다. 발표 글의 예시와 참조 에이전트는 BigQuery 테이블·지표 설명이며, Google 쪽의 채택은 Knowledge Catalog입니다. 코딩 에이전트의 프로젝트 메모리에 쓰는 것은 독립 도구들의 확장이고, 사양이 그 용도를 검증한 것은 아닙니다.
• 도구의 수치는 전부 개발자 주장입니다. 300µs, 80%, 20ms 모두 README의 문장이며 측정 조건이 없습니다. 두 도구 모두 만들어진 지 한두 달입니다.
• HN의 검색 비교는 한 사람의 경험담입니다. BM25 61% 대 의미 검색 37%는 개인 말뭉치에서 나온 값이고 방법이 공개되지 않았습니다. 이 글은 방향만 인용했습니다.
• Karpathy gist의 날짜는 페이지 표시 기준입니다. GitHub API가 메타데이터를 돌려주지 않아 페이지에 표시된 2026-04-04를 썼습니다. 별 수는 페이지의 "5,000+" 표시만 확인했습니다.
• 저장소 수치는 하루치 스냅샷입니다. 별 수와 최근 커밋은 2026-09-21 값입니다. 발표 글의 날짜는 페이지 메타데이터(datePublished) 기준이며, 화면 표시는 시간대 차이로 하루 뒤(6월 13일, 7월 25일)로 보입니다.
• 이 글이 다루지 않은 것. mem0·Letta·Zep 같은 관리형 메모리 서비스와의 기능 비교, LoCoMo·LongMemEval 같은 장기 메모리 벤치마크 결과는 범위 밖입니다. 형식 논의와 벤치마크 논의는 아직 만나지 않았습니다.

9. 참고자료

2026-09-21 확인했습니다. [1]~[3]은 사양과 개발사 발표 글이고, [4]·[5]는 제안자의 원문입니다. [6]·[8]은 도구 저장소의 자기 기술, [7]·[9]·[10]·[12]는 커뮤니티 토론, [11]은 도구 개발사 블로그입니다.

편집 기준: 사양이 정한 것과 도구·커뮤니티의 주장을 절마다 구분했고, 도구의 성능 수치는 전부 "주장"으로 표기했습니다. 2차 블로그의 "Google 표준" 표현은 발표 글의 실제 범위로 되돌려 적었습니다.