Skip to content

v0.8.0

Latest
Latest

Choose a tag to compare

View all tags
@github-actions github-actions released this 05 Nov 22:47
v0.8.0
This tag was signed with the committer’s verified signature.
sknr Stephan Knauer
SSH Key Fingerprint: dG8YAu7mgXjucmJVpCx3dsUmCkCHbrHvaCQwgAkb+Ps
Verified
Learn about vigilant mode.
1a6303d
This commit was signed with the committer’s verified signature.
sknr Stephan Knauer
SSH Key Fingerprint: dG8YAu7mgXjucmJVpCx3dsUmCkCHbrHvaCQwgAkb+Ps
Verified
Learn about vigilant mode.

Release v0.8.0: Bundle Scope Isolation, Concurrent Write Protection & Multi-Writer Sync Hardening

Release v0.8.0 introduces declarative Bundle Scope Isolation via scopes in the root knowledge/index.md frontmatter, adds Two-Stage Concurrent Local Write Protection (WithBundleLock and ErrConcurrentModification), hardens multi-writer Hub Sync conflict forks (#60, PR #66), wires automatic SSoT tool symlinks into okf bootstrap, and removes the legacy bundle alias for --scope across the CLI and MCP server. Because removing the --scope bundle alias is a breaking CLI/MCP schema change, this is a minor release (v0.8.0).

1. Breaking Changes & Migration

  • Removed the legacy bundle alias for --scope (okf search and MCP okf_search).
    • --scope now accepts only the canonical scope names: all, project, vendor, user, and system.
    • Passing --scope bundle (or "scope": "bundle" in MCP okf_search) now returns an invalid-scope error.
    • Migration: Replace --scope bundle with --scope project. The --bundle <dir> flag and the MCP "bundle" directory parameter remain unchanged.

2. Features

  • Declarative Bundle Scope Isolation (scopes in root knowledge/index.md).

    • Projects (such as client repositories, open-source projects, or isolated domains) can now restrict which memory layers are active by declaring an explicit scopes list in the root knowledge/index.md frontmatter (both flow lists and block lists are supported): 
      ---
okf_version: "0.2"
scopes: [project, vendor]
---
    • Default Behavior: When scopes is omitted, all four canonical scopes (project, vendor, user, system) remain active.
    • Implicit Filtering: Disabled scopes (e.g. user and system in the example above) are automatically skipped during --scope all searches (SearchLayered) and bare-ID okf show / okf_show fallback (ResolveScopedConcept).
    • Strict Enforcement: Explicit queries targeting a disabled scope (e.g. okf search --scope user, okf show user:secret, or okf://user/secret) are rejected with an error: scope "user" is disabled by bundle configuration in index.md (allowed: project, vendor).
    • Fail-Closed Validation: Declaring an empty scopes key (scopes: [] or scopes:) or any non-canonical value (such as all, bundle, or a typo) immediately fails bundle loading and okf validate.

  • Two-Stage Concurrent Local Write Protection (WithBundleLock & Optimistic Concurrency Check).

    • Stage 1 – Cross-Process Bundle Write Lock (.okf-write.lock): InitBundle, SaveConcept, UpdateConcept, RelateConcepts, UpdateParentIndex, and AppendLogEntry now serialize local Read-Modify-Write transactions across concurrent processes and goroutines (e.g. parallel subagents or multiple IDE MCP servers sharing knowledge/ or ~/.okf/) using an atomic O_CREATE|O_EXCL bundle lockfile with bounded backoff and automatic stale-lock recovery.
    • Stage 2a – Transactional RMW Serialization (UpdateConcept & RelateConcepts): CLI okf update, MCP okf_update, CLI okf relate, and MCP okf_relate now acquire the bundle write lock before loading and mutating the target concept, preventing concurrent field updates or link insertions on the same concept from overwriting each other.
    • Stage 2b – Optimistic Concurrency Check (ErrConcurrentModification): LoadBundle records the on-disk SHA-256 content digest of each concept; if a caller mutates a pre-loaded Concept struct and calls SaveConcept after an external write modified that file on disk, SaveConcept detects the digest mismatch inside the lock and rejects the stale overwrite with ErrConcurrentModification.

  • Automatic SSoT Tool Symlinks in okf bootstrap.

    • okf bootstrap now automatically creates the canonical SSoT tool symlinks (CLAUDE.md, .cursorrules, .windsurfrules, and .github/copilot-instructions.md pointing to AGENTS.md) whenever AGENTS.md is installed, so freshly bootstrapped repositories pass okf validate --agents and okf agents check out of the box. Can be skipped via --no-symlinks.

3. Bug Fixes

  • Distinct Conflict Fork Paths for Multi-Writer Hub Sync (Fixes #60, PR #66).
    • ApplyConflictFailsafe and HubSync now compute conflict fork paths via ConflictForkPath, appending the first 8 hex characters of the local entry's plaintext_hash (<name>.conflict-local-<hash8>.<ext>). When three or more devices edit the same concept from the same base and sync sequentially, a later conflicting writer no longer overwrites an earlier device's committed conflict fork.

4. Documentation & Knowledge

5. Community & Special Thanks

  • A huge thank you to Cordero Core (@cdcore09) for reporting and isolating the three-writer conflict fork overwrite in okf hub sync (#60).
  • A huge thank you to fchengyan (@fcy222fcy) for implementing distinct plaintext-hash conflict fork paths (ConflictForkPath) and three-writer regression tests (#66).

🌐 Discover & Share Knowledge: OKF Registry

Scale persistent memory across projects and agent sessions with the decentralized OKF Registry:

  • Browse & Share: Discover curated, quality-scored memory packages (e.g. framework best practices, architecture rules, compliance guidelines) at registry.okf-memory.dev.
  • Install in Seconds: Pull external knowledge directly into .okf/vendor/ with zero dependencies: 
    okf pull <bundle-id>
  • Guaranteed Conformance: Every package is verifiable against Open Knowledge Quality Scorecards (--min-score) with atomic rollback to ensure deterministic agent consumption.

Pre-built Binaries & Verification

Release binaries are automatically built by GitHub Actions:

Full Changelog

Full Changelog: v0.7.2...v0.8.0

Assets 10
Loading