OKF Agent Memory

Open Knowledge Format (OKF) v0.2를 기반으로 한, 도메인 중립적이고 Git 네이티브한 AI 에이전트용 영구 프로젝트 메모리.

Tooling

CI

Trendshift

On StackMap

Protocol

License

Sponsor

🌟 개요 (Overview)

AI 에이전트와의 대화는 컨텍스트 창(context window)이 닫히면 초기화됩니다. 중요한 아키텍처 결정, 도메인 발견 사항, 운영 사실 등은 영구적으로 저장되지 않으면 손실됩니다.

기존 접근 방식들은 두 가지 치명적인 실패 모드를 안고 있습니다:

1. 프롬프트 모놀리스 (The Prompt Monolith): 모든 도메인 지식과 규칙을 AGENTS.md나 CLAUDE.md 같은 파일에 때려 넣으면, 거대한 컨텍스트 블로트(context bloat)가 발생하고 **주의 분산(attention drift)**이 초래되어 (에이전트가 중요한 지침을 무시함).
2. RAG 사각지대 (The RAG Blindspot): 행동 규칙을 벡터 데이터베이스에 덤프하는 것은 실패합니다. 왜냐하면 에이전트는 일반적인 작업을 수행할 때 운영 제약 조건(예: 형식 지정 또는 보안 규칙)을 의미론적으로 검색하지 않기 때문입니다.

OKF Agent Memory는 **듀얼 메모리 에이전트 아키텍처 (Dual-Memory Agent Architecture, DMAA)**를 통해 이 딜레마를 해결합니다:

flowchart TD
    subgraph PUSH[

* **레이어 1: 규범적 작업 기억 (Normative Working Memory, Push Layer)**: [**에이전트 액션 문법(Agent Action Grammar, AAG)**](docs/spec/AGENT_ACTION_GRAMMAR_RFC.md)으로 표현되는 영구적이고 초압축적인 행동 코드북(최대 400 토큰 제한). 세션 시작 시 로드되어 무관용의 불변성(zero-tolerance invariants)을 강제합니다.
* **레이어 2: 의미론적 도메인 메모리 (Semantic Domain Memory, Pull Layer)**: 기본적으로 **0 토큰**을 소비하며 마이크로초 단위로 온디맨드 검색이 가능한 [**OKF v0.2**](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md) 지식 번들(`knowledge/`)입니다.

```mermaid
flowchart TD
    L1["1. OKF v0.2 사양<br/>(규범적 마크다운 및 YAML 형식)"]
    L2["2. 에이전트 메모리 컨벤션 및 DMAA<br/>(듀얼-메모리 모델, 검색-쓰기 전 검증, 신뢰)"]
...

⚡ 주요 하이라이트 (Key Highlights)

• 듀얼-메모리 인지 아키텍처 (Dual-Memory Cognitive Architecture, DMAA): 규범적 푸시 작업 기억(AGENTS.md 코드북)과 의미론적 풀 도메인 메모리(knowledge/ 번들)를 분리하여 프롬프트 비대화(prompt bloat)를 완전히 제거합니다.

• 에이전트 액션 문법 (Agent Action Grammar, AAG): 자연어 프롬프트 지침 대비 ~78–85% 토큰을 절약하는 초압축적이고 결정론적인 ASCII 마이크로 구문입니다.

• 놀라운 성능 (<300µs 검색, ~4ms 그래프 검증): 인메모리 BM25 검색 및 번들 유효성 검사는 VM 스핀업이나 네트워크 왕복 없이 마이크로초 단위로 실행됩니다.

• 100% Git 네이티브 & 제로 벤더 종속성 (Zero Vendor Lock-in): 모든 것이 버전 관리되는 일반 텍스트입니다. 표준 git diff 및 git log를 사용하여 에이전트의 메모리를 검사, 감사 및 검토할 수 있습니다. 외부 데이터베이스가 필요 없습니다.

• 메모리 검색에 대한 API 비용 제로: 로컬 어휘적 BM25 인덱싱은 반복적인 벡터 임베딩 API 비용과 네트워크 왕복을 제거합니다.

• Google OKF v0.2 기반 구축: 에이전트 지식의 개방형 표준 형식(open standard format)을 사용하며, 출처(sources), 신뢰 등급(generated 대 verified), 수명 주기 메타데이터(status, stale_after)에 대한 전체 지원을 제공합니다.

• 컨텍스트 비대화(Context Bloat) 및 메모리 부패(Memory Rot) 해결: 에이전트가 필요한 정확한 개념만 로드하도록 점진적 공개(Progressive Disclosure) (계층적 index.md 파일 및 링크 그래프)를 활용합니다.

• 검색-후-작성 원칙(Search-Before-Write Principle): 개념 중복을 방지하고 환각적인 분기(hallucinated divergence)를 막기 위해 작성 전에 기존 메모리를 쿼리하도록 의무화합니다.

• 거버넌스 및 코드-지식 바인딩(Code-to-Knowledge Binding): 아키텍처 결정을 code_refs를 통해 소스 파일에 직접 연결하고, 코드를 수정하기 전에 --for-path를 통해 활성 제약 조건/보유 상태(active constraints/holds)를 쿼리합니다.

• 진정한 도메인 중립성: 소프트웨어 엔지니어링, 코칭, 과학 연구, 문헌 검토, 운영 등 다양한 분야에 설계되었습니다.

📊 성능 벤치마크(Performance Benchmarks)

okf는 외부 의존성이 전혀 없는 Go 언어로 구축되었으며, 고빈도 에이전트 도구 호출 루프를 위해 설계되었습니다:

[!TIP]
자체 LLM으로 로컬 재현: Time-To-First-Token (TTFT) 속도 향상 및 로컬 하드웨어에서 토큰 80% 감소를 검증하기 위해 순수 Go로 작성된 자동화된 벤치마크 러너를 제공합니다 (LM Studio / Ollama와 Gemma, Qwen, Llama 사용). make benchmark를 실행하거나 Progressive Disclosure Benchmark Suite을 탐색하세요.

🚀 빠른 시작(Quickstart)

1. 도구링 빌드 (Build the Tooling)

저장소(repository)를 클론하고 독립 실행형 okf 실행 파일을 컴파일합니다:

make build

이 명령어는 bin/okf 위치에 독립 실행형 바이너리를 생성합니다.

2. 기본 CLI 명령어 (Basic CLI Commands)

# 번들 준수성, 그래프 연결성 및 설명 드리프트(description drift) 검증
./bin/okf validate knowledge --strict --drift

...

3. 다중 범위 메모리 계층화 및 스코프별 해결 (Multi-Scope Memory Layering & Scoped Resolution)

OKF Agent Memory는 네 가지 결정론적 메모리 범위(deterministic memory scopes)에 걸쳐 지식을 구성합니다. 상위 레이어는 검색 과정에서 하위 레이어의 동일한 개념 ID를 엄격하게 덮어쓰기(shadow)하여, 로컬 프로젝트 결정이 외부 업스트림 패키지나 머신 베이스라인보다 항상 우선권을 갖도록 보장합니다:

flowchart TD
    subgraph Scopes [OKF 4-Tier Memory Hierarchy]
        P["<b>Project</b> (Priority 100)<br/>Prefix: <i>none</i> (e.g. decisions/auth)<br/>Location: ./knowledge/] 
... 

범위 명세 매트릭스 (Scope Specification Matrix)

검색 및 표시 시 범위 필터링 (Filtering by Scope in Search & Show)

# 기본값 (--scope all): 자동 덮어쓰기 및 우선순위 순위를 통해 모든 레이어를 검색합니다.
./bin/okf search "authentication"

... 

4. 프로젝트 내에서 에이전트 메모리 부트스트랩 (Bootstrapping Agent Memory in Any Project)

단일 명령어로 새로운 또는 기존 리포지토리에 전체 OKF Agent Memory 아키텍처를 구축(scaffold)할 수 있습니다:

# 대상 프로젝트에 전체 메모리 스택을 부트스트랩합니다.
./bin/okf bootstrap /path/to/my-project --name "My Service"

이 명령어는 다음 항목들을 자동으로 설정합니다:

• knowledge/ — OKF v0.2 규격의 영구 메모리 번들 (index.md, log.md)
• .agents/skills/okf-memory/ — 내장 에이전트 스킬 정의 및 기능 가이드
• AGENTS.md — AI 코딩 에이전트를 위한 프로젝트 맞춤형 운영 지침서
• Makefile — 검증(make validate) 및 검색(make search q="...")을 위한 편의 작업(convenience tasks)

4. MCP 서버로 실행 (Running as an MCP Server)

okf는 Claude Code, Cursor, Codex 및 기타 에이전트 플랫폼과 원활하게 연결하기 위해 stdio를 통해 네이티브 모델 컨텍스트 프로토콜(Model Context Protocol, MCP) 서버를 제공합니다:

./bin/okf mcp knowledge

예시 MCP 설정 (claude_desktop_config.json 또는 Cursor):

{
  "mcpServers": {
    "okf-memory": {
...

📂 저장소 구조 (Repository Structure)

okf-agent-memory/
├── .agents/                # 활성 에이전트 스킬 및 에이전트 설정
│   └── skills/okf-memory/  # AI 에이전트를 위한 권위 있는 OKF 메모리 스킬 (Single Source of Truth)
...

🧪 테스트 및 검증 (Testing & Verification)

전체 테스트 스위트를 실행하고 저장소의 자체 문서화 지식 번들을 검증하세요:

make check

📖 추가 문서 (Further Documentation)

• 문서 색인 (Documentation Index) — 모든 프로젝트 문서의 중앙 디렉토리.

• 시작 가이드 (Getting Started Guide) — 에이전트와 인간을 위한 종합 온보딩 가이드.

• CLI 및 MCP 참조 (CLI & MCP Reference) — 전체 명령줄 및 프로토콜 도구 참조.

• Dual-Memory Agent Architecture RFC — 인지적 2계층 에이전트 메모리 모델 (Push codex + Pull knowledge).

• Agent Action Grammar RFC — AGENTS.md를 위한 결정론적이고 토큰 효율적인 AAG 마이크로 문법 사양.

• 에이전트 지침 모범 사례 (Agent Instruction Best Practices) — 결정론적 지침 설계 및 토큰 최적화 가이드.

• OKF 에이전트 메모리 규칙 v0.1 (OKF Agent Memory Convention v0.1) — 행동 규칙 및 생명 주기 사양.

• 기여 가이드 (Contributing Guide) — 개발 설정, 품질 게이트, 및 풀 리퀘스트 표준.

• 보안 및 개인 정보 보호 지침 (Security & Privacy Guidelines) — 데이터 거버넌스, 비밀 방지, 및 PII(개인 식별 정보) 보호 규칙.

• 다중 에이전트 테스트 및 평가 (Multi-Agent Testing & Evaluation) — 테스트 시나리오, 호환성 매트릭스, 및 벤치마크.

• 프로젝트 로드맵 및 마일스톤 (Project Roadmap & Milestones) — 단계별 개발 계획.

• 릴리스 플레이북 (Release Playbook) — 버전 관리, CI/CD 파이프라인, 및 배포 절차.

• 릴리스 노트 및 히스토리 — 버전별 변경 로그와 역사적 릴리스 노트 아카이브.

• OKF v0.2 호환성 매트릭스 — 사양 검증 분석.

• 왜 OKF 에이전트 메모리가 필요한가? — 상세한 가치 제안 및 차별점.

• 대체재 및 생태계 비교 — Mem0, Letta, 그리고 임시 마크다운 파일과의 비교.

👥 기여자 (Contributors)

OKF Agent Memory를 구축하고 개선하는 데 도움을 준 모든 멋진 기여자분들께 감사드립니다!

모든 종류의 기여가 환영받습니다! 자세한 내용은 CONTRIBUTING.md와 CONTRIBUTORS.md를 참조하세요.

💖 지원 및 후원 (Support & Sponsoring)

OKF Agent Memory가 자율 에이전트 워크플로우에 가치 있다고 생각하신다면, 지속적인 개발, 보안 강화(security hardening), 사양 준수(spec compliance)를 지원하기 위해 GitHub에서 프로젝트 후원을 고려해 주세요!

📄 라이선스 (License)

MIT License. 자세한 내용은 LICENSE를 참조하세요.