Harbor Gang.
Browse Lighthouse docs
Lighthouse docs
LighthouseQuickstart

Lighthouse quickstart

What you're about to run

Lighthouse is a temporal knowledge graph that gives AI agents memory across sessions. You install it locally, point it at some content, and expose it to any MCP‑aware client. The pieces are a FalkorDB graph store, a small FastAPI service, and an MCP server that wraps the search tools. Everything runs on your laptop.

This page is the install path. For the why and the architecture, the Lighthouse product page is the read.

Prerequisites

  • Python 3.11 or later.
  • Docker (FalkorDB runs in a container).
  • About 2 GB of free disk for the graph data.
  • An Anthropic API key (for the librarian — the agent that curates incoming facts).

Install

pip install lighthouse-kg

The package ships the FastAPI service, the CLI, the MCP server, and the connectors.

Start the graph

Clone the repo for the bundled compose file (it's a single service):

git clone https://github.com/ElMundiUA/lighthouse
cd lighthouse

cp .env.example .env
# Fill in ANTHROPIC_API_KEY and LIGHTHOUSE_PROPOSAL_API_KEY

docker compose -f infra/docker-compose.yml up -d

FalkorDB now listens on localhost:6379. You don't talk to it directly — Lighthouse does.

Run the server

uvicorn lighthouse.api.main:app --reload

The API binds to localhost:8000. Two endpoints to verify it's up:

curl http://localhost:8000/health
curl 'http://localhost:8000/search?q=hello&top_k=5'

The first returns the build status. The second returns an empty hit list — you haven't ingested anything yet.

Ingest something

Three connectors ship today. Pick whichever matches what you actually want the agent to remember.

Local markdown

lighthouse ingest markdown ./docs

Walks a directory, parses every .md and .markdown file, and feeds them through the librarian for fact extraction. Use this for your team's internal handbook, runbooks, or any folder of notes you already keep.

Web pages

lighthouse ingest web https://example.com/post1 https://example.com/post2

Fetches each URL, parses it with Trafilatura (no JavaScript rendering), and extracts facts. Good for canonical docs you'd otherwise paste into a prompt.

GitHub repo docs

GITHUB_TOKEN=ghp_... lighthouse ingest github fastapi/fastapi --branch master

Pulls .md, .rst, .mdx, and .txt files from any public repo. Override the extension list with --ext .md .rst if you want only specific types. The token is optional for public repos but bumps the rate limit.

Point an MCP client at it

Two transports. Desktop clients want stdio; remote agents want HTTP.

Claude Desktop, Cursor (stdio)

lighthouse mcp

Spawns a stdio MCP server. Add this to your client's MCP config:

{
  "mcpServers": {
    "lighthouse": {
      "command": "lighthouse",
      "args": ["mcp"]
    }
  }
}

The client now has three tools available: library_search, library_fetch, and library_propose. Most prompts only need the first.

Remote agents (HTTP / SSE)

lighthouse mcp --transport http --port 8765

Same three tools, exposed over HTTP. Useful when the agent runs in a different process or container than Lighthouse.

Verify

Run a search through your MCP client. Something specific to whatever you ingested. If the agent answers with citations to your content instead of a hallucinated training‑memory answer, the loop is working.

The Anthropic prompt cache means the second query through the same MCP role hits the cache — input cost on subsequent searches drops sharply. That's expected.

Next steps

← Back to Lighthouse