v0.2.0

OKF Agent Memory v0.2.0 — Epistemic Governance & Code Binding

Major Milestone Release: Introducing 3-Tier Epistemic Governance, Code-to-Knowledge Binding (code_refs), Scoped Pre-Edit Discovery (--for-path), Automated Dogfooding Parity Gates, and Hardened Path Security (CWE-22).

We are thrilled to release OKF Agent Memory v0.2.0! This milestone marks a major evolution in how autonomous coding agents interact with project memory: shifting from passive, flat text retrieval to active, code-aware epistemic governance.

---

🌟 Highlights & Major Features

1. 3-Tier Epistemic Governance Model (governance: constraint | hold | context)

AI agents frequently suffer from "authority blindness"—treating non-negotiable architectural mandates with the same casual weight as advisory background notes. OKF v0.2.0 establishes an explicit 3-tier epistemic governance model:

• constraint (Mandatory Guardrail): The agent may modify code, but must strictly adhere to the constraints defined in this document (e.g. pure standard library Go, zero external dependencies, security trust boundaries).
• hold (Execution Freeze): The referenced code paths are undergoing active refactoring, migration, or security lockdown. The agent must not modify the referenced code files without explicit human signoff. (The concept is loaded into context as an active barrier).
• context (Advisory Background): Informational domain knowledge, system rationale, or past history. Helps reasoning without restricting actions.

Zero-Boilerplate Ergonomics

To keep YAML clean and eliminate ceremony, governance is inferred automatically via EffectiveGovernance():

• Files under knowledge/convention/ implicitly default to constraint.
• Domain and architecture files implicitly default to context.
• Explicit governance: in frontmatter always overrides defaults.

---

2. Code-to-Knowledge Binding (code_refs) & Pre-Edit Discovery (--for-path)

Concepts can now declare the exact source code files, modules, or directories they govern via the code_refs frontmatter attribute:

---
type: Decision
title: Ed25519 Stateless JWT Tokens
governance: constraint
code_refs:
  - services/auth/jwt/**
  - pkg/auth/**
---

Fast Pre-Edit Scoped Checks (CLI & MCP)

Before starting substantial work on a subsystem, an agent queries governing rules in sub-300 microseconds:

# Deterministic CLI
okf search --for-path services/auth/jwt/token.go knowledge

# Native MCP Tool
okf_search({ "for_path": "services/auth/jwt/token.go" })

Results are prioritized by governance authority (hold > constraint > context), providing immediate clarity on what is allowed before any code edits take place.

Path Resilience & Normalization

The matching engine (matchCodeRef) seamlessly normalizes paths across all environments:

• Relative paths (pkg/okf/types.go)
• Leading dot-slashes (./pkg/okf/types.go)
• Leading slashes (/pkg/okf/types.go)
• Windows backslashes (pkg\okf\types.go)
• Full absolute IDE system paths (/Users/.../pkg/okf/types.go) via automatic suffix and subpath resolution.

---

3. Automated Dogfooding Safeguards & Embedded Asset Sync

This repository dogfoods its own agent memory conventions. To prevent drift and protect external third-party users:

• Single Source of Truth: .agents/skills/okf-memory/ is the authoritative source for agent skills.
• Embedded Bootstrap Assets: pkg/okf/assets/skill/ contains the embedded copy distributed via okf bootstrap.
• Sync Command: make sync-assets synchronizes active skills to embedded assets.
• Automated CI Gate: TestDogfoodingAssetDrift in pkg/okf/dogfood_test.go runs during make check and fails if assets drift or if internal repository paths leak into the generic scaffold template pkg/okf/assets/templates/AGENTS.md.

---

4. Security & Boundary Hardening (CWE-22 / CWE-59)

• Code Reference Traversal Prevention: ValidateBundle explicitly validates code_refs and rejects any .. path traversal or absolute system paths (/etc/..., C:\...) as fatal GateFindings.
• Drift Check Boundary: okf validate --drift verifies code reference existence while strictly confining file checks within the project root, preventing side-channel file probing.
• MCP Server Root Confinement: resolveBundleDir strictly enforces that the bundle argument stays within the server's canonical workspace root.
• Gosec Clean: Static analysis passes with 0 findings across all packages.

---

5. CLI & Engine Enhancements (Community Contributions)

• CLI Flag Preservation (#14): Fixed an argument-parsing bug where flag values were silently discarded when the bundle path was omitted. Contributed by Denis Samatov (@denis-samatov).
• GitFlow & Issue-First Policy (#19): Transitioned active development to develop with main reserved for tagged releases, and established the Issue-First workflow. Contributed by @dajiaohuang.

---

👥 Community Acknowledgements & Credits

We extend our deep gratitude to the community members whose contributions and ideas shaped this release:

• @krakozavr: Author of MemContinuum. The architectural design of OKF's 3-tier epistemic governance model (constraint, hold, context), code_refs binding, and solving agent amnesia / code fragmentation was directly inspired by concepts in MemContinuum.
• Denis Samatov (@denis-samatov): For PRs #14, #15, #16, and #17 improving CLI argument parsing, Windows relative links, and open actor prefixes.
• @dajiaohuang: For PR #19 and collaborative workflow improvements.

---

📦 Verification & Conformance

• Spec Conformance: 100% OKF v0.2 compliant (make validate-all).
• Dependencies: Pure Go standard library (0 external dependencies).
• Test Suite: 100% passing tests with -race enabled.
• Security Audit: Passed (0 High/Critical).

---

🚀 Getting Started with v0.2.0

Homebrew (macOS / Linux)

brew update
brew upgrade okf

Go Install

go install github.com/okf-memory/okf-agent-memory/cmd/okf@v0.2.0

Standalone Binary

Download pre-compiled binaries for ARM64 and x86_64 from the GitHub Releases page.