Teaching your agent to use the wiki

Connecting an agent gives it the tools. It does not give it the habit.

Left to itself, a connected agent will mostly ignore the wiki — it has no reason to believe there is anything in there worth reading, and no prompt telling it to write anything back. The snippets on this page are what close that gap. They are the difference between a wiki that accumulates knowledge and one that stays empty next to a working MCP connection.

If you haven't connected yet, /connect does it in a minute; Connect Claude Code is the same by hand.

What the server teaches on its own

Two things arrive without any prompt. When a client connects, the server's initialize reply carries a three-line contract: read a page with wiki_getPage and keep its version; change it with wiki_patchPage against that version; use wiki_updatePage only to create a page or rewrite one. And wiki_guide returns the full manual — paths, wikilinks, diagrams, the read-keep-the-version-patch loop — which is why every snippet below starts by calling it. The snippet is what turns that into a habit: when to read, when to write, and that the wiki is worth the trouble.

The loop you're encoding

Every snippet below is a variation on the same four beats:

1. Orient at session start — read the index, then the pages that matter
2. Search before deciding — look for existing knowledge before assuming
3. Write back what was learned — decisions, patterns, gotchas
4. Log what happened — leave a trail of intent, not just diffs

Beat 3 is the one agents skip. Be explicit about it.

What belongs in the wiki, and what belongs in git

The most common way a wiki like this fails is that someone tries to move everything into it. Don't. Your repo is already the right home for most of what an agent needs, and it has a property WitWiki cannot match.

Git holds what is true for this branch. A CLAUDE.md, an AGENTS.md, a file under .claude/rules/ — build commands, conventions, the shape of this codebase. Those version with the code, branch with the code, get reviewed in the pull request, and work offline. If a fact stops being true when you check out a different branch, it belongs in the repo.

The wiki holds what is true across repos, people and time. The decision and the reasoning behind it. The incident and what it taught you. The thing the frontend team worked out that the backend team keeps rediscovering. Anything whose audience is wider than one repository, or whose life is longer than one branch — and anything you want attributed, versioned, and reviewable per write.

There is a practical reason for the split as well as a conceptual one. Claude Code's own guidance is to keep a CLAUDE.md under roughly 200 lines, because instruction files load into context every session and adherence drops as they grow. Teams hit that ceiling. What overflows does not want to become a longer file loaded into every session — it wants to be searchable and fetched on demand, for the one task at hand. That is the job the wiki is for.

A rule of thumb: if you would put it in a pull request, put it in the repo. If you would say it in a code review, put it in the wiki.

CLAUDE.md snippet

Paste into your project's CLAUDE.md:

## WitWiki Knowledge Base

This project uses WitWiki as a persistent knowledge base via MCP.

### When to read
- **Task start** — call wiki_getBrief({task: "<what you are about to do>"})
  first. One call returns the pages worth reading, each with its version, its
  age and who wrote it last. wiki_getPage for anything it cut short; wiki_guide
  once per session for the conventions; wiki_getIndex when you want the map
- **Before deciding** — search with wiki_listPages (use the q param) for what
  the brief did not cover, before asking the user or making assumptions

### When to write
- **After completing work** — record decisions, patterns, and discoveries on
  the page they belong to; don't let knowledge vanish at session end
- **After significant operations** — call wiki_appendLog to record what you did
  and why (ingest sessions, architectural choices, answered questions)

### Changing a page
Read it with wiki_getPage and keep the version it returns. Change it with
wiki_patchPage (base_version = that version) — this is the default: replace a
sentence, insert after a line, replace or append to a section, create one.
wiki_updatePage replaces the WHOLE page; use it only to create a page or
rewrite one, and pass expected_version. A stale version is refused with
VERSION_CONFLICT and a diff of what changed: read again and re-apply. Reconcile
contradictions explicitly rather than silently clobbering them.

### Writing conventions
- Cross-reference related pages with [[wikilinks]] — also [[path|display text]]
- Keep each page focused on a single topic
- Use lowercase hyphen-separated paths; never a .md extension
- Update the index with wiki_updateIndex when adding major new pages
- Run wiki_lint after batches of edits to surface orphans and dead links

AGENTS.md snippet

For the OpenAI Agents SDK, AutoGen, LangGraph, Codex, or a custom framework — paste into AGENTS.md:

## WitWiki Knowledge Base

This agent has access to a WitWiki knowledge base via MCP tools. Read
accumulated knowledge before starting work; record new knowledge after.

### When to read
- At task start, call wiki_getBrief({task}) first; wiki_getPage for what it
  cut short; wiki_guide once for the conventions; wiki_getIndex for the map
- Search with wiki_listPages (q parameter) for what the brief did not cover

### When to write
- After completing a task, record what you learned on the page it belongs to
- After significant operations, append an entry with wiki_appendLog

### Changing a page
wiki_getPage first and keep its version. Change the page with wiki_patchPage
(base_version = that version). wiki_updatePage replaces the whole page — only to
create or rewrite one, with expected_version. A stale version is refused with
VERSION_CONFLICT and a diff: read again, re-apply.

### Conventions
- Link related pages with [[wikilinks]]
- One topic per page; lowercase hyphen-separated paths, no .md extension
- Run wiki_lint periodically to find dead links and orphan pages

The tools your agent gets

Twenty-two, across six groups. Full parameters and return shapes are in the MCP Tool Reference.

Tips for a wiki worth reading

• Link aggressively. Every [[wikilink]] builds the graph, and the graph is what makes search, backlinks, and lint useful. A page with no links in or out is nearly invisible.
• One topic per page. Narrow pages are easier to update and far less likely to go stale in half their content while staying accurate in the other half.
• Keep the index honest. Agents orient from it. A stale index means agents reliably fail to find pages that exist, then write duplicates.
• Lint after batches. wiki_lint surfaces orphans and dead links. Fix them while you still remember the context.
• Write decisions, not summaries. "We chose X over Y because Z" survives contact with the future. A restatement of what the code already says does not.

More depth on all of this in Wiki Conventions.