mudler/LocalRecall

LocalRecall – A Local‑Only RAG Knowledge‑Base Server

What it is

• A lightweight REST API that lets you store, index, and retrieve documents (text, markdown, PDF) using vector‑search databases.
• Designed to run completely offline – no GPU, no cloud, no external API required (except optional embedding services you run yourself, e.g. LocalAI).
• Works with two back‑ends:
  1. Chromem – a simple file‑based vector store that ships with the binary (default).
  2. PostgreSQL – a production‑grade engine that adds hybrid BM25 + vector search via TimescaleDB, pgvector, and vectorscale extensions.

Why it matters

• Provides a generic “memory” layer for AI agents, chat‑bots, or any application that needs long‑term or short‑term retrieval‑augmented generation (RAG).
• Keeps everything on your own hardware, which is useful for privacy‑sensitive workloads or environments without internet access.

Key features

• RESTful API for creating collections, uploading files, and searching.
• Hybrid search (BM25 keyword + vector similarity) when using PostgreSQL, with configurable weighting.
• File ingestion – supports markdown, plain‑text, PDF (more formats planned).
• External sources – you can add URLs, Git repos, or sitemaps that are periodically fetched and indexed.
• Caller‑supplied vectors – an endpoint that stores pre‑computed embeddings without invoking an embedding model.
• Web UI – a simple browser interface for managing collections and assets.
• Docker ready – official images and Docker‑Compose setup for both Chromem and PostgreSQL deployments.
• MCP integration – can be controlled via the Model Context Protocol, enabling AI agents to call LocalRecall actions directly.

Typical workflow

1. Create a collection via POST /api/collections.
2. Upload documents (/upload) or add an external source (/sources).
3. The service chunks the files, sends each chunk to an embedding model (e.g., granite-embedding-107m-multilingual via LocalAI), and stores the vectors.
4. Search the collection with a natural‑language query (POST /search).
5. Retrieve matching chunks and feed them to your LLM for RAG.

Getting started

# Clone & build
git clone https://github.com/mudler/LocalRecall.git && cd LocalRecall
go build -o localrecall
./localrecall   # UI at http://localhost:8080

Or run the official Docker image (Chromem backend):

docker run -ti -v $(pwd)/state:/state \
  -e COLLECTION_DB_PATH=/state/db \
  -e EMBEDDING_MODEL=granite-embedding-107m-multilingual \
  -e OPENAI_API_KEY=sk-xxxx \
  -e OPENAI_BASE_URL=http://localai:8080 \
  -p 8080:8080 quay.io/mudler/localrecall

For production, spin up the PostgreSQL stack with Docker‑Compose:

docker compose up -d   # brings up LocalAI, PostgreSQL, and LocalRecall

Configuration

• All behaviour is driven by environment variables (database URL, vector engine, chunk size, hybrid weights, API keys, etc.).
• An .env file can be used; the Docker‑Compose file reads it automatically.

Who should use it

• Developers building local AI agents that need a persistent knowledge store.
• Teams that require offline RAG for privacy or edge devices.
• Anyone looking for a simple, self‑hosted alternative to cloud vector DB services (e.g., Pinecone, Weaviate).

License

• MIT – free to use, modify, and embed in commercial projects.

---

All information above is taken directly from the repository’s README; no additional features have been inferred.