v0.5.0

Release v0.5.0: OKF Registry, Dependency Locking & Multi-Scope Vendor Layering

Release v0.5.0 introduces native package management and multi-scope knowledge layering to the OKF ecosystem. With the launch of the official OKF Registry (https://registry.okf-memory.dev), agents and developers can now distribute, pull, lock, and compose external knowledge bundles alongside local project memory with deterministic precedence, cryptographic verification, and hermetic cross-scope linking.

---

1. OKF Registry Integration & Package Resolution

• Decentralized Registry Client (pkg/registry):
  • Connects to the canonical registry at https://registry.okf-memory.dev with support for private mirrors via --registry <url> and OKF_REGISTRY_URL.
  • Supports both scoped (@org/bundle) and top-level (bundle) package slugs.
  • Resolves explicit semantic versions (@1.2.0, @v1.2.0), tags (@latest), and direct Git repository archives (github.com/org/repo@vX.Y.Z).
  • Warns when pulling floating branch targets, encouraging immutable version tags.
• On-the-Fly Archive Extraction & Knowledge Promotion:
  • Automatically flattens root container directories in GitHub release archives.
  • Stream-filters and promotes standard knowledge/ directories from DMAA repositories directly into .okf/vendor/<bundle-id>/ without disk churn or repository root pollution.
• Cryptographic Integrity & Rollback Failsafe:
  • Verifies downloaded archives against SHA-256 integrity checksums.
  • Executes immediate post-install validation (okf validate); any validation failure or broken graph triggers an automatic, clean rollback.

2. Zero-Dependency Lockfile (okf.lock)

• Standardized okf.lock Specification (pkg/lock):
  • Deterministically tracks installed vendor packages, source URLs, pinned versions, SHA-256 checksums, and installation timestamps.
  • Pure Go implementation with zero external dependencies, adhering strictly to the repository's zero-dependency invariant.
• Deterministic Restoration:
  • okf restore: Re-installs and validates all declared dependencies from okf.lock in fresh environments and CI/CD pipelines.

3. Package Management Subcommands (internal/cli)

• okf pull [<bundle-id|git-url>]:
  • Installs a dependency, verifies it, writes .okf/vendor/<bundle-id>/, and records it in okf.lock.
  • When called without arguments, seamlessly falls back to restoring all locked bundles.
• okf restore:
  • Restores all dependencies declared in okf.lock with optional --force reinstallation.
• okf vendor:
  • okf vendor list: Displays installed vendor bundles, versions, and paths.
  • okf vendor remove <bundle-id>: Cleans the bundle directory from .okf/vendor/, safely handles namespace parent directories, and prunes okf.lock.

4. Multi-Scope Composite BM25 Indexing & Cross-Scope Linking (Closes #11)

• Multi-Scope Priority Layering (pkg/okf/scope.go):
  • Establishes a 4-tier scope hierarchy: project (priority 100), vendor (priority 70), user (priority 50), and system (priority 10).
  • Enforces local shadowing: local project concepts in knowledge/ override vendor concepts with identical IDs, which in turn shadow user and system concepts.
• Scope Specification Matrix:

Scope	Link / Reference Syntax	Canonical URN	Storage Location	Priority	Precedence & Behavior
project	decisions/routing.md	(bundle relative)	./knowledge/	100	Authoritative local project memory. Strictly shadows identical IDs across vendor, user, and system layers.
vendor	@nextjs-15/routing.md @peter/django-rules/auth.md	okf://@nextjs-15/routing okf://@peter/django-rules/auth	.okf/vendor/<bundle>/	70	External packages pulled via okf pull. Strictly shadows user and system layers.
user	user:guidelines/style.md	okf://user/guidelines/style	~/.okf/	50	Personal developer preferences and cross-project notes. Strictly shadows system layer.
system	system:corp/policies.md	okf://system/corp/policies	/etc/okf/	10	Machine-level and enterprise compliance standards.

• Layer-Filtered Search (--scope):
  • okf search supports --scope <all|project|bundle|vendor|user|system> (default: all).
  • Cross-scope searches normalize BM25 scores while ranking strictly by layer priority.
• Hermetic Cross-Scope Linking:
  • Vendor references use clean package identifiers: @<bundle-id>/<concept-id>.md (e.g. @peter/django-5-rules/decisions/auth.md or @nextjs-15/decisions/routing.md).
  • User and System references use collision-free URN shorthands: user:<concept-id>.md and system:<concept-id>.md.
  • Strict boundary disambiguation: identifiers with leading @ resolve into .okf/vendor/, while references without @ strictly search the local project bundle (knowledge/).
  • Bundle validation (okf validate --strict) recognizes all external references (@, user:, system:, okf://, https://) without emitting broken links or orphan false-positives, guaranteeing 0 broken links in standalone CI.

---

Community & Special Thanks

• Ritsu Kuroda (@kurodaritsu): For initiating the multi-scope bundle memory proposal (#11) and detailed analysis of multi-bundle IDF ranking dynamics.
• MemContinuum & OKF Community: Invaluable architectural discussions regarding multi-scope memory layering, dependency composition, and epistemic boundaries.

---

Pre-Built Binaries

Pre-compiled standalone binaries for macOS, Linux, and Windows are available in the release assets on GitHub:

• macOS (darwin/arm64, darwin/amd64)
• Linux (linux/amd64, linux/arm64)
• Windows (windows/amd64, windows/arm64)

Full Changelog

See commits between v0.4.4...v0.5.0 on GitHub.