lore

# 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.

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

```bash
# 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](https://github.com/namishsaxena/lore/releases) and run:

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

## Quick Start

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

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

```bash
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.

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

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

## Documentation

- [User Guide](docs/USER_GUIDE.md) - Complete usage documentation
- [About](docs/ABOUT.md) - Philosophy and vision
- [Architecture](docs/ARCHITECTURE.md) - Technical details
- [Decisions](docs/DECISIONS.md) - Why we built it this way

## Status

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

- [x] CLI with all core commands
- [x] SQLite storage with FTS5 search
- [x] Markdown import with intelligent chunking
- [x] Claude Code integration via hooks
- [x] Claude Code plugin with Skill and Commands
- [x] 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](LICENSE)