okf-memory/okf-agent-memory

Git-native persistent memory for AI coding agents. Implements Google OKF v0.2 with sub-300µs in-memory BM25 search, embedded MCP server, and progressive disclosure. Slashes token bloat by 80% with zero external databases or dependencies. Built in pure Go.

OKF Agent Memory – 개요

OKF Agent Memory는 AI 기반 코딩 어시스턴트에게 영구적이고 버전 관리되는 지식 기반을 제공할 수 있는 Go 기반 툴킷입니다. 오픈 지식 형식(OKF) v0.2 사양을 따르며, 사실, 결정, 실행 매뉴얼 및 기타 "도메인 지식"을 코드와 동일한 Git 저장소에 있는 knowledge/ 폴더 내의 일반 텍스트 Markdown/YAML 파일로 저장합니다.

중요한 이유

컨텍스트 손실 없음 – LLM과의 채팅이 끝나면 모델은 전달한 모든 것을 잊어버립니다. 구조화된 지식 번들을 Git에 유지함으로써 에이전트는 다음 요청에 필요한 개념을 정확히 검색할 수 있습니다.
프롬프트 비대화 방지 – 거대한 AGENTS.md 파일을 모든 프롬프트에 채워 넣는 대신, 시스템은 에이전트의 "작업 기억"(약 400 토큰의 작은 코덱스)을 온디맨드로 쿼리되는 더 큰 의미적 기억과 분리합니다.
벤더 종속 없음 – 모든 데이터는 일반 텍스트입니다. git diff로 변경 사항을 검사하고 출처를 감사할 수 있으며 원격 벡터 데이터베이스에 의존하지 않습니다.
빠르고 저렴한 검색 – 내장된 BM25 엔진은 인메모리 어휘 검색(< 300 µs)을 수행하며 API 비용이 없습니다.

핵심 개념

개념	기능
이중 메모리 에이전트 아키텍처(DMAA)	푸시 계층(`AGENTS.md`의 규범적 규칙, 약 400 토큰으로 제한)과 풀 계층(필요할 때만 쿼리되는 `knowledge/` 번들)을 분리합니다.
에이전트 동작 문법(AAG)	결정적 에이전트 지침을 작성하기 위한 간결한 ASCII 마이크로 구문으로, 자유 형식 산문에 비해 약 80%의 토큰을 절약합니다.
4계층 메모리 계층 구조	`project`(로컬 번들) → `vendor`(가져온 번들) → `user`(개인 메모) → `system`(엔터프라이즈 정책). 상위 계층이 하위 계층을 가립니다.
OKF v0.2 번들	내장 출처(`sources`), 신뢰 계층(`generated` vs `verified`), 수명 주기 메타데이터(`status`, `stale_after`)가 있는 Markdown/YAML 파일 세트.
쓰기 전 검색 원칙	에이전트는 새 개념을 추가하기 전에 기존 번들을 쿼리하여 중복과 환각을 방지해야 합니다.

제공 내용(도구 상자)

okf CLI – 단일 컴파일 바이너리(bin/okf)로 다음을 수행할 수 있습니다:
- 번들의 스키마, 그래프 무결성 및 품질 스코어카드 검증.
- BM25로 개념 검색(okf search "..." knowledge).
- 개념 및 관계 표시(okf show <id> knowledge).
- 번들 생성, 업데이트 또는 부트스트랩(okf create ..., okf bootstrap ...).
- MCP(모델 컨텍스트 프로토콜) 서버로 실행되어 Claude, Cursor, Codex와 같은 에이전트가 stdio를 통해 호출할 수 있습니다.
제로 종속성 Go 라이브러리(pkg/okf) – 사용자 지정 통합을 구축하려는 경우 다른 도구에 포함할 수 있습니다.
벤더 번들 처리 – 선택적 품질 게이트(--min-score)와 함께 OKF 레지스트리 또는 Git에서 기성 지식 번들을 가져옵니다.
벤치마크 스위트 – 서브 밀리초 검색 및 수 밀리초 전체 번들 검증을 보여주는 재현 가능한 성능 테스트.

빠른 시작 가이드

바이너리 빌드:
```
make build   # bin/okf 생성
```
기존 번들 검증(점수 < 80이면 CI 실패):
```
./bin/okf validate knowledge --min-score 80
```

개념 검색:

./bin/okf search "authentication" knowledge

새 프로젝트에 전체 메모리 스택 부트스트랩:
```
./bin/okf bootstrap /path/to/my-project --name "My Service"
```
이렇게 하면 knowledge/ 폴더, 프로젝트별 AGENTS.md, 헬퍼 Makefile 대상이 생성됩니다.
MCP를 통해 에이전트 연결(Claude Desktop 예시):
```
{
  "mcpServers": { "okf-memory": { "command": "./bin/okf", "args": ["mcp", "./knowledge"] } }
}
```
이제 에이전트는 코딩 세션 중에 search 또는 show 호출을 실행할 수 있습니다.

성능 및 비용 하이라이트(README에서)

지표	OKF Agent Memory (Go)	일반적인 대안
개념 검색 지연 시간	< 300 µs(인메모리 BM25)	40 ms – 800 ms(임베딩 + 벡터 DB)
전체 번들 파싱 및 그래프 검증	~4 ms(50+ 개념)	80 ms – 1.5 s
콜드 스타트 오버헤드	< 4 ms(단일 바이너리)	80 ms – 600 ms(Python/Node 런타임)
1000개 쿼리당 검색 비용	$0.00(로컬)	$0.10 – $0.50(임베딩 API)
메모리 사용량	< 15 MB	60 MB – 350 MB

누가 사용할 수 있나요?

소프트웨어 팀 – LLM 기반 코드 어시스턴트에 의존하며 프로젝트별 규칙, 아키텍처 결정, 실행 매뉴얼에 대한 신뢰할 수 있고 감사 가능한 소스를 원하는 팀.
연구 또는 코칭 프로젝트 – 동일한 LLM을 반복적으로 사용하며 Git과 함께 진화하는 안정적인 "지식 기반"이 필요한 프로젝트.
엔터프라이즈 – 외부 벡터 서비스 비용을 지불하지 않고 여러 에이전트 간에 규정 준수 정책(보안, 스타일, 라이선스)을 적용해야 하는 기업.

자세히 알아보기

문서 인덱스 – docs/README.md
시작 가이드 – docs/guides/GETTING_STARTED.md
에이전트 동작 문법 사양 – docs/spec/AGENT_ACTION_GRAMMAR_RFC.md
이중 메모리 아키텍처 RFC – docs/spec/DUAL_MEMORY_AGENT_ARCHITECTURE_RFC.md
스코어카드 및 품질 게이트 – docs/guides/CLI.md(--scorecard 플래그 참조)

요약: OKF Agent Memory는 AI 코딩 에이전트가 필요로 하는 지식을 저장하고 검색하는 Git 네이티브, 토큰 효율적, 초고속 방법을 제공하여 프롬프트 비대화와 값비싼 벡터 DB 호출을 제거하면서 모든 것을 감사 가능하고 버전 관리된 상태로 유지합니다.