Pi Okf

pi-okf

A Pi-agent extension for Open Knowledge Format (OKF) bundles. It lets an agent read a curated, git-versioned knowledge bundle so it does not start every session from scratch, and write enrichments back. Consumption is always allowed; new knowledge reaches the canonical bundle only through a trust gate, the same way pi-gate gates code changes.

OKF (Google Cloud, v0.1) represents knowledge as a directory of markdown files with YAML frontmatter. One file is a concept; a directory of concepts is a bundle. The only required frontmatter field is a non-empty type. If you can cat a file you can read it; if you can git clone you can ship it.

Why

MCP tools give an agent access to your systems. They do not tell it where the data sits, which source is canonical, or how the systems connect — that knowledge lives in people, and the agent re-discovers it every session. An OKF bundle is that knowledge written down, versioned in git, and served to the agent. pi-okf is the deterministic, harness-owned tool for reading and curating it.

Install

Requires Node ≥ 18 and git.

git clone https://github.com/renezander030/pi-okf
ln -s "$PWD/pi-okf/pi-okf" /usr/local/bin/pi-okf   # or add to PATH
pi-okf help

Quick start

# CONSUME — what does the bundle hold, and is it conformant?
pi-okf survey   --bundle ./knowledge -H
pi-okf validate --bundle ./knowledge -H
pi-okf read tables/users --bundle ./knowledge      # one concept as JSON

# AUTHOR — the agent writes a concept into its staging copy
pi-okf enrich tables/orders --type "BigQuery Table" \
  --description "Canonical order ledger" --staging ./agent-tree

# LAND — merge staging enrichments into the trusted, git-versioned bundle
pi-okf trust  --bundle ./knowledge                 # bless the source once, after review
pi-okf plan   --canonical ./knowledge --staging ./agent-tree -H
pi-okf apply  --canonical ./knowledge --staging ./agent-tree

An untrusted bundle is read-only to apply: enrichments are withheld until you review and pi-okf trust it (or pass --override "").

CLI

| Command | Purpose | |---|---| | survey | Catalog every concept (id, type, title, description) for progressive disclosure. | | read | Fetch one concept: parsed frontmatter + body. | | validate | OKF v0.1 conformance (spec §9). Exit 1 if any concept lacks a parseable frontmatter with non-empty type. Broken links / missing index.md are warnings. | | index [--write] | Generate the progressive-disclosure index.md, grouped by type. | | enrich --type T | Author a conformant concept stub into --staging; logs to log.md. | | plan | Concept-level diff (added / modified / removed) of staging vs canonical, plus trust state. | | apply [--override R] | Merge staging enrichments into the canonical bundle, IFF staging is conformant and canonical is trusted. | | trust [--label L] | Register the canonical bundle as a trusted knowledge source. | | bundles | List trusted bundles. |

JSON by default; -H/--human for a table.

Trust model

Faithful to pi-gate:

| Invariant | How | |---|---| | The record of what is trusted lives outside the agent's tree | trusted-bundle registry at ~/.config/pi-okf/bundles.json; apply state at ~/.local/state/pi-okf/ | | Stable bundle identity across moves | git root-commit sha, falling back to a path hash | | Enrichments land only on a conformant, trusted bundle | apply gate; non-conformant or untrusted requires an explicit --override "" | | Every land is auditable | appended to the bundle's log.md and to the state apply.log |

Conformance (spec §9)

A bundle is conformant when every non-reserved .md file parses to a YAML frontmatter block with a non-empty type. Reserved files (index.md, log.md) carry no frontmatter. Consumers tolerate unknown types, unknown keys, broken cross-links, and a missing index.md — these are warnings, never errors.

Roadmap

Typed-edge extraction from cross-links, search over concept bodies, an MCP server that exposes a trusted bundle as resource:// URIs, and per-concept (rather than whole-bundle) trust promotion.

License

MIT

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: renezander030
• Source: renezander030/pi-okf
• License: MIT

Install and usage instructions live in the source repository linked above.