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)

Module	Description
backend/app/vector_store.py	SQLite document store + all-MiniLM-L6-v2 semantic embeddings
backend/app/api.py	FastAPI CRUD, search, reindex, analytics, namespace endpoints
backend/app/mcp_server.py	MCP tools (stdio, SSE, streamable-http transports)
backend/app/service.py	Per-namespace KB instances with LRU caching
backend/app/analytics.py	MCP event logging in a global analytics.db
frontend/	Vite + React + TypeScript, TanStack Router, Tailwind

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:

Path	Contents
.localdata/backend/knowledge_base*.db	Document store (one file per namespace)
.localdata/backend/analytics.db	MCP event log

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

Tool	Description
get_document(document_id)	Fetch full document content
search_documents(query, limit)	Semantic + lexical search with freshness decay
create_document(title, content)	Add a new document
update_document(document_id, ...)	Update title and/or content
delete_document(document_id)	Remove a document
verify_document(document_id)	Confirm a document is still accurate (bumps freshness timestamp)
get_stale_documents(days_threshold)	Find documents that may be outdated
reindex_documents	Re-embed all documents (run after first deploy or model changes)

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