Format Otwartej Wiedzy: pliki Markdown jako przenośna warstwa wiedzy dla agentów

Agenci marnują tokeny, ciągle ponownie czytając te same wewnętrzne dokumenty, a Google Cloud zaproponowało rozwiązanie: Open Knowledge Format, OKF. Wersja 0.1 została ogłoszona na blogu Google Cloud 12 czerwca 2026 roku. Ideologia jest prosta – każdy koncept, który jest ważny dla zespołu, staje się jednym plikiem w formacie Markdown, a folder tych plików pełni rolę lekkiej sieci wiedzy, którą może odczytać każdy agent. Nie wymaga SDK, bazy danych ani ograniczeń. Skeptyk mógłby oczekiwać kolejnej platformy udającej format, ale w rzeczywistości chodzi tu po prostu o pliki, i to właśnie jest interesujące. Zespoły nadal dodają złożoność do agentów, podczas gdy jedno z najtrudniejszych pytań jest prostsze: gdzie faktycznie znajduje się przydatna wiedza?

Problem: agenci muszą ciągle się uczyć na nowo

Oto typowy schemat. Agent otrzymuje pytanie dotyczące jakiejś miary, ładuje całą wewnętrzną witrynę wiki, wstawia tekst i samodzielnie próbuje zrozumieć jego znaczenie. Przy kolejnym zapytaniu robi dokładnie to samo. Surowy tekst może być zapisywany w pamięci cache, ale nikt nie przechowuje informacji o jego zrozumieniu.

Wyobraźmy sobie agenta, który musi za każdym razem ponownie czytać dokument definiujący aktywnego użytkownika, ponieważ ta definicja nie ma określonego miejsca przechowywania i znajduje się na stronie w Notion trzy foldery niżej. Każda interakcja jest tania, ale te straty się kumulują, tak jak małe marnotrawstwa, gdy nikt tego nie obserwuje, a w zespole wykonującym codziennie te same zapytania koszt wykorzystania tokenów jest znaczący. Nie ma publicznych danych na ten temat, ponieważ osoby z zewnątrz nie mają dostępu do wewnętrznych statystyk Google, jednak problem ten jest dobrze znany większości osób obsługujących agenty.

Przykład bardziej konkretny: dokument analityczny definiuje aktywnego użytkownika jako osobę, która dokonała co najmniej jednej istotnej akcji związanej z produktem w danym miesiącu kalendarzowym. Gdy zapytamy pracownika, ilu aktywnych użytkowników było w zeszłym miesiącu, potrzebne są dwie różne rzeczy – liczby oraz informacja o tym, co dokładnie oznacza tutaj pojęcie „aktywny”. To są odrębne problemy. Baza danych podaje informacje o tym, co się wydarzyło, natomiast warstwa wiedzy rejestruje, co firma ma na myśli. OKF ma na celu ułatwienie reprezentacji tej drugiej części.

Rozwiązaniem jest format, a nie większy model

OKF jest celowo niemal nudnie prosty. Pakiiet to folder zawierający pliki w formacie Markdown, z których każdy opisuje jeden koncept – czy to tabelę, wskaźnik, API czy instrukcję postępowania. Każdy plik zaczyna się od małego bloku w formacie YAML, tzw. frontmatter, umieszczonego pomiędzy dwiema liniami znacznikowymi. Tylko jedno pole jest obowiązkowe:

---
type: Metric   # required – tells the agent what kind of concept this is
---

Pięć pól opcjonalnych uzupełnia ten formularz; są one wymienione poniżej wraz z ich przeznaczeniem:

| Field         | Purpose                      |
| ------------- | ---------------------------- |
| `title`       | Human-readable name          |
| `description` | Short summary                |
| `resource`    | Link to the underlying asset |
| `tags`        | Keywords for categorization  |

Wersja 0.2 dodaje opcjonalne pola dotyczące pochodzenia, weryfikacji, świeżości, cyklu życia oraz przeprowadzonych obliczeń. Można dodać dowolne dodatkowe klucze, a oczekuje się, że użytkownicy będą ignorować te, których nie rozpoznają, bez powodowania błędów – to właśnie umożliwia rozszerzanie formatu bez uszkodzenia agenta innej osoby. Zarezerwowano dwa nazwy plików: index.md dla listy zawartości katalogu oraz log.md dla historii zmian, co oszczędza czas na wymyślanie konwencji już ustalonych w specyfikacji. Specyfikacja została opublikowana jako projekt wersji v0.1, więc należy oczekiwać jej dalszego rozwoju i sprawdzać repozytorium pod kątem aktualnej wersji przed tworzeniem czegokolwiek poważnego.

Linki tworzą graf

Ponieważ pliki są zwykłym formatem Markdown, koncepcje łączą się za pomocą standardowych łączy [tekst](inny-plik.md), a te linki stanowią krawędzie grafu znajdującego się w folderze, bez konieczności używania dodatkowej bazy danych. Poprawny plik z koncepcjami wygląda tak:

---
type: Metric
title: Monthly Revenue
description: Total money earned each month.
resource: https://console.cloud.google.com/bigquery?p=project&d=dataset&t=revenue
tags: [finance, monthly]
---

Revenue is counted after refunds are removed.

See also: [customer_acquisition_cost.md](customer_acquisition_cost.md)

Agent czytający revenue.md dowiaduje się, że powiązany z nim koncept znajduje się w pliku customer_acquisition_cost.md. Znaczenie linku nadal pochodzi od osoby, która napisała te pliki, ponieważ format nie jest w stanie samodzielnie go zinterpretować.

Próba w pięć minut

Specyfikacja zawiera rzeczywiste przykładowe zestawy danych utworzone na podstawie informacji z e-commerce w GA4, danych z Stack Overflow oraz łańcucha bloków Bitcoin. Agent referencyjny, który przegląda zbiory danych w BigQuery i tworzy dokumenty OKF, wygenerował je automatycznie, a wszystko znajduje się w jednym repozytorium typu Apache 2.0:

git clone https://github.com/GoogleCloudPlatform/knowledge-catalog.git
cd knowledge-catalog/okf

# Add your own concept
cat > new_metric.md <<'EOF'
---
type: Metric
title: Net Promoter Score
description: Measure of customer loyalty.
resource: https://console.cloud.google.com/bigquery?p=company&d=metrics&t=nps
tags: [customer, loyalty]
---
EOF

Każdy zestaw próbek zawiera plik viz.html. Otwórz go w dowolnym przeglądarce, aby uzyskać interaktywny wykres zestawu z węzłami, łączami, funkcjami wyszukiwania i filtrami – bez konieczności korzystania z backendu czy serwera. Jedyną uwagą jest to, że utworzenie pliku viz.html dla własnego zestawu oznacza uruchomienie małego narzędzia referencyjnego w Pythonie znajdującego się w repozytorium. Narzędzie to przekształca zestaw w jedną samodzielną stronę HTML opartą na Cytoscape.js i marked.js, ponownie bez backendu – jest to po prostu plik, który można wysłać e-mailem koleżeńsko.

Korzyści

• Niższe koszty: definicja jest zapisywana raz i odczytywana bezpośrednio, dzięki czemu nie trzeba płacić za jej ponowne generowanie pięćdziesiąt razy dziennie.
• Szybsze ładowanie: na dysku znajduje się zwykły tekst, bez konieczności wysyłania żądań do usług w chmurze ani dodatkowych kroków integracji przed użyciem.
• Prawdziwa przenośność: sklonuj repozytorium, skopiuj folder lub wgraj go do obrazu Dockera – będzie działał tak samo na GCP, Azure, AWS czy w laptopie. Nic nie zmusza cię do pozostania przy jednym rozwiązaniu.
• Kontrola wersji za darmo: pliki przechowywane są w git, więc dostępne są prośby o włączenie zmian, różnice, analiza autorstwa oraz przeglądanie zmian, a zarządzanie wiedzą staje się zwykłą pracą inżynierską.
• Jedyny źródło informacji dla ludzi i agentów: nowy pracownik oraz agent na zmianie otwierają ten sam plik, więc wiki nie może podawać jednych informacji, podczas gdy agent wierzy w inne.
• Wymiana między zespołami i organizacjami: dostawca może dostarczyć katalog w formie pliku OKF, który twój agent może bezpośrednio używać, bez żadnej pracy integracyjnej.

Kontrolowalność jest kolejną zaletą. Załóżmy, że agent proponuje taką zmianę:

- Revenue is recognized when an order is placed.
+ Revenue is recognized after delivery and the 30-day return window.

To zwykły diff w Git, dzięki czemu recenzent dokładnie widzi, co się zmieniło. Jest o wiele łatwiejszy do oceny niż cicha aktualizacja ukryta w zamkniętym systemie wiedzy.

Gdzie ma wady

• Nie naprawia błędnych definicji. OKF standaryzuje kontener, a nie jego zawartość, więc jeśli zespół nie może się zgodzić na znaczenie „aktywnego użytkownika”, plik markdown nie zmusi ich do porozumienia.
• Ktoś musi go utrzymywać. Pliki stają się przestarzałe, a pole timestamp oraz plik log.md są pomocne tylko wtedy, gdy ludzie lub agenci je aktualizują. Przestarzała wiedza może zaszkodzić bardziej niż jej brak, ponieważ agenci wierzą we wszystko, co znajdą.
• To młody projekt, wyraźnie niedokończony, więc pola i konwencje mogą ulegać zmianom, a wczesni użytkownicy powinni się spodziewać zmian.
• Znaczenie nie jest narzucane. Link wskazuje, że dwa pojęcia są ze sobą powiązane, ale nie określa, w jaki sposób, a ta relacja znajduje się w tekście prozatorskim, który jest elastyczny, ale także niejednoznaczny. Ścisłe relacje typowe wymagają nadal rzeczywistej bazy danych grafowych.
• Do tej pory niewielu użytkowników. Prawie wszyscy twórcy i klienci na początku pochodzili z Google, a format może odnieść sukces tylko wtedy, gdy inne narzędzia i zespoły go przyjmą.

OKF obok RAG i MCP

Nic z obecnego stosu nie jest wyrzucane, ponieważ OKF znajduje się poniżej. RAG nadal znajduje istotne fragmenty tekstowe po otrzymaniu zapytania, a OKF dostarcza mu czystszy, uprzednio skonstruowany tekst, co sprawia, że embeddingi są dokładniejsze i łatwiejsze do utworzenia. MCP, protokół kontekstu modelu firmy Anthropic, przenosi kontekst podczas rozmowy, a OKF może funkcjonować poniżej niego jako źródło danych dla tych narzędzi. MCP zarządza przepływem informacji, podczas gdy OKF przechowuje definicje, dzięki czemu nikt nie musi ich na nowo wyprowadzać za każdym razem. Te trzy warstwy wyglądają w ten sposób:

OKF
↓
"What does this concept mean?"

RAG
↓
"Which pieces of knowledge should I retrieve?"

MCP
↓
"How does the agent interact with the tools and context?"

Każda warstwa rozwiązuje inny problem, dlatego OKF lepiej postrzegać jako wspólną warstwę wiedzy znajdującą się poniżej obu, a nie jako konkurenta. Pliki Markdown wcale nie przypominają prezentacji nowego produktu, a jednak czasami to właśnie ta mniej atrakcyjna opcja okazuje się skuteczna.

Czy powinieneś to używać?

Dla każdego agenta, który odpowiada na pytania dotyczące twoich danych, metryk lub systemów, odpowiedź brzmi tak – warto to wypróbować. Próba nie kosztuje prawie nic: napisz trzy pliki, połącz je, wskazaj agentowi folder, a po popołudniu dowiesz się, czy to pomaga. Jeśli twoja wiedza znajduje się tylko w głowie jednej osoby lub w nieuporządkowanym wiki, OKF oferuje prosty, możliwy do wersjonowania sposób na jej zapisanie, co może być wartościowe zarówno z agentem, jak i bez niego. Jeśli potrzebujesz ścisłych schematów, typowanych relacji lub rygorystycznych zasad zarządzania, obecnie jest to zbyt swobodne rozwiązanie, więc zachowaj swój katalog i być może później wyeksportuj całość.

Nie zaczynaj od całej bazy wiedzy firmy. Wybierz jedną małą dziedzinę, na przykład:

metrics/
  active-user.md
  revenue.md
  conversion-rate.md

systems/
  payments-api.md
  orders-api.md

runbooks/
  payment-failure.md

Połącz pliki, przekaż je jednemu agentowi i sprawdź, jakie zmiany nastąpią. To o wiele lepszy eksperyment niż trzy miesiące spędzone na projektowaniu platformy OKF dla przedsiębiorstw, zanim udowodni się jej potrzebę.

Jedno obowiązkowe pole i folder z plikami markdown sami w sobie nie naprawią złej dokumentacji. To, co oferują, to wspólna, nudna, przenośna baza dla dobrej dokumentacji, którą zespół już posiada – co ma większą wartość, niż się na papierze wydaje.