If two sources conflict, an agent does not have organizational context. It has a guessing problem.
Instead of arguing this in the abstract, I want to walk through a setup that solves it in practice: a markdown wiki that is built and maintained *with* AI, and that agents can read directly, with retrieval added only when it helps. The whole approach follows one idea, which Google recently formalized as the [Open Knowledge Format](https://cloud.google.com/blog/products/data-analytics/how-the-open-knowledge-format-can-improve-data-sharing): a directory of plain markdown files with YAML frontmatter, versioned in git, where ordinary markdown links form the relationship graph. No proprietary wiki database, no vendor lock-in. The same folder works in an editor, in Obsidian, and as direct context for an agent. Related article: [How to Turn Scattered Data into AI Intelligence](https://www.sebastianstoehr.de/blog/2026-05-turn-scattered-data-into-ai-intelligence/) ## Why markdown in git Three properties make this combination unusually well suited for agent-ready knowledge: - **Markdown can be used directly as agent context.** For small knowledge bases, that can avoid a separate ingestion, chunking, or embedding layer. - **Git gives you history and a review gate.** Every change to the knowledge base is a diff. Nothing enters silently, and you can always answer "when did this change, and who approved it?" - **Links are relations.** A wikilink like `[[refund-policy]]` is not decoration. It is a machine-readable statement that two pieces of knowledge belong together. The rest of the setup is about making those properties enforceable: a defined structure, defined domains, and an AI workflow that keeps the format intact while content flows in. ## Step 1: Specify the structureThe examples are simplified and need to be adjusted to your specific use case. You can use AI tools to help you identify a possible structure for your use cases.
The first artifact is not content. It is a written specification of what a valid note looks like – written for the agent as much as for people. A minimal repository layout: ``` knowledge/ _schema/ STRUCTURE.md # what a valid note looks like DOMAINS.md # domains and allowed relations CONTENT-RULES.md # how raw input becomes a note processes/ index.md products/ index.md teams/ index.md decisions/ index.md ``` Every note follows the same template: one topic per file, frontmatter that makes its status explicit, and a body written as instruction rather than narrative. ```markdown --- title: Escalation path for Product X domain: processes owner: team-support status: current # current | draft | superseded reviewed: 2026-07-01 supersedes: escalation-path-2024 scope: product-x --- When a Product X ticket cannot be resolved in first-level support: 1. Check whether the case matches a known exception in [[product-x-exceptions]]. 2. If yes, follow the exception. If no, hand over to [[team-platform]]. 3. Refunds above the threshold in [[refund-policy]] always require human approval. ``` OKF itself is deliberately minimal – the spec requires only a `type` field and leaves the content model to the producer. The fields above are an extension for exactly the questions an agent otherwise has to guess at: status, ownership, scope, and validity. This frontmatter is the difference between searchable and agent-ready. An agent that finds this note does not have to infer authority from wording or recency. The status, owner, scope, and supersession are stated – and a superseded note is marked as such instead of silently competing with its replacement. ## Step 2: Specify domains and their relations Structure tells the agent what a note is. Domains tell it how notes may relate. `DOMAINS.md` defines both – the domains you actually operate in, and the relations that are allowed between them: ```markdown ## Domains - **process** – how work is done: steps, handoffs, escalation paths - **product** – what the process applies to - **team** – who owns and executes - **decision** – why something is the way it is, and what it replaced ## Allowed relations - process → owned-by → team (required) - process → applies-to → product - process → depends-on → process - decision → supersedes → decision - decision → affects → process ``` This looks bureaucratic on paper. In practice it is a short file, and it turns vague knowledge problems into checkable rules: - A process note without an `owned-by` relation is incomplete – flag it. - Two `current` notes claiming the same scope are a conflict – flag it, don't guess. - A decision that affects a process must link to it – otherwise the change is invisible. The agent does not need judgement to enforce any of this. It needs the rules written down. ## Step 3: A skill that turns raw content into notes Knowledge does not arrive as clean markdown. It arrives as Slack threads, Confluence pages, meeting notes, and email chains. This is where AI does the heavy lifting. The core of the setup is a skill – a reusable, versioned instruction set for the agent – that takes raw content as input, through whatever MCP connector it happens to live behind, and incorporates it according to the content rules: ```markdown # Skill: incorporate-knowledge Input: raw content (Slack thread, Confluence page, meeting notes, transcript) 1. Identify the domain(s) the content belongs to (see DOMAINS.md). 2. Strip everything that is not knowledge: greetings, scheduling, dead ends, opinions that were not decided on. 3. Restructure the rest per STRUCTURE.md: one topic per note, instruction over narrative, frontmatter complete. 4. Link to existing notes. Search the wiki before creating a new note – extend or supersede an existing one where possible. 5. If the content conflicts with a `current` note, do NOT resolve it. Mark the conflict explicitly in the PR description. 6. Open a pull request. Never commit to main. ``` The last two rules carry most of the weight. The skill is allowed to structure and propose. It is not allowed to decide what is true or to change the knowledge base directly. A concrete run looks like this: a decision gets made in a Slack thread, someone points the agent at it, and a few minutes later there is a PR containing one new decision note, an updated process note with a corrected handoff, and a `status: superseded` change on the old version – with the noise of the thread stripped out. ## Step 4: Pull requests as the review gate At the start, every PR is reviewed by a person. That is deliberate, and it is cheaper than it sounds: the diffs are small, the notes are structured, and reviewing a ten-line note is nothing like reviewing a wiki page rewrite. You are not proofreading prose – you are checking whether a statement is true and whether it belongs where the agent put it. The evolution path is to move parts of that review to a second agent: 1. **Format validation first.** An agent checks what needs no judgement: links resolve, required relations exist, frontmatter is complete, no second `current` note claims the same scope. 2. **Statement validation next.** The agent cross-checks new claims against existing notes and the source material, and annotates the PR: what is new, what confirms existing knowledge, what contradicts it. 3. **Scoped auto-approval last.** Low-risk changes – a new glossary entry, an added link, a review-date bump – can eventually merge on agent approval. Conflicts, supersessions, and anything touching decision boundaries stay with a human. This is also the correction path. When the agent gives a wrong answer, the fix is not a prompt tweak – it is a PR against the note that misled it. Agent failures become knowledge maintenance work with a diff and an approver. Related article: [AI Exposes Your Knowledge Debt](https://www.sebastianstoehr.de/blog/2026-07-ai-exposes-your-knowledge-debt/) ## Step 5: See the relations as a graph Because relations are plain wikilinks, you get visualization for free: open the same folder in Obsidian and the graph view renders the knowledge base as a network – domains as clusters, relations as edges. This is not decoration. The graph is a maintenance instrument: - **Orphan notes** – no links in or out – are suspect. Either they are missing relations, or they are knowledge nobody's workflow actually touches. - **Dense clusters with no bridges** between them often mean two teams describe the same process without knowing about each other. - **A superseded note that still has many inbound links** tells you exactly which notes need updating next. The same questions can be asked by an agent walking the links. The graph just makes them visible to people in one glance.Searchable knowledge helps an agent find material. Agent-ready knowledge tells it what is current, who owns it, and how it connects.
## Start small None of this needs to begin as a company-wide knowledge program. Pick one workflow where an agent is expected to influence real work. Write `STRUCTURE.md` and `DOMAINS.md` for that slice, build the incorporate skill, and route the next five pieces of raw content through it. What you get is not just a cleaner document library. It is a knowledge base with explicit status, ownership, and relations – maintained through the same review mechanics your engineers already trust, and readable by every agent you will connect next. I have a version of this setup running across eight domains. It pulls relevant content from JIRA, Confluence, and office documents each night, and it has been reliable enough to extend gradually with new domains and sources. At first, my agents read the Git repository directly, using `index.md` files and lexical tools to locate relevant notes. I now expose the same knowledge through a small MCP tool with lexical search. A full RAG layer may make sense later, but the simple setup is working well today. The benefit of structuring knowledge first is not tied to the query backend. The agent extracts and condenses content, changes are reviewed, conflicts are explicit, and ownership is recorded. Those improvements raise knowledge quality whether the eventual interface is direct files, lexical search, or RAG. ## Related media - Article image:  — Agent-ready knowledge needs explicit relationships, ownership, and status. (AI generated) - Carousel ("Agent-ready knowledge" — 9 slides): -  -  -  -  -  -  -  -  -  ## Related reading - [How to Turn Scattered Data into AI Intelligence](https://www.sebastianstoehr.de/blog/2026-05-turn-scattered-data-into-ai-intelligence/) - [AI Exposes Your Knowledge Debt](https://www.sebastianstoehr.de/blog/2026-07-ai-exposes-your-knowledge-debt/)