Agentic Wiki
omer→·Apr 05, 2026·7 min read·10
The AI Knowledge Base System
A persistent, Wikipedia-style wiki that lives in your codebase and travels with your AI agents
The Problem
If you've used Claude Code, Cursor, or GitHub Actions AI agents for more than a few sessions, you've hit this wall:
The agent doesn't remember anything.
Every new session, every new agent run — it starts completely cold. It rediscovers your file structure, re-reads your conventions, re-figures out your tech stack. It makes the same mistakes that burned you last week. It wastes the first several turns just getting oriented. And if you're running agents in CI (like Claude Code GitHub Actions), they have zero memory of what went wrong last time.
This isn't just annoying. It's expensive — in tokens, in time, and in failed agent runs.
The Solution: A Two-Tier Wiki System
The idea is simple: give the agent a Wikipedia it can read before doing anything.
Not a README. Not a CLAUDE.md. A living, hyperlinked knowledge base that agents actively maintain and update — so every future agent starts smarter than the last one.
Two tiers
~/.claude/wiki/ ← Global wiki (local machine only)
index.md ← Master catalog of all your projects
about-you.md ← Your work style, preferences, frustrations
patterns/ ← Cross-project patterns (testing, git, agents)
sessions/ ← Cross-project session logs
projects/ ← Per-project summary cards
{repo}/WIKI/ ← Project wiki (lives in the repo, in version control)
index.md ← Project entry point — architecture, key files, data flow
gotchas.md ← Real failures that happened, documented with cause + fix
agents.md ← Agent-specific context (env, test setup, required steps)
decisions/ ← Architecture decision records
sessions/ ← Session logs for this project
tags/ ← Tag index pages linking related content
The global wiki lives on your machine. It's for your local Claude Code sessions. It knows who you are, how you work, and gives any session a cross-project view.
The project wiki lives in the repo. It travels with the code. GitHub Actions agents can read it because they check out the repo. It's version controlled, so it grows with the project.
What Problems This Solves
1. Agent dementia
Agents no longer start from zero. Before doing any work, they read WIKI/index.md (60 seconds) and WIKI/gotchas.md. They know the architecture, the conventions, the things that have gone wrong.
2. Repeated failures
The gotchas.md file is a permanent record of every surprising thing that happened — missing dependencies, wrong API inputs, workflow bugs, rate limits. Each entry has a date, a symptom, a cause, and a fix. Agents read this and don't repeat history.
3. Token waste on context discovery
Instead of an agent spending its first 10 turns reading files to understand the codebase, you pre-embed the relevant source files directly into the agent's prompt at dispatch time. The agent arrives with full context already loaded.
4. No institutional memory
Session logs capture what was built, what decisions were made, and why. Next week's agent (or next month's you) can read the session log and understand the full story — not just what the code looks like now, but how it got there.
5. Cross-project pattern drift
The global wiki stores patterns that apply everywhere: how to write tests, how to use git, what agent workflow bugs to avoid. These patterns are automatically available to any project session.
How Agents Use It
The wiki is wired into the system at multiple levels:
CLAUDE.mdreferences the wiki at the top — the first thing any agent readsWIKI/gotchas.mdis injected directly into every GitHub Actions agent prompt at dispatch time- GitHub Actions agents auto-commit a session log entry after every run (success or failure)
- At the end of every session, Claude updates the wiki — appending to the session log, adding new gotchas, updating status
The result: the wiki gets smarter after every agent run, automatically.
The Structure in Practice
Here's what a project wiki looks like after a few sessions:
WIKI/
index.md → What the app does, data flow diagram, key files table,
design tokens, KV keys, environment variables, conventions
gotchas.md → "2026-04-05 — @testing-library/react not installed:
agent claimed success but PR had no code because it spent
all turns fighting import errors. Fix: always install the
package before kicking off an agent run."
agents.md → Required GitHub Actions permissions, test setup, mocks
needed, exact steps every agent must complete before
pushing (tests, type check, commit, push)
decisions/
agent-workflow.md → Full debugging history of the 4 bugs we hit setting
up claude-code-action, so we never fix them twice
sessions/
2026-04-05.md → Timeline of everything built that day, decisions made,
gotchas discovered
Setup: One Prompt
Getting this set up for a new project takes one command in Claude Code:
/setup-wiki
That's it. Claude reads your codebase, understands the stack, and generates all the wiki files with project-specific content — not generic templates. It also updates the global catalog so cross-project context stays current.
For existing projects, it takes about 2 minutes of Claude reading and writing. For new projects, you run it right after initial setup.
The Compounding Effect
This is the key insight: the wiki gets better automatically over time.
- Every agent run adds a session log entry
- Every failure adds a gotchas entry
- Every architecture decision gets documented
- Every session leaves the next agent smarter
You're not writing documentation. You're building a knowledge base that AI agents actively maintain on your behalf — and that compounds across every project you work on.
Who This Is For
- Developers using Claude Code for active development
- Anyone running AI agents in GitHub Actions (claude-code-action)
- Teams who want AI agents to have real context, not just a README
- Anyone who's watched an agent burn tokens rediscovering things it should already know
Want the full setup guide? See wiki-knowledge-base-detailed.md