AGENTS.md and CLAUDE.md for a knowledge base

AGENTS.md and CLAUDE.md are plain markdown files that coding agents read before they work in a folder. In a knowledge base, they are where you tell agents how your notes are organised and which rules every document must follow. Neither file has required fields or a schema: you write instructions in ordinary markdown.

This guide covers the manual setup first. Next to each part, you'll see what changes with Knowtarium, our end-to-end encrypted knowledge base that people and agents write together, and the conventions it gives every agent you connect.

AGENTS.md

AGENTS.md is an open format for guiding coding agents, stewarded by the Agentic AI Foundation under the Linux Foundation. Many coding agents read it, including OpenAI Codex and Cursor. You put it at the root of your folder, and you can add more in subfolders: the nearest AGENTS.md to the file being edited wins, and what you type in the chat overrides all of them.

CLAUDE.md

CLAUDE.md is Claude Code's version. According to Anthropic's docs, Claude Code reads it from several places, broadest first:

Organisations can also deploy a managed CLAUDE.md. Files don't override each other: Claude Code concatenates them, from the filesystem root down to where you started it, so the most specific instructions come last. Files in subfolders load when Claude reads a file in that subfolder. A CLAUDE.md can pull in other files with @path/to/file, up to four levels deep. Anthropic recommends keeping each file under 200 lines.

In Knowtarium

Knowtarium adds checks that an instructions file can't. Whatever an agent does with your rules, every change it makes is signed and can be undone in one click, it deletes documents only if you gave it that permission, and it can't mark anything as checked by a person. In folders where you turn on review, its changes wait as diffs until you approve them.

(opens full size in a new tab) (opens full size in a new tab)

If you use more than one agent, write your rules once in AGENTS.md. Recent versions of Claude Code read AGENTS.md on their own when there's no CLAUDE.md or CLAUDE.local.md in the folder or above it (v2.1.277 and later). If you also want Claude-specific instructions, or you're on an older version, create a CLAUDE.md next to it that imports it:

@AGENTS.md
 
## Claude Code
 
- Work in plan mode for any change that touches more than three documents.

Claude reads the imported AGENTS.md first, then the lines below it. Every other agent reads AGENTS.md directly, so the rules never drift apart.

Most AGENTS.md examples are written for code: build commands, tests, style. A knowledge base needs different rules. These are the ones that matter most when agents write a lot of your notes.

Folder layout

Say what each top-level folder is for and where new documents go. Without this, agents invent folders, and two agents file the same kind of note in two places.

Naming

One concept per file, one naming pattern. Dated names for decisions and meetings make the folder sort itself.

Linking

Pick one link style and say so. Standard markdown links work in every tool; [[wikilinks]] only work in some. Tell agents to update links when they move a file, and that a link to a document nobody has written yet is allowed.

Frontmatter for provenance and freshness

This is the rule most templates leave out, and the one that makes an agent-written knowledge base checkable later. Require every document to say who wrote it and when it goes stale. The Open Knowledge Format, an open specification published by Google Cloud, gives you the field names: type (the only required one), generated, verified, status, stale_after and sources. Using a published format means any tool that reads OKF understands your notes.

Source citation

Require a source for every number, date, name and quote, cited next to the claim. The guide to making agents cite sources goes deeper.

What agents must never do

Write the hard lines as "Never" rules: never mark something as checked by a person, never delete, never overwrite a person's edit. Anthropic's docs note that specific, concise instructions are followed more consistently than general ones.

How to record a check

When an agent confirms a document, it should say so in a fixed way: its own entry in verified with a timestamp. Then anyone can tell an agent's check from a person's.

In Knowtarium

In folders with review on, Knowtarium turns those entries into a trust tier. An agent's entry makes a document machine-confirmed, yours makes it human-reviewed, and both after the last change make it fully verified. When you approve an agent's change there, the app writes your entry for you.

(opens full size in a new tab) (opens full size in a new tab)

Copy this into AGENTS.md at the root of your notes folder, then change the folder list to match yours. It stays under Anthropic's 200-line guideline with room to spare.

---
type: Instructions
title: Rules for agents
---
 
# Knowledge base: rules for agents
 
This folder is a knowledge base that people and agents write together.
Every file is plain markdown with YAML frontmatter (OKF v0.2).
Read this whole file before you change anything.
 
## Layout
 
- index.md in each folder lists what the folder holds. Read it first.
- log.md records what changed, newest first. Add a line for every session.
- company/     mission, glossary, how we work
- customers/   segments, interviews/ (one file per interview)
- metrics/     one file per metric; computations/ for approved queries
- decisions/   one file per decision, named YYYY-MM-DD-short-title.md
- references/  copies of source material you cite (PDF, CSV, saved pages)
- Never create a new top-level folder. Ask first.
 
## Finding things
 
- Start from the root index.md and follow links. Don't read every file.
- Search before you write. If a document on the topic exists, update it.
 
## Naming
 
- One concept per file. File names are lowercase-with-hyphens.md.
- index.md and log.md are reserved. Never use them for a document.
 
## Links
 
- Use standard markdown links, never [[wikilinks]].
- Link from the bundle root: [Churn](/metrics/churn.md).
- Linking to a document that doesn't exist yet is fine. Don't create
  an empty file just to fix the link.
- When you rename or move a file, update every link to it.
 
## Frontmatter
 
Every document starts with frontmatter. Keep keys you don't recognise
exactly as they are.
 
```yaml
---
type: Metric                # required: Metric, Decision, Interview, ...
title: Churn
description: One sentence, used in index.md and search.
status: stable              # draft | stable | deprecated
generated: { by: <your-name>/<version>, at: <UTC time, ISO 8601> }
stale_after: <UTC time>     # when this stops being safe to quote
sources:
  - id: billing-export
    resource: /references/billing-2026-09.csv
    title: Billing export, September 2026
---
```
 
- Sign every document you write or change in `generated`.
  Update `generated.at` on every meaningful change.
- Set `stale_after`: 90 days for metrics, 1 year for decisions.
- New documents start as `status: draft`.
 
## Sources
 
- Every number, date, name and quote needs a source.
- Add the source to `sources` with a short, stable `id`, then cite it
  after the claim with a footnote: Churn fell to 2.4%.[^billing-export]
- Only cite a source you opened in this session. Never invent a URL.
- If you can't find a source, write the claim under
  "## Open questions" instead of stating it as fact.
 
## Checking a person's edit
 
- Read the change, then every document that links to it or shares a
  source with it.
- If everything still matches, add yourself to `verified`:
  - { by: <your-name>/<version>, at: <UTC time> }
- If something no longer matches, propose the fix. Don't apply it silently.
 
## Never
 
- Never add a `human:` entry to `verified`. Only a person does that.
- Never remove or reorder someone else's `verified` entries.
- Never delete a document. Set `status: deprecated` and say why.
- Never overwrite a person's edit. If you disagree, say so and stop.
- Never edit files in references/. They are the evidence.
 
## When you finish
 
- Add a dated entry to log.md.
- List every file you created, changed, moved or deprecated.

Replace the retention periods under Frontmatter with your own. OKF counts every .md file except index.md and log.md as a document, so the template starts with its own frontmatter and a type to keep the bundle valid. The example frontmatter block inside is there for agents to copy.

Some rules only matter in one place. With AGENTS.md, put a second file in that folder, such as metrics/AGENTS.md; agents use the nearest one. Claude Code also has path-scoped rules: markdown files in .claude/rules/ with a paths field, loaded only when Claude reads a matching file.

---
paths:
  - "metrics/**/*.md"
---
 
# Metrics
 
- Every metric links to the query that computes it in metrics/computations/.
- Never change a number without a new source entry.

This keeps the root file short. Anthropic's docs warn that longer instruction files use more context and reduce adherence.

In Claude Code, run /context and look under Memory files to confirm your file loaded. With any agent, start a session by asking it to restate the rules for writing a new document. If it can't, the file isn't being read or is too long.

Then check the output, not the promise. Two greps catch the most common slips:

# documents with no type: the one required OKF field
$ grep -rL "^type:" --include="*.md" . | grep -v -e "/index.md$" -e "/log.md$"
 
# wikilinks that slipped in
$ grep -rn "\[\[" --include="*.md" .

When the same mistake shows up twice, add a rule for it. That's also Anthropic's advice for CLAUDE.md: write down what you'd otherwise explain again.

Knowtarium includes a conventions skill that every agent you connect gets along with its tools (Claude Code, Codex, Cursor, Claude Desktop and others), so you don't have to write the conventions of a Knowtarium knowledge base into every instructions file.

What it teaches

• Read the workspace's own index first. Where it has an index.md, read it and follow its links instead of loading every document.
• Read before you write. Titles and descriptions before whole documents, and every change names the version it was based on, so an agent can't overwrite an edit it hasn't read.
• Know how a change lands. In most folders a change is saved at once and can be undone, so be conservative; in folders with review on, it waits for approval. Either way, tell the person which.
• Check after a person's edit. In folders with review on, read the connected documents, record the check if everything still matches, and flag a conflict if something doesn't.

How it pairs with your AGENTS.md

In Knowtarium, your AGENTS.md is the folder's instructions: write it in the app, and agents get it with every note they write there.

Some rules don't depend on anyone reading a file. In Knowtarium, every change an agent makes is signed with its own key, agents delete documents only if you gave them that permission, they can't mark anything as checked by a person, and in folders with review on they can't skip your review. An agent only reaches the workspace and folders you connected it to. The app doesn't call an AI itself: when you want your edits checked, you ask your agent, and it follows the skill.

Agents connect over MCP with npx knowtarium connect, with the Knowtarium plugin in Claude Code and Codex (it includes the skill), with the extension in Claude Desktop, or in one click for Cursor and VS Code. Connectors for chat apps such as claude.ai and ChatGPT come later. See how agents work with Knowtarium.