Knowledge Catalog (OKF)

The Knowledge Catalog stores domain knowledge as Open Knowledge Format (OKF) bundles and grounds a model call on them at request time. A bundle is a set of markdown files with YAML frontmatter; on an opted-in request the gateway picks the concepts that match the user’s turn and injects them as one system message before the provider is called, so GPT, Claude, and Gemini all answer from your knowledge without the client resending it. Grounding is opt-in per request through a single metadata field, so a call is only ever touched when you ask for it

OKF is markdown plus YAML frontmatter under an Apache-2.0 spec, so a bundle you author here is portable to any other OKF tool. ForceAI adds the catalog, the governed store, and the injection hook that makes an agent actually use it

How it fits together

Import and grounding run on two planes. The catalog API runs on the control plane, the grounding hook runs on the data plane, and both read and write one shared context store. That is why a bundle you import through the dashboard is available to every model call the gateway serves

The shared store is not optional. Import writes on the control plane and grounding reads on the data plane, so both must point at the same store or the gateway never sees your bundles and grounding silently does nothing (it fails open). In production set FORCEAI_CONTEXT_BACKEND=s3 plus the bucket and endpoint on both the backend and the gateway

The real-time flow

This is what happens on every grounded request, in the few milliseconds before the provider is called

The caller opts in

The request carries metadata.forceai_okf. Without it the hook returns immediately and the call is untouched

The hook loads the bundle

It reads the named bundle, and a pinned version if you gave one, from the shared context store

Access groups are applied

A concept whose frontmatter lists access_groups is dropped unless the caller’s access groups intersect it, so a caller is only grounded on knowledge it is entitled to

The best concepts are selected

Every remaining concept is scored against the user’s last message, tags counting double and prose once. The top three are kept; index.md and log.md are never injected

Knowledge is injected and audited

The selected concepts are prepended as one system message and a summary is written to spend_logs_metadata.forceai_okf, then the provider call proceeds with the knowledge in context

Author a bundle

A bundle is a directory of .md files, one concept per file. A type in the frontmatter is required; everything else is optional but improves how well a concept is retrieved and governed. Relative markdown links between files become edges in the concept graph

---
type: index
title: Sales Catalog
okf_version: "0.1"
---
Root index of the sales knowledge bundle. See [Acme Widget](./acme_widget.md)
and the [Refund Policy](./refund_policy.md).

---
type: product
title: Acme Widget
description: Flagship widget product
tags: [widget, hardware, flagship]
---
The Acme Widget is our flagship product. Pricing is governed by the
[Pricing Policy](./pricing_policy.md).

---
type: policy
title: Refund Policy
description: Refund and return terms
tags: [refund, returns, policy]
access_groups: [finance, support]
---
Refunds are accepted within 30 days of purchase. See the
[Pricing Policy](./pricing_policy.md) for restocking fees.

tags is the strongest lever on retrieval because it is weighted twice as heavily as prose, so tag a concept with the words a user would actually say. access_groups gates who can be grounded on the concept. index.md and log.md are reserved names and are never injected into a prompt

Import a bundle

Open the dashboard Knowledge Catalog page (admin only), give the bundle an id, add your .md files, and click Import. Valid files become concepts; invalid files are reported, not silently dropped. Select the bundle to browse its concepts and the concept graph. The same thing over the API:

curl -s -X POST http://localhost:3000/forceai/okf/bundles/sales_catalog/import \
  -H "Authorization: Bearer $FORCEAI_KEY" -H "Content-Type: application/json" \
  -d '{
    "files": {
      "index.md": "---\ntype: index\ntitle: Sales Catalog\nokf_version: \"0.1\"\n---\nRoot index.",
      "refund_policy.md": "---\ntype: policy\ntitle: Refund Policy\ntags: [refund, returns]\n---\nRefunds within 30 days."
    }
  }'
# -> {"bundle_id":"sales_catalog","version":"v1","imported":2,"skipped":[],"errors":[]}

You can also post a gzip tarball with Content-Type: application/gzip, which is exactly what GET /forceai/okf/bundles/{id}/export returns, so bundles round-trip cleanly. Each import is a new version, so a re-import never overwrites the old one

Ground a request in real time

This is the part an agent or app does on every turn. Add metadata.forceai_okf to the chat completion and the gateway does the rest. The value is a bundle id, or an object that pins a version:

curl -s http://localhost:4000/v1/chat/completions \
  -H "Authorization: Bearer $FORCEAI_KEY" -H "Content-Type: application/json" \
  -d '{
    "model": "claude-haiku-4-5",
    "metadata": {"forceai_okf": "sales_catalog"},
    "messages": [{"role": "user", "content": "What is the refund window for the Acme Widget?"}]
  }' | jq -r '.choices[0].message.content'
# -> "Refunds are accepted within 30 days of purchase..."

from openai import OpenAI

client = OpenAI(base_url="http://localhost:4000/v1", api_key=FORCEAI_KEY)

resp = client.chat.completions.create(
    model="claude-haiku-4-5",
    messages=[{"role": "user", "content": "What is the refund window for the Acme Widget?"}],
    extra_body={"metadata": {"forceai_okf": "sales_catalog"}},
)
print(resp.choices[0].message.content)

{
  "model": "claude-haiku-4-5",
  "metadata": {"forceai_okf": {"bundle": "sales_catalog", "version": "v2"}},
  "messages": [{"role": "user", "content": "..."}]
}

Streaming works the same way; injection happens before the first token, so "stream": true needs no extra handling. Without forceai_okf in the request the model runs ungrounded, which is the point: you decide per call

How an agent uses it

Grounding keys off the request body, so whatever builds the model call sets the metadata. For a direct API or SDK client, set metadata.forceai_okf as above; this is the supported path today for any OpenAI-compatible caller. Agent, A2A, and orchestrator turns all pass through the gateway, so grounding fires as soon as the metadata is present on the turn

Attaching a bundle to an agent so its runtime stamps forceai_okf on every turn automatically, with no caller involvement, is a planned per-agent setting rather than a current option. Until then, ground an agent by setting the metadata wherever its turns originate

Tune what gets selected

Selection is lexical and deterministic, so you shape it by shaping the concepts. If the right concept is not being pulled in, add the user’s vocabulary to that concept’s tags, since tags outweigh prose. At most three concepts are injected per turn, which keeps the added tokens small and predictable. Split a sprawling document into several focused concepts rather than one large file, so the matcher can pick the relevant piece

See what a request used

Open the request in Logs and expand it to see which concepts were injected, or read it back from the spend log. The summary is stamped into spend_logs_metadata.forceai_okf:

{
  "bundle": "sales_catalog",
  "available": 3,
  "loaded": 3,
  "loaded_paths": ["acme_widget.md", "refund_policy.md", "pricing_policy.md"],
  "tokens_loaded": 77
}

available is how many concepts the caller was allowed to see, loaded is how many were injected, and loaded_paths names them exactly

Scope and safety

A caller is only ever grounded on concepts it could see, since access_groups filtering runs before selection. The hook fails open, so a store hiccup leaves the request untouched rather than blocking it. Injected knowledge is system context the model reads, so treat a bundle as content any grounded caller may see and keep secrets out of it

Grounding only happens on requests that opt in, so a request without metadata.forceai_okf is never modified. A concept with no access_groups is visible to every caller of the bundle; add access_groups to restrict it

API reference

Catalog routes are admin-gated and served on the control plane; chat completions are served on the data plane. Behind the dashboard both are the same origin, proxied by nginx, which is why the examples above use http://localhost:3000 for catalog calls and http://localhost:4000 for chat

Method	Path	Purpose
`POST`	`/forceai/okf/bundles/{id}/import`	Import a bundle (JSON `{files}` or tar.gz)
`GET`	`/forceai/okf/bundles`	List bundle ids
`GET`	`/forceai/okf/bundles/{id}/versions`	List versions of a bundle
`GET`	`/forceai/okf/bundles/{id}/concepts`	List concepts (type, title, tags)
`GET`	`/forceai/okf/bundles/{id}/graph`	Concept graph (nodes, edges, unresolved)
`GET`	`/forceai/okf/bundles/{id}/export`	Download the bundle as tar.gz
`POST`	`/v1/chat/completions`	Ground a call with `metadata.forceai_okf`

Get started

LLM providers

A2A agents

Skills