Lore DB

A local, vector-based knowledge base with semantic search, a web UI, and an MCP server for use with Claude and other AI tools.

• Python backend — FastAPI REST API, sentence-transformer embeddings, SQLite storage
• React frontend — document management, semantic search, analytics dashboard
• MCP server — eight tools (get, search, create, update, delete, verify, stale, reindex) over HTTP or stdio
• Multi-namespace — isolate knowledge bases per project using the X-KB-Namespace header or KB_NAMESPACE env var
• Analytics — tracks MCP tool usage (searches, views, creates) in a separate SQLite database

Architecture

proxy (nginx :8765)
  ├── /api/         → backend (FastAPI :8000)
  ├── /mcp/         → mcp    (FastMCP :8000, streamable-http)
  └── /             → frontend (nginx :80, React SPA)

Quick Start

Production

npm run start

Runs docker compose up --build -d. The app is available at http://localhost:8765.

npm run stop      # docker compose down
npm run restart   # down + up --build -d

Development (hot reload)

npm run dev

Runs docker compose -f docker-compose.dev.yml up --build. The app is available at http://localhost:8766.

• Backend restarts on Python file changes (--reload)
• Frontend uses the Vite dev server with full HMR
• Uses a separate database at .localdata/backend-dev/ so dev never touches prod data

Persistent Storage

SQLite databases are stored on the host and are gitignored:

MCP Configuration

The MCP server is exposed at http://localhost:8765/mcp/ using the streamable-http transport.

Add a .mcp.json in the directory where you start Claude:

{
  "mcpServers": {
    "knowledge-base": {
      "type": "http",
      "url": "http://localhost:8765/mcp/",
      "headers": {
        "X-KB-Namespace": "my-project"
      }
    }
  }
}

Set X-KB-Namespace to any alphanumeric slug. Each unique namespace gets its own isolated database.

Available MCP Tools

Stdio fallback

For direct CLI invocation without the HTTP server:

{
  "mcpServers": {
    "knowledge-base": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "compose",
        "exec",
        "-T",
        "-e",
        "KB_NAMESPACE=my-project",
        "backend",
        "python",
        "-m",
        "app.mcp_server"
      ]
    }
  }
}

Reindexing

Run reindex_documents() via MCP tool, the Settings page, or curl after:

• First deploy switching from the old hash embedder to all-MiniLM-L6-v2
• Upgrading to a different embedding model

curl -X POST http://localhost:8765/api/reindex -H "X-Kb-Namespace: my-project"

Normal create and update operations always auto-embed — no manual reindex needed.

Running Tests

cd backend
python -m pytest tests/ -v