Set Up an OKF-KB (Knowledge Base)

Quick reference for initializing and using an OKF-KB.

Want to see OKF-KB in action? See HW Debugging Workflow Tutorial for a real automotive debugging scenario.

Want to understand the design philosophy? See OKF-KB Design Choices.

Quick Start (5 Minutes)

1. Initialize

mkdir my-kb
cd my-kb
okfkb init

Creates: index.md, log.md, and tier folders (findings/, concepts/, principles/, etc.).

2. Agent Creates a Finding

okfkb new-finding "What was observed"

Creates findings/YYYY.MM.DD-HH.MM-<slug>.md with template frontmatter. Agent edits, then:

okfkb update findings/YYYY.MM.DD-HH.MM-<slug>.md

3. Index

okf-schema index --path .

Computes backlinks, regenerates index.md and log.md.

4. Validate

okf-schema lint --path .

Checks required fields, timestamps, link validity.

Schema Reference

Findings: findings/YYYY.MM.DD-HH.MM-<slug>.md

Immutable raw observations. Created by agents.

type: Finding
title: What was observed?
confidence: low | medium | high
context: System state, configuration, environment
timestamp: 2026-07-04T14:30:00Z
tags: [domain, tags]
links: [findings/..., concepts/...]
backlinks: []  # Auto-computed
status: active | contradicted | archived
contradicted_by: [findings/...]

Concepts: concepts/<name>.md

Stable understanding promoted from converged findings.

type: Concept
title: Stable understanding
confidence: high
promoted_from: [findings/..., findings/...]
links: [concepts/..., principles/...]
backlinks: []
status: active | superseded

Hypotheses: hypotheses/<name>.md

Testable propositions.

type: Hypothesis
title: Proposition to test
proposed_by: [findings/... or concepts/...]
links: []
status: open | validated | refuted

Experiments: experiments/<name>.md

Planned investigations.

type: Experiment
title: What are we testing?
hypothesis: [hypotheses/...]
expected_outcome: What we expect if true
planned_for: YYYY-MM-DD
status: planned | in-progress | completed
results_in: [findings/...]

Principles: principles/<name>.md

Team-agreed standards (rarely created, high stakes).

type: Principle
title: Standard or policy we agree on
status: active | deprecated
effective_date: YYYY-MM-DD

Structures: structures/<name>.md

System composition patterns.

type: Structure
title: System composition or pattern
links: [concepts/...]
status: active

Outcomes: outcomes/<name>.md

Planned deliverables.

type: Outcome
title: Project or deliverable
depends_on: [concepts/...]
status: planned | in-progress | completed
target_date: YYYY-MM-DD

Reference: reference/<name>.md

External sources.

type: Reference
title: Paper/link title
url: https://...
abstract: Summary
links: [concepts/..., findings/...]

Guides: guides/<name>.md

Operational how-to notes.

type: Guide
title: How to do X
status: active
links: []

Linking Your Documents

Add links: entries to connect documents:

links:
  - findings/2026-07-03-root-cause.md
  - concepts/subsystem-behavior.md
  - principles/timeout-policy.md

Run okf-schema index --path . to auto-compute backlinks.

Frontmatter Validation

okf-schema lint --path .

Verifies:

  • Required fields present

  • Confidence values valid (low, medium, high)

  • Timestamps in ISO 8601 format

  • All links: point to existing files

  • status: values match schema

Tips for Success

  1. Findings are immutable — once created, only update lifecycle fields (status, contradicted_by)

  2. Link aggressively — more links = more navigable KB

  3. Index after batches — run okf-schema index after each editing session

  4. Use tags for filtering — tags help agents search by domain

  5. Review log.md regularly — keep it human-readable; summarize weekly changes

  6. Principles are rare — only for team consensus decisions

  7. Promotion requires convergence — wait for 2+ findings before creating a concept

Further Reading