Workspace wiki: project memory for humans and AI agents

It didn't start with a problem, it started with having fun. I began building reference projects: for every area I work in, one project that shows how I think it should be done, with all the decisions you otherwise make from scratch every time. Half out of curiosity, half with an ulterior motive, because when working with agents I wanted to draw on these best practices instead of explaining everything from the beginning each time.

That worked. But with every new project certain patterns kept repeating, and at some point every feature and every piece of tooling raised the same question: which project is actually the real reference for this? The auth setup from one, the deploy from another, the test structure from a third. The reference existed, it just wasn't findable.

Then there was scale. My workspace has grown to over 40 projects: apps, web services, tools, experiments. Since I started working AI-natively, new ones appear faster, and the work spreads across many Claude Code sessions. Every session starts from zero. The agent knows neither the project nor last week's decisions, so it searches the code, builds up a picture, and discards it as soon as the context window ends. Next time, from scratch.

The usual answers don't scale. A CLAUDE.md per project is good for rules but too small for architecture: it grows long, goes stale, and gets loaded in full in every session. README files describe how things looked back then. And the actual knowledge, why something is built the way it is, what wire format a message has, which env variable the deploy needs, lived in chat histories nobody can find again.

The tipping point was Andrej Karpathy's “LLM wiki” idea: instead of searching over raw data anew for every question, the model maintains a persistent wiki of Markdown that grows with every source and every question, with three operations, ingest, query, and lint. The human curates and asks, the model handles summarizing, linking, and filing. That was exactly what my reference projects were missing: they turned into a wiki system where not only the best practices but every single project is documented, in a format agents can read and keep writing. For me, ingest is the create-wiki skill, query is wiki ask, and lint became the drift audit against the code.

Then there's the drift problem: documentation maintained by hand eventually lies. A path gets renamed, a function disappears, the article stays put. Annoying for a human reader, fatal for an agent, because it takes the text at face value and builds on top of it.

So four requirements were set:

• The knowledge lives with the code: in the repo, versioned, as Markdown, without a database and without a build step
• Agents can query it in seconds, semantically too, without a running service and without any content going to a cloud
• False statements get caught mechanically before they are committed
• Writing is not optional: agents read the wiki before searching the code, and maintain it before they finish

The result is a system of three parts that read the same files: one convention per project, a CLI, and a web frontend. None of it is exotic, the impact comes from consistency.

A wiki nobody reads is dead weight, and a wiki nobody maintains becomes a trap. So usage is built into the rules every agent gets in every session, on three levels.

Today the system covers my entire workspace:

• 43 projects and over 800 articles in the same format, from an iOS game to a web service, all readable through one CLI
• 76 technology files with best practices, gotchas, and a pattern library, extracted across projects so every solution is filed exactly once
• Semantic search over around 5,000 chunks, locally on the CPU, German and English mixed, without a single byte leaving the machine
• Drift audit over more than 11,000 code references in around twelve seconds; most projects sit at zero errors, and where drift occurs, the audit names the article, path, and reason
• A Q&A bot with citations, no API key and no server, over the existing Claude Code login
• A web frontend that renders the Markdown files without a build step
• Mandatory wiki use on three levels: global rules, project rules, and automated skills, hooks, and release flow

The tangible effect shows in the sessions. An agent that starts with wiki vsearch has the picture after one minute that used to take ten minutes of reading code, and it's the same picture I have. Lost decisions have become rarer because their place is fixed. And because agents must write before they finish, the wiki grows with the code instead of trailing behind it.

The question about the real reference has resolved itself. Solutions that work well get filed in the wiki and reused in the next project, no matter which repo they originally came from. With every project, efficiency grew noticeably, because less gets built from scratch and more gets pulled from the existing stock.

The takeaway: documentation for AI agents needs different properties than documentation for humans. It has to be machine-findable, it has to be mechanically verifiable, and it has to be mandatory. A convention of Markdown and frontmatter, a CLI, and an audit are enough for that. What matters is not the tool but that it sits at every point of the workflow: at project start, in every session, in every release.

The system is tailored to my workspace and not released as a package. But the ideas behind it, convention instead of a database, local vector search, a drift audit against the code, and mandatory wiki use in the workflow, can be rebuilt in any team setup.