Lore

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.5.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)

> 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

| Command | Purpose | | --------------------------- | --------------------------------------------------------- | | lore init --repo | First-time setup: provision Ollama, create config, ingest | | lore ingest | Re-index the knowledge base after editing markdown files | | lore ingest --file | Index a single file without requiring a git commit | | lore serve | Start the MCP server (stdio transport for Claude Code) | | lore search | Search from the command line | | lore extract-queries | Simulate the hook's FTS5 query extraction for a tool call | | lore status | Check health of all components |

> 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 five 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 | | lore_status | Report knowledge base health: git status, indexed counts, last commit |

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](docs/configuration.md#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](docs/configuration.md#loreignore) for details.

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

# Error Handling with Result Types

Always use Result 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

| Guide | Description | | --------------------------------------------------------------------- | ------------------------------------------------------------ | | [Pattern Authoring Guide](docs/pattern-authoring-guide.md) | How to write patterns that agents actually follow | | [Search Mechanics Reference](docs/search-mechanics.md) | Full search pipeline internals for debugging discoverability | | [Hook Pipeline and Plugin Reference](docs/hook-pipeline-reference.md) | Hook lifecycle, plugin setup, and injection tuning | | [Configuration Reference](docs/configuration.md) | lore.toml options, environment variables, CLI flags | | [Release Process](docs/release-process.md) | 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](LICENSE-MIT) and [Apache 2.0](LICENSE-APACHE).

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: attila
• Source: attila/lore
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.