Lore

Your engineering wisdom, always in context.

Lore is a local semantic search engine for your software patterns and conventions, exposed as an 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 Ollama
for embeddings.

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     │  both compiled into the binary
│   .db file)  │
└──────┬───────┘
       │
       ▼  MCP over stdio
┌──────────────┐
│  Claude Code │
└──────────────┘

Quick Start

Prerequisites

• Rust (latest stable, pinned via rust-toolchain.toml)
• just — task runner (cargo install just)
• Ollama — brew install ollama or see install options

Install

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 and set TARGET to one of
x86_64-unknown-linux-gnu (most Linux), x86_64-unknown-linux-musl (Alpine and musl distros),
aarch64-apple-darwin (Apple Silicon), or x86_64-apple-darwin (Intel Mac):

VERSION=0.1.0-alpha.1
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)

macOS Gatekeeper note: 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

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

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

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 config (~/.config/lore/lore.toml). If
you use a custom config 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 that
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 — emitted in full at every SessionStart and re-injected 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

MCP Tools

The server exposes five tools:

Knowledge Base Format

Your knowledge base 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 silently skipped — they will 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.
• FTS-only: Set hybrid = false in lore.toml to skip Ollama at query time.

Documentation

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

License

Dual-licensed under MIT and Apache 2.0.