Format Otwartej Wiedzy: Pamięć przenośna dla agentów programistycznych AI

Format Open Knowledge to standard, który ma na celu umożliwienie przenoszenia pamięci agenta, jej wersjonowanie oraz czytelność przez wszystkie narzędzia w środowisku programisty.

Problem z rozpoczynaniem pracy od nowa każdego ranka

Każdy, kto korzysta z agenta do programowania opartego na sztucznej inteligencji, napotkał ten sam problem. Sesja zostaje zamknięta, a następnego dnia agent nic nie pamięta. Musi na nowo przechodzić proces autoryzacji, ponownie próbować odgadnąć uzasadnienie decyzji architektonicznej podjętej trzy lata temu oraz ponownie czytać te same pięć plików, aby odbudować kontekst, który poprzedniego dnia wymagał godziny wyjaśnień.

Powszechnym rozwiązaniem tymczasowym jest plik CLAUDE.md lub AGENTS.md – dokument kontekstowy, który jest czytany na początku każdej sesji. Są to prymitywne narzędzia. Za każdym razem pobierają wszystko, niezależnie od tego, czy jest to istotne, zostały napisane dla pojedynczego agenta na pojedynczej platformie i nie radzą sobie dobrze z migracją. Ponadto łączą instrukcje behawioralne, takie jak „zawsze pisać testy”, z faktami, np. „tabela zamówień łączy się z tabelą klientów za pomocą pola customer_id”, co szybko prowadzi do chaosu.

12 czerwca 2026 roku Google Cloud opublikował specyfikację adresującą ten problem, zwaną Open Knowledge Format lub OKF. Jest to jak dotąd najbardziej uporządkowana odpowiedź na problem pamięci agentów.

Gdzie dziś znajduje się wiedza

Załóżmy, że agent musi odpowiedzieć na pytanie, jak oblicza się tygodniową liczbę aktywnych użytkowników na podstawie strumienia zdarzeń. Odpowiedź znajduje się przynajmniej w czterech miejscach:

+-----------------------+--------------------------------------------+
| WHERE IT LIVES        | WHAT'S THERE                               |
+-----------------------+--------------------------------------------+
| Metadata catalogs     | Table schemas (but vendor-locked APIs)     |
| Wiki / Notion         | Runbooks, metric definitions               |
| Code comments         | Docstrings, inline notes                   |
| People's heads        | Join paths, deprecation warnings           |
+-----------------------+--------------------------------------------+

Nic tutaj nie funkcjonuje zgodnie z kodem, a nic nie przetrwa otwarcia nowego okna kontekstowego. Każdy twórca agentów ponownie rozwiązuje ten sam problem budowy kontekstu, a każdy dostawca katalogów tworzy własne schematy.

OKF uważa, że brakuje formatu, a nie kolejnej platformy.

Jaki jest ten format

Wersja 0.1 Formatu Otwartej Wiedzy to otwarta, neutralna pod względem dostawców specyfikacja licencjonowana na zasadach Apache 2.0. Wiedza jest przechowywana jako katalog plików w formacie markdown, z których każdy zawiera metadane w formacie YAML. Brzmi to prosto, ponieważ rzeczywiście jest proste, i to jest zamierzone.

Nie ma rejestru schematów, silnika w czasie wykonywania ani obowiązkowego SDK. Wszystko, co potrafi użyć polecenia cat do otwarcia pliku, może go odczytać, a wszystko, co potrafi wykonać polecenie git clone wobec repozytorium, może je rozpowszechnić. Cała specyfikacja mieści się na jednej stronie i zawiera dokładnie jedno obowiązkowe pole, przy czym wszystko inne jest opcjonalne lub pozostawione do decyzji twórcy.

Anatomia paczki

Paczka to po prostu folder, a ścieżka pliku służy jako identyfikator jego koncepcji.

.okf/
+-- index.md                      <- progressive entry point
+-- log.md                        <- dated change history, newest first
+-- services/
|   +-- index.md
|   +-- auth-api.md               <- one concept = one file
|   +-- payments-service.md
+-- datasets/
|   +-- index.md
|   +-- orders-db.md
+-- metrics/
|   +-- index.md
|   +-- weekly-active-users.md
+-- decisions/
    +-- index.md
    +-- why-we-use-postgres.md

Twoje nazwy plików są zarezerwowane w każdym pakuie:

• index.md służy do stopniowego ujawniania informacji. Agenaty przeglądają pakiet, czytając indeks na każdym poziomie i schodząc niżej tylko wtedy, gdy tego wymaga zadanie. To ten sam stopniowy proces ładowania, który sprawia, że Claude Skills zużywa mniej tokenów.
• log.md to historia zmian z datami w formacie ISO, przy czym najnowsze wpisy znajdują się na początku. Zarówno ludzie, jak i agenaty zarządzający pakietem, dodają do niego informacje w momencie zmiany koncepcji.

Każdy inny plik to dokument przedstawiający daną koncepcję, identyfikowany przez jego ścieżkę. Jedyne pole, które musi zawierać taki dokument, to niepuste pole type.

---
type: Service
title: "Auth API"
description: "Issues and verifies short-lived access tokens."
resource: https://github.com/acme/auth
tags: [auth, platform]
timestamp: 2026-06-14T10:00:00Z
---

Ciało tego elementu zawiera zwykły markdown, włączając w to tabele.

## Endpoints| Method | Path     | Description               |
|--------|----------|---------------------------|
| POST   | /token   | Exchange creds for a JWT. |
| GET    | /verify  | Validate a token.         |## Why This ExistsSee the decision at [decisions/why-we-separated-auth.md](../decisions/why-we-separated-auth.md).
Joins with [datasets/orders-db.md](../datasets/orders-db.md) for user scoping.

Następnie przychodzi kluczowy krok w projektowaniu. Koncepcje są ze sobą powiązane za pomocą standardowych łączy markdown. Dzięki temu katalog staje się grafem, zbiorem uporządkowanej, wzajemnie odnoszącej się wiedzy o wyraźnych relacjach, którą można przemierzać, zamiast płaskim stosem dokumentów.

[auth-api.md]
                    /            \
                  links          links
                  /                \
[decisions/why-separated-auth.md]  [datasets/orders-db.md]
                                        |
                                      links
                                        |
                                [datasets/customers-db.md]

Narzędzie zdolne do śledzenia linku w formacie Markdown może przemieszczać się po grafie, a agent z dostępem do plików może je zarówno czytać, jak i zapisywać.

Ponieważ wymagany jest tylko type, producent decyduje, jakie typy istnieją (Service, Dataset, Metric, Decision, Runbook itp.), jakie pola opcjonalne użyć oraz jakie sekcje treści włączyć. OKF definiuje interoperacyjność, a nie modele treści.

Producenci i konsumenty

Format funkcjonuje tak samo po obu stronach, więc zamiana producenta lub konsumenta nie zakłóca struktury danych.

PRODUCERS                       CONSUMERS
---------                       ---------
Human authors       ---->       AI agents
BigQuery pipelines  ---->       HTML visualizers
LLM-generated       ---->       Search indexes
Wiki exports        ---->       Other agents / tools

Nie ma kont własnościowych, żadnego SDK ani centralnego rejestru. Wartość rośnie wraz z rozprzestrzenianiem się tego rozwiązania, a nie dzięki zamykaniu użytkowników w ramach konkretnego dostawcy. To odpowiada filozofii stojącej za git, markdown i JSON – formatami, które przetrwały, ponieważ nie wymagały niczego dodatkowego do używania.

Jak to się łączy z CLAUDE.md i MCP

Większość nieporozumień pochodzi właśnie stąd. OKF nie zastępuje narzędzi już używanych – wypełnia określoną lukę.

+---------------------+---------------------------+---------------------------+
| TOOL                | PURPOSE                   | SCOPE                     |
+---------------------+---------------------------+---------------------------+
| CLAUDE.md           | How the agent behaves     | Per-project, one agent    |
| AGENTS.md           | Repo instructions         | Per-repo, tool-specific   |
| Karpathy LLM wiki   | Agent-maintained notes    | Pattern, not a spec       |
| MCP                 | Live tool access          | Runtime connections        |
| OKF                 | What the team knows       | Cross-project, any agent  |
+---------------------+---------------------------+---------------------------+

Czysty model mentalny rozdziela trzy pytania:

• CLAUDE.md określa, jak agent powinien się zachowywać.
• OKF wskazuje, co zespół wie o tym systemie.
• MCP podaje, które narzędzia w czasie rzeczywistym agent może wywołać w danym momencie.

Są one ze sobą powiązane. Linia w pliku CLAUDE.md może polecać przeczytanie katalogu .okf/metrics/ przed wykonaniem jakiegokolwiek zadania analitycznego. Następnie plik OKF dostarcza ustrukturyzowane informacje, do których odnosi się CLAUDE.md, a połączenia MCP dostarczają źródła danych w czasie rzeczywistym opisane w dokumentach OKF.

Idea wiki, którą to echo

Andrej Karpathy, który wprowadził pojęcie „vibe coding”, a obecnie preferuje termin „agentic engineering”, opublikował notatkę na wiki dotyczącą LLM, która zebrała ponad 5 000 gwiazdek. Jego argument jest prosty: ludzie porzucają wiki, gdy ich utrzymanie staje się uciążliwe, natomiast agenci się tym nie męczą, nie zapominają o odnośnikach ani nie mają trudności z edycją 15 plików za jednym razem.

To samo wzorce pojawiały się niezależnie – w Obsidianie w połączeniu z agentami do programowania, w repozytoriach pełnych plików AGENTS.md, a także w plikach index.md i log.md w dziesiątkach projektów. Ludzie po prostu wynajdywali na nowo to samo rozwiązanie. OKF dodaje natomiast zgodę co do tego, jakie dane zawiera każdy dokument i co oznaczają nazwy plików, dzięki czemu oddzielne wiki, a nawet eksport z katalogu BigQuery, mogą współpracować bez konieczności tłumaczenia.

Mapowanie pomiędzy nimi składa się z trzech warstw:

KARPATHY LAYER              OKF EQUIVALENT
--------------              --------------
Raw sources (immutable) --> External datasets, docs, APIs
                            (OKF bundles are the compiled layer)

Wiki (LLM-maintained)   --> OKF bundle (*.md + frontmatter)
                            (OKF adds type, resource, tags, timestamp)Schema (CLAUDE.md)      --> Producer/consumer conventions + okf/SPEC.md
                            (org-wide spec replaces per-vault bespoke rules)

Zarówno Karpathy, jak i OKF przeznaczyli pliki index.md i log.md do tych samych zadań, a to zbieżność nie była przypadkiem.

Co dostarczył Google wraz z tym rozwiązaniem

OKF to specyfikacja, jednak Google opublikował wraz z nią trzy praktyczne narzędzia:

1. Agent wzbogacający BigQuery. Skierowany na zbiór danych, tworzy dokument opisujący koncepcję OKF dla każdej tabeli i widoku, a następnie przeprowadza drugą iterację z użyciem LLM, która dodaje cytaty, schematy oraz ścieżki łączenia pozyskane z dokumentacji. Wynikiem dla magazynu danych jest wypełniony katalog .okf/.
2. Statyczny wizualizator HTML. Przekształca dowolny plik OKF w interaktywny wykres w jednym samodzielnym pliku HTML, bez konieczności używania serwera backendowego i bez żadnych elementów opuszczających stronę. Koncepcje przedstawiane są jako węzły, a linki w formacie Markdown jako krawędzie; kliknięcie w węzeł otwiera panel w stylu wiki z zrenderowanym tekstem Markdown oraz linkami zwrotnymi oznaczonymi jako „Linki do / Cytowane przez”.
3. Przykładowe pliki. Trzy rzeczywiste pliki na GitHubie wykorzystują publiczne zestawy danych BigQuery:

+--------------------+----------------------------------+
| BUNDLE             | WHAT IT DOCUMENTS                |
+--------------------+----------------------------------+
| GA4 e-commerce     | Analytics tables and metrics     |
| Stack Overflow     | Public dataset concepts          |
| Bitcoin            | Blockchain dataset structure     |
+--------------------+----------------------------------+

Służą zarówno jako szablony początkowe do kopiowania, jak i jako dowód na to, że format funkcjonuje poprawnie w różnych domenach.

Kiedy OKF jest właściwym wyborem

Jest odpowiedni, gdy problem związany z wiedzą przypomina jeden z następujących przypadków:

• Te same wyjaśnienia powtarzają się przy każdej nowej sesji agenta. Jeśli jakiś blok kontekstowy jest ciągle wklejany do CLAUDE.md, powinien znajdować się w OKF.
• Wiedza dotyczy kilku projektów lub zespołów. CLAUDE.md jest powiązany z jednym projektem i jednym agentem, natomiast pliki OKF mogą być przenoszone między repozytoriami, agentami i narzędziami.
• Dokumentacja projektu powinna być wersjonowalna. OKF znajduje się w git obok kodu, który opisuje, każda zmiana jest widoczna w raporcie różnic, a prośba o połączenie może zawierać aktualizacje wiedzy wraz ze zmianami w kodzie.
• Platformą bazową są Google Cloud i BigQuery. Istnieje bezpośrednia integracja z katalogiem wiedzy Google, który przyjmuje pakiety i przekazuje je agentom GCP.
• Potrzebny jest graf wiedzy, a nie zwykła wiki. Graf linków w formacie markdown umożliwia reprezentację powiązań między pojęciami, bez konieczności używania bazy danych grafowych.

W niektórych przypadkach jest to niewłaściwy wybór:

• Wymagane są dane w czasie rzeczywistym, co wymusza użycie MCP.
• Reguły behawioralne wymagają kodowania, co jest zadaniem CLAUDE.md.
• Projekt jest mały i mieści się w jednej sesji, w której wystarcza sam CLAUDE.md.

Pierwsze kroki

Konfiguracja jest minimalna ze względu na projekt.

Z Claude Code

Wtyczka okf-skills zawiera trzy umiejętności. /okf:okf tworzy i zarządza plikami z umiejętnościami, /okf:validate sprawdza, czy plik spełnia wymagania, a /okf:visualize generuje interaktywny wykres. Zainstaluj ją za pomocą:

/plugin marketplace add scaccogatto/okf-skills
/plugin install okf@scaccogatto

Każdy agent, w tym Claude Code, Cursor, Codex oraz ponad dwadzieścia innych, może zamiast tego używać npm:

npx skills add scaccogatto/okf-skills

Następnie uruchom umiejętności:

/okf:okf produce .okf        # create your first bundle
/okf:validate .okf --strict  # check conformance
/okf:visualize .okf          # generate viz.html

Aby automatycznie aktualizować informacje, tak by Claude czytał pliki z katalogu .okf/ przed wykonywaniem zadań i zapisywał to, czego się nauczył, skopiuj szablon templates/CLAUDE-okf.md do pliku CLAUDE.md w projekcie. Nie ma żadnego przymusu do wykonania tego kroku.

Pisanie ręcznie

Stwórz katalog .okf/ i dodaj do niego plik index.md. Następnie dodaj po jednym pliku z koncepcją dla każdej ważnej funkcji realizowanej przez system. Zapis decyzji wygląda w ten sposób:

---
type: Decision
title: "Why we use Postgres over MySQL"
description: "JSONB support and row-level security were decisive."
timestamp: 2026-03-01T00:00:00Z
tags: [infrastructure, database]
---

Następuje treść:

## ContextIn early 2026 we evaluated both options. MySQL's JSON support was insufficient for our metadata schema...## DecisionPostgres 16. See [datasets/primary-db.md](../datasets/primary-db.md) for schema docs.

To wszystko, co jest potrzebne. Każdy agent z dostępem do pliku może go od razu przeczytać, a także przejrzeć go w PR i porównać w git.

Cały zestaw narzędzi

Oto jak OKF funkcjonuje obok pozostałych elementów w sesji:

+--------------------------------------------------+
|              AGENT SESSION                       |
+--------------------------------------------------+
|  CLAUDE.md / AGENTS.md                          |
|  (behavioral rules - how agent acts)            |
+--------------------------------------------------+
|  OKF BUNDLE (.okf/)                             |
|  (curated team knowledge - what we know)        |
|  - index.md: entry points per domain            |
|  - concepts/*.md: services, datasets, decisions |
|  - log.md: change history                       |
+--------------------------------------------------+
|  AUTO-MEMORY (memory.md)                        |
|  (what the agent picked up implicitly)          |
+--------------------------------------------------+
|  MCP CONNECTIONS                                |
|  (live tool access - what the agent can do)     |
+--------------------------------------------------+
|  SKILLS (.claude/skills/)                       |
|  (reusable SOPs - how to do specific tasks)     |
+--------------------------------------------------+

Każda warstwa odpowiada na swój własny pytanie. Nie nakładają się one na siebie, lecz uzupełniają się.

Co pozostawia otwarte wersja v0.1

Google otwarcie określa wersję v0.1 jako punkt wyjścia, przy czym najpierw rozwiązano problem interoperacyjności. Pozostaje kilka kwestii projektowych:

• Sprzeczności. Gdy dwa dokumenty OKF różnią się co do jednego faktu, nie istnieją jeszcze żadne zasady łączenia tych dokumentów.
• Przestarzała wiedza. Ponieważ OKF opiera się na plikach, dokument pozostawiony bez zmian, gdy system rozwija się dalej, jest wynikiem awarii procesu, a nie formatu.
• Relacje typowane. Obecna specyfikacja używa zwykłych linków markdown, natomiast bardziej złożone typy relacji, takie jak „sprzeciwia się”, „rozszerza” czy „zastępuje”, są opracowywane przez społeczność.
• Wyszukiwanie wielowymiarowe. Niektórzy użytkownicy chcą większej liczby tagów niż oferuje minimalna specyfikacja.

wersja v0.2 prawdopodobnie rozwiąże kilka z tych problemów na podstawie opinii użytkowników, a repozytorium specyfikacji jest publiczne i przyjmuje zgłoszenia błędów oraz propozycje zmian.

Dlaczego zwyciężają nudne formaty

Formaty, które stają się elementem infrastruktury, zazwyczaj są monotonne. JSON zwyciężyło, ponieważ było najprostszym rozwiązaniem, które działało i nie wymagało żadnych kosztów wdrożenia, a nie dlatego, że było genialne. Markdown osiągnęło ten sam sukces w podobny sposób.

OKF pasuje do tego opisu. Nie wymaga żadnych nakładów przy czytaniu ani pisaniu, a działa z każdym narzędziem obsługującym pliki. Jego wartość rośnie wraz z liczbą twórców i użytkowników, a decyzje pojedynczego dostawcy nie wpływają na nią. Zapisuje również wzorce, do których ludzie doszli samodzielnie, dzięki notatkom Karpathy’ego, nawykom z AGENTS.md oraz samodzielnie budowanym hierarchiom w index.md – co stanowi najlepszy dowód na rozwiązywanie rzeczywistego problemu.

Karpathy twierdził, że agenci lepiej zarządzają witrynami wiki niż ludzie, ponieważ nie nudzą się. Z kolei OKF uważa, że wartość wiki rośnie tylko wtedy, gdy może być dostępna wszędzie. Razem te dwa pomysły mogą w ciągu kilku lat stać się podstawą rozwoju wspomaganego przez agenty. Budowanie tego rozwiązania teraz, gdy jest jeszcze nowe, przyniesie korzyści zarówno później tobie, jak i każdemu agentowi, którego poinstruujesz.