Guides

Best practices and workflows for getting the most out of LoreHub.

Quick Start Guides

🏢 Team Knowledge Sharing - Get your team using LoreHub effectively
📦 Monorepo Setup - Configure LoreHub for multi-service projects
🔍 Search Strategies - Master literal, semantic, and hybrid search
🎯 Best Practices - Recommended patterns for lore management

Getting Started with Your Team

Install LoreHub

Have team members install LoreHub globally:


npm install -g lorehub

Start Adding Knowledge

Begin capturing decisions as they’re made:


# Use interactive mode for better experience
lh add
 
# Or inline for quick captures
lh add "Decided to use TypeScript for all new services" --type decree --confidence 95

Browse and Search

Team members can discover knowledge:


# Interactive browse mode
lh browse
 
# Search across all realms
lh search "authentication"
 
# Semantic search for concepts
lh search "how do we handle user sessions" --semantic

Knowledge Capture Patterns

During Meetings:


# Capture architectural decisions
lh add "Moving to microservices for better scalability" --type decree --why "Monolith becoming hard to deploy"
 
# Document constraints
lh add "Must maintain IE11 support for enterprise clients" --type constraint --confidence 100

After Incidents:


# Document lessons learned
lh add "Memory leak occurs when webhook retries exceed 10" --type wisdom --why "Caused outage on 2024-01-15"
 
# Track risks
lh add "Database migrations timeout on tables > 1M rows" --type risk --confidence 90

During Development:


# Track future work
lh add "Investigate replacing moment.js with date-fns" --type quest --why "Bundle size concerns"
 
# Document requirements
lh add "GDPR requires 30-day data retention maximum" --type requirement --confidence 100

Monorepo Setup

Using Provinces

For monorepos, use provinces to organize knowledge by service:


# Add lore for specific service
lh add "Auth service uses JWT with 1-hour expiry" --provinces auth --type decree
 
# Add lore affecting multiple services
lh add "All services must implement health checks" --provinces api,auth,worker --type requirement
 
# Search within a province
lh search "token" --province auth

Province Naming Conventions

Recommended patterns:


monorepo/
├── services/
│   ├── auth/        → province: auth
│   ├── api/         → province: api
│   └── worker/      → province: worker
├── packages/
│   ├── ui/          → province: ui
│   └── shared/      → province: shared
└── apps/
    ├── web/         → province: web
    └── mobile/      → province: mobile

Search Strategies

When to Use Each Mode

Mode	Best For	Example
Literal	Exact terms, code, errors	`lh search "ECONNREFUSED"`
Semantic	Concepts, questions	`lh search "how to improve performance" --semantic`
Hybrid	General exploration	`lh search "caching strategy"` (default)

Effective Searches

Literal Search Tips:

Use wildcards: lh search "redis*" or lh search "*cache*"
Search for exact errors: lh search "TypeError: Cannot read"
Find specific technologies: lh search "postgresql"

Semantic Search Tips:

Ask questions: lh search "why is the app slow" --semantic
Find related concepts: lh search "user authentication" --semantic
Discover solutions: lh search "prevent memory leaks" --semantic

Browse Mode Features

In lh browse:

Press / to filter results
Press m to toggle search modes
Press s to see similar lores
Use j/k or arrow keys to navigate

Best Practices

Lore Content Guidelines

Be Specific: Include concrete details, versions, and context

❌ “Use caching” ✅ “Use Redis for session caching with 24-hour TTL”

Confidence Levels

Use confidence scores meaningfully:

90-100%: Proven in production, well-documented
70-89%: Strong evidence, tested
50-69%: Hypothesis, needs validation
Below 50%: Speculation, unverified

Type Selection

Choose the most appropriate type:


# Technical decision
lh add "Use PostgreSQL for main database" --type decree
 
# Learned from experience  
lh add "Batch API calls reduce latency by 60%" --type wisdom
 
# Future investigation
lh add "Research GraphQL for API v2" --type quest
 
# Known issue
lh add "File uploads fail over 100MB" --type anomaly

Sigil Usage

Use consistent sigils for categorization:


# Technology sigils
--sigils postgres,database,sql
 
# Domain sigils
--sigils authentication,security,jwt
 
# Quality sigils
--sigils performance,optimization,caching

Knowledge Evolution

Using Relations

Track how decisions change over time:


# When updating a decision
# First, find the old lore
lh search "database choice"
 
# Add new decision with relation
lh add "Migrating to MongoDB for flexibility" --type decree
 
# Then create relation (using MCP or future CLI feature)
# new-lore-id supersedes old-lore-id

Status Management

Update lore status as they age:

living: Current, active knowledge
ancient: Historical but outdated
whispered: Uncertain, needs verification
proclaimed: Official, documented
archived: No longer relevant (soft delete)

Export and Backup

Regular Exports

Create backups of your knowledge:


# Export all lores as JSON
lh export --output knowledge-backup-$(date +%Y%m%d).json
 
# Export as Markdown for documentation
lh export --format md --output knowledge.md
 
# Export specific realm
lh export --realm /path/to/project --output project-knowledge.json

Share exports with your team:

Export knowledge: lh export --output team-knowledge.json
Share via git, Slack, or documentation
Team members import: lh import team-knowledge.json

Terminal UI Tips

Keyboard Shortcuts

Browse Mode:

↑/↓ or j/k - Navigate
/ - Filter (search)
m - Change search mode
s - View similar lores
d - Delete lore
? - Help
q - Quit

Add Mode:

Tab - Next field
↑/↓ - Adjust confidence
Enter - Submit

Color Meanings

Cyan: Selected/active
Green: Success
Yellow: Warnings
Red: Errors
Gray: Secondary info

Integration Tips

With AI Assistants

When using with Claude via MCP:

Claude can search your lores
Claude can add new lores from conversations
Ask Claude to find related knowledge
Have Claude summarize decisions by type

Git Workflow

Integrate with your git workflow:


# Before starting feature
lh search "feature-name" --semantic
 
# After completing feature
lh add "Implemented feature X using pattern Y" --type wisdom
 
# In commit messages
git commit -m "feat: add user auth
 
Related lores: auth-decision-001, jwt-implementation-002"

Common Patterns

Decision Records


lh add "ADR-001: Use event sourcing for audit trail" \
  --type decree \
  --why "Need complete history of all changes for compliance" \
  --confidence 90 \
  --sigils architecture,event-sourcing,compliance

Post-Mortem Lessons


lh add "Cascading failure when Redis connection pool exhausted" \
  --type wisdom \
  --why "Incident 2024-01-15: All services tried to reconnect simultaneously" \
  --confidence 100 \
  --sigils incident,redis,connection-pool

Technical Debt


lh add "Legacy payment system needs refactoring" \
  --type quest \
  --why "Code is 5 years old, hard to maintain, no tests" \
  --confidence 85 \
  --sigils tech-debt,payments,refactoring

Troubleshooting

Semantic Search Issues

If semantic search isn’t working:


# Generate embeddings
lh migrate-embeddings
 
# Force regenerate all
lh migrate-embeddings --force

Performance

For large knowledge bases:

Use --limit to reduce results
Filter by type or province
Use literal search for exact matches

Next Steps

Explore Integrations for connecting LoreHub to your tools
Check the API Reference for MCP integration
Review Commands for all available options