Multi-Arch Container Distribution (ghcr.io/abcubed3/okf:latest): Official distroless images for Linux AMD64 and ARM64 published to GitHub Container Registry, ready for CI linting and containerized MCP servers.
Strict Conformance Linter (): Elevate soft validation warnings (missing titles/descriptions, unverified links) to hard errors to enforce zero-defect quality gates in CI/CD pipelines.
The OKF-go provides a high-performance suite of utilities to validate bundles, harvest metadata from databases and APIs, assemble context for Large Language Models (LLMs), and run an MCP Server.
星标
9
工具
—
可用率
—
okf lint --strict
Opinionated AI Agent Skill (okf skill): Compile any knowledge bundle into an active SKILL.md or install the official OKF skill (okf skill install) with embedded references (spec-v02.md, create-bundle.md, cli-cheatsheet.md) and examples for Antigravity, Claude Code, Cursor, Windsurf, and Codex.
Grounded AI Q&A (okf ask): Natural language question answering directly from the CLI backed by deterministic BFS context assembly and Gemini generative AI, citing verified concept files and verbatim attested computations.
Attested Computation & Trust Layer (OKF Spec v0.2): Native support for provenance (sources), freshness (stale_after), verification tiers (generated/verified), and reproducible computations (type: Attested Computation).
Unified CLI Architecture: All toolchains (lint, harvest, assemble, mcp, skill, ask, doc, lsp, sync, export, diff, merge) consolidated into a single, high-performance okf executable.
The Open Knowledge Format (OKF) is a vendor-neutral, lightweight specification for structuring organizational knowledge (documentation, runbooks, metrics, database schemas, and API definitions) into machine-readable, human-friendly Markdown files.
By representing knowledge as a directory of Markdown files with structured YAML frontmatter, OKF bridges the gap between structured metadata repositories and unstructured text documentation, serving as an ideal substrate for AI agents, Retrieval-Augmented Generation (RAG) pipelines, and the Model Context Protocol (MCP). OKF-go provides native, full-featured support for OKF Specification v0.2, including its Trust Layer and Attested Computation.
📄 Knowledge Format Specification (OKF Spec v0.2)
The Open Knowledge Format (OKF) is an open, vendor-neutral specification developed by Google Cloud for representing structured metadata as plain Markdown files with YAML frontmatter. For the full format specification, conventions, schema details, and reference examples, see the official Google Cloud OKF Specification.
The OKF-go provides a high-performance suite of utilities to validate bundles, harvest metadata from databases and APIs, assemble context for Large Language Models (LLMs), and run an MCP Server.
📜 OKF v0.2 Concept Examples
OKF v0.2 introduces a trust layer (status, stale_after, sources, generated, verified) and Attested Computation (type: Attested Computation).
---
type: "Attested Computation"
title: "Sanctioned MRR Calculation Query"
description: "Audited and attester-approved BigQuery SQL for computing MRR."
resource: "bigquery.analytics.mrr_query"
tags:
- "finance"
- "revenue"
- "kpi"
status: "stable"
runtime: "bigquery"
parameters:
- name: "year"
type: "integer"
required: false
executor:
resource: "references/skills/run-on-bq.md"
receipt: ["job_id", "executed_sql", "result"]
attester:
resource: "references/attesters/sql-equality.py"
generated:
by: "okf-ai-curator"
at: "2026-08-01T12:00:00Z"
verified:
- by: "human:[email protected]"
at: "2026-08-01T12:20:00Z"
tier: "human"
stale_after: "2027-01-01T00:00:00Z"
sources:
- id: "rev-policy"
resource: "https://wiki.acme/finance/revenue-recognition"
title: "Revenue Recognition Policy"
---
# Computation
SELECT
DATE_TRUNC(created_at, MONTH) AS revenue_month,
SUM(amount) AS total_mrr
FROM `my-project.analytics.subscriptions`
WHERE status = 'active'
GROUP BY 1
This concept defines the sanctioned, audit-verified computation logic for financial reporting.[^rev-policy]
[^rev-policy]: Revenue Recognition Policy
[!NOTE]
OKF v0.2 Attested Computations define a runtime, typed parameters, executor, and attester, evaluated via deterministic verification recipes. The CLI also provides backward compatibility for legacy type: Attestation concepts.
OKF v0.2 Trust Signals & Attestation: Native support for the v0.2 Trust Layer, including Provenance (sources), Trust Verification (generated/verified), Freshness Expiration (stale_after), Lifecycle Status (status), and Attested Computation (type: Attested Computation).
Conformance Engine & Linter (okf lint): Validates knowledge bundles for YAML frontmatter correctness, required attributes, broken internal links, and OKF v0.2 trust signal compliance. Supports --strict to fail on soft warnings in CI/CD pipelines.
Metadata Harvesters (okf harvest): Automatically extracts and converts schemas from databases (PostgreSQL, MySQL, Cloud Spanner, BigQuery), OpenAPI specs, Protobuf files, Git repositories, and web pages into OKF concept documents.
Context Assembler (okf assemble): Performs graph-based Breadth-First Search (BFS) starting from a core concept, resolving related concepts within a specified character/token budget to build pruned, high-quality prompt context.
Agent Skills Engine (okf skill): Compile OKF knowledge bundles into production-grade AI Agent Skills (SKILL.md) for Antigravity, Claude, Cursor, and Codex, arming autonomous agents with verified schemas, attested SQL queries, and domain rules. Also provides okf skill install for deploying the official OKF skill into workspaces (.agents/skills/okf, .claude/skills/okf, .cursor/skills/okf).
Grounded AI Q&A (okf ask): Query verified organizational knowledge using graph BFS context assembly + Gemini generative AI, providing grounded answers with source concept citations and verbatim attested computation queries.
Model Context Protocol Server (okf mcp): Exposes your knowledge base directly to MCP-compatible AI clients (e.g. Claude Desktop, Cursor, Antigravity) via Stdio or HTTP transport, with built-in tools for search, context assembly, dynamic skill compilation, and grounded Q&A.
Bundle Operations (okf diff / okf merge): Compare two OKF bundles for structural and content differences, or merge them to unify distributed knowledge bases.
AI Curator (--ai-enrich flag): AI-powered concept curation during metadata harvesting to automatically generate business descriptions and categorize concepts using Gemini models.
JSON-LD & Skill Export (okf export): Export your OKF graph into JSON-LD format for the semantic web or directly into Agent Skills.
Interactive HTML Portal Compiler (okf doc): Compiles an OKF bundle into an interactive static web application with search, tagging, and link relationship graphs.
Language Server Protocol Daemon (okf lsp) & VS Code Extension: Runs an LSP server over Standard I/O to publish diagnostic errors/warnings in real-time inside IDEs. A dedicated VS Code Extension is also available.
Bi-directional Sync Daemon (okf sync): Automatically synchronizes local concepts with remote document nodes in Notion, Confluence, Jira, and Google Drive.
Blazing Fast Performance: Highly optimized Go architecture parsing ~97k concepts/sec, completing full 200-node graph BFS traversals in <40µs, and validating 100-concept bundles in ~125µs.
📦 Installation and Distribution
This section details how to install and run the pre-built okf CLI binaries, how developers can automate releases, and how to structure and bundle OKF repositories.
1. Installing the Pre-Built CLI
You can install the okf CLI without building it from source using the options below:
Linux (64-bit AMD64):okf_<version>_linux_amd64.tar.gz
Linux (ARM64 / Graviton):okf_<version>_linux_arm64.tar.gz
Windows (64-bit):okf_<version>_windows_amd64.zip
Extract the binary and add it to your system's PATH.
Option C: Go Install (Build from Source)
If you have Go installed, you can compile and install the CLI directly from the GitHub repository:
go install github.com/abcubed3/okf@latest
Ensure your GOBIN directory (typically $HOME/go/bin or $GOPATH/bin) is in your system's PATH.
Option D: Docker
GoReleaser publishes a multi-platform image to GitHub Container Registry for
each release, using the same Linux binaries as the downloadable release
archives. The runtime is a minimal, non-root Debian 13 distroless image, and
the entrypoint is okf, so Docker arguments are passed to the CLI as
subcommands.
docker pull ghcr.io/abcubed3/okf:latest
Lint a bundle mounted from the current directory:
docker run --rm -v "$(pwd):/bundle:ro" ghcr.io/abcubed3/okf:latest lint /bundle
Run MCP over HTTP with Docker Compose. Save this as compose.yaml and change
my_bundle_location to the path to your bundle:
An OKF Knowledge Bundle is a structured directory of Markdown files. Bundles can be versioned, archived, and distributed easily.
Folder Structure Layout
A typical bundle layout looks like this:
my-knowledge-bundle/
├── index.md # Optional directory index for progressive disclosure
├── log.md # Optional change history log
├── tables/ # Conceptual namespace for DB tables
│ ├── users.md
│ └── orders.md
├── apis/ # Conceptual namespace for API routes
│ └── create_user.md
└── playbooks/ # Runbooks and guides
└── database_cleanup.md
Compressing the Bundle for Distribution
To distribute a bundle (e.g., to upload to an ingestion pipeline, send to an agent, or attach to a deployment artifact), you can compress the bundle folder:
Using tar (Gzipped Tarball):
# Compress the bundle
tar -czvf my-bundle-v1.0.tar.gz -C my-knowledge-bundle/ .
# Extract the bundle
tar -xzvf my-bundle-v1.0.tar.gz -C /path/to/destination/
Using zip:
# Compress the bundle
zip -r my-bundle-v1.0.zip my-knowledge-bundle/
# Extract the bundle
unzip my-bundle-v1.0.zip -d /path/to/destination/
[!TIP]
GitOps Distribution: Because OKF bundles are plain-text Markdown files, the recommended way to distribute, track changes, and review updates to your knowledge graph is via Git. You can run okf lint as a pre-commit hook or CI/CD workflow step.
💻 CLI Commands & Detailed Documentation
1. Linter & Validator (lint)
Ensures that the knowledge bundle conforms to the specification. It verifies YAML syntax, ensures required fields are set, and checks that internal Markdown links are not broken.
# Lint the bundle in the current directory
okf lint
# Lint a bundle at a specific directory
okf lint /path/to/my-bundle
# Enforce strict conformance (treat validation warnings as errors, ideal for CI/CD)
okf lint /path/to/my-bundle --strict
Flags
path: Path to the knowledge bundle directory (default: . or current directory).
--strict: Fails with exit code 1 if any warnings are detected (such as missing recommended fields or orphaned internal links).
--host: Host URL for remote concept resolution via OKF Hub (default: http://localhost:8080).
--api-key: API key for authenticated OKF Hub requests.
Conformance Rules
Hard Rules (Fails with Error):
Syntactically valid YAML frontmatter.
Presence of the type field in frontmatter.
Required fields for Attested Computations (runtime).
Soft Rules (Emits Warning; Fails with --strict):
Presence of recommended fields (title, description).
Resolves and verifies all relative Markdown links (e.g. [Users](users.md)) to guarantee the graph is fully connected and lacks orphaned links.
Extracts metadata from databases, API specs, protobuf files, git repositories, and web pages, generating structured OKF concepts automatically.
A. Database Schema Harvesting (harvest db)
Supports PostgreSQL, MySQL, Cloud Spanner, and BigQuery. Connects to the database, queries the information schema, and generates tables, columns, constraints, and relationships as OKF concepts.
# PostgreSQL Example
okf harvest db \
--driver postgres \
--conn "postgresql://postgres:password@localhost:5432/my_db?sslmode=disable" \
--schema public \
--output ./my-bundle/tables
# MySQL Example
okf harvest db \
--driver mysql \
--conn "user:password@tcp(localhost:3306)/my_db" \
--output ./my-bundle/tables
# Cloud Spanner Example
okf harvest db \
--driver spanner \
--conn "projects/my-project/instances/my-instance/databases/my-db" \
--output ./my-bundle/tables
# BigQuery Example
okf harvest db \
--driver bigquery \
--conn "projects/my-project" \
--dataset "my_dataset" \
--output ./my-bundle/tables
B. OpenAPI Spec Harvesting (harvest openapi)
Parses OpenAPI spec documents (JSON/YAML) and generates OKF concepts representing API endpoints.
# Harvest an OpenAPI spec and output to a bundle
okf harvest openapi
--spec ../openapi-sample.yaml
--output harvested-endpoints
C. Protobuf Schema Harvesting (harvest proto)
Extracts messages, RPC services, and field definitions from .proto schemas.
okf harvest proto \
--path ./protos/user_service.proto \
--output ./my-bundle/protobufs
D. Git Repository Harvesting (harvest git)
Extracts metadata from a Git repository, turning commits, file structures, and architecture documents into OKF concepts.
Crawls target URLs to scrape documentation and structure it as OKF concepts. Optionally powered by the AI Curator (--ai-enrich flag) to automatically generate business descriptions and enrich concepts using Gemini models.
Traverses the concept relationship graph starting from a target concept ID. Follows relative markdown links up to a configured traversal depth to compile a unified context document for LLMs.
--bundle: Path to the OKF bundle (default: . or current directory).
--depth: Maximum depth of link traversal (default: 2).
--direction: Traverse outbound, inbound, or bidirectional links (default: bidirectional).
--format: Output format, either xml or markdown (default: xml).
--max-chars: Maximum character budget for the output. If exceeded, traversal stops to prevent context overflow (default: 16000).
4. Model Context Protocol Server (mcp)
Exposes the OKF graph as an MCP Server. This allows LLM clients (like Antigravity, Claude Desktop or Cursor) to dynamically discover, search, retrieve, and assemble context from the bundle.
To register the OKF-go MCP server with Claude Desktop, add the server to your claude_desktop_config.json (typically located at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS or %APPDATA%\Claude\claude_desktop_config.json on Windows):
Note: If okf is not in your system PATH, provide the absolute path to your okf executable.
Exposed MCP Capabilities
Resources:
okf://index: A text/markdown list of all concepts in the bundle.
okf://concept/{id}: Resolves the complete document for a concept by its ID.
Prompts:
okf_concept_context: Automatically generates an analysis prompt for a concept along with its assembled subgraph.
Tools:
list_concepts: Returns summaries of all concepts.
search_concepts: Search matching terms in concept IDs, titles, descriptions, and tags.
get_concept: Fetch raw contents of a concept.
assemble_context: Run depth-traversal context assembly dynamically from the LLM.
export_agent_skill: Compile the bundle (or filtered tags) into an Agent Skill (SKILL.md) dynamically.
ask_knowledge_base: Perform grounded Q&A over the knowledge graph with trust verification.
5. Interactive HTML Portal Compiler (doc)
Compiles an OKF knowledge bundle into a fully self-contained static HTML documentation portal featuring search, tagging, and link graphs.
# Compile bundle in current directory to docs/ folder
okf doc
# Compile specific bundle to custom directory
okf doc --bundle /path/to/my-bundle --output /var/www/okf-portal
--bundle: Path to the OKF bundle (default: .).
--output: Output path for the static website files (default: docs).
6. Language Server Protocol Daemon (lsp)
Integrates OKF validation directly into your IDE. The LSP daemon runs over standard input/output to report conformance linter diagnostics (missing types, broken relative links) as you type.
# Start Language Server over Stdio
okf lsp
To use with Cursor or VS Code, configure your LSP client to invoke okf lsp for markdown files.
7. Bi-directional Sync Daemon (sync)
Keeps your OKF knowledge bundle in sync with remote document nodes. The sync daemon queries local changes and pushes them, while pulling remote updates from your workspace.
# Perform a single sync cycle
okf sync --config okf.yaml
# Run continuously as a daemon
okf sync --config okf.yaml --daemon --interval 300
Configuration (okf.yaml)
Create an okf.yaml file in the bundle directory to define connector credentials:
Bridge organizational knowledge directly into autonomous coding agents (Google Antigravity, Claude Code, Cursor, Windsurf, GitHub Copilot).
A. Exporting a Bundle to an Agent Skill (okf skill export)
Compiles an OKF bundle or filtered tag subset into an authoritative SKILL.md file containing verified schema dictionaries, business metric rules, and sanctioned computation queries:
# Compile entire bundle into an Agent Skill
okf skill export --bundle ./knowledge --output .agents/skills/data-warehouse/SKILL.md --name "data-warehouse"
# Filter by domain tags and types
okf skill export --bundle ./knowledge --output .agents/skills/finance/SKILL.md --name "finance" --tags "finance,revenue"
# Using unified export command
okf export skill --bundle ./knowledge --output ./SKILL.md
B. Installing the Official OKF Skill (okf skill install)
Installs the official, self-contained OKF Agent Skill into your project or IDE configuration:
# Install into default workspace location (.agents/skills/okf)
okf skill install
# Target specific agent platforms
okf skill install --platform antigravity # Installs to .agents/skills/okf
okf skill install --platform claude # Installs to .claude/skills/okf
okf skill install --platform cursor # Installs to .cursor/skills/okf
okf skill install --dir /path/to/dir # Installs to an explicit directory
The installed skill is packaged directly into the okf binary via Go embed and deploys a complete agent knowledge system:
SKILL.md: Opinionated guidelines for autonomous agents on how to ground claims in evidence, respect trust verification tiers, honor sanctioned computations, and validate edits with okf lint.
references/spec-v02.md: The complete OKF Specification v0.2 reference.
references/create-bundle.md: Step-by-step guide for creating, structuring, and indexing new knowledge bundles.
references/cli-cheatsheet.md: Cheatsheet for all okf CLI commands and options.
examples/: Working sample concepts for metrics, database schemas, and attested computations.
9. Grounded AI Q&A (ask)
Query verified organizational knowledge from the command line using deterministic graph BFS context assembly combined with Gemini generative AI:
# Ask a question across the knowledge bundle
okf ask "How is monthly recurring revenue calculated and which table stores subscriptions?" --bundle ./knowledge
# Direct to a specific seed concept with deeper graph traversal
okf ask "What are the downstream dependencies of users?" --seed tables/users --depth 3 --bundle ./knowledge
# Output raw answer text (ideal for piping into agent prompts or scripts)
okf ask "What is the sanctioned query for MRR?" --bundle ./knowledge --raw
🤝 Contributing
Contributions are welcome! Please read our Contributing Guide to learn how to set up your development environment, run linters, execute unit tests, and submit pull requests.
Telemetry
When --remote is enabled, the CLI sends an anonymous mcp_start_remote telemetry event to the OKF Hub. To use the local MCP server without sending this event, explicitly set --remote=false:
OTEL_SDK_DISABLED=true okf mcp --remote=false
--remote defaults to false, but setting it explicitly makes the local-only behavior clear. OTEL_SDK_DISABLED=true disables OpenTelemetry SDK instrumentation; it does not disable this event, which is sent directly over HTTP. The --remote=false setting is what prevents mcp_start_remote from being sent.
This project is licensed under the Apache License 2.0. See the LICENSE file for the full text.
O
Okf
abcubed3·9 个星标·
The OKF-go provides a high-performance suite of utilities to validate bundles, harvest metadata from databases and APIs, assemble context for Large Language Models (LLMs), and run an MCP Server.
上次检查时间:2026-11-05。 The OKF-go provides a high-performance suite of utilities to validate bundles, harvest metadata from databases and APIs, assemble context for Large Language Models (LLMs), and run an MCP Server.