The Knowledge Base Your AI Agent Can Actually Use

Documentation written for humans fails agents

Most project documentation is written for humans who skim. A README gives an overview. A wiki page covers a topic with enough context for a new team member to orient themselves. An architecture document describes the system at a level of abstraction that helps engineers make decisions.

AI agents do not skim. They query. They are looking for a specific piece of information to complete a specific task. A 2,000-word document explaining the history of an architectural decision is not useful: the three-sentence summary of what was decided and why is.

This does not mean you need to throw away existing documentation. It means that the knowledge you expose to your agent should be structured differently than the knowledge you write for teammates.

What makes a good topic

A topic is the atomic unit of a knowledge base. Each one should answer a single, well-defined question. Not "how does the project work" but "what database do we use and why." Not "who are our users" but "what are the three user personas and what does each one care about."

Topics that tend to be most useful to agents:

• Architectural decisions with rationale. Not just "we use PostgreSQL" but "we use PostgreSQL because we need transactional consistency across the order and inventory tables: do not switch this without discussing with the team."
• Operational constraints. Things the agent must never do, or must always do, when working on the project. File conventions, naming rules, environment-specific behavior.
• Domain concepts. The vocabulary your project uses and what each term means precisely. "A Project in meridiaan is a container for topics, with its own API key and MCP endpoint. It is not a team or a workspace."
• Recent changes. What was built or decided recently that the agent might not infer from the codebase alone. Useful for keeping the agent oriented without it having to read git history.

The iterative approach beats the comprehensive one

The temptation when setting up a knowledge base is to write everything upfront. Document the whole project before the agent touches it. This produces two outcomes: either you spend days writing documentation before you can start working, or you write a rough first draft that is too incomplete to be useful and then abandon the whole thing.

A better approach is additive. Start with the three or four things that are most likely to trip up an agent working on your project for the first time. Add topics as you notice the agent making incorrect assumptions. When a decision changes, update the relevant topic. When a new constraint emerges, add a topic.

A knowledge base that grows with the project is more accurate than one written all at once. It reflects what actually matters rather than what seemed important before work began.

It is not just for the developer

The same knowledge base that helps your coding agent is immediately useful to every other AI tool your team uses. A marketing person asking their assistant about product positioning, a support agent answering customer questions, a manager summarizing project status: all of them benefit from the same source of truth.

When knowledge is centralized and queryable, the cost of keeping everyone aligned drops to near zero. You write a topic once. Every person and every agent that needs that information can get it, in context, on demand.

That is what separates a knowledge base that agents can actually use from one that just sits there and rots.