okf

okf command [arguments] [flags]okf {version | -v | --version}okf {help | -h | --help}

okf is the command-line tool from OKF Agent Memory, a Git-native persistent memory layer for AI coding agents. It reads and writes Open Knowledge Format (OKF) v0.2 bundles: a directory of Markdown files with YAML frontmatter, plus hierarchical index.md files and a dated log.md. The usual bundle root in a project is knowledge/.The binary is a single Go program with no third-party Go modules. It parses the corpus, validates the concept graph, searches with in-memory BM25 (lexical ranking, not embeddings), creates and updates concepts with automatic index/log bookkeeping, and can expose the same operations over MCP stdio for clients such as Claude Code and Cursor.Concept ids are paths relative to the bundle root without the .md suffix (for example architecture/layers for architecture/layers.md). When a command omits the bundle path, okf uses ./knowledge if that directory exists, otherwise the current directory.A companion okf-benchmark binary in the same repository measures progressive-disclosure token and latency effects against local LLM runtimes; it is not installed as okf.

--json

Emit machine-readable JSON instead of terminal text. Accepted by validate, search, show, create, update, and relate.

On validate, treat connectivity warnings (orphans, broken relative links, provenance gaps) as a failed producer gate (exit 1).

On validate, fail when a concept's frontmatter description does not match its listing in the parent index.md.

On search, maximum hits to return (default 10).

On show, print the concept file exactly as stored on disk.

knowledge/

Default project bundle. okf bootstrap creates it; most subcommands default to it when present.

Root progressive-disclosure index. Declares okf_version: "0.2" and lists child concepts.

Dated change log (ISO 8601 YYYY-MM-DD). create, update, and relate append here unless --no-log is set.

Agent skill files installed by bootstrap (unless --no-skill).

Project instructions for coding agents. bootstrap creates the file or appends a delimited section unless --overwrite-agents-md or --no-agents-md is set.

Optional convenience targets (validate, search) written by bootstrap unless --no-makefile.

validate [bundle]

Audit an OKF bundle for structural conformance, graph health, and provenance. Default bundle is ./knowledge if that directory exists, otherwise .. Exit 0 if conformant (and the producer gate passed), 1 if non-conformant or the gate failed, 2 if the bundle could not be loaded.

Rank concepts with in-memory BM25 over titles, descriptions, tags, ids, and body text. query is required.

Print metadata, trust provenance, inbound/outbound links, and the markdown body. concept-id is the bundle-relative path without .md (a trailing .md is stripped).

Write a new concept file and, unless disabled, append log.md and update the parent index.md. --type Type (default Fact; examples: Decision, Architecture, Entity, Runbook), --title text (default: last path component of the id), --desc sentence, --body markdown, --tags tag1,tag2, --actor who (default agent/cli), --no-log, --no-index.

Change --title, --desc, and/or --body on an existing concept, refresh timestamps, and record the change in log.md unless --no-log is set. --actor, --no-index, and --json as on create.

Add a relative markdown link from source to target. --desc context explains the relationship. --actor and --json as on create.

Create a bare OKF v0.2 bundle: index.md (declaring okf_version: "0.2") and log.md. Default directory is ./knowledge if present, otherwise ..

Scaffold a full agent-memory stack into target-dir (default .): knowledge/, .agents/skills/okf-memory/, AGENTS.md, and a convenience Makefile. --name project (default: directory name). --overwrite-agents-md replaces an existing AGENTS.md instead of appending a delimited section. --no-skill, --no-agents-md, --no-makefile, and --no-bundle skip individual pieces.

Run an embedded Model Context Protocol server on stdio. Tools: okf_search, okf_show, okf_create, okf_update, okf_relate, okf_validate.

Print `okf version … (OKF v0.2 specification)`. Also accepted as -v / --version.

Print the command list. Also accepted as -h / --help. With no arguments, okf prints help and exits 1.

Several unrelated projects ship a binary named okf (other OKF bundle CLIs and a Ruby gem). Confirm okf version mentions OKF v0.2 specification and okf help lists bootstrap / mcp before relying on a distro or `PATH` install.Search is lexical BM25, not vector similarity. It does not call an embedding API.--json, --strict, and --drift are not global flags: they must follow the subcommand that accepts them. Unknown flags on that subcommand cause the process to exit.mcp speaks MCP only over stdio. It is meant to be launched by an editor or agent host, not as a network daemon.The in-tree Homebrew formula targets okf-memory/tap/okf and GitHub release assets for v0.1.0. Distro packages may be missing or may refer to a different okf. Building from source needs a Go toolchain (go.mod requires 1.22); make build writes bin/okf, make install uses go install.

Open Knowledge Format is a vendor-neutral Markdown-plus-YAML spec from Google Cloud (Knowledge Catalog / open-knowledge-format), published in June 2026 (v0.1, then v0.2). okf is a separate MIT-licensed Go implementation by sknr and the OKF Memory contributors. The okf-agent-memory repository was created on 5 September 2026; the project announced v0.1.0 on Hacker News the following day as a zero-dependency CLI and MCP server for Git-tracked agent memory.

git(1), claude(1), codex(1), opencode(1), codeknow(1)

Source code · Documentation