# Lore

> Your engineering wisdom, always in context.

- **Type:** MCP server
- **Install:** `agentstack add mcp-attila-lore`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [attila](https://agentstack.voostack.com/s/attila)
- **Installs:** 0
- **Category:** [Search](https://agentstack.voostack.com/c/search)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [attila](https://github.com/attila)
- **Source:** https://github.com/attila/lore

## Install

```sh
agentstack add mcp-attila-lore
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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](https://ollama.com)
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](https://rustup.rs/) (latest stable, pinned via `rust-toolchain.toml`)
- [just](https://github.com/casey/just) — task runner (`cargo install just`)
- [Ollama](https://ollama.com) — `brew install ollama` or see install options

### Install

Prebuilt binaries are published with every tagged release on the
[releases page](https://github.com/attila/lore/releases), 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):

```sh
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

```sh
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:

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

### Initialize and Use

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

```sh
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:

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

```markdown
---
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](https://github.com/casey/just) — task runner
- [dprint](https://dprint.dev/install/) — formatter
- [cargo-deny](https://github.com/EmbarkStudios/cargo-deny) — dependency auditor
- [git-cliff](https://git-cliff.org) — changelog generator

### Commands

```sh
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](https://github.com/attila)
- **Source:** [attila/lore](https://github.com/attila/lore)
- **License:** Apache-2.0

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-attila-lore
- Seller: https://agentstack.voostack.com/s/attila
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.