Knotenhirn
Sign in Try it free

All guides

CLAUDE.md or knowledge base: when is one file enough?

Updated 6 November 2026 · by Michael Schwarz

A CLAUDE.md is enough as long as it holds rules that apply to almost every task: how to build and test, which conventions you use, what is off limits. As soon as it collects knowledge that is needed only sometimes, such as edge cases, customer agreements and the why behind decisions, that knowledge belongs in a knowledge base that Claude Code searches when it needs to. The CLAUDE.md then stays short and keeps its job.

What the CLAUDE.md is made for

Claude Code reads the CLAUDE.md at the start of every session. Everything in it is in context from the first message. That is its strength: what should always apply does not have to be looked up first. The command for the tests, the order of the build steps, the rule that migrations are never changed afterwards. Sentences like these belong exactly there.

It lives in the repository, is versioned with the code and read in review. For a team that wants to record rules about its code, there is hardly a better place.

Signs that the file is getting too big

The CLAUDE.md grows quietly. After every session in which Claude Code misunderstood something, another paragraph goes in. After a few months it no longer says only how you work, but also what the team has learned over time. These signs suggest that part of it needs another place:

  • Many sections concern only individual customers, modules or outages and are irrelevant to most tasks.
  • You shorten explanations to keep the file manageable, and lose the why in the process.
  • The same knowledge appears in several repositories because it concerns more than one project.
  • Colleagues without access to the repository know something Claude Code would need, and cannot add it.
  • New knowledge only gets in through a pull request, so most of the time it does not get in at all.

Then there is the context. Whatever is in the CLAUDE.md takes up space in every session, even if the task needs only a small part of it. With twenty lines that does not matter. With hundreds of lines about edge cases, you pay in every session for knowledge that nobody needs right now.

What a knowledge base does differently

A knowledge base is not loaded in advance; it is queried. Claude Code searches it when a task calls for it and fetches only the notes that fit. Whether it holds ten notes or a thousand makes hardly any difference to a single session.

Knotenhirn is a hosted team memory for AI agents with a built-in MCP server. Its search combines full text and meaning, so Claude Code finds a note even when it uses different words from the question. People write notes in the browser in Markdown, and Claude Code writes them itself when you ask it to. No pull request is needed, and people from support or sales can record what they know as well.

Groups decide who sees which notes. Claude Code sees only what the connected person may see. Every change stays in the history, with person, time and whether it was made in the browser or via MCP.

A simple rule of thumb

Ask of every paragraph: does Claude Code need this for almost every task in this repository?

  • Yes: it stays in the CLAUDE.md. Examples are commands, conventions, prohibitions and the structure of the project.
  • Only sometimes: it belongs in the knowledge base. Examples are decisions with their reasons, edge cases, agreements with customers, pitfalls and fixes for past outages.
  • People should read it in one go: it belongs in the wiki. Examples are architecture, handbooks and processes.

The three places do not exclude each other. Each has a job, and none has to take over the job of the others.

An example of the split

An example: a team runs an online shop. Its CLAUDE.md starts with fifteen lines on build, tests and style. Over time, sections are added: why shipping costs for islands are calculated separately, which major customer has its own discount logic, why the nightly export starts only after the stock reconciliation, what helped during the last outage in the payment flow. In the end there are several hundred lines, and most of them have nothing to do with the current task.

The team moves the sections about customers, outages and decisions into Knotenhirn as individual notes, one note per topic, with the reason written out instead of shortened. The CLAUDE.md keeps the fifteen lines plus one sentence: for questions about the why, about customers or past outages, Claude Code searches Knotenhirn first. When someone later asks why the discount for this customer is calculated differently, Claude Code finds the note and names it as its source.

The support team, who know the agreement, can now add to the customer section too, without touching the repository. And when a customer no longer has the special rule, someone changes one note instead of hunting for the right place in a long file.

How to connect Claude Code

Sign in with Microsoft or Google, create your team and connect Claude Code with one line in the terminal:

claude mcp add --transport http --scope user knotenhirn https://knotenhirn.dev/mcp

Then run /mcp in Claude Code, choose knotenhirn and sign in in the browser. Other clients are covered by the Connect MCP guide. How Claude Code works with the memory is shown in the guide Giving Claude Code a memory for your team.

Try it with your team

Try Knotenhirn free for 14 days, with no payment details. The trial does not turn into a subscription automatically.

Try free for 14 days

Knotenhirn

The shared memory for your team and your AI agents. Complements your wiki.

Servers in Germany · AI in the EU

Try free for 14 days

Product

  • Features
  • Pricing
  • Comparisons
  • Connect MCP
  • Guides
  • Sign in

Security

  • Security and DPA
  • DPA as PDF
  • Privacy

Legal

  • Legal notice
  • Terms
  • Right of withdrawal

Contact

  • knotenhirn@michael-schwarz.dev
  • 15 minutes with Michael
  • LinkedIn
  • GitHub
  • michael-schwarz.dev
© 2026 Michael Schwarz Cancel contracts here Deutsch