OQA Open Query Agent
Draft · v0.1

Quickstart

An OQA bundle is just a folder of markdown files. You can build one by hand in a few minutes — no SDK, no build step. Here's the smallest useful bundle.

1 · Create a bundle

A bundle is a directory. Anything inside it that ends in .md (except the reserved index.md and log.md) is a concept.

my-knowledge/
├── index.md          # optional listing
├── checkout-api.md   # a concept
└── refund-policy.md  # a concept

2 · Add a concept

Every concept is a markdown file with YAML frontmatter. The only required field is type. Everything else is optional but recommended.

---
type: API Endpoint
title: Checkout API
description: Creates and confirms a customer order.
resource: https://api.example.com/v1/checkout
tags: [payments, public]
timestamp: 2026-06-24T00:00:00Z
---

# Checkout API

Creates an order and charges the saved payment method. Returns the
order id and a confirmation status.

See the [refund policy](./refund-policy.md) for reversals.
Soft by design Unknown type values, extra frontmatter keys, and broken links are all tolerated — a consumer must never reject a bundle for them. Pick descriptive type names; there's no central registry.

Concepts relate to each other with ordinary markdown links. A link from A to B asserts a relationship; the meaning lives in the surrounding prose. Together they form the knowledge graph a query agent traverses.

Refunds are issued against the original [Checkout API](/checkout-api.md)
transaction within 90 days.

Use bundle-absolute links (starting with /) when you want them stable as files move; relative links (./) otherwise.

4 · Add an index (optional)

index.md is a reserved file: a plain listing with no frontmatter that helps agents discover what's in a directory. Declare the spec version here.

---
okf_version: "0.1"
---

# My Knowledge

- [Checkout API](/checkout-api.md) — create and confirm orders
- [Refund Policy](/refund-policy.md) — when and how refunds are issued

Next

That's a conformant bundle. Read the Open Knowledge Format base spec for the full field reference, or the OQA layer for the query-agent conventions on top.