lore

module

v0.1.2 Latest Latest Go to latest Published: Aug 17, 2026 License: MIT

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/cheetahbyte/lore

Links

Open Source Insights

README ¶

lore

A local-first documentation index served to LLM agents over MCP. Single static Go binary — no Node, no Python, no CGO, no hosted service required. lore ingests docs from GitHub repos, llms.txt sites, package registries, and crawled websites, indexes them with full-text (and optionally semantic) search, and serves them to any MCP client.

Comparable to context7, docs-mcp-server, rtfmbro-mcp, and contextmine — see issue #1 for the full design spec and the reasoning behind every architectural decision below.

Install

go install github.com/cheetahbyte/lore/cmd/lore@latest

Prebuilt cross-platform binaries are published to GitHub Releases on tag push.

Usage

lore add github:owner/repo        # index a GitHub repo's docs (latest tag, or default branch)
lore add npm:react                # index an npm package's readme
lore add pypi:requests             # index a PyPI project's description
lore add pkg.go.dev:golang.org/x/tools
lore add llms-txt:example.com      # index a site's llms.txt / llms-full.txt
lore add url:https://docs.example.com --depth 2 --include /docs/

lore list                          # what's indexed
lore search github:owner/repo "how do I configure X"
lore refresh                       # re-fetch everything, skip unchanged content
lore serve                         # run the MCP server over stdio

Point any MCP client at lore serve. It exposes three tools: list_libraries, resolve_library, search_docs.

Config

Global, not per-project — one index at $XDG_DATA_HOME/lore/index.db (~/.local/share/lore by default), one config at $XDG_CONFIG_HOME/lore/config.toml:

[embeddings]
provider = ""   # "" = FTS-only (default), or "openai" | "ollama" to enable vector search
api_key = ""    # or set LORE_EMBEDDINGS_API_KEY
endpoint = ""   # e.g. http://localhost:11434/v1 for Ollama

[sources."url:https://docs.example.com"]
depth = 2
include = ["/docs/"]

Status

Implements the spec in issue #1 end to end: all four source adapters, structure-aware chunking, FTS5 + optional vec1-fused-via-RRF retrieval, the three MCP tools, and the full CLI. Known gaps, tracked as follow-ups rather than blocking:

Bare-name source inference (lore add react without a npm: prefix) isn't implemented — the type prefix is required for now.
lore refresh always does a full re-fetch + content-hash diff; the conditional-request optimization (ETags/commit SHAs) from issue #12 isn't wired up yet, so refreshing unchanged content still costs a fetch, just not a re-index.
The retrieval-quality fixture corpus and CI eval from issue #11 aren't set up.

Directories ¶

Path	Synopsis
cmd
lore command Command lore is the CLI decided in https://github.com/cheetahbyte/lore/issues/3.	Command lore is the CLI decided in https://github.com/cheetahbyte/lore/issues/3.
internal
chunk Package chunk defines lore's chunk data model and the structure-aware chunker, decided in https://github.com/cheetahbyte/lore/issues/7 and https://github.com/cheetahbyte/lore/issues/8.	Package chunk defines lore's chunk data model and the structure-aware chunker, decided in https://github.com/cheetahbyte/lore/issues/7 and https://github.com/cheetahbyte/lore/issues/8.
config Package config implements lore's minimal config file, decided in https://github.com/cheetahbyte/lore/issues/3: only embeddings provider settings and per-crawled-source options live here, everything else is pure CLI args.	Package config implements lore's minimal config file, decided in https://github.com/cheetahbyte/lore/issues/3: only embeddings provider settings and per-crawled-source options live here, everything else is pure CLI args.
embed Package embed implements the optional embeddings path decided in https://github.com/cheetahbyte/lore/issues/7: vector search is opt-in, never generated in-process (no bundled/local model, per the research on issue #6) — always an external API call.	Package embed implements the optional embeddings path decided in https://github.com/cheetahbyte/lore/issues/7: vector search is opt-in, never generated in-process (no bundled/local model, per the research on issue #6) — always an external API call.
identity Package identity implements lore's typed-prefix source identity scheme, decided in https://github.com/cheetahbyte/lore/issues/8.	Package identity implements lore's typed-prefix source identity scheme, decided in https://github.com/cheetahbyte/lore/issues/8.
ingest Package ingest wires the Source adapters (issue #8), the chunker (issue #7), the optional embedder (issue #7), and the Store (issue #10) together into the `lore add`/`lore refresh` flows (issue #3).	Package ingest wires the Source adapters (issue #8), the chunker (issue #7), the optional embedder (issue #7), and the Store (issue #10) together into the `lore add`/`lore refresh` flows (issue #3).
logging Package logging implements lore's local logging approach, decided in https://github.com/cheetahbyte/lore/issues/13: log/slog, always to stderr (stdout is reserved for MCP protocol traffic during `lore serve`), with a text or JSON handler and level controlled by --verbose or LORE_LOG_LEVEL (flag wins).	Package logging implements lore's local logging approach, decided in https://github.com/cheetahbyte/lore/issues/13: log/slog, always to stderr (stdout is reserved for MCP protocol traffic during `lore serve`), with a text or JSON handler and level controlled by --verbose or LORE_LOG_LEVEL (flag wins).
mcpserver Package mcpserver implements the MCP tool surface decided in https://github.com/cheetahbyte/lore/issues/2: stdio transport, three tools (list_libraries, resolve_library, search_docs), read-only over the local index — no tool can trigger ingestion.	Package mcpserver implements the MCP tool surface decided in https://github.com/cheetahbyte/lore/issues/2: stdio transport, three tools (list_libraries, resolve_library, search_docs), read-only over the local index — no tool can trigger ingestion.
retrieval Package retrieval implements the hybrid FTS+vector fusion decided in https://github.com/cheetahbyte/lore/issues/7.	Package retrieval implements the hybrid FTS+vector fusion decided in https://github.com/cheetahbyte/lore/issues/7.
source Package source implements the Source interface and its four adapters, decided in https://github.com/cheetahbyte/lore/issues/8: each adapter only resolves identity/versions and fetches raw content — chunking is one shared pipeline stage in the ingest package, not reimplemented per adapter.	Package source implements the Source interface and its four adapters, decided in https://github.com/cheetahbyte/lore/issues/8: each adapter only resolves identity/versions and fetches raw content — chunking is one shared pipeline stage in the ingest package, not reimplemented per adapter.
store Package store implements the Store interface decided in https://github.com/cheetahbyte/lore/issues/10: everything above this package (ingestion, retrieval, MCP handlers) talks only to Store, never to a concrete database type, so a future hosted backend can be a second implementation rather than a rewrite.	Package store implements the Store interface decided in https://github.com/cheetahbyte/lore/issues/10: everything above this package (ingestion, retrieval, MCP handlers) talks only to Store, never to a concrete database type, so a future hosted backend can be a second implementation rather than a rewrite.

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL