lore-mcp

Purpose

Lore is an MCP server positioned as the "operational knowledge layer" for engineering teams and their AI agents. The problem it solves is this: agents know nothing about the system at the start of each session, and the runbooks they have written, the pitfalls they have hit, and the incidents they have investigated cannot carry over, leading to repeated explanations and repeated discoveries, with context disappearing when the session ends. Lore makes this operational knowledge continuously queryable by any agent through a persistent knowledge base.

Main Capabilities

• Knowledge base: captures runbooks, tricky pitfalls, architecture decisions, deployment status, and more; each entry carries author, source_type, and verified attribution information, enabling agents to judge the source and whether it has been human-verified.
• Investigation threads: when a problem occurs, a structured investigation can be opened to record symptoms, test hypotheses, and record what was tried and what was found, so that if the same problem recurs later (with a different engineer or a different agent) it can still be traced.
• Journal: records milestones, architecture decisions, procurement decisions, and other information that usually exists only in someone's head.
• Semantic search: finds entries by semantics rather than only by keywords; for example, searching for "DNS broken in containers" can return an entry titled "LXC containers inherit resolv.conf from the host". Powered by local sentence-transformers embeddings (no API key, no external calls), combined with lexical full-text search and Reciprocal Rank Fusion. The lexical part uses FTS5 for SQLite; PostgreSQL uses a GIN full-text index on title+content plus pgvector for the semantic part. The mode resolution order for kb_search is: explicit search_mode/semantic/hybrid parameters, then LORE_SEARCH_MODE_DEFAULT, and finally the built-in default hybrid; the response returns both requested_mode (the caller's intent) and search_mode (the mode actually executed). The summary mode has been removed, and passing search_mode="summary" returns a validation error; Lore is designed not to depend on an LLM, and summarization is the caller's responsibility.
• Automatic memory extraction (optional): at the end of a session, session turns are asynchronously sent toa fast LLM, which extracts facts, preferences, goals, events, and system facts, and deduplicates them against the existing knowledge base before writing. Disabled by default (auto_extract.enabled: false). Supports OpenRouter (default) or the Cerebras direct API (gpt-oss-120b). On failure it silently returns an empty result and will not throw an exception or block the session. Auto-extracted entries are marked source:auto-extracted and can optionally enter a human review queue (topic="auto-memory-pending").
• Multi-agent attribution: provenance matters in multi-agent environments, and each entry carries author, source_type, and verified.

How to Use

1. No database setup is required; it works out of the box with SQLite by default; the SQLite database and the local file search corpus are located under KNOWLEDGE_DATA_DIR, defaulting to ./knowledge-data. To enable semantic search, set LORE_SEMANTIC_SEARCH=true.
2. Start the server. HTTP authentication is optional and disabled by default: when LORE_API_KEY is not set, the HTTP server is open (no authentication), and when bound to a non-localhost host (0.0.0.0 or a LAN IP) without a key, it outputs a prominent WARNING at startup; after LORE_API_KEY is set, all HTTP/SSE requests must carry Authorization: Bearer <key>, and a missing or incorrect one returns 401 {"error":"unauthorized"} (constant-time token comparison), while health endpoints (/health, /healthz, /) remain open; stdio mode is unaffected. The same rule applies to the HTTP entry point (lore-mcp --host/--port, i.e. the FastMCP server). The default CORS origins are * with credentials disabled; LORE_CORS_ORIGINS can be set to a comma-separated allowlist.
3. Add it to an MCP client: Claude Code / Claude Desktop can add the configuration in ~/.mcp.json; HTTP mode (recommended for teams)When setting LORE_API_KEY on the server, the client configuration must include a matching bearer token; if it is not set, the headers block can be omitted. During integration, you can add one line to each agent's system prompt and add an entry in ~/.mcp.json.
4. Existing entries can be backfilled to generate embeddings; for multilingual content, you can set LORE_EMBEDDING_MODEL=paraphrase-multilingual-MiniLM-L12-v2 (also 384-dimensional, no schema changes required).
5. The PostgreSQL version is aimed at teams that want to share a knowledge layer across multiple machines or multiple agents. DB_BACKEND=postgres (and the postgresql alias) selects the bundled local PostgreSQL client, using the same path as DB_BACKEND=local; the connection defaults to DB_NAME=lore and DB_USER=lore_user, and can be overridden with connection variables.

Applicable Scenarios

• Multi-agent engineering pipelines: each stage reads prior knowledge from Lore and writes its findings back, covering stages such as research, architecture review, implementation, adversarial code review, QA, and documentation.
• Team-shared operational knowledge: make runbooks, incident troubleshooting records, and architecture decisions queryable by any agent.
• Claude Code integration with unified knowledge management, knowledge graphs, and research workflows.

Limitations and Notes

• Defaults to SQLite and runs without database configuration; PostgreSQL requires configuring connection parameters.
• Automatic extraction is disabled by default; you need to set OPENROUTER_API_KEY (or CEREBRAS_API_KEY) and enable it in the plugin configuration.
• The summary search mode has been removed.
• Deployment-related search root paths (LATVIAN_LEARNING_ROOT, LATVIAN_XTTS_ROOT, INGEST_ROOT) are unset by default; when not configured, the related search tools return empty results and explicitly mark them as "not configured," rather than scanning nonexistent paths.
• The Hermes memory provider plugin hermes-lore-plugin is provided as a standalone package, used to support session memory with Lore, prefetch relevant context at session start, deduplicate before storage, and drive the automatic memory extraction pipeline.
• License: MIT, see LICENSE for details.

For complete installation and configuration details (including API keys for automatic extraction, provider configuration, tuning thresholds, review modes, inspecting or deleting extracted entries, and how to wire up the six-stage multi-agent pipeline), please refer to docs/auto-extraction-setup.md in the repository and the related documentation.