[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-95954":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":9,"language":10,"languages":9,"totalLinesOfCode":9,"stars":11,"forks":12,"watchers":13,"openIssues":14,"contributorsCount":14,"subscribersCount":14,"size":14,"stars1d":14,"stars7d":14,"stars30d":15,"stars90d":14,"forks30d":14,"starsTrendScore":14,"compositeScore":16,"rankGlobal":9,"rankLanguage":9,"license":17,"archived":18,"fork":18,"defaultBranch":19,"hasWiki":18,"hasPages":18,"topics":20,"createdAt":9,"pushedAt":9,"updatedAt":21,"readmeContent":22,"aiSummary":23,"trendingCount":14,"starSnapshotCount":14,"syncStatus":24,"lastSyncTime":25,"discoverSource":26},95954,"okf-agent-memory","okf-memory\u002Fokf-agent-memory","okf-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.",null,"Go",557,35,109,0,271,8.67,"MIT License",false,"main",[],"2026-09-21 02:04:29","# OKF Agent Memory\n\n> **A Domain-Neutral, Git-Native Persistent Project Memory for AI Agents based on the Open Knowledge Format (OKF) v0.2.**\n\n[![Specification](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FSpecification-OKF_v0.2-blue.svg)](https:\u002F\u002Fgithub.com\u002FGoogleCloudPlatform\u002Fknowledge-catalog\u002Fblob\u002Fmain\u002Fokf\u002FSPEC.md)\n[![Tooling](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FTooling-Go_1.26_%7C_Zero_Deps-00ADD8.svg)](pkg\u002Fokf)\n[![Protocol](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FMCP-Ready-purple.svg)](cmd\u002Fokf)\n[![License](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FLicense-MIT-green.svg)](LICENSE)\n\n---\n\n## 🌟 Overview\n\nConversations with AI agents reset when context windows close. Valuable architectural decisions, domain discoveries, and operational facts are lost unless stored persistently.\n\n**OKF Agent Memory** provides a standardized, vendor-neutral memory layer that lives directly in your repository (`knowledge\u002F`) 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.\n\n```mermaid\nflowchart TD\n    L1[\"1. OKF v0.2 Specification\u003Cbr\u002F>(Normative Markdown & YAML Format)\"]\n    L2[\"2. Agent Memory Convention\u003Cbr\u002F>(Behavioral Rules: Search, Review, Trust)\"]\n    L3[\"3. Agent Skill\u003Cbr\u002F>(LLM Prompts & Operational Workflows)\"]\n    L4[\"4. Tooling Layer: Go Library & CLI\u003Cbr\u002F>(Deterministic Parsing, Validation, Search, MCP)\"]\n    L5[\"5. Project Knowledge Corpus\u003Cbr\u002F>(knowledge\u002F OKF Bundle)\"]\n\n    L1 --> L2\n    L2 --> L3\n    L3 --> L4\n    L4 --> L5\n```\n\n---\n\n## ⚡ Key Highlights\n\n* **Blazing Fast Performance (\u003C300µs Search, ~4ms Graph Validation)**: In-memory BM25 retrieval and bundle validation execute in microseconds without VM spin-up or network roundtrips.\n* **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.\n* **Zero API Costs for Memory Retrieval**: Local lexical BM25 indexing eliminates recurring vector embedding API costs and network roundtrips.\n* **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`).\n* **Solves Context Bloat & Memory Rot**: Employs **Progressive Disclosure** (hierarchical `index.md` files and link graphs) so agents only load the exact concepts they need.\n* **Search-Before-Write Principle**: Mandates querying existing memory before authoring, preventing concept duplication and hallucinated divergence.\n* **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`).\n* **Truly Domain-Neutral**: Designed for Software Engineering, Coaching, Scientific Research, Literature Reviews, and Operations.\n\n---\n\n## 📊 Performance Benchmarks\n\nBuilt in Go with zero external dependencies, `okf` is engineered for high-frequency agent tool calling loops:\n\n| Benchmark Metric | Python \u002F Vector DB Runtimes (Mem0, Letta) | Deno \u002F Node.js Tooling | **OKF Agent Memory (Go)** |\n| :--- | :--- | :--- | :--- |\n| **Concept Search Latency** | 150ms – 800ms (Embedding API + Vector DB) | 40ms – 120ms | **\u003C 300 µs (Microseconds, In-Memory BM25)** |\n| **Full Corpus Parse & Graph Validation** | 200ms – 1.5s | 80ms – 250ms | **~4.0 ms (50+ concepts, bidirectional graph)** |\n| **Process Cold-Start Overhead** | 250ms – 600ms (Python VM boot) | 80ms – 180ms (V8 \u002F Deno boot) | **\u003C 4 ms (Compiled Single Binary)** |\n| **Retrieval Cost per 1,000 Queries** | ~$0.10 – $0.50 (Embedding tokens) | $0.00 | **$0.00 (Zero API cost, fully local)** |\n| **Memory Footprint (RSS)** | ~120 MB – 350 MB | ~60 MB – 140 MB | **\u003C 15 MB** |\n\n> [!TIP]\n> **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 \u002F Ollama with Gemma, Qwen, Llama). Run `make benchmark` or explore the [Progressive Disclosure Benchmark Suite](benchmarks\u002F).\n\n---\n\n## 🚀 Quickstart\n\n### 1. Build the Tooling\n\nClone the repository and compile the standalone `okf` executable:\n\n```bash\nmake build\n```\n\nThis generates the standalone binary at `bin\u002Fokf`.\n\n### 2. Basic CLI Commands\n\n```bash\n# Validate bundle conformance, graph connectivity, and description drift\n.\u002Fbin\u002Fokf validate knowledge --strict --drift\n\n# Search concepts via in-memory BM25 scoring\n.\u002Fbin\u002Fokf search \"architecture layers\" knowledge\n\n# Inspect a concept and its relationships (with --json support)\n.\u002Fbin\u002Fokf show architecture\u002Flayers knowledge --json\n\n# Create a new concept with automated log.md and index.md bookkeeping\n.\u002Fbin\u002Fokf create decisions\u002Fauth-flow knowledge \\\n  --type Decision \\\n  --title \"OAuth2 Authorization Flow\" \\\n  --desc \"Standardized on PKCE for client authentication.\"\n\n# Update an existing concept\n.\u002Fbin\u002Fokf update decisions\u002Fauth-flow knowledge \\\n  --desc \"Updated OAuth2 PKCE token refresh interval.\"\n\n# Bootstrap full agent memory stack into any target project\n.\u002Fbin\u002Fokf bootstrap \u002Fpath\u002Fto\u002Fproject --name \"My Project\"\n\n# Initialize only a bare OKF bundle in any directory\n.\u002Fbin\u002Fokf init my-project\u002Fknowledge\n```\n\n### 3. Bootstrapping Agent Memory in Any Project\n\nScaffold the complete OKF Agent Memory architecture into any new or existing repository with a single command:\n\n```bash\n# Bootstrap full memory stack into target project\n.\u002Fbin\u002Fokf bootstrap \u002Fpath\u002Fto\u002Fmy-project --name \"My Service\"\n```\n\nThis automatically sets up:\n* `knowledge\u002F` — OKF v0.2 compliant persistent memory bundle (`index.md`, `log.md`)\n* `.agents\u002Fskills\u002Fokf-memory\u002F` — Embedded agent skill definition and capability guides\n* `AGENTS.md` — Project-tailored operating instructions for AI coding agents\n* `Makefile` — Convenience tasks for validation (`make validate`) and search (`make search q=\"...\"`)\n\n### 4. Running as an MCP Server\n\n`okf` ships with a native Model Context Protocol (MCP) server over `stdio` to seamlessly connect with Claude Code, Cursor, Codex, and other agent platforms:\n\n```bash\n.\u002Fbin\u002Fokf mcp knowledge\n```\n\n#### Example MCP Configuration (`claude_desktop_config.json` or Cursor):\n```json\n{\n  \"mcpServers\": {\n    \"okf-memory\": {\n      \"command\": \"\u002Fpath\u002Fto\u002Fokf-agent-memory\u002Fbin\u002Fokf\",\n      \"args\": [\"mcp\", \"\u002Fpath\u002Fto\u002Fproject\u002Fknowledge\"]\n    }\n  }\n}\n```\n\n---\n\n## 📂 Repository Structure\n\n```\nokf-agent-memory\u002F\n├── benchmarks\u002F             # Progressive disclosure benchmark suite & hardware test data\n│   ├── data\u002F               # Monolith docs vs OKF bundle test fixtures\n│   └── results\u002F            # Reproducible benchmark logs across 8+ local & cloud LLMs\n├── cmd\u002F\n│   ├── okf\u002F                # Standalone CLI and embedded MCP server (`stdio`)\n│   └── okf-benchmark\u002F      # Automated benchmark runner for LLM TTFT & token measurements\n├── docs\u002F                   # Guides, specifications, architecture & release playbook\n│   ├── AGENT_TESTING.md    # Multi-agent testing, prompt scenarios & compatibility matrix\n│   ├── ALTERNATIVES.md     # Comparison against Mem0, Letta, and ad-hoc markdown\n│   ├── CLI.md              # Complete command-line & MCP tool reference\n│   ├── CONVENTION.md       # OKF Agent Memory Convention v0.1\n│   ├── GETTING_STARTED.md  # Comprehensive onboarding guide\n│   ├── OKF-COMPATIBILITY.md# OKF v0.2 spec compatibility analysis\n│   ├── RELEASE_PLAYBOOK.md # Automated release process & version tagging\n│   ├── ROADMAP.md          # Project roadmap & milestones\n│   └── SECURITY.md         # Data governance, secret prevention & PII rules\n├── examples\u002F               # Domain-neutral reference OKF v0.2 bundles\n│   ├── books\u002F              # Literature & cognitive science knowledge bundle\n│   ├── coaching\u002F           # Executive coaching & client session bundle\n│   └── software\u002F           # Microservices architecture & ADR bundle\n├── knowledge\u002F              # Project's own OKF v0.2 persistent memory bundle\n│   ├── index.md            # Root progressive disclosure index (okf_version: \"0.2\")\n│   ├── log.md              # Dated change log (ISO 8601 YYYY-MM-DD)\n│   ├── project\u002F            # Overview & value propositions\n│   ├── architecture\u002F       # 5-tier architecture & tooling decisions\n│   ├── convention\u002F         # Principles & lifecycle workflows\n│   └── roadmap\u002F            # Milestones\n├── packaging\u002F              # Distribution packaging\n│   └── homebrew\u002F           # Official Homebrew formula & tap instructions\n├── pkg\u002Fokf\u002F                # Zero-dependency Go core library (parser, validator, BM25, MCP, bootstrap)\n├── AGENTS.md               # Operating instructions for AI coding agents\n├── CONTRIBUTING.md         # Contribution guidelines & development workflow\n├── Makefile                # Build, test, lint, validation & release targets\n├── LICENSE                 # MIT License\n├── README.md               # Main repository documentation\n└── SECURITY.md             # Security policy & reporting guidelines\n```\n\n---\n\n## 🧪 Testing & Verification\n\nRun the full test suite and validate the repository's self-documenting knowledge bundle:\n\n```bash\nmake check\n```\n\n---\n\n## 📖 Further Documentation\n\n* [Getting Started Guide](docs\u002FGETTING_STARTED.md) — Comprehensive onboarding guide for agents and humans.\n* [CLI & MCP Reference](docs\u002FCLI.md) — Complete command-line and protocol tools reference.\n* [Contributing Guide](CONTRIBUTING.md) — Development setup, quality gates, and pull request standards.\n* [Security & Privacy Guidelines](docs\u002FSECURITY.md) — Data governance, secret prevention, and PII protection rules.\n* [Multi-Agent Testing & Evaluation](docs\u002FAGENT_TESTING.md) — Test scenarios, compatibility matrix, and benchmarks.\n* [OKF Agent Memory Convention v0.1](docs\u002FCONVENTION.md) — Behavioral rules and lifecycle specification.\n* [Project Roadmap & Milestones](docs\u002FROADMAP.md) — Phased development plan.\n* [Release Playbook](docs\u002FRELEASE_PLAYBOOK.md) — Versioning, CI\u002FCD pipeline, and distribution procedures.\n* [OKF v0.2 Compatibility Matrix](docs\u002FOKF-COMPATIBILITY.md) — Specification validation analysis.\n* [Why OKF Agent Memory?](knowledge\u002Fproject\u002Fvalue-proposition.md) — Detailed value proposition & differentiators.\n* [Alternatives & Ecosystem Comparison](docs\u002FALTERNATIVES.md) — Comparison with Mem0, Letta, and ad-hoc markdown files.\n\n---\n\n## 📄 License\n\nMIT License. See [LICENSE](LICENSE) for details.\n","OKF Agent Memory 是一个面向 AI 编程代理的 Git 原生持久化记忆系统，基于 Google OKF v0.2 开放规范，以纯文本 Markdown + YAML 格式将知识存于代码仓库的 `knowledge\u002F` 目录中。其核心功能包括亚毫秒级（\u003C300µs）内存内 BM25 检索、内置 Model Context Protocol（MCP）服务、渐进式披露机制及搜索前置写入原则，全程无需外部数据库或依赖，可降低 token 开销达 80%。适用于需要长期维护领域知识、保障可审计性与协作一致性的 AI 编程代理场景，如软件工程、科研辅助、技术文档协同等。",2,"2026-09-07 02:30:06","CREATED_QUERY"]