--- title: 'Moving repository memory from specs to OKF' description: 'How my project memory evolved from architecture decision records to living specs and now Open Knowledge Format bundles maintained together with the code.' date: 2026-08-07 tags: - ai - agents - documentation - developer-experience - knowledge-management --- Before AI coding, my main approach to keep knowledge about software I was building was Architecture Decision Records. Basically, ADRs were project memory. In 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. Then AI coding started, and ADRs were not enough anymore. ![Repository memory evolving from ADRs to specs and then OKF](memory-evolution.svg) ## ADRs Are History, Not Current Memory ADRs answer one important question: why did we make this decision at that moment? But 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. Even 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 :) So I moved to specs. ## Specs as a Snapshot I started keeping a `specs/` directory in repositories. You can see a real example in [Everruns v0.15.0](https://github.com/everruns/everruns/tree/v0.15.0/specs). A spec is not another name for ADR. It is a snapshot of current project memory. Most specs answer three questions: - **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? The important difference is maintenance. Agent is required to update specs in the same pull request as code. I put this rule in `AGENTS.md`, process skills, and pull request checklists. Periodically I also ask agent to inspect recent commits and find drift. This 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/). Specs also support progressive disclosure. `AGENTS.md` stays 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. This worked. But every repository invented slightly different structure. `specs/`, `decisions/`, indexes, metadata, links — same pattern, no shared format. ## Okay, So What Is OKF? In 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. The official abstract is quite precise: > OKF is an open, human- and agent-friendly format for representing knowledge: the metadata, context, and curated insight that surrounds data and systems. In practical terms, it is a directory of Markdown files with YAML frontmatter and few conventions. Each knowledge document is a concept. `type` is the only required frontmatter field. Regular Markdown links connect concepts. Optional `index.md` files give progressive disclosure, and optional `log.md` files record changes. For example: ```text knowledge/ ├── index.md ├── log.md ├── foundations/ │ ├── index.md │ ├── architecture.md │ └── execution-model.md └── operations/ ├── index.md ├── testing.md └── release-process.md ``` And a concept starts with something like this: ```markdown --- type: Architecture title: Execution Model description: How work moves through the runtime. --- ``` That is mostly it. No database, no SDK, no special reader. If agent can read files, it can consume OKF. This 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. The 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. ## How I Am Using It I 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/` root, indexes for navigation, typed concepts, and maintenance rules in `AGENTS.md`. ### Bashkit: Full Project Memory [Bashkit](https://github.com/everruns/bashkit/tree/main/knowledge) uses `knowledge/` as canonical project memory and targets OKF v0.2. Concepts 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. Bashkit 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. This 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. ### Yolop: Specs Inside an OKF Bundle [Yolop](https://github.com/everruns/yolop/tree/main/knowledge) took the most direct migration path. Existing product specs moved under `knowledge/specs/`, got typed frontmatter, and became one OKF bundle with a root index. `AGENTS.md` tells 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. ### Everruns: The Large Specs Migration [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/`, covering architecture, APIs, runtime, security, operations, and product decisions. This corpus now lives in the same OKF structure as Bashkit: `knowledge/` at 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. This 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. Across all three repositories the rules are now more or less the same: 1. `knowledge/index.md` is the entry point. 2. Domain indexes provide progressive disclosure. 3. Every concept has a type and small amount of useful metadata. 4. `AGENTS.md` tells agent when and how to maintain the bundle. 5. CI validates structure and links. ## Maintenance Is Still the Real Problem Format does not keep knowledge current. [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. But generating knowledge from code has a hard limit. Code 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. This 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. This is the important part: **agent maintains knowledge as part of the PR**, not in a separate documentation project weeks later. Typical maintenance prompt I use before opening a PR looks like this: > Review 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. [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. Generated 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. My current maintenance loop is super simple: 1. Read relevant knowledge before changing behavior. 2. Update affected concepts together with code. 3. Update indexes when structure changes. 4. Validate format and links in CI. 5. Periodically inspect recent commits for semantic drift. Validator can catch missing `type`, broken links, or forgotten index entry. It cannot catch a perfectly formatted lie. Review is still required. ## The `log.md` Problem I am less convinced about central `log.md`. When 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. OKF makes `log.md` optional, which is good. For bundles living in Git, I am leaning toward removing it altogether. Git is the log. There are still cases where `log.md` makes 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. I will probably keep `index.md`, because it is the navigation layer that enables progressive disclosure, and drop `log.md` from repository-local bundles. Less bookkeeping, fewer conflicts, same useful knowledge. ## Where I Landed ADRs captured decisions. Specs captured current state. OKF gives this project memory a standard, portable shape. It 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. For me OKF is not a new knowledge system. It is a common contract for the one that was already working.