# 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**:

```bash
# 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**:

```text
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**:

```nickel
# 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**:

```text
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**:

```text
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. `kogral 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: `kogral 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**:

```text
Developer → writes code → commits
```

**With KB**:

```text
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](core-concepts.md)
- **Learn philosophy**: [Design Philosophy](design-philosophy.md)
- **Quick start**: [Quick Start Guide](../guides/quickstart.md)
- **See examples**: [Use Cases](../guides/use-cases.md)

---

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

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