메뉴
HN
Hacker News • 20일 전

OKF Agent Memory – 깃 기반 AI 코딩 에이전트 영구 메모리

IMP
6/10
핵심 요약

OKF Agent Memory는 AI 에이전트의 대화가 컨텍스트 창이 닫히면 사라지는 문제를 해결하기 위해, 저장소 내 knowledge/ 디렉터리에 마크다운 파일로 영구 메모리를 저장하는 깃 네이티브 솔루션입니다. 임베딩 API 비용 없이 로컬 BM25 검색으로 300마이크로초 미만의 검색 속도를 제공하며, 외부 의존성 없는 Go 단일 바이너리와 MCP 서버를 포함합니다. 벤더 종속이 전혀 없어 표준 git diff와 git log로 에이전트 메모리를 감사하고 검토할 수 있다는 점이 핵심 강점입니다.

번역된 본문

OKF Agent Memory – AI 에이전트를 위한 깃 네이티브 영구 메모리

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

🌟 개요

AI 에이전트와의 대화는 컨텍스트 창이 닫히면 초기화됩니다. 소중한 아키텍처 결정 사항, 도메인 발견 내용, 운영 관련 사실들은 영구적으로 저장하지 않으면 모두 사라집니다. OKF Agent Memory는 저장소 내부(knowledge/ 폴더)에 YAML 프론트매터가 포함된 일반 마크다운 파일로 존재하는, 표준화되고 벤더 중립적인 메모리 계층을 제공합니다. 비정형적인 임시 마크다운 파일(CLAUDE.md, AGENTS.md)과 복잡한 블랙박스 벡터 데이터베이스 사이의 간극을 메워줍니다.

시스템은 5개 계층으로 구성됩니다: 1) OKF v0.2 사양(규범적 마크다운 및 YAML 형식), 2) 에이전트 메모리 규칙(검색, 검토, 신뢰 등 행동 규칙), 3) 에이전트 스킬(LLM 프롬프트 및 운영 워크플로), 4) 툴링 계층(Go 라이브러리 및 CLI – 결정론적 파싱, 검증, 검색, MCP), 5) 프로젝트 지식 코퍼스(knowledge/ OKF 번들).

⚡ 주요 특징

  • 압도적으로 빠른 성능 (검색 300µs 미만, 그래프 검증 약 4ms): 메모리 내 BM25 검색과 번들 검증이 VM 기동이나 네트워크 왕복 없이 마이크로초 단위로 실행됩니다.
  • 100% 깃 네이티브 및 벤더 종속 제로: 모든 것이 버전 관리되는 일반 텍스트입니다. 표준 git diff와 git log로 에이전트의 메모리를 검사, 감사, 검토할 수 있습니다. 외부 데이터베이스가 필요 없습니다.
  • 메모리 검색 API 비용 제로: 로컬 어휘 기반 BM25 인덱싱으로 반복적인 벡터 임베딩 API 비용과 네트워크 왕복이 발생하지 않습니다.
  • Google OKF v0.2 기반: 출처(sources), 신뢰 등급(generated vs. verified), 라이프사이클 메타데이터(status, stale_after)를 완전 지원하는 개방형 표준 형식을 사용합니다.
  • 컨텍스트 비대화 및 메모리 부패 해결: 점진적 공개(Progressive Disclosure, 계층적 index.md 파일과 링크 그래프)를 채택해 에이전트가 필요한 개념만 정확히 로드합니다.
  • 쓰기 전 검색 원칙: 새로 작성하기 전에 기존 메모리를 먼저 조회하도록 강제하여 개념 중복과 환각으로 인한 분기를 방지합니다.
  • 의존성 없는 Go 툴체인: 외부 의존성이 전혀 없는 단일 바이너리, 5ms 미만의 CLI 시작 시간, 내장 MCP(Model Context Protocol) 서버(okf mcp)를 제공합니다.
  • 완전한 도메인 중립성: 소프트웨어 엔지니어링, 코칭, 과학 연구, 문헌 검토, 운영 등에 활용 가능하도록 설계되었습니다.

📊 성능 벤치마크

외부 의존성 없이 Go로 제작된 okf는 고빈도 에이전트 도구 호출 루프에 최적화되어 있습니다:

벤치마크 지표 Python / 벡터 DB 런타임 (Mem0, Letta) Deno / Node.js 도구 OKF Agent Memory (Go)
개념 검색 지연 시간 150ms–800ms (임베딩 API + 벡터 DB) 40ms–120ms 300µs 미만 (메모리 내 BM25)
전체 코퍼스 파싱 및 그래프 검증 200ms–1.5s 80ms–250ms 약 4.0ms (개념 50개 이상, 양방향 그래프)
프로세스 콜드 스타트 오버헤드 250ms–600ms (Python VM 부팅) 80ms–180ms (V8/Deno 부팅) 4ms 미만 (컴파일된 단일 바이너리)
1,000회 검색당 비용 약 $0.10–$0.50 (임베딩 토큰) $0.00 $0.00 (API 비용 제로, 완전 로컬)
메모리 사용량(RSS) 약 120MB–350MB 약 60MB–140MB 15MB 미만

팁: 자체 LLM으로 로컬에서 재현하세요. Time-To-First-Token(TTFT) 속도 향상과 80% 토큰 절감을 로컬 하드웨어(LM Studio/Ollama + Gemma, Qwen, Llama)에서 검증할 수 있는 순수 Go 자동 벤치마크 러너를 제공합니다. make benchmark를 실행하거나 Progressive Disclosure 벤치마크 스위트를 살펴보세요.

🚀 빠른 시작

1. 도구 빌드: 저장소를 클론하고 독립 실행형 okf 실행 파일을 컴파일합니다:

make build

bin/okf에 단일 바이너리가 생성됩니다.

2. 기본 CLI 명령어:

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

# 메모리 내 BM25 스코어링으로 개념 검색
./bin/okf search "architecture layers" knowledge

# 개념 및 관계 확인 (--json 지원)
./bin/okf show architecture/layers knowledge --json

# 새 개념 생성
원문 보기
원문 보기 (영어)
OKF Agent Memory A Domain-Neutral, Git-Native Persistent Project Memory for AI Agents based on the Open Knowledge Format (OKF) v0.2. 🌟 Overview Conversations with AI agents reset when context windows close. Valuable architectural decisions, domain discoveries, and operational facts are lost unless stored persistently. OKF Agent Memory provides a standardized, vendor-neutral memory layer that lives directly in your repository ( knowledge/ ) as plain Markdown files with YAML frontmatter. It bridges the gap between unstructured ad-hoc markdown files ( CLAUDE.md , AGENTS.md ) and complex, black-box vector databases. flowchart TD L1["1. OKF v0.2 Specification<br/>(Normative Markdown & YAML Format)"] L2["2. Agent Memory Convention<br/>(Behavioral Rules: Search, Review, Trust)"] L3["3. Agent Skill<br/>(LLM Prompts & Operational Workflows)"] L4["4. Tooling Layer: Go Library & CLI<br/>(Deterministic Parsing, Validation, Search, MCP)"] L5["5. Project Knowledge Corpus<br/>(knowledge/ OKF Bundle)"] L1 --> L2 L2 --> L3 L3 --> L4 L4 --> L5 Loading ⚡ Key Highlights Blazing Fast Performance (<300µs Search, ~4ms Graph Validation) : In-memory BM25 retrieval and bundle validation execute in microseconds without VM spin-up or network roundtrips. 100% Git-Native & Zero Vendor Lock-in : Everything is version-controlled plain text. Inspect, audit, and review your agent's memory using standard git diff and git log . No external database required. Zero API Costs for Memory Retrieval : Local lexical BM25 indexing eliminates recurring vector embedding API costs and network roundtrips. Built on Google OKF v0.2 : Uses the open standard format for agent knowledge with full support for provenance ( sources ), trust tiers ( generated vs. verified ), and lifecycle metadata ( status , stale_after ). Solves Context Bloat & Memory Rot : Employs Progressive Disclosure (hierarchical index.md files and link graphs) so agents only load the exact concepts they need. Search-Before-Write Principle : Mandates querying existing memory before authoring, preventing concept duplication and hallucinated divergence. Zero-Dependency Go Toolchain : Single binary with zero external dependencies , sub-5ms CLI startup time, and a built-in Model Context Protocol (MCP) server ( okf mcp ). Truly Domain-Neutral : Designed for Software Engineering, Coaching, Scientific Research, Literature Reviews, and Operations. 📊 Performance Benchmarks Built in Go with zero external dependencies, okf is engineered for high-frequency agent tool calling loops: Benchmark Metric Python / Vector DB Runtimes (Mem0, Letta) Deno / Node.js Tooling OKF Agent Memory (Go) Concept Search Latency 150ms – 800ms (Embedding API + Vector DB) 40ms – 120ms < 300 µs (Microseconds, In-Memory BM25) Full Corpus Parse & Graph Validation 200ms – 1.5s 80ms – 250ms ~4.0 ms (50+ concepts, bidirectional graph) Process Cold-Start Overhead 250ms – 600ms (Python VM boot) 80ms – 180ms (V8 / Deno boot) < 4 ms (Compiled Single Binary) Retrieval Cost per 1,000 Queries ~$0.10 – $0.50 (Embedding tokens) $0.00 $0.00 (Zero API cost, fully local) Memory Footprint (RSS) ~120 MB – 350 MB ~60 MB – 140 MB < 15 MB Tip Reproduce Locally with your own LLM : We provide an automated benchmark runner in pure Go to verify Time-To-First-Token (TTFT) speedups and -80% token reduction on your local hardware (LM Studio / Ollama with Gemma, Qwen, Llama). Run make benchmark or explore the Progressive Disclosure Benchmark Suite . 🚀 Quickstart 1. Build the Tooling Clone the repository and compile the standalone okf executable: make build This generates the standalone binary at bin/okf . 2. Basic CLI Commands # Validate bundle conformance, graph connectivity, and description drift ./bin/okf validate knowledge --strict --drift # Search concepts via in-memory BM25 scoring ./bin/okf search " architecture layers " knowledge # Inspect a concept and its relationships (with --json support) ./bin/okf show architecture/layers knowledge --json # Create a new concept with automated log.md and index.md bookkeeping ./bin/okf create decisions/auth-flow knowledge \ --type Decision \ --title " OAuth2 Authorization Flow " \ --desc " Standardized on PKCE for client authentication. " # Update an existing concept ./bin/okf update decisions/auth-flow knowledge \ --desc " Updated OAuth2 PKCE token refresh interval. " # Bootstrap full agent memory stack into any target project ./bin/okf bootstrap /path/to/project --name " My Project " # Initialize only a bare OKF bundle in any directory ./bin/okf init my-project/knowledge 3. Bootstrapping Agent Memory in Any Project Scaffold the complete OKF Agent Memory architecture into any new or existing repository with a single command: # Bootstrap full memory stack into target project ./bin/okf bootstrap /path/to/my-project --name " My Service " This automatically sets up: knowledge/ — OKF v0.2 compliant persistent memory bundle ( index.md , log.md ) .agents/skills/okf-memory/ — Embedded agent skill definition and capability guides AGENTS.md — Project-tailored operating instructions for AI coding agents Makefile — Convenience tasks for validation ( make validate ) and search ( make search q="..." ) 4. Running as an MCP Server okf ships with a native Model Context Protocol (MCP) server over stdio to seamlessly connect with Claude Code, Cursor, Codex, and other agent platforms: ./bin/okf mcp knowledge Example MCP Configuration ( claude_desktop_config.json or Cursor): { "mcpServers" : { "okf-memory" : { "command" : " /path/to/okf-agent-memory/bin/okf " , "args" : [ " mcp " , " /path/to/project/knowledge " ] } } } 📂 Repository Structure okf-agent-memory/ ├── benchmarks/ # Progressive disclosure benchmark suite & hardware test data │ ├── data/ # Monolith docs vs OKF bundle test fixtures │ └── results/ # Reproducible benchmark logs across 8+ local & cloud LLMs ├── cmd/ │ ├── okf/ # Standalone CLI and embedded MCP server (`stdio`) │ └── okf-benchmark/ # Automated benchmark runner for LLM TTFT & token measurements ├── docs/ # Guides, specifications, architecture & release playbook │ ├── AGENT_TESTING.md # Multi-agent testing, prompt scenarios & compatibility matrix │ ├── ALTERNATIVES.md # Comparison against Mem0, Letta, and ad-hoc markdown │ ├── CLI.md # Complete command-line & MCP tool reference │ ├── CONVENTION.md # OKF Agent Memory Convention v0.1 │ ├── GETTING_STARTED.md # Comprehensive onboarding guide │ ├── OKF-COMPATIBILITY.md# OKF v0.2 spec compatibility analysis │ ├── RELEASE_PLAYBOOK.md # Automated release process & version tagging │ ├── ROADMAP.md # Project roadmap & milestones │ └── SECURITY.md # Data governance, secret prevention & PII rules ├── examples/ # Domain-neutral reference OKF v0.2 bundles │ ├── books/ # Literature & cognitive science knowledge bundle │ ├── coaching/ # Executive coaching & client session bundle │ └── software/ # Microservices architecture & ADR bundle ├── knowledge/ # Project's own OKF v0.2 persistent memory bundle │ ├── index.md # Root progressive disclosure index (okf_version: "0.2") │ ├── log.md # Dated change log (ISO 8601 YYYY-MM-DD) │ ├── project/ # Overview & value propositions │ ├── architecture/ # 5-tier architecture & tooling decisions │ ├── convention/ # Principles & lifecycle workflows │ └── roadmap/ # Milestones ├── packaging/ # Distribution packaging │ └── homebrew/ # Official Homebrew formula & tap instructions ├── pkg/okf/ # Zero-dependency Go core library (parser, validator, BM25, MCP, bootstrap) ├── AGENTS.md # Operating instructions for AI coding agents ├── CONTRIBUTING.md # Contribution guidelines & development workflow ├── Makefile # Build, test, lint, validation & release targets ├── LICENSE # MIT License ├── README.md # Main repository documentation └── SECURITY.md # Security policy & reporting guidelines 🧪 Testing & Verification Run the full test suite and validate the repository's self-documenting knowledge bundle: make check 📖 Further Documentation Getting Started Guide — Comprehensive onboarding guide
에이전트 메모리 깃(Git) 오픈소스 BM25 검색 MCP