Claude Code Knowledge Base System

A personal knowledge management system for Claude Code that automatically captures, organizes, and retrieves development knowledge across all your repositories.

What It Does

This system helps Claude Code remember what you've learned:

• Automatic Documentation: After solving complex problems, Claude proactively offers to document the solution
• Intelligent Search: Before starting work, Claude searches existing knowledge for similar patterns
• Self-Organizing: Knowledge base structure adapts to each repository's domain and tech stack
• Machine-Optimized: Index format designed for efficient Claude Code searching, not human browsing

Architecture

The system consists of three components:

1. documentation-scout (agent) - Searches for existing knowledge in the knowledge base
2. knowledge-manager (agent) - Evaluates what to document and maintains the index
3. /kb (slash command) - Sets up the knowledge base in new repositories

Each repository gets an untracked knowledge/ directory that Claude Code manages automatically.

Installation

1. Install Agents

Copy the agent files to your Claude Code agents directory:

# Copy agents
cp agents/documentation-scout.md ~/.claude/agents/
cp agents/knowledge-manager.md ~/.claude/agents/

2. Install Slash Command

Copy the slash command to your Claude Code commands directory:

# Copy command
cp commands/kb.md ~/.claude/commands/

3. Update Global Configuration

Add to your ~/.claude/CLAUDE.md (create if it doesn't exist):

## Knowledge Management System

A personal knowledge base system for preserving learnings, patterns, and solutions across all repositories.

### Custom Agents

**documentation-scout** - Finds existing knowledge
- Searches knowledge/index.md for relevant docs
- Greps through documentation when needed
- Returns excerpts and related documents
- Has Bash access for running queries or scripts

**knowledge-manager** - Creates and maintains documentation
- Evaluates what's worth documenting
- Determines appropriate location (knowledge/ vs CLAUDE.md vs CLAUDE.local.md)
- Creates documentation with proper structure
- Updates the index file (automatically runs build script)
- Has Bash access to run index rebuild

### Quick Setup

Use the `/kb` slash command to automatically set up the knowledge base in any repository.

### How It Works Automatically

Claude Code will proactively:

1. **Search for existing knowledge** - Before starting complex tasks, check if we've solved similar problems
2. **Document valuable solutions** - After completing non-trivial work, evaluate if it's worth documenting
3. **Maintain the index** - Automatically rebuild when creating new documentation

You don't need to manually invoke agents or run scripts - it happens automatically.

Usage

Setting Up a Repository

Navigate to any repository and type:

/kb

Claude Code will:

• Create knowledge/ directory
• Add to .gitignore
• Copy and adapt build_index.rb script
• Generate initial index.md
• Explain what happens automatically

Working with the System

Just work normally! Claude Code will automatically:

When you need information:

• Claude searches knowledge/index.md for relevant docs
• Matches keywords, class names, technologies
• Returns relevant excerpts and examples

When you solve something complex:

• Claude evaluates if it's worth documenting
• Asks permission to document
• Creates appropriately named file
• Updates the index automatically

Example workflow:

You: "How do we handle user authentication?"
Claude: [searches documentation-scout]
Claude: "Found existing documentation in knowledge/api-auth-patterns.md..."

[Later, after solving a tricky bug]
Claude: "This non-obvious race condition fix seems worth documenting.
        Should I create knowledge/investigations/auth-race-condition.md?"
You: "yes"
Claude: [uses knowledge-manager to create doc and rebuild index]

Directory Structure

repository/
├── knowledge/                    # Untracked, per-repository
│   ├── index.md                 # Machine-optimized catalog
│   ├── build_index.rb           # Index generator script
│   └── {your docs}.md           # Documentation files
├── .gitignore                   # knowledge/ added here
└── CLAUDE.md                    # Project-wide config (optional)

The structure adapts to your repository:

• Ruby repos might have queries/, investigations/
• Python repos might have notebooks/, api/
• Infrastructure repos might have terraform/, k8s/

Let the content guide the organization.

Customization

Adapting to Your Tech Stack

Edit build_index.rb in each repository:

Technologies to extract (line 38):

tech_keywords = %w[Rails Django Flask FastAPI React Vue Angular Node
                   PostgreSQL MySQL MongoDB Redis Kafka gRPC REST
                   GraphQL AWS Azure GCP Docker Kubernetes Terraform]

Categories (line 45):

def categorize_file(filename, _content)
  return 'Root Cause Analysis' if filename.include?('root_cause')
  return 'Architecture' if filename.include?('architecture')
  # Add your domain-specific categories
  'General Documentation'
end

File Naming Convention

Use the pattern: {domain}-{topic}-{type}.{ext}

Good names:

• database-user-lookup-patterns.md
• api-authentication-guide.md
• queries-fraud-detection.sql
• scripts-data-migration.py
• investigations-performance-issue.md

Bad names:

• notes.md (too vague)
• temp.md (not descriptive)
• stuff.md (meaningless)

How It Works

The Index

The knowledge/index.md uses structured metadata optimized for Claude Code:

### Topic Name
**Path**: `filename.md`
**Keywords**: UserEntity, database, lookup, authentication
**Description**: How to find users by various identifiers
**Contains**:
- Code examples
- SQL queries
**File Type**: documentation
**Last Updated**: 2025-10-09

Claude Code matches:

• Specific keywords (class names, table names, technologies)
• File types (prioritize queries vs docs vs scripts)
• Recency (for time-sensitive information)

Decision Framework

The knowledge-manager agent documents when:

• Complex problem took multiple steps
• Non-obvious solution or pattern
• Architectural decision with trade-offs
• Debugging session with valuable findings
• Reusable query or code pattern

It skips when:

• Simple, one-off task
• Already well-documented elsewhere
• Trivial change
• Temporary workaround

Contributing

This is a personal knowledge management system, but contributions are welcome!

To contribute:

1. Test the system in your own repositories
2. Share improvements to the agents or scripts
3. Report issues or suggest enhancements
4. Share examples of how you've adapted it

Please:

• Keep it language-agnostic (works with any tech stack)
• Maintain simplicity (avoid over-engineering)
• Focus on automatic behavior (minimize manual steps)
• Preserve privacy (no company-specific logic)

Tips and Best Practices

1. Let it grow organically: Don't create subdirectories upfront - let content dictate structure
2. Trust the agents: Claude Code knows when documentation is valuable
3. Use descriptive names: Future you will thank you for clear file names
4. Cross-reference: Link related documents in front matter
5. Update regularly: The knowledge-manager keeps index current automatically

Troubleshooting

Index not updating?

• Manually run: cd knowledge/ && ruby build_index.rb
• Check that build_index.rb is executable: chmod +x knowledge/build_index.rb

Agent not activating?

• Verify agents are in ~/.claude/agents/
• Check tool permissions (both need Read, Write, Edit, Glob, Bash)
• Restart Claude Code session

Ruby version issues?

• The script uses basic Ruby that works everywhere
• If needed, adapt to Python/Node.js in your repo

Contributors

Thanks to these wonderful people (emoji key):

Tabitha Katz 💻 📖 🤔 🚇

This project follows the all-contributors specification. Contributions of any kind welcome!

License

MIT License - Use freely, adapt as needed

Credits

Created to solve the problem of: "I know we solved this before, but I can't remember where..."

Built with Claude Code, for Claude Code users.

---

Questions or feedback? Open an issue or discussion on GitHub.