We need to talk about context. The standard advice in the AI space has become “just write better prompts,” and frankly, that is killing your productivity. If you start every terminal session by explaining your project’s architecture or business logic, you aren’t using an agent. You are babysitting a junior dev with short-term memory loss. The fix is a Claude Code knowledge base that persists across sessions and projects.
I learned this the hard way last month. I was juggling three different WooCommerce customizations, and I spent more time feeding Claude the same API docs than actually writing code. So I built a centralized “brain” that lives in my ~/.claude directory. It saves snippets, but the real point is the Progressive Disclosure mechanism built into Claude Code, which loads exactly what’s needed, when it’s needed.
Why you need a Claude Code knowledge base
Large language models are only as good as the context you give them. But dumping 50 meeting transcripts and a 200-page style guide into every prompt gives you high latency and “context rot,” where the model loses the signal in the noise. A structured Claude Code knowledge base lets you store information so Claude can “search” it without bloating the active context window. It uses the SKILL.md file as a router for your personal knowledge.
If you haven’t explored the context layer yet, read my guide on building a persistent AI context layer first. It is the foundation for what we are doing here.
Step 1: Setting up the global context
First, you need a global entry point. Claude Code looks at ~/.claude/CLAUDE.md for rules that apply across every project on your machine. This is the perfect place to define where your knowledge base lives. Instead of putting all the data here, we use it to point the agent to our specialized skills.
# Global Rules for Claude Code
- Always check the 'pkb' skill if the user asks for business logic or project history.
- My personal knowledge base (PKB) is located at ~/Documents/Brain.
- When referencing the PKB, prioritize files updated in the last 30 days.Step 2: Engineering the retrieval skill
Next, create a custom skill inside ~/.claude/skills/pkb/SKILL.md. The skill’s frontmatter tells Claude exactly when to reach for this knowledge base. You can also use the references/ directory pattern to keep the data files separate from the instructions.
description: Use this skill when the user asks about personal meetings, project decisions, or "how we do things." It retrieves context from the local personal knowledge base.
# Personal Knowledge Retrieval (PKB)
## Instructions
1. Navigate to ~/Documents/Brain.
2. Search for markdown files matching the user's query keywords.
3. If a meeting transcript is found, summarize the "Action Items" before answering.
4. If there is conflicting information, flag the most recent file as the source of truth.
## Reference Material
- !cat ~/Documents/Brain/index.mdFor why this beats pasting text into every prompt, read my article on why Claude Code skills beat ad-hoc prompting. It covers how the SKILL.md schema works.
Automating the sync: don’t do it manually
A knowledge base is only useful if it is current. I run a simple cron job every evening. The script pulls my latest meeting notes from Notion, exported via the API, and drops them in my ~/Documents/Brain/meetings folder. When I fire up Claude the next morning, it already knows what I discussed with a client the day before.
#!/bin/bash
# Simple PKB Sync Script
# bbioon_sync_pkb.sh
SYNC_DIR="~/Documents/Brain/meetings"
mkdir -p "$SYNC_DIR"
# Example: Pulling from a hypothetical local notes app
cp ~/Library/Application\ Support/Notes/*.md "$SYNC_DIR/"
# Indexing for Claude
echo "# PKB Index - Updated $(date)" > ~/Documents/Brain/index.md
ls -R "$SYNC_DIR" >> ~/Documents/Brain/index.mdMaintenance: avoiding “context rot”
The biggest “gotcha” with a Claude Code knowledge base is information drift. If your notes say a project runs PHP 7.4 but you have upgraded to 8.2, Claude will hallucinate legacy code. To prevent that, once a week I run a maintenance session and prompt: /pkb check for outdated versions or conflicting tech stacks. Since Claude can read my actual project files from the terminal, it cross-references my composer.json against my notes and flags the discrepancies.
If this Claude Code knowledge base stuff is eating up your dev hours, I can handle it for you. I have been wrestling with WordPress and AI automation since the early days, and I build systems that stay out of your way.
The takeaway
Stop treating Claude like a search engine and start treating it like a teammate with access to your internal wiki. Combine global CLAUDE.md rules with specific SKILL.md retrieval logic, and the terminal becomes a proactive assistant. For the technical details, keep an eye on the official Claude Code skills documentation, since the API is still changing fast.
