Skip to content
Back to search

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.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/okf-memory/okf-agent-memory with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/okf-memory/okf-agent-memory'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/okf-memory--okf-agent-memory/badge.svg)](/listings/okf-memory--okf-agent-memory)

HTML

<a href="/listings/okf-memory--okf-agent-memory"><img src="/api/listings/okf-memory--okf-agent-memory/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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

# Discover constraints and active holds governing a specific source file before editing
./bin/okf search --for-path pkg/okf/types.go 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

# Zero-Knowledge Sync: initialize vault and print Emergency Kit
./bin/okf hub init-vault knowledge

# Zero-Knowledge Sync: push or sync changes with the Hub (optional: --token or OKF_HUB_TOKEN)
./bin/okf hub push knowledge --password "pass" --secret-key "XXXX-..." --auth-token "my-token"
./bin/okf hub sync knowledge --password "pass" --secret-key "XXXX-..."

# Pull external knowledge bundles from OKF Registry (registry.okf-memory.dev) or Git
./bin/okf pull nextjs-15
./bin/okf pull peter/django-5-rules
./bin/okf pull github.com/acme/agent-rules@v1.0.0

# Restore all locked vendor bundles in fresh environments
./bin/okf restore

# Inspect and manage installed vendor bundles
./bin/okf vendor list
./bin/okf vendor remove nextjs-15

3. Multi-Scope Memory Layering & Scoped Resolution

OKF Agent Memory organises knowledge across four deterministic memory scopes. Higher layers strictly shadow identical concept IDs in lower layers during search, ensuring local project decisions always take precedence over external upstream packages or machine baselines:

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/"]
        V["<b>Vendor</b> (Priority 70)<br/>Prefix: @bundle/... (e.g. @nextjs-15/routing)<br/>Location: .okf/vendor/"]
        U["<b>User</b> (Priority 50)<br/>Prefix: user:... (e.g. user:guidelines/style)<br/>Location: ~/.okf/"]
        S["<b>System</b> (Priority 10)<br/>Prefix: system:... (e.g. system:corp/policy)<br/>Location: /etc/okf/"]
    end

    P -->|shadows| V
    V -->|shadows| U
    U -->|shadows| S

Scope Specification Matrix

| Scope | Link / Reference Syntax | Canonical URN | Storage Location | Priority | Precedence & Rules | | :--- | :--- | :--- | :--- | :--- | :--- | | **`project`** | `decisions/auth.md` | *(bundle relative)* | `./knowledge/` | **100** | **Local Project Memory.** Authoritative SSoT for current repository; strictly shadows identical IDs from vendor, user, and system layers. | | **`vendor`** | `@nextjs-15/routing.md`<br/>`@peter/django-rules/auth.md` | `okf://@nextjs-15/routing`<br/>`okf://@peter/django-rules/auth` | `.okf/vendor/<bundle>/` | **70** | **External Packages.** Pinned dependencies pulled from OKF Registry (`registry.okf-memory.dev`) or Git. Shadows user and system. | | **`user`** | `user:guidelines/style.md` | `okf://user/guidelines/style` | `~/.okf/` | **50** | **Personal Agent Memory.** Developer preferences and cross-project notes. Shadows system. |

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 404 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # OKF Agent Memory
  2. > **A Domain-Neutral, Git-Native Persistent Project Memory for AI Agents based on the Open Knowledge Format (OKF) v0.2.**
  3. [![Specification](https://img.shields.io/badge/Specification-OKF_v0.2-blue.svg)](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md)
  4. [![Tooling](https://img.shields.io/badge/Tooling-Go_1.26_%7C_Zero_Deps-00ADD8.svg)](pkg/okf)
  5. [![CI](https://github.com/okf-memory/okf-agent-memory/actions/workflows/ci.yml/badge.svg)](https://github.com/okf-memory/okf-agent-memory/actions/workflows/ci.yml)
  6. [![Trendshift](https://img.shields.io/badge/Trendshift-%232_Go_Trending-ff5722.svg)](https://trendshift.io/repositories/215663)
  7. [![Protocol](https://img.shields.io/badge/MCP-Ready-purple.svg)](cmd/okf)
  8. [![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
  9. [![Sponsor](https://img.shields.io/badge/Sponsor-%E2%9D%A4-ea4aaa.svg)](https://github.com/sponsors/sknr)
  10. ---
  11. ## 🌟 Overview
  12. Conversations with AI agents reset when context windows close. Valuable architectural decisions, domain discoveries, and operational facts are lost unless stored persistently.
  13. Traditional approaches suffer from two fatal failure modes:
  14. 1. **The Prompt Monolith**: Stuffing all domain knowledge and rules into `AGENTS.md` or `CLAUDE.md` creates massive context bloat and causes **attention drift** (agents ignore critical instructions).
  15. 2. **The RAG Blindspot**: Dumping behavioral rules into vector databases fails because agents never semantically search for operational constraints (e.g. formatting or security rules) during general tasks.
  16. **OKF Agent Memory** resolves this dilemma with the **Dual-Memory Agent Architecture (DMAA)**:
  17. ```mermaid
  18. flowchart TD
  19. subgraph PUSH["1. Normative Working Memory (Push Layer)"]
  20. direction TB
  21. C1["Canonical AGENTS.md (capped at 400 tokens)"]
  22. C2["Domain Codex (Invariants, Ethics, Tone)"]
  23. C3["OKF Memory Bridge (Deterministic Triggers)"]
  24. C4["Agent Action Grammar (AAG) Micro-Syntax"]
  25. end
  26. subgraph PULL["2. Semantic Domain Memory (Pull Layer)"]
  27. direction TB
  28. O1["OKF v0.2 Knowledge Bundle (knowledge/)"]
  29. O2["0 Tokens baseline in system prompt"]
  30. O3["Selective Retrieval via okf_search / okf_show"]
  31. O4["Persistent Graph of Decisions, Facts & Runbooks"]
  32. end
  33. INPUT["User Request"] --> PUSH
  34. PUSH -->|Enforces Domain Codex & Triggers| AGENT["AI Agent (LLM)"]
  35. AGENT -->|Selective Retrieval| PULL
  36. PULL -->|Context & Facts| AGENT
  37. AGENT --> OUTPUT["Deterministic Response"]
  38. ```
  39. ### The Universal Composition Model
  40. In DMAA, every agent configuration is structured by a universal composition:
  41. $$\text{AGENTS.md} = \underbrace{\text{Domain Codex (AAG)}}_{\text{Project Invariants, Tone, Guardrails}} + \underbrace{\text{OKF Memory Bridge}}_{\text{Standardized Triggers: Search-Before-Write}}$$
  42. * **Layer 1: Normative Working Memory (Push Layer)**: A permanent, ultra-compact behavioral codex (capped at 400 tokens) expressed in [**Agent Action Grammar (AAG)**](docs/spec/AGENT_ACTION_GRAMMAR_RFC.md). Loaded at session start, enforcing zero-tolerance invariants.
  43. * **Layer 2: Semantic Domain Memory (Pull Layer)**: An [**OKF v0.2**](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md) knowledge bundle (`knowledge/`) that consumes **0 tokens at baseline** and is queried on-demand in microseconds.
  44. ```mermaid
  45. flowchart TD
  46. L1["1. OKF v0.2 Specification<br/>(Normative Markdown & YAML Format)"]
  47. L2["2. Agent Memory Convention & DMAA<br/>(Dual-Memory Model, Search-Before-Write, Trust)"]
  48. L3["3. Agent Skill & AAG Codex<br/>(Agent Action Grammar, Workflows, Triggers)"]
  49. L4["4. Tooling Layer: Go Library & CLI<br/>(Deterministic Parsing, Validation, BM25, MCP)"]
  50. L5["5. Project Knowledge Corpus<br/>(knowledge/ OKF Bundle)"]
  51. L1 --> L2
  52. L2 --> L3
  53. L3 --> L4
  54. L4 --> L5
  55. ```
  56. ---
  57. ## ⚡ Key Highlights
  58. * **Dual-Memory Cognitive Architecture (DMAA)**: Separates normative push working memory (`AGENTS.md` codex) from semantic pull domain memory (`knowledge/` bundle), completely eliminating prompt bloat.
  59. * **Agent Action Grammar (AAG)**: Ultra-compact, deterministic ASCII micro-syntax saving **~78–85% tokens** compared to natural language prompt instructions.
  60. * **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.
  61. * **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.
  62. * **Zero API Costs for Memory Retrieval**: Local lexical BM25 indexing eliminates recurring vector embedding API costs and network roundtrips.
  63. * **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`).
  64. * **Solves Context Bloat & Memory Rot**: Employs **Progressive Disclosure** (hierarchical `index.md` files and link graphs) so agents only load the exact concepts they need.
  65. * **Search-Before-Write Principle**: Mandates querying existing memory before authoring, preventing concept duplication and hallucinated divergence.
  66. * **Governance & Code-to-Knowledge Binding**: Bind architecture decisions directly to source files via `code_refs` and query active constraints/holds via `--for-path` before modifying code.
  67. * **Truly Domain-Neutral**: Designed for Software Engineering, Coaching, Scientific Research, Literature Reviews, and Operations.
  68. ---
  69. ## 📊 Performance Benchmarks
  70. Built in Go with zero external dependencies, `okf` is engineered for high-frequency agent tool calling loops:
  71. | Benchmark Metric | Python / Vector DB Runtimes (Mem0, Letta) | Deno / Node.js Tooling | **OKF Agent Memory (Go)** |
  72. | :--- | :--- | :--- | :--- |
  73. | **Concept Search Latency** | 150ms – 800ms (Embedding API + Vector DB) | 40ms – 120ms | **< 300 µs (Microseconds, In-Memory BM25)** |
  74. | **Full Corpus Parse & Graph Validation** | 200ms – 1.5s | 80ms – 250ms | **~4.0 ms (50+ concepts, bidirectional graph)** |
  75. | **Process Cold-Start Overhead** | 250ms – 600ms (Python VM boot) | 80ms – 180ms (V8 / Deno boot) | **< 4 ms (Compiled Single Binary)** |
  76. | **Retrieval Cost per 1,000 Queries** | ~$0.10 – $0.50 (Embedding tokens) | $0.00 | **$0.00 (Zero API cost, fully local)** |
  77. | **Memory Footprint (RSS)** | ~120 MB – 350 MB | ~60 MB – 140 MB | **< 15 MB** |
  78. > [!TIP]
  79. > **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](benchmarks/).
  80. ---
  81. ## 🚀 Quickstart
  82. ### 1. Build the Tooling
  83. Clone the repository and compile the standalone `okf` executable:
  84. ```bash
  85. make build
  86. ```
  87. This generates the standalone binary at `bin/okf`.
  88. ### 2. Basic CLI Commands
  89. ```bash
  90. # Validate bundle conformance, graph connectivity, and description drift
  91. ./bin/okf validate knowledge --strict --drift
  92. # Evaluate bundle quality scorecard (3 pillars: maintenance, stewardship, integrity)
  93. ./bin/okf validate knowledge --scorecard
  94. # Gate bundle quality in CI or pre-commit pipelines (fails if score < 80)
  95. ./bin/okf validate knowledge --min-score 80
  96. # Search concepts via in-memory BM25 scoring
  97. ./bin/okf search "architecture layers" knowledge
  98. # Discover constraints and active holds governing a specific source file before editing
  99. ./bin/okf search --for-path pkg/okf/types.go knowledge
  100. # Inspect a concept and its relationships (with --json support)
  101. ./bin/okf show architecture/layers knowledge --json
  102. # Create a new concept with automated log.md and index.md bookkeeping
  103. ./bin/okf create decisions/auth-flow knowledge \
  104. --type Decision \
  105. --title "OAuth2 Authorization Flow" \
  106. --desc "Standardized on PKCE for client authentication."
  107. # Update an existing concept
  108. ./bin/okf update decisions/auth-flow knowledge \
  109. --desc "Updated OAuth2 PKCE token refresh interval."
  110. # Bootstrap full agent memory stack into any target project
  111. ./bin/okf bootstrap /path/to/project --name "My Project"
  112. # Initialize only a bare OKF bundle in any directory
  113. ./bin/okf init my-project/knowledge
  114. # Zero-Knowledge Sync: initialize vault and print Emergency Kit
  115. ./bin/okf hub init-vault knowledge
  116. # Zero-Knowledge Sync: push or sync changes with the Hub (optional: --token or OKF_HUB_TOKEN)
  117. ./bin/okf hub push knowledge --password "pass" --secret-key "XXXX-..." --auth-token "my-token"
  118. ./bin/okf hub sync knowledge --password "pass" --secret-key "XXXX-..."
  119. # Pull external knowledge bundles from OKF Registry (registry.okf-memory.dev) or Git
  120. ./bin/okf pull nextjs-15
  121. ./bin/okf pull nextjs-15 --min-score 80 # Gate bundle quality before installation
  122. ./bin/okf pull peter/django-5-rules
  123. ./bin/okf pull github.com/acme/agent-rules@v1.0.0
  124. # Restore all locked vendor bundles in fresh environments
  125. ./bin/okf restore
  126. ./bin/okf restore --min-score 80 # Gate all restored bundles
  127. # Inspect and manage installed vendor bundles
  128. ./bin/okf vendor list
  129. ./bin/okf vendor remove nextjs-15
  130. ```
  131. ### 3. Multi-Scope Memory Layering & Scoped Resolution
  132. OKF Agent Memory organises knowledge across four deterministic memory scopes. Higher layers strictly shadow identical concept IDs in lower layers during search, ensuring local project decisions always take precedence over external upstream packages or machine baselines:
  133. ```mermaid
  134. flowchart TD
  135. subgraph Scopes ["OKF 4-Tier Memory Hierarchy"]
  136. P["<b>Project</b> (Priority 100)<br/>Prefix: <i>none</i> (e.g. decisions/auth)<br/>Location: ./knowledge/"]
  137. V["<b>Vendor</b> (Priority 70)<br/>Prefix: @bundle/... (e.g. @nextjs-15/routing)<br/>Location: .okf/vendor/"]
  138. U["<b>User</b> (Priority 50)<br/>Prefix: user:... (e.g. user:guidelines/style)<br/>Location: ~/.okf/"]
  139. S["<b>System</b> (Priority 10)<br/>Prefix: system:... (e.g. system:corp/policy)<br/>Location: /etc/okf/"]
  140. end
  141. P -->|shadows| V
  142. V -->|shadows| U
  143. U -->|shadows| S
  144. ```
  145. #### Scope Specification Matrix
  146. | Scope | Link / Reference Syntax | Canonical URN | Storage Location | Priority | Precedence & Rules |
  147. | :--- | :--- | :--- | :--- | :--- | :--- |
  148. | **`project`** | `decisions/auth.md` | *(bundle relative)* | `./knowledge/` | **100** | **Local Project Memory.** Authoritative SSoT for current repository; strictly shadows identical IDs from vendor, user, and system layers. |
  149. | **`vendor`** | `@nextjs-15/routing.md`<br/>`@peter/django-rules/auth.md` | `okf://@nextjs-15/routing`<br/>`okf://@peter/django-rules/auth` | `.okf/vendor/<bundle>/` | **70** | **External Packages.** Pinned dependencies pulled from OKF Registry (`registry.okf-memory.dev`) or Git. Shadows user and system. |
  150. | **`user`** | `user:guidelines/style.md` | `okf://user/guidelines/style` | `~/.okf/` | **50** | **Personal Agent Memory.** Developer preferences and cross-project notes. Shadows system. |
  151. | **`system`** | `system:corp/policies.md` | `okf://system/corp/policies` | `/etc/okf/` | **10** | **Enterprise / Machine Memory.** Infrastructure baselines and compliance policies. |
  152. #### Filtering by Scope in Search & Show
  153. ```bash
  154. # Default (--scope all): Search across all layers with automatic shadowing & priority ranking
  155. ./bin/okf search "authentication"
  156. # Search strictly within vendor packages
  157. ./bin/okf search "routing" --scope vendor
  158. # Search strictly within local project memory
  159. ./bin/okf search "architecture" --scope project
  160. # Search user or system layers
  161. ./bin/okf search "style" --scope user
  162. ./bin/okf search "compliance" --scope system
  163. # Inspect concepts across scopes
  164. ./bin/okf show decisions/auth # Local project concept
  165. ./bin/okf show @nextjs-15/decisions/routing # Vendor package concept
  166. ./bin/okf show user:guidelines/style # Personal user concept
  167. ./bin/okf show system:corp/policies # System compliance concept
  168. ```
  169. #### Bundle Scope Isolation (`scopes` in `knowledge/index.md`)
  170. By default, all four scopes (`project`, `vendor`, `user`, `system`) are active. To isolate a project (e.g. preventing agents in a client or open-source repository from accessing personal `~/.okf/` notes), declare an explicit `scopes` list in the root `knowledge/index.md` frontmatter:
  171. ```yaml
  172. ---
  173. okf_version: "0.2"
  174. scopes: [project, vendor]
  175. ---
  176. ```
  177. * Only the listed scopes are searched under `--scope all` or bare-ID `okf show` fallback.
  178. * Explicit queries targeting a disabled scope (e.g. `okf search --scope user` or `okf show user:secret`) are rejected with an error.
  179. * Empty (`scopes: []`) or non-canonical scope names fail bundle loading and validation immediately (fail-closed).
  180. ### 4. Bundle Quality Scorecards (OpenSSF-Style)
  181. Evaluate knowledge bundles across three weighted pillars to eliminate "reproducibly wrong" context without maintenance chores:
  182. 1. **Epistemic Maintenance (35%):** Invariant version-bound facts without `stale_after` remain 100% valid by default; penalties apply only to lapsed review deadlines or deprecated status.
  183. 2. **Human Stewardship (35%):** Strictly distinguishes verified human sign-offs (`verified.by: human/*` or `user/*`) from unreviewed synthetic bot dumps. Non-human verifications earn 0 stewardship points.
  184. 3. **Graph Integrity (30%):** Strict OKF v0.2 graph health (0 broken links, 0 orphans, valid DAG).
  185. ```bash
  186. # Human-readable scorecard breakdown with Grade (A-F)
  187. ./bin/okf validate knowledge --scorecard
  188. # Machine-readable JSON output
  189. ./bin/okf validate knowledge --scorecard --json
  190. # Quality gating in CI (fails with exit code 1 if score < 80)
  191. ./bin/okf validate knowledge --min-score 80
  192. # Pre-pull quality gating (aborts installation & rolls back if score < 80)
  193. ./bin/okf pull nextjs-15 --min-score 80
  194. ```
  195. ### 5. Bootstrapping Agent Memory in Any Project
  196. Scaffold the complete OKF Agent Memory architecture into any new or existing repository with a single command:
  197. ```bash
  198. # Bootstrap full memory stack into target project
  199. ./bin/okf bootstrap /path/to/my-project --name "My Service"
  200. ```
  201. This automatically sets up:
  202. * `knowledge/` — OKF v0.2 compliant persistent memory bundle (`index.md`, `log.md`)
  203. * `.agents/skills/okf-memory/` — Embedded agent skill definition and capability guides
  204. * `AGENTS.md` — Project-tailored operating instructions for AI coding agents
  205. * `Makefile` — Convenience tasks for validation (`make validate`) and search (`make search q="..."`)
  206. ### 6. Running as an MCP Server
  207. `okf` ships with a native Model Context Protocol (MCP) server over `stdio` to seamlessly connect with Claude Code, Cursor, Codex, and other agent platforms:
  208. ```bash
  209. ./bin/okf mcp knowledge
  210. ```
  211. #### Example MCP Configuration (`claude_desktop_config.json` or Cursor):
  212. ```json
  213. {
  214. "mcpServers": {
  215. "okf-memory": {
  216. "command": "/path/to/okf-agent-memory/bin/okf",
  217. "args": ["mcp", "/path/to/project/knowledge"]
  218. }
  219. }
  220. }
  221. ```
  222. ---
  223. ## 📂 Repository Structure
  224. ```
  225. okf-agent-memory/
  226. ├── .agents/ # Active agent skills and agent configuration
  227. │ └── skills/okf-memory/ # Authoritative OKF memory skill for AI agents (Single Source of Truth)
  228. ├── benchmarks/ # Progressive disclosure benchmark suite & hardware test data
  229. │ ├── data/ # Monolith docs vs OKF bundle test fixtures
  230. │ └── results/ # Reproducible benchmark logs across 8+ local & cloud LLMs
  231. ├── cmd/
  232. │ ├── okf/ # Standalone CLI and embedded MCP server (`stdio`)
  233. │ └── okf-benchmark/ # Automated benchmark runner for LLM TTFT & token measurements
  234. ├── docs/ # Guides, specifications, architecture & release playbook
  235. │ ├── README.md # Central documentation index & navigation
  236. │ ├── guides/ # User guides, CLI/MCP reference & AI instruction best practices
  237. │ ├── spec/ # OKF convention v0.1, compatibility analysis & architecture RFCs
  238. │ ├── security/ # Data governance, secret prevention & adversarial security audits
  239. │ ├── project/ # Project roadmap, release playbook & multi-agent testing
  240. │ └── releases/ # Versioned release notes & changelog archive (v0.1.0 - v0.8.0)
  241. ├── examples/ # Domain-neutral reference DMAA projects (AGENTS.md + OKF v0.2 knowledge/)
  242. │ ├── books/ # Literature & editorial analysis repository
  243. │ ├── coaching/ # Executive coaching & client session repository
  244. │ └── software/ # Microservices architecture & ADR engineering repository
  245. ├── knowledge/ # Project's own OKF v0.2 persistent memory bundle
  246. │ ├── index.md # Root progressive disclosure index (okf_version: "0.2")
  247. │ ├── log.md # Dated change log (ISO 8601 YYYY-MM-DD)
  248. │ ├── project/ # Overview & value propositions
  249. │ ├── architecture/ # 5-tier architecture, governance model & decisions
  250. │ ├── convention/ # Principles & lifecycle workflows
  251. │ └── roadmap/ # Milestones
  252. ├── packaging/ # Distribution packaging
  253. │ └── homebrew/ # Official Homebrew formula & tap instructions
  254. ├── pkg/
  255. │ ├── lock/ # Zero-dependency okf.lock parser & serializer
  256. │ ├── okf/ # Core library (parser, validator, BM25, MCP, bootstrap)
  257. │ │ └── assets/ # Embedded bootstrap templates & skills mirrored via `make sync-assets`
  258. │ ├── registry/ # Decentralized OKF Registry client & archive unpacker
  259. │ ├── sync/ # Blind sync engine, 3-way reconcile & hub client/server
  260. │ └── vault/ # AES-256-GCM envelope crypto, Argon2id KDF & CAS blind storage
  261. ├── AGENTS.md # Operating instructions for AI coding agents
  262. ├── CONTRIBUTING.md # Contribution guidelines & development workflow
  263. ├── CONTRIBUTORS.md # Community contributors & acknowledgements
  264. ├── CODE_OF_CONDUCT.md # Contributor Covenant v2.1 code of conduct
  265. ├── Makefile # Build, test, lint, validation & release targets
  266. ├── LICENSE # MIT License
  267. ├── README.md # Main repository documentation
  268. └── SECURITY.md # Security policy & reporting guidelines
  269. ```
  270. ---
  271. ## 🧪 Testing & Verification
  272. Run the full test suite and validate the repository's self-documenting knowledge bundle:
  273. ```bash
  274. make check
  275. ```
  276. ---
  277. ## 📖 Further Documentation
  278. * [Documentation Index](docs/README.md) — Central directory of all project documentation.
  279. * [Getting Started Guide](docs/guides/GETTING_STARTED.md) — Comprehensive onboarding guide for agents and humans.
  280. * [CLI & MCP Reference](docs/guides/CLI.md) — Complete command-line and protocol tools reference.
  281. * [Dual-Memory Agent Architecture RFC](docs/spec/DUAL_MEMORY_AGENT_ARCHITECTURE_RFC.md) — Cognitive 2-layer agent memory model (Push codex + Pull knowledge).
  282. * [Agent Action Grammar RFC](docs/spec/AGENT_ACTION_GRAMMAR_RFC.md) — Deterministic, token-efficient AAG micro-syntax specification for `AGENTS.md`.
  283. * [Agent Instruction Best Practices](docs/guides/AGENT_INSTRUCTION_BEST_PRACTICES.md) — Guide to deterministic instruction design and token optimization.
  284. * [OKF Agent Memory Convention v0.1](docs/spec/CONVENTION.md) — Behavioral rules and lifecycle specification.
  285. * [Contributing Guide](CONTRIBUTING.md) — Development setup, quality gates, and pull request standards.
  286. * [Security & Privacy Guidelines](docs/security/SECURITY.md) — Data governance, secret prevention, and PII protection rules.
  287. * [Multi-Agent Testing & Evaluation](docs/project/AGENT_TESTING.md) — Test scenarios, compatibility matrix, and benchmarks.
  288. * [Project Roadmap & Milestones](docs/project/ROADMAP.md) — Phased development plan.
  289. * [Release Playbook](docs/project/playbooks/RELEASE_PLAYBOOK.md) — Versioning, CI/CD pipeline, and distribution procedures.
  290. * [Release Notes & History](docs/releases/README.md) — Versioned changelogs and historical release notes archive.
  291. * [OKF v0.2 Compatibility Matrix](docs/spec/OKF-COMPATIBILITY.md) — Specification validation analysis.
  292. * [Why OKF Agent Memory?](knowledge/project/value-proposition.md) — Detailed value proposition & differentiators.
  293. * [Alternatives & Ecosystem Comparison](docs/project/ALTERNATIVES.md) — Comparison with Mem0, Letta, and ad-hoc markdown files.
  294. ---
  295. ## 👥 Contributors
  296. Thank you to all the wonderful contributors who have helped build and refine OKF Agent Memory!
  297. <a href="https://github.com/okf-memory/okf-agent-memory/graphs/contributors">
  298. <img src="https://contrib.rocks/image?repo=okf-memory/okf-agent-memory" alt="OKF Agent Memory Contributors" />
  299. </a>
  300. Contributions of all kinds are warmly welcomed! See [CONTRIBUTING.md](CONTRIBUTING.md) and [CONTRIBUTORS.md](CONTRIBUTORS.md) for details.
  301. ---
  302. ## 💖 Support & Sponsoring
  303. If you find **OKF Agent Memory** valuable for your autonomous agent workflows, consider [sponsoring the project on GitHub](https://github.com/sponsors/sknr) to help support continuous development, security hardening, and spec compliance!
  304. ---
  305. ## 📄 License
  306. MIT License. See [LICENSE](LICENSE) for details.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.