## Keyboard shortcuts

Press `←` or `→` to navigate between chapters

Press `S` or `/` to search in the book

Press `?` to show this help

Press `Esc` to hide this help

# Why KB?

Understanding the motivation behind the Knowledge Base system.

## The Problem: Knowledge Fragmentation

Modern software development generates enormous amounts of knowledge:

📝 Notes: Implementation details, learnings, discoveries 🤔 Decisions: Why we chose X over Y 📚 Guidelines: How we write code, architecture patterns 🔄 Patterns: Reusable solutions we've discovered 💭 Discussions: Slack threads, meeting notes, PR comments 🐛 Bug Fixes: How we solved issues

But where does this knowledge live?

- Meeting notes in Google Docs
- Decisions buried in Slack threads
- Guidelines in a wiki nobody updates
- Patterns in someone's head
- PR discussions lost in GitHub history
- Bug solutions in closed Jira tickets

The result?

❌ Rediscovering solutions to problems we've already solved ❌ Inconsistent practices because guidelines aren't accessible ❌ Slow onboarding as new developers lack context ❌ Lost context when team members leave ❌ Repeated mistakes because past lessons aren't preserved

## The Solution: Unified, Queryable Knowledge Graph

Knowledge Base provides a single source of truth for project knowledge:

✅ Capture once: Notes, decisions, guidelines, patterns ✅ Connect concepts: Typed relationships between ideas ✅ Query naturally: Text and semantic search ✅ AI-assisted: Claude Code integration via MCP ✅ Git-tracked: Version control for knowledge ✅ Shared wisdom: Organization-wide guidelines + project-specific

## What Makes KB Different?

### 1. Git-Native

Other tools: Notion, Confluence, wikis in web apps

KB: Markdown files in `.kogral/` directory

Benefits:

    # Review knowledge changes in PRs
    git diff .kogral/decisions/

    # Branch knowledge with code
    git checkout feature-branch
    # .kogral/ follows the branch

    # Merge knowledge from feature work
    git merge feature-branch
    # Knowledge merges like code

Result: Knowledge versioned alongside code it describes.

### 2. AI-Native

Other tools: Manual search, browse folders

KB: AI queries via Claude Code

Example:

    You: "Find anything about error handling"

    Claude: [Searches semantically, not just keywords]
    Found 5 concepts:
    - Pattern: Error Handling with thiserror
    - Guideline: Result Type Best Practices
    - Decision: Use anyhow for Application Errors
    - Note: Custom Error Types
    - Journal: Fixed error propagation bug

    [All related, even without exact keyword match]

Result: Find concepts, not just documents with keywords.

### 3. Config-Driven

Other tools: Hardcoded behavior, limited customization

KB: Nickel schemas define everything

Example:

    # Development: local embeddings, no costs
    { embeddings = { provider = 'fastembed } }

    # Production: cloud embeddings, best quality
    { embeddings = { provider = 'openai, model = "text-embedding-3-large" } }

Result: Adapt behavior without code changes.

### 4. Multi-Graph

Other tools: One knowledge base per project

KB: Shared organizational knowledge + project-specific

Structure:

    Organization Shared KB
      ├── Rust Guidelines (applies to all projects)
      ├── Security Patterns (applies to all projects)
      └── Testing Standards (applies to all projects)

    Project A KB
      ├── Inherits shared guidelines
      ├── Project-specific decisions
      └── Can override shared guidelines

    Project B KB
      ├── Inherits same shared guidelines
      ├── Different project decisions
      └── Different overrides

Result: Consistency across organization, flexibility per project.

### 5. Structured Relationships

Other tools: Backlinks, tags, folders

KB: Typed relationships with meaning

Example:

    Pattern: Repository Pattern
        ↑ [implements]
    Note: User Service Implementation
        ↑ [relates_to]
    Decision: Use PostgreSQL
        ↑ [depends_on]
    Guideline: Database Access Patterns

Result: Understand how knowledge connects, not just that it connects.

## Real-World Impact

### Before KB

New developer joins:

1. Read outdated wiki (2 hours)
2. Ask teammates for context (1 hour per question × 10 questions)
3. Discover guidelines by reading code (days)
4. Miss important decisions (leads to mistakes)

Time to productivity: 2-4 weeks

### With KB

New developer joins:

1. `kb search "architectural decisions"` → finds all ADRs
2. Ask Claude: "What are our coding guidelines?" → gets current guidelines with inheritance
3. Browse related notes via graph traversal
4. Full context available, no tribal knowledge

Time to productivity: 3-5 days

### Before KB

Team makes decision:

1. Discussion in Slack (lost after a week)
2. Someone documents in wiki (maybe)
3. 6 months later: "Why did we choose X?" → nobody remembers
4. Re-debate the same decision

### With KB

Team makes decision:

1. Discussion captured as ADR during meeting
2. Context, decision, consequences documented
3. Linked to related patterns and guidelines
4. 6 months later: `kb show decision-use-x` → full context instantly

### Before KB

Solving a bug:

1. Encounter race condition in cache
2. Debug for 2 hours
3. Fix it
4. Solution lost in PR comments

Two months later: Different developer, same bug, 2 more hours

### With KB

Solving a bug:

1. Encounter race condition
2. Ask Claude: "Have we seen cache race conditions before?"
3. Claude finds journal entry from 2 months ago with solution
4. Apply fix in 10 minutes

Two months later: Same query, same instant solution

## Who Benefits?

### Individual Developers

✅ Personal knowledge base: Capture learnings, build expertise ✅ Quick recall: "How did I solve this before?" ✅ Context switching: Return to old projects with full context ✅ Career growth: Document what you learn, portfolio of knowledge

### Teams

✅ Shared context: Everyone has access to team knowledge ✅ Onboarding: New members ramp up faster ✅ Consistency: Follow shared guidelines and patterns ✅ Collaboration: Build on each other's knowledge

### Organizations

✅ Institutional memory: Knowledge persists beyond individual tenure ✅ Best practices: Standardize across teams ✅ Compliance: Document security and architecture decisions ✅ Efficiency: Stop solving the same problems repeatedly

### AI Agents

✅ Context injection: Agents query guidelines before generating code ✅ Decision awareness: Agents check past decisions ✅ Pattern following: Agents use documented patterns ✅ Execution tracking: Agent actions documented automatically

## When NOT to Use KB

KB is not ideal for:

❌ Personal journaling: Use Obsidian or Logseq ❌ Team wikis: Use Notion or Confluence ❌ Customer docs: Use mdBook or Docusaurus ❌ Project management: Use Jira or Linear ❌ Code comments: Use inline documentation

KB is perfect for:

✅ Developer knowledge graphs ✅ Architectural decision records ✅ Pattern libraries ✅ Coding guidelines ✅ Technical context ✅ AI-assisted development

## The Vision

Today's development:

    Developer → writes code → commits

With KB:

    Developer → writes code → documents decisions → links to patterns → commits code + knowledge
                        ↓
                AI Agent queries knowledge → generates better code
                        ↓
                Team discovers patterns → reuses solutions → faster development

Knowledge becomes an active participant in development, not an afterthought.

## Design Philosophy

Three core principles drive KB:

### 1. Knowledge should be captured during work, not after

❌ "I'll document this later" → never happens ✅ "Claude, document this decision" → done in 30 seconds

### 2. Knowledge should be connected, not isolated

❌ Standalone documents in folders ✅ Graph of interconnected concepts

### 3. Knowledge should be queryable, not browsable

❌ "Let me look through 50 docs to find..." ✅ "Find anything related to error handling" → instant semantic results

## Get Started

Ready to stop losing knowledge?

- Understand concepts: Core Concepts
- Learn philosophy: Design Philosophy
- Quick start: Quick Start Guide
- See examples: Use Cases

> "The best time to document was during implementation. The second best time is now."

But with KB + AI, "now" is instant.