Core Concepts

Understanding LoreHub’s fundamental concepts will help you get the most out of the tool.

Lores

A lore is a piece of wisdom, knowledge, or decision about your codebase. Each lore represents valuable information that should be preserved and shared.

Lore Types

LoreHub categorizes lores into specific types:

Type	Purpose	Example
decree	Architectural or technical choice	”Use microservices for scalability”
wisdom	Something discovered or learned	”Caching reduces API response time by 80%“
belief	Unverified belief or hypothesis	”Users prefer dark mode”
constraint	Limitation or restriction	”Must support IE11 for enterprise clients”
requirement	Business or technical requirement	”All PII must be encrypted at rest”
risk	Potential problem or concern	”Database migrations can timeout on large tables”
quest	Future action needed	”Investigate alternative to deprecated library”
saga	Major initiative	”Migrate from monolith to microservices”
story	User story	”As a user, I want to reset my password”
anomaly	Bug or issue	”Memory leak in webhook processor”
other	Miscellaneous	Any other type of knowledge

Lore Properties

Each lore contains:

Content: The main knowledge or decision (required)
Type: Category from the list above (default: other)
Confidence: 0-100 score indicating certainty (default: 80)
Why: Additional context or reasoning
Sigils: Tags for categorization
Provinces: Services/modules in monorepos
Status: Living, ancient, whispered, proclaimed, or archived
Relations: Links to other lores

Confidence scores help indicate how certain you are about a piece of knowledge. Use higher scores (90-100) for proven facts and lower scores (50-70) for hypotheses.

Realms

A realm represents a codebase or repository. LoreHub automatically detects and tracks realms based on git repositories.

Automatic Realm Tracking

When you add a lore, LoreHub associates it with the current directory’s git repository
Each realm maintains its own collection of lores
Realms are identified by their git remote URL

Viewing Realms


lh realm        # Current realm info
lh realm list   # List all tracked realms
lh realm stats  # Detailed statistics

Provinces

Provinces are sub-sections within a realm, perfect for monorepos where different services or packages have their own context.


# Add a lore specific to the auth service
lh add "JWT tokens expire after 24 hours" --provinces auth
 
# Search within a province
lh search "authentication" --province auth

Search Modes

LoreHub offers three powerful search modes:

Literal Search

Traditional substring matching.


lh search "redis"       # Finds lores containing "redis"
lh search "cache*"      # Wildcard search

Semantic Search

AI-powered search using embeddings to find conceptually related lores.


lh search "make app faster" --semantic
# Finds lores about performance, optimization, caching, etc.

Hybrid Search

Combines literal and semantic search for best results (default).

30% weight on literal matches
70% weight on semantic similarity

Press m in browse mode to cycle through search modes. The current mode is shown in the interface.

Sigils (Tags)

Sigils are tags that help categorize and filter lores. Unlike types, you can have multiple sigils per lore.

Common sigil patterns:

Technology: redis, postgresql, react
Domain: auth, payments, analytics
Quality: performance, security, accessibility


# Add with sigils
lh add "Use React.memo for expensive renders" --sigils react,performance,optimization
 
# Search by sigil
lh search "security" --type risk

Relations

Lores can be linked to show how knowledge evolves:

Relation	Meaning	Example
supersedes	Replaces older knowledge	”Use Vite” supersedes “Use Webpack”
contradicts	Conflicts with another lore	”NoSQL for analytics” contradicts “Always use PostgreSQL”
supports	Reinforces another lore	”Index foreign keys” supports “Optimize query performance”
depends_on	Requires another lore	”Use Redis cache” depends on “Redis is available”
relates_to	General connection	”API versioning” relates to “Breaking changes policy”

Lore Status

Status indicates a lore’s current relevance:

living: Active and current (default)
ancient: Outdated but historically important
whispered: Uncertain or unverified
proclaimed: Officially documented
archived: Soft deleted (can be restored)

Confidence Levels

Confidence scores communicate certainty:

Range	Meaning	Use Case
90-100	Proven fact	Well-tested, production-verified knowledge
70-89	High confidence	Strong evidence but not absolute
50-69	Moderate confidence	Working theory or partial evidence
30-49	Low confidence	Hypothesis or early observation
0-29	Speculation	Unverified assumption

Terminal UI Features

Browse View

Split-pane interface showing list and details
Real-time filtering with /
Search mode switching with m
Navigate similar lores with s
Dynamic sizing based on terminal width

Add View

Conversational interface with emoji indicators
Tab navigation between fields
Confidence adjustment with arrow keys
Active field highlighting

Color Coding

Cyan - Active/selected items
Green - Success messages
Red - Errors
Yellow - Warnings
Gray - Secondary information

MCP Integration

LoreHub includes a Model Context Protocol server, allowing AI assistants like Claude to:

Search and retrieve lores
Create new lores from conversations
Find related knowledge
Track decisions across codebases

Performance

LoreHub is designed for speed:

SQLite - Fast embedded database
Embeddings - Cached for instant semantic search
Wildcard Search - Efficient pattern matching
Local-First - No network latency

Typical performance:

Browse startup: < 50ms
Literal search: < 10ms
Semantic search: < 100ms (after embedding generation)

Next Steps

Now that you understand the core concepts:

Learn all Commands available
Configure LoreHub in Configuration
Read Guides for best practices
Set up Integrations with your workflow