localdb

Point it at your stuff. Search it instantly — from the terminal, or from any AI assistant you
already use. Notes, specs, PDFs, Word/Excel/PowerPoint docs, EPUBs, bookmarked pages — one
localdb index later, hybrid (keyword + semantic) search returns cited, byte-exact excerpts in
milliseconds. One binary, no Python, no Docker, no cloud, no daemon required for search, no API key.
See how it compares to GPT4All, Khoj, Basic Memory, and others.

The long-horizon goal is larger: a private, trust-weighted alternative to the feed — your knowledge
enriched by what the people you trust have found, with provenance at every hop. The foundation for
that is built in from day one: content-addressed documents, per-chunk provenance, and stores as
first-class shareable units. Start with the project vision — the whole picture
in plain language.

Whatever the scale — a personal knowledge base, an AI agent's memory served back over MCP (see
docs/agent-memory.md), or a document collection running to millions of pages
— your data stays on your machine, and you decide what, if anything, ever leaves it.

localdb also continues a long-running thread: its author previously built and ran
ipfs-search.com — open-source, decentralized search for the IPFS
network — for seven years.

Status: hybrid search uses real dense embeddings via the default local model
(pplx-embed-context-v1-0.6b, ONNX on CPU by default; CoreML ANE/GPU on Apple Silicon macOS
automatically); the first indexing or search operation — including add's auto-index — downloads
~706 MB from HuggingFace (no API key required). The HTTP daemon remains experimental, with no auth.
See docs/architecture.md#known-gaps for the full list of what's
not there yet.

Quickstart

1. Install (pick one):

   brew install dokterbob/localdb/localdb        # Homebrew, macOS and Linux
   curl --proto '=https' --tlsv1.2 -LsSf https://github.com/dokterbob/localdb/releases/latest/download/localdb-installer.sh | sh
   

   See docs/install.md for tarballs, building from source, and completions.

2. Add and index a folder — scaffolds config.yaml and a default store on first use, then
   indexes it:

   localdb add ~/notes
   

   The first indexing or search operation (including this auto-index) downloads the ~706 MB default
   embedding model from HuggingFace; later runs reuse the cached copy.

3. Search:

   localdb search "some query"
   

   Add --json for structured Citation objects (chunk IDs, provenance hashes, per-component
   scores, document metadata). Scope either command to one store with -s — flags go before the
   query, e.g. localdb search -s notes "some query" (everything after the first query word is
   treated as query text).

4. Connect an AI assistant:

   claude mcp add localdb -- $(which localdb) mcp
   

   Use the absolute path — MCP clients spawn the binary directly, without your shell's PATH, so a
   bare localdb often fails to launch. See docs/mcp.md for other clients and the
   remote/HTTP setup.

   Optionally, install the localdb agent skill — a crib sheet that
   teaches any skill-capable agent (Claude Code, Cursor, Codex, …) the CLI, citation shape, and MCP
   tools:

   npx skills add dokterbob/localdb
   

Comparison to other tools

localdb is a single dependency-free binary with no external services, hybrid BM25+vector search, a
native MCP server, and structured byte-span citations — a combination no surveyed alternative
(GPT4All, Khoj, Basic Memory, and five others) matches in full. See
docs/comparison.md for the full survey, including where localdb is behind (no
GUI yet, single-node, read-only MCP, no knowledge graph).

Feature highlights

Citeable hybrid search with full provenance, local files/URLs/feeds, an embedded-first design
(nothing needs to be running), five MCP tools, multiple isolated stores, a context-aware local
embedder with CoreML acceleration on Apple Silicon, a libsql backend (DiskANN + FTS5), and --json
everywhere. See docs/comparison.md
for the detailed rundown.

MCP hookup

An MCP client is the AI app that connects to localdb to retrieve information for your conversation:
for example, Claude Desktop, Claude Code, Codex, or LM Studio. For a local model setup, see
Chat with your notes locally using LM Studio.

localdb mcp exposes five read-only tools (search, list_stores, get_document, get_chunks,
list_documents) over stdio, or over HTTP at /mcp via localdb serve — including from another
machine over Tailscale/LAN. See docs/mcp.md for full tool schemas, transports, and
example calls.

Privacy boundary: with a local embedding provider, localdb indexes, embeds, and searches your
data locally, but MCP results are delivered to the MCP client. If that client uses a cloud-hosted
model, retrieved excerpts or full
documents may be sent to that provider under its data-handling policy. To minimize data exposure,
use a local/self-hosted model and the stdio transport, and expose only the required stores with
--store. Preventing data egress also requires independently reviewing and restricting the client's
outbound networking, including telemetry, cloud memory, and plugins. Store scoping reduces what the
client can retrieve; neither it nor stdio controls what the client does with returned data.
See docs/mcp.md.

Experimental HTTP daemon

localdb serve exposes a REST API (/v1) plus the same MCP tools at /mcp, backed by the same
unified database the CLI uses, with ingestion running through an async job queue with live SSE
progress. It remains experimental and unauthenticated. See docs/http-api.md for
the endpoint reference and known limitations.

Schema migrations

store-libsql tracks its schema version explicitly and refuses to open a store whose schema is
behind, ahead, or predates the migration framework (exit 2) rather than silently rebuilding — run
localdb db status / db migrate / db downgrade / db vacuum. See
docs/migrations.md for the full walkthrough and the migration-authoring guide.

Documentation

License

AGPL-3.0-or-later. See the license file for full terms.