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:

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

Time to productivity: 2-4 weeks

With KB

New developer joins:

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

Time to productivity: 3-5 days

Before KB

Team makes decision:

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

With KB

Team makes decision:

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

Before KB

Solving a bug:

Encounter race condition in cache
Debug for 2 hours
Fix it
Solution lost in PR comments

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

With KB

Solving a bug:

Encounter race condition
Ask Claude: "Have we seen cache race conditions before?"
Claude finds journal entry from 2 months ago with solution
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.

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.

KOGRAL Documentation

Why KB?

The Problem: Knowledge Fragmentation

The Solution: Unified, Queryable Knowledge Graph

What Makes KB Different?

1. Git-Native

2. AI-Native

3. Config-Driven

4. Multi-Graph

5. Structured Relationships

Real-World Impact

Before KB

With KB

Before KB

With KB

Before KB

With KB

Who Benefits?

Individual Developers

Teams

Organizations

AI Agents

When NOT to Use KB

The Vision

Design Philosophy

1. Knowledge should be captured during work, not after

2. Knowledge should be connected, not isolated

3. Knowledge should be queryable, not browsable

Get Started

Keyboard shortcuts

KOGRAL Documentation