Lore

The Knowledge Memory for AI Agents

Lore replaces bloated context files with selective, queryable knowledge. Instead of loading thousands of lines into every AI conversation, query for just the relevant entries.

Traditional:  context files (2000+ lines) → AI context (mostly wasted)
Lore:         knowledge base → query → 5-10 relevant entries → AI context (focused)

The Problem

AI coding assistants are powerful, but context windows have limits. Teams respond by creating CLAUDE.md, AGENTS.md, feature docs, and best practices files. Some split into multiple files, loading them selectively.

It doesn't scale. Whether one file or fifty, context bloats. "Selective" loading still pulls in mostly irrelevant content. The AI generates code that works but doesn't fit your conventions.

The Solution

Lore stores knowledge as discrete entries, each scoped to specific files or tasks. Query returns only what's relevant to your current work.

# Query by what you're working on
lore query --files "src/auth/**" --task "implement OAuth"

# Returns focused entries:
# - Password Hashing Convention (score: 0.87)
# - JWT Token Structure (score: 0.72)
# - Auth Error Handling (score: 0.65)

Installation

# Clone and build
git clone https://github.com/namishsaxena/lore.git
cd lore
pnpm install && pnpm build
npm link packages/cli

Or download a release and run:

unzip lore-VERSION.zip && cd dist && ./install.sh

Quick Start

# Initialize in your project
cd your-project
lore init

# Import existing documentation
lore import ./docs --recursive

# Add specific knowledge
lore add "Always use bcrypt with cost factor 12 for password hashing" \
  --title "Password Hashing Convention" \
  --type convention \
  --scope-files "src/auth/**"

# Query relevant knowledge
lore query --task "implement user registration"

# Check health
lore doctor

How It Works

Knowledge Entries

Each entry is a discrete piece of knowledge:

┌─────────────────────────────────────────┐
│ Title: Password Hashing Convention      │
│ Type: convention                        │
│ Scope: src/auth/**                      │
│ Tags: security, passwords               │
├─────────────────────────────────────────┤
│ Always use bcrypt with cost factor 12.  │
│ Never store passwords in plain text.    │
└─────────────────────────────────────────┘

Entry Types

Type	Purpose
convention	How things are done here
pattern	Reusable solutions
architecture	System design
decision	Why we chose this
gotcha	Warnings and pitfalls
workflow	How-to processes
reference	Quick lookup
example	Code samples

Scoped Retrieval

Entries are scoped to files and tasks. When you query with --files "src/auth/**", entries scoped to src/auth/** rank higher. Context-aware, not just search.

Claude Code Integration

Lore integrates with Claude Code in three ways:

Option 1: Plugin (Recommended)

Install the plugin globally for automatic knowledge retrieval:

# Add the marketplace (one-time)
/plugin marketplace add namishsaxena/lore

# Install the plugin
/plugin install lore@lore

The plugin provides:

• Automatic Skill: Claude queries knowledge automatically based on context
• Slash Commands: /lore:query, /lore:capture, /lore:list, /lore:show, /lore:prime
• Session Hook: Automatically primes context at session start

Option 2: Project Hooks

Set up per-project hooks:

lore init  # Sets up hooks automatically

This configures SessionStart hooks so Claude receives awareness of the knowledge system when sessions begin.

Option 3: MCP Server (Advanced)

For native tool integration, use the MCP server. This requires building from source until @lore/mcp is published to npm.

# Add MCP config to your project's .claude/settings.json
{
  "mcpServers": {
    "lore": {
      "command": "node",
      "args": ["/path/to/lore/packages/mcp/dist/server.js"],
      "env": {
        "LORE_PROJECT_PATH": "/path/to/your/project"
      }
    }
  }
}

This gives Claude four native tools:

• lore_query: Query knowledge by task, files, or tags
• lore_capture: Capture new knowledge entries
• lore_feedback: Mark entries as helpful/not helpful
• lore_suggest_capture: Batch capture suggestions

Commands

Command	Description
lore init	Initialize Lore in your project
lore add	Add a knowledge entry
lore import	Import from markdown files
lore query	Query relevant entries
lore list	List all entries
lore show <id>	Show entry details
lore sync	Sync between SQLite and JSONL
lore doctor	Health check and diagnostics

Storage

Lore uses dual storage:

• SQLite for fast queries and full-text search (local cache, gitignored)
• JSONL for git-friendly storage (source of truth, version-controlled)

Your knowledge merges cleanly across branches. Database corrupts? Rebuild from JSONL in seconds:

rm .lore/lore.db
lore sync --import-only

Documentation

• User Guide - Complete usage documentation
• About - Philosophy and vision
• Architecture - Technical details
• Decisions - Why we built it this way

Status

Version 0.1.0 - Early release. Core functionality works. Feedback welcome.

• CLI with all core commands
• SQLite storage with FTS5 search
• Markdown import with intelligent chunking
• Claude Code integration via hooks
• Claude Code plugin with Skill and Commands
• MCP server for native tool integration

Contributing

We're not accepting pull requests at this time, but we welcome:

• Bug reports
• Feature suggestions
• Usage feedback
• Documentation improvements

Please open an issue to discuss.

License

MIT - see LICENSE