{"slug": "moving-repository-memory-from-specs-to-okf", "title": "Moving repository memory from specs to OKF", "summary": "Google Cloud published the Open Knowledge Format (OKF) v0.2, an open, human- and agent-friendly format for representing knowledge as Markdown files with YAML frontmatter, designed to improve data sharing and AI agent context. The format formalizes the LLM-wiki pattern and adds provenance, trust, lifecycle, and attested computations, aiming to replace outdated Architecture Decision Records (ADRs) as project memory for AI-assisted development.", "body_md": "Before AI coding, my main approach to keep knowledge about software I was building was Architecture Decision Records. Basically, ADRs were project memory.\n\nIn bigger systems I used two levels. There was cross-repository ADR structure for decisions affecting the whole system, and local ADRs inside each repository for decisions affecting only this part. It worked super well. A new engineer could read the decisions, understand why system looks this way, and continue from there.\n\nThen AI coding started, and ADRs were not enough anymore.\n\n## ADRs Are History, Not Current Memory\n\nADRs answer one important question: why did we make this decision at that moment?\n\nBut they are sequential, eventually outdated, and never have 100% coverage. This is fine for humans. We combine ADRs with code, tickets, conversations, and memory of other engineers. Agent does not have all of this unless we explicitly give it access.\n\nEven worse, an old ADR can describe a decision correctly while the current implementation already moved somewhere else. Now agent has to reconstruct present state from a timeline of partially superseded documents. Sometimes it can. Sometimes it confidently picks wrong ADR :)\n\nSo I moved to specs.\n\n## Specs as a Snapshot\n\nI started keeping a `specs/`\n\ndirectory in repositories. You can see a real example in [Everruns v0.15.0](https://github.com/everruns/everruns/tree/v0.15.0/specs).\n\nA spec is not another name for ADR. It is a snapshot of current project memory. Most specs answer three questions:\n\n**Why** does this thing exist, including decisions and rejected alternatives?**How** is it supposed to work?**Where** are the important boundaries and sources of truth?\n\nThe important difference is maintenance. Agent is required to update specs in the same pull request as code. I put this rule in `AGENTS.md`\n\n, process skills, and pull request checklists. Periodically I also ask agent to inspect recent commits and find drift.\n\nThis was one of main enablers for my private and public projects over last year. I wrote more about the overall setup in [Making Your Repository AI-Ready](/blog/ai-ready-repository/).\n\nSpecs also support progressive disclosure. `AGENTS.md`\n\nstays small and points to the spec index. Agent reads the index, opens only documents relevant to current task, and follows links when it needs more depth. No reason to inject 100 pages of architecture into every turn.\n\nThis worked. But every repository invented slightly different structure. `specs/`\n\n, `decisions/`\n\n, indexes, metadata, links — same pattern, no shared format.\n\n## Okay, So What Is OKF?\n\nIn June Google Cloud published [Open Knowledge Format](https://cloud.google.com/blog/products/data-analytics/how-the-open-knowledge-format-can-improve-data-sharing/), or OKF. The initial v0.1 formalized the LLM-wiki pattern. Current [OKF v0.2 specification](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md) adds provenance, trust, lifecycle, and attested computations.\n\nThe official abstract is quite precise:\n\nOKF is an open, human- and agent-friendly format for representing knowledge: the metadata, context, and curated insight that surrounds data and systems.\n\nIn practical terms, it is a directory of Markdown files with YAML frontmatter and few conventions. Each knowledge document is a concept. `type`\n\nis the only required frontmatter field. Regular Markdown links connect concepts. Optional `index.md`\n\nfiles give progressive disclosure, and optional `log.md`\n\nfiles record changes.\n\nFor example:\n\n```\nknowledge/\n├── index.md\n├── log.md\n├── foundations/\n│   ├── index.md\n│   ├── architecture.md\n│   └── execution-model.md\n└── operations/\n    ├── index.md\n    ├── testing.md\n    └── release-process.md\n```\n\nAnd a concept starts with something like this:\n\n```\n---\ntype: Architecture\ntitle: Execution Model\ndescription: How work moves through the runtime.\n---\n```\n\nThat is mostly it. No database, no SDK, no special reader. If agent can read files, it can consume OKF.\n\nThis simplicity is why I like it. OKF is not trying to solve retrieval, build a knowledge graph product, or replace domain-specific schemas. It gives common shape to the pattern many of us already used.\n\nThe v0.2 trust model is also interesting. A concept can say what sources it came from, who or what generated it, who verified it, whether it is draft or deprecated, and when it becomes stale. A consumer derives trust from those signals instead of accepting every Markdown file equally.\n\n## How I Am Using It\n\nI am converging on the same repository-memory structure in Bashkit, Yolop, and Everruns. The amount of knowledge is different, but the pattern is the same: one `knowledge/`\n\nroot, indexes for navigation, typed concepts, and maintenance rules in `AGENTS.md`\n\n.\n\n### Bashkit: Full Project Memory\n\n[Bashkit](https://github.com/everruns/bashkit/tree/main/knowledge) uses `knowledge/`\n\nas canonical project memory and targets OKF v0.2.\n\nConcepts are grouped by domain: foundations, security, runtimes, integrations, operations, and generated status. Each directory has an index. Agent starts at root, picks relevant domain, and only then reads individual concepts.\n\nBashkit also has a [knowledge maintenance contract](https://github.com/everruns/bashkit/blob/main/knowledge/knowledge-contract.md). It defines what belongs in the bundle, local concept types, linking rules, and validation. CI runs both upstream OKF linting and repository-specific drift checks.\n\nThis part matters: OKF conformance does not mean knowledge is good. The standard intentionally stays minimal. Each project still needs to say what useful knowledge means for this project.\n\n### Yolop: Specs Inside an OKF Bundle\n\n[Yolop](https://github.com/everruns/yolop/tree/main/knowledge) took the most direct migration path. Existing product specs moved under `knowledge/specs/`\n\n, got typed frontmatter, and became one OKF bundle with a root index.\n\n`AGENTS.md`\n\ntells agent to read the index first and update affected concepts in the same change. Yolop also ships an [OKF skill](https://github.com/everruns/yolop/blob/main/knowledge/specs/okf.md) with the v0.2 mental model and a validator. No runtime capability is needed. OKF is just Markdown, and regular file tools already know how to read it.\n\n### Everruns: The Large Specs Migration\n\n[Everruns](https://github.com/everruns/everruns/tree/main/knowledge) was the largest migration. In [v0.15.0](https://github.com/everruns/everruns/tree/v0.15.0/specs) it had more than 100 documents under `specs/`\n\n, covering architecture, APIs, runtime, security, operations, and product decisions.\n\nThis corpus now lives in the same OKF structure as Bashkit: `knowledge/`\n\nat the root, domain directories with their own indexes, and typed frontmatter on every concept. The content and its purpose stay the same. Migration mostly gives it standard navigation and metadata. The repository also has a [knowledge maintenance contract](https://github.com/everruns/everruns/blob/main/knowledge/knowledge-contract.md) describing the boundaries and same-change update rule.\n\nThis is useful example because migration does not require rewriting all repository memory. Existing specs already contain the why and the current intent. OKF gives them common structure.\n\nAcross all three repositories the rules are now more or less the same:\n\n`knowledge/index.md`\n\nis the entry point.- Domain indexes provide progressive disclosure.\n- Every concept has a type and small amount of useful metadata.\n`AGENTS.md`\n\ntells agent when and how to maintain the bundle.- CI validates structure and links.\n\n## Maintenance Is Still the Real Problem\n\nFormat does not keep knowledge current.\n\n[LangChain OpenWiki](https://github.com/langchain-ai/openwiki) can generate and continuously maintain an OKF wiki from a codebase. It can run from CI and open documentation updates based on changed code. This is useful, especially for inventories, module maps, APIs, and other facts that can be recovered from source.\n\nBut generating knowledge from code has a hard limit.\n\nCode can tell agent what exists now. It can recover module maps, APIs, dependencies, and behavior visible in tests. But most important thing in project memory is **why**. Code usually cannot tell why this option won, what we deliberately refused to build, which constraint came from production incident, or what tradeoff we accepted. If this information was never recorded, another model cannot reverse-engineer it reliably.\n\nThis is why in most of my projects knowledge changes are part of normal pull request. When implementation changes durable behavior, architecture, policy, threat model, or process, agent updates relevant concept in the same change. Reviewer sees code and memory diff together.\n\nThis is the important part: **agent maintains knowledge as part of the PR**, not in a separate documentation project weeks later.\n\nTypical maintenance prompt I use before opening a PR looks like this:\n\nReview changes in this branch and update repository knowledge. Capture durable behavior, architecture, decisions, constraints, rejected alternatives, threats, tests, and process changes. Keep volatile implementation details in code. Update affected concepts and indexes, then run OKF validation.\n\n[Everruns](https://github.com/everruns/everruns/blob/main/knowledge/knowledge-contract.md), [Bashkit](https://github.com/everruns/bashkit/blob/main/AGENTS.md#knowledge), and [Yolop](https://github.com/everruns/yolop/blob/main/AGENTS.md#keeping-knowledge-current) contain the permanent maintenance rule. Their CI runs small [Everruns](https://github.com/everruns/everruns/blob/main/scripts/check_okf.py), [Bashkit](https://github.com/everruns/bashkit/blob/main/scripts/check_okf.py), and [Yolop](https://github.com/everruns/yolop/blob/main/scripts/validate_okf.py) validators to catch broken structure, metadata, indexes, and links.\n\nGenerated knowledge still has a place. Bashkit uses it for machine inventories and marks who generated the concept plus the source it describes. This is where OKF v0.2 trust metadata is useful. Generated facts are visibly generated; human-authored decisions stay human-authored and reviewed.\n\nMy current maintenance loop is super simple:\n\n- Read relevant knowledge before changing behavior.\n- Update affected concepts together with code.\n- Update indexes when structure changes.\n- Validate format and links in CI.\n- Periodically inspect recent commits for semantic drift.\n\nValidator can catch missing `type`\n\n, broken links, or forgotten index entry. It cannot catch a perfectly formatted lie. Review is still required.\n\n## The `log.md`\n\nProblem\n\nI am less convinced about central `log.md`\n\n.\n\nWhen agent maintains knowledge in every pull request, many unrelated changes touch the same file. Result is predictable: merge conflict after merge conflict. The log also repeats information already available in Git history and pull request descriptions, usually with less detail.\n\nOKF makes `log.md`\n\noptional, which is good. For bundles living in Git, I am leaning toward removing it altogether. Git is the log.\n\nThere are still cases where `log.md`\n\nmakes sense: exported bundle without repository history, a curated public knowledge release, or maybe one log per domain. But mandatory central log inside active repository feels like ceremony with very obvious cost and unclear value.\n\nI will probably keep `index.md`\n\n, because it is the navigation layer that enables progressive disclosure, and drop `log.md`\n\nfrom repository-local bundles. Less bookkeeping, fewer conflicts, same useful knowledge.\n\n## Where I Landed\n\nADRs captured decisions. Specs captured current state. OKF gives this project memory a standard, portable shape.\n\nIt does not remove need to write things down, maintain them, or review the why. Good. I do not want format to pretend it can solve that.\n\nFor me OKF is not a new knowledge system. It is a common contract for the one that was already working.\n\nFor comments or feedback, write at[x.com/chaliy](https://x.com/chaliy).", "url": "https://wpnews.pro/news/moving-repository-memory-from-specs-to-okf", "canonical_source": "https://chaliy.name/blog/from-adrs-to-specs-to-okf/", "published_at": "2026-08-07 00:00:00+00:00", "updated_at": "2026-08-09 12:39:06.597166+00:00", "lang": "en", "topics": ["ai-tools", "developer-tools", "ai-agents", "artificial-intelligence"], "entities": ["Google Cloud", "Open Knowledge Format", "Everruns"], "alternates": {"html": "https://wpnews.pro/news/moving-repository-memory-from-specs-to-okf", "markdown": "https://wpnews.pro/news/moving-repository-memory-from-specs-to-okf.md", "text": "https://wpnews.pro/news/moving-repository-memory-from-specs-to-okf.txt", "jsonld": "https://wpnews.pro/news/moving-repository-memory-from-specs-to-okf.jsonld"}}