Our project wiki: memory that AI agents can read and write

Markdown files with wikilinks turning into a graph of linked notes that a person and an agent both work in.

Agents forget everything between sessions

If you use an AI coding agent every day, you know the pattern. You open a new session, and the agent knows nothing about your project. It does not know why you picked this database or that a module was removed last week.

So it either reads half the codebase to rebuild the picture, which is slow and expensive, or it guesses, which is worse.

Code tells the agent what exists, not how things should work or why. We wanted one place that answers "how should this work?" and that an agent can read in seconds.

That place is our project wiki.

What the wiki actually is

No special service. Our wiki is two things:

  1. An Obsidian vault. A folder of plain Markdown files in its own git repository. In our code repo it sits at docs/wiki/. Pages link to each other with [[wikilinks]], so teammates browse it in Obsidian too, and a fix a person makes reaches every agent in its next session.
  2. Agent skills that teach the AI to read and write it. A skill is a short instruction file that Claude Code loads when it needs it. We use the open obsidian-skills collection: obsidian-markdown (wikilinks, callouts, frontmatter), obsidian-bases, json-canvas, obsidian-cli and defuddle (turns a web page into clean Markdown). The rules for what goes into the wiki and how pages change live in a plain rules file, which we cover below.

Because the wiki is just files, the agent reads it with the same tools it uses for code.

The pattern: Karpathy's "LLM Wiki"

We did not invent the shape. Andrej Karpathy described it in his LLM Wiki note. It has three layers:

  • Raw sources. What the human provides: a spec, meeting notes, an article. The LLM never edits them.
  • The wiki. Pages the LLM writes and keeps current.
  • The schema. One file of rules (for us, CLAUDE.md) that tells the agent how the wiki is organised and how to maintain it.

And three operations: ingest (add a source, and the LLM updates every page it affects), query (ask a question, get an answer with links to pages) and lint (a health check for broken links, contradictions and stale claims).

Ours looks roughly like this:

docs/wiki/
├── CLAUDE.md      # the rules: how agents read and curate
├── index.md       # the map: one line per page
├── hot.md         # what changed in the last 7 days
├── log.md         # short log of every curation pass
├── concepts/  features/  decisions/  conventions/
└── sources/       # raw human input, never edited

Tracker plus wiki: the whole picture

An agent working on a task has two questions: what should I do? and how does this system work, and which rules apply? We answer them from two sources.

  • The tracker answers "what". The task holds the request in the human's own words. Each earlier stage of our workflow (interview, requirements, decomposition) leaves an artifact on it. We explain those stages in Stop writing prompts: why AI coding agents need a workflow.
  • The wiki answers "how". Concepts, features, decisions and conventions describe the system and its rules.

Together they give the agent a complete source of context, and the agent chooses what to read. We don't paste a fixed bundle of files into its prompt. The agent opens index.md (the map) and hot.md (last week's changes), picks the pages this task needs and follows links from there. A few kilobytes of reading replace a long crawl through the code.

The developer agent treats the wiki as the spec, and for the developer it is read-only. The wiki curator is the last step. After the code is reviewed, a curator agent reads the actual diff and updates every page the change made false. Then it opens a pull request against the wiki repo, and a human merges it.

When the agent catches your mistake

Reliable context does more than save time. It lets the agent notice when the human is wrong.

Decision pages make this work. A decision page, or ADR (architecture decision record), is a short note: what we decided, why, and what we rejected. For example: "we store all times in UTC and convert them only in the UI". Months later it still answers "why is it built like this?"

Now imagine a request that quietly contradicts a decision the team accepted a month ago. Maybe the person forgot it, or really changed their mind. Without the wiki, the agent just does what it is told. With the wiki, it finds the decision page while reading for the task and sees the conflict. So it stops, names the decision and asks which one should win: should the decision change, or was the request a slip?

Either answer helps. A slip caught early is a change you don't have to undo. A real change of mind updates the decision page, so the next agent reads the new rule, not the old one.

The rule that keeps it useful: rewrite, don't append

We learned this one the hard way. At first, each task added its own section to a page: "Added in task X", "Changed in task Y". Nothing was ever lost, so it felt safe. A few months later one page had grown to about 540 KB. It still described long-removed components as live, and the agent believed every word.

Now the rule is simple. A page describes the system as it is today. When a change makes a sentence false, the curator rewrites that sentence. History lives in git and in log.md, not in the page. A few more rules keep things small:

  • Every page stays under 30 KB. A bigger page gets condensed or split.
  • When code is removed, its page becomes a short "deprecated" stub that points to its replacement. Old links still work.
  • A plan that is not built yet is a decision page marked "accepted, not yet implemented", never a current-state page.
  • A lint script checks sizes, frontmatter and links before the wiki pull request opens.

The result: a couple of hundred short pages, one subject each, all true today.

Good for humans too

A new teammate can open the same vault, start at the index and click through the graph. A team lead can read a decision page to learn why something was built a certain way.

Start your own

There is no special tooling behind any of this. It is an Obsidian vault in a git repository, the obsidian-skills for Claude Code, and one short file of rules. We walk through the setup step by step in How to set up a project wiki for AI agents in 30 minutes.

All articles