Skip to content

Installation

System Requirements

Component Minimum Notes
Python 3.11+ 3.12 recommended
RAM 512 MB 1 GB+ for large knowledge bases
Disk 200 MB Base install; data grows with your KB
OS Linux, macOS, Windows (WSL2) Docker image is linux/amd64 and linux/arm64

Sentence Transformers

Lithos downloads a sentence-transformers model (all-MiniLM-L6-v2, ~90 MB) on first run to power semantic search. Subsequent starts use the cached model. No internet connection is required after the first run.

Install Methods

Docker is the easiest way to run Lithos — no Python environment management, no dependency conflicts.

Prerequisites: Docker and Docker Compose (v2+)

git clone https://github.com/agent-lore/lithos.git
cd lithos
docker compose up -d

This starts Lithos on SSE transport at http://localhost:8765/sse.

Data is persisted in a Docker volume (lithos_data). To use a local directory instead:

# docker-compose.override.yml
services:
  lithos:
    volumes:
      - ./my-knowledge-base:/app/data

pip install lithos-mcp

Then start the server:

# SSE transport (recommended for network clients)
lithos serve --transport sse --host 0.0.0.0 --port 8765

# stdio transport (for Claude Desktop, local MCP clients)
lithos serve

uv is the fastest way to install Python packages:

uv pip install lithos-mcp
lithos serve --transport sse --port 8765

Local dev with telemetry

Use --telemetry-console to stream OTEL spans and metrics to stdout without a collector: 

lithos serve --transport sse --port 8765 --telemetry-console

For hacking on Lithos itself, the project now uses uv exclusively:

git clone https://github.com/agent-lore/lithos.git
cd lithos
uv sync --extra dev
make check        # lint + type check + unit tests
uv run lithos serve --transport sse --port 8765

Connect an Agent

Once Lithos is running, add it to your agent's MCP config:

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or the equivalent on your platform:

{
  "mcpServers": {
    "lithos": {
      "command": "lithos",
      "args": ["serve"]
    }
  }
}

Restart Claude Desktop. You'll see the Lithos tools in the tool list.

claude mcp add --transport sse lithos http://localhost:8765/sse

In ~/.openclaw/workspace/config/mcporter.json:

{
  "mcpServers": {
    "lithos": {
      "baseUrl": "http://localhost:8765/sse"
    }
  },
  "imports": []
}

If Lithos is on a different machine:

{
  "mcpServers": {
    "lithos": {
      "baseUrl": "http://samsara.local:8765/sse"
    }
  }
}

In Agent Zero's MCP server config (usually in the web UI or mcp_servers.json):

{
  "mcpServers": {
    "lithos": {
      "url": "http://host.docker.internal:8765/sse"
    }
  }
}

Use host.docker.internal when Agent Zero runs in Docker on the same machine as Lithos.

Lithos speaks standard MCP. Any client that supports SSE transport can connect:

SSE endpoint: http://<host>:8765/sse

For stdio transport, use lithos serve (no flags) as the command.

Verify the Installation

# Check the server is running
curl http://localhost:8765/health

# Or use the CLI
lithos stats

You should see:

{
  "documents": 0,
  "chunks": 0,
  "agents": 0,
  "active_tasks": 0,
  "open_claims": 0,
  "tags": 0,
  "duplicate_urls": 0
}

Upgrading

docker compose pull
docker compose up -d

pip install --upgrade lithos-mcp
# or
uv pip install --upgrade lithos-mcp

Pre-1.0 compatibility

Lithos follows a migration safety over API stability policy pre-1.0. MCP tool signatures may change between minor versions, but your on-disk Markdown knowledge is always preserved. Check the Changelog before upgrading.

v0.2.1 breaking changes

lithos_links and lithos_provenance were removed in v0.2.1. Replace them with lithos_related.

Next Steps