Lore MCP server

Lore

Your engineering wisdom, always in context.

Lore is a local semantic search engine for your software patterns and conventions, exposed as a Model Context Protocol (MCP) tool for Claude Code. Your knowledge lives as markdown files in a git repository. Lore indexes them with hybrid full-text and vector search, then serves results over MCP so your AI coding agent consults your patterns before writing code.

Single Rust binary. No external database. Only runtime dependency is an embedding server: Ollama by default, or an OpenAI-compatible embedding server such as llama-server.

How It Works

Markdown files (git repo, source of truth)
        │
        ▼  ingest
┌───────────────┐       ┌──────────┐
│     lore      │──────▶│  Ollama  │  (embed chunks)
│ (Rust binary) │◀──────│  :11434  │
└───────┬───────┘       └──────────┘
        │
        ▼
┌───────────────┐
│  SQLite       │  FTS5 (lexical) + sqlite-vec (vector)
│ (single file) │  both compiled into the binary
└───────┬───────┘
        │
        ▼  MCP over stdio
┌───────────────┐
│  Claude Code  │
└───────────────┘

Install

Prerequisites

• Ollama: brew install ollama or see install options

To use llama-server, LM Studio or a hosted service instead, see Embedding Servers.

lore init needs the embedding server running. After setup, if the server becomes unavailable, search falls back to keyword matching and warns that it has.

Homebrew

On macOS (Apple Silicon or Intel) and Linux (x86_64 or Arm), install with Homebrew:

brew install attila/tap/lore

The formula installs the prebuilt release archive, verified against its published checksum, and is updated with every stable release. It does not install Ollama.

Prebuilt archive

Prebuilt binaries are published with every tagged release on the releases page, accompanied by a SHA256SUMS file for integrity verification. Pick VERSION from the releases page. Set TARGET to one of x86_64-unknown-linux-gnu (most Linux), x86_64-unknown-linux-musl (Alpine and musl distros), aarch64-unknown-linux-musl (Arm Linux), aarch64-apple-darwin (Apple Silicon), or x86_64-apple-darwin (Intel Mac):

VERSION=0.6.0
TARGET=x86_64-unknown-linux-gnu

curl -LO https://github.com/attila/lore/releases/download/v${VERSION}/lore-${VERSION}-${TARGET}.tar.gz
curl -LO https://github.com/attila/lore/releases/download/v${VERSION}/SHA256SUMS
sha256sum -c SHA256SUMS --ignore-missing   # macOS: shasum -a 256 -c SHA256SUMS --ignore-missing
tar xzf lore-${VERSION}-${TARGET}.tar.gz
sudo mv lore /usr/local/bin/
# (no sudo? mkdir -p ~/.local/bin && mv lore ~/.local/bin/, then ensure ~/.local/bin is on PATH)

Why does Gatekeeper block the binary? Tarballs downloaded via curl run without further intervention. If you download via a browser, macOS may attach the com.apple.quarantine extended attribute and refuse to launch the binary. Clear it with xattr -d com.apple.quarantine ./lore after extraction (or right-click → Open the first time). The binary is not Apple-notarized: that requires a paid Developer ID certificate, which the project does not currently hold.

Build from source

Building from source needs Rust (the version pinned in rust-toolchain.toml) and just (cargo install just).

just install

This runs cargo install --path ., placing the lore binary in ~/.cargo/bin/ (which rustup adds to PATH during Rust installation). To build without installing:

cargo build --release
# binary at ./target/release/lore

Quick Start

Initialise and Use

# Point lore at a directory of markdown files (git repository recommended)
lore init --repo ~/my-patterns

# Test a search
lore search "error handling"

# Check health
lore status

The init command verifies Ollama is running, pulls the embedding model (nomic-embed-text, ~270MB), creates lore.toml and the knowledge database, and runs the first ingestion.

For an OpenAI-compatible embedding server, add --provider openai-compatible, --url and --model, as Embedding Servers shows.

Use with Claude Code

Install the lore plugin to get the MCP server, lifecycle hooks, and the /search and /coverage-check skills:

claude --plugin-dir /path/to/lore/integrations/claude-code/

The plugin assumes lore is on PATH and uses the default configuration (~/.config/lore/lore.toml). If you use a custom configuration path, either edit integrations/claude-code/mcp.json to add your --config flag, or add the MCP server manually:

claude mcp add --scope user --transport stdio lore -- \
  lore serve --config /path/to/lore.toml

The manual approach gives only the MCP server. The plugin also includes hooks that inject relevant patterns before edits, a /search skill for on-demand queries, and a /coverage-check skill. The /coverage-check skill audits a draft pattern's vocabulary coverage by simulating the PreToolUse hook's own query extraction against synthetic tool calls.

Patterns whose tags: frontmatter list contains universal opt into an always-on tier. Lore emits these in full at every SessionStart. It re-injects them on every relevant tool call, for process-level conventions like push discipline that need continuous reinforcement. See the "When to use the universal tag" section in the pattern authoring guide.

Commands

Command	Purpose
lore init --repo <path>	First-time setup: provision Ollama, create configuration, ingest
lore ingest	Re-index the knowledge directory after editing markdown files
lore ingest --file <path>	Index a single file without requiring a git commit
lore serve	Start the MCP server (stdio transport for Claude Code)
lore search <query>	Search from the command line
lore extract-queries	Simulate the hook's FTS5 query extraction for a tool call
lore list	List every indexed pattern
lore status	Check health of all components
lore trace why	Explain lore's injection decisions from its trace files
lore trace prune	Compress and delete old trace files

What if the knowledge directory is empty? lore ingest and lore serve print a warning to stderr ("Warning: knowledge directory is empty …") and continue. An empty directory is a legal state, not an error, so the exit status stays 0. Add a .md file or relax .loreignore to populate the index. lore status reports the same state via its Scan set: line, and the MCP lore_status tool exposes empty_knowledge_dir: true plus knowledge_dir_status: "empty" for monitoring callers.

MCP Tools

The server exposes six tools:

Tool	Purpose
search_patterns	Semantic + keyword search across all patterns
add_pattern	Create a new pattern file, index it, and commit if the base is a git repository
update_pattern	Replace an existing pattern's content, re-index, and commit if git is in use
append_to_pattern	Add a section to an existing pattern, re-index, and commit if git is in use
list_patterns	List every indexed pattern with its tags and whether it is universal
lore_status	Report knowledge directory health: git status, indexed counts, last commit

Knowledge Directory Format

Your knowledge directory is a directory of markdown files. Any structure works:

my-patterns/
├── error-handling.md
├── testing/
│   ├── unit-tests.md
│   └── integration-tests.md
├── api-design.md
└── code-style.md

Only files with a .md or .markdown extension are ingested. Other files (.txt, .mdx, .rst, etc.) are skipped without a warning. They do not appear in search results.

Git is recommended but not required. Lore works against a plain directory, but delta ingest, the inbox branch workflow, and version history are all unavailable without a git repository. See Configuration Reference → Git Integration for the full picture.

Files are chunked by heading: each ## Section becomes a separate searchable unit. YAML frontmatter tags are extracted and searchable.

To exclude non-pattern files such as README.md, CONTRIBUTING.md, or a drafts/ directory from indexing, place a .loreignore file at the repository root. The syntax matches .gitignore and supports negation patterns. See the Configuration Reference for details.

---
tags: [error-handling, rust, result-types]
---

# Error Handling with Result Types

Always use Result<T, E> for fallible operations...

Search

• Hybrid (default): Combines FTS5 lexical search and sqlite-vec vector similarity using Reciprocal Rank Fusion. Title and tag matches are weighted above body text, so domain-scoped queries return the right patterns first.
• Full-Text Search (FTS) only: Set hybrid = false in lore.toml to skip the embedding server at query time.

Documentation

Guide	Description
Pattern Authoring Guide	How to write patterns that agents follow
Search Mechanics Reference	Full search pipeline internals for debugging discoverability
Hook Pipeline and Plugin Reference	Hook lifecycle, plugin setup, and injection tuning
Configuration Reference	lore.toml options, environment variables, CLI flags
Embedding Servers	Use an OpenAI-compatible embedding server instead of Ollama
Release Process	Maintainer runbook for cutting releases

Development

Prerequisites

• just: task runner
• dprint: formatter
• cargo-deny: dependency auditor
• git-cliff: changelog generator

Commands

just setup    # configure git hooks (run once after clone)
just ci       # run the full quality gate pipeline

Command	What it does
just setup	Configure git hooks (run once after clone)
just fmt	Check formatting
just fmt-fix	Fix formatting
just clippy	Run clippy lints
just test	Run tests (no Ollama needed)
just deny	Run dependency audits
just doc	Build documentation
just changelog	Regenerate CHANGELOG.md from git history
just ci	Run the full pipeline

License

Dual-licensed under MIT and Apache 2.0.