Give Claude Code a Self-Maintaining Wiki That Survives Session Resets

April 27, 2026

Every Claude Code session starts the same way: blank slate, no memory of the last three hours you spent explaining your architecture decisions. You re-paste the same context, re-answer the same clarifying questions, and lose the first ten minutes of every session to onboarding an agent that was already onboarded yesterday.

Andrej Karpathy floated the fix: your AI agent should maintain its own wiki. Two open-source implementations — Wuphf (around 120 upvotes and 54 comments on Hacker News) and BrainDB — prove the idea is sound. Neither plugs directly into Claude Code. This post builds that wiring: two CLAUDE.md sections and a git hook that makes the whole thing auditable.

What you need

A project already using Claude Code, a CLAUDE.md at the project root, and git initialized. No external dependencies, no database, no API calls. The entire pattern is Markdown and shell.

Step 1: Design the wiki structure

Create a Markdown wiki file at your project root — for example, agent-wiki.md or docs/agent-wiki.md, wherever fits your layout. The file has four sections Claude Code will both read and write:

# Agent Wiki

## Project Context
<!-- What this codebase is, the stack, the constraints that never change. -->
<Describe your stack, the top-level architecture, and the invariants Claude should never violate.>

## Decisions Made
<!-- Architectural and design decisions, with brief rationale. Append, don't overwrite. -->
- YYYY-MM-DD: <decision> — <one sentence of rationale>

## Open Questions
<!-- Unresolved issues and ambiguities. Cross off when resolved. -->
- [ ] <open question or blocker>
- [x] <resolved question> → Resolved: <brief explanation>

## Learned Patterns
<!-- Patterns that bit us, patterns that worked. Claude: read this before suggesting code. -->
- <gotcha, convention, or shortcut worth remembering>

Four sections, plain Markdown, append-only except for closing out open questions. The key discipline: never rewrite history. Append to Decisions Made. Cross off items in Open Questions. This makes the diff readable.

When you first fill in Project Context, be specific enough that a new Claude Code session could start working without asking a single clarifying question. Stack, auth model, key conventions, things that are off-limits — all of it belongs here. The rest of the sections start empty and fill up as work happens.

A cross-section diagram of layered sediment where each stratum is a different color and density, representing accumulated knowledge building up over time without disturbing the layers beneath

Step 2: Write the CLAUDE.md initialization hook

In your CLAUDE.md, add a section at the top — before any task instructions — that forces a wiki read on every session start:

## Session Initialization

At the start of every session, before doing anything else:

1. Read the agent wiki file (agent-wiki.md) in full.
2. Write a 3–5 sentence summary of your current understanding of the project:
   - what it is
   - the active constraints and conventions
   - any open questions that are relevant to today's task
3. Ask the user to correct or confirm before proceeding.

This is not optional. If the wiki file does not exist, say so and ask the user
whether to create it before starting work.

That’s it. Claude Code will read the file, surface its understanding, and let you catch any staleness before it writes a single line of code. The confirm-before-proceeding step is what makes the cold-start vs. wiki-start contrast so stark: a wiki-initialized session asks zero clarifying questions about things already documented.

Step 3: Write the session-end update hook

Below the initialization section, add the update rule:

## Session End (Wiki Update)

When a task is complete, or when the user says they're done for the session,
update the agent wiki file as follows:

- Append to **Decisions Made** any architectural or design choices made this session,
  with today's date and one sentence of rationale.
- Move any resolved items in **Open Questions** from `[ ]` to `[x]`,
  appending ` → Resolved: <brief explanation>`.
- Add any new unresolved issues to **Open Questions**.
- Append to **Learned Patterns** anything that would save time in the next session —
  bugs, gotchas, patterns that worked.

Do NOT rewrite or delete existing content. Append only.
Do NOT update the wiki mid-task — only at session end, or when explicitly asked.

The “append only” constraint is load-bearing. Without it, Claude Code will helpfully “clean up” old entries and you’ll lose the audit trail that makes the wiki trustable.

Step 4: Add the git hook for auditability

A wiki that can be silently overwritten is a wiki you can’t trust. Add a post-commit hook that separates wiki commits from code commits and enforces a conventional commit format. Adjust the WIKI path to match wherever you placed your wiki file:

#!/usr/bin/env bash
# .git/hooks/post-commit
# Automatically stage and commit wiki changes if they weren't included
# in the current commit but the file has been modified.

WIKI="agent-wiki.md"  # adjust to your wiki file path

if git diff --name-only HEAD | grep -q "$WIKI"; then
  # Wiki was already part of this commit — nothing to do.
  exit 0
fi

if ! git diff --quiet -- "$WIKI"; then
  git add "$WIKI"
  TODAY=$(date +%Y-%m-%d)
  git commit -m "docs(wiki): agent update $TODAY [auto]"
fi

Make it executable:

chmod +x .git/hooks/post-commit

Now wiki changes are always committed, always separately from code, and always with a prefix that makes them greppable:

git log --oneline --grep="docs(wiki)"
# docs(wiki): agent update <date> [auto]
# docs(wiki): agent update <date> [auto]
# docs(wiki): agent update <date> [auto]

The full project timeline becomes readable: code commits interleaved with agent learning commits. If the wiki starts drifting — entries that contradict the code, stale open questions — you can diff any two points and see exactly when the divergence started.

Where this breaks

Wiki rot. If Claude Code makes an incorrect entry and you don’t catch it in the confirm step, the error propagates to every future session. The initialization hook’s confirm-before-proceeding step is your only circuit breaker — don’t skip it, and don’t skip reading the summary it produces.

Long-running projects. After a few months, Learned Patterns and Decisions Made get long enough that the initialization read starts consuming meaningful context window. The fix: periodically review the wiki yourself and archive old entries to a separate file, keeping the active wiki concise. This is manual work — there’s no automatic trim that won’t risk losing something important. Both Wuphf and BrainDB tackle the broader persistent-memory problem from different angles; if you outgrow flat Markdown, either project is worth exploring as a next step.

Next steps

The two-section CLAUDE.md pattern above is the minimum viable version. Wuphf and BrainDB each take more structured approaches to the broader persistent-memory problem — worth exploring once a single Markdown file isn’t enough. But most projects don’t need that yet. They need their agent to stop asking what framework they’re using on day thirty. Two sections in CLAUDE.md and a one-file Markdown wiki does that reliably, with zero infrastructure and a git log you can audit.

← Back to blog