Localhold

LocalHold

[](https://github.com/gearboxlogic/localhold/actions/workflows/ci.yml) [](https://github.com/gearboxlogic/localhold/actions/workflows/outdated.yml)

Searchable context that stays yours.

LocalHold is local context infrastructure for AI agents. It runs as a standalone Model Context Protocol server and keeps durable, searchable memory independent of any one agent or model provider.

LocalHold is in early beta. Linux CPU is the primary supported environment. Windows, PostgreSQL, and CUDA reranking are preview surfaces.

What It Provides

• SQLite storage by default, with optional PostgreSQL and pgvector
• MCP over stdio or streamable HTTP
• keyword, semantic, hybrid, and text fallback search
• OpenAI-compatible embedding endpoints, including local and cloud providers
• optional ONNX cross-encoder reranking on CPU or CUDA
• scoped memories, access policies, audit history, and maintenance tools

Storage is local by default. When an external embedding provider is enabled, memory content and search queries are sent to the configured endpoint. LocalHold does not start or manage model servers.

Install A Release

GitHub prereleases provide a Linux x8664 CPU archive and a Windows x8664 preview archive. Each archive contains hold, the example configuration, current documentation, and license notices. Verify the downloaded archive with the accompanying SHA256SUMS file before extracting it. See [Installation](docs/installation.md) for the archive layout and commands.

CUDA reranking remains a source-build preview and is not included in the binary archives.

Build From Source

Required for the standard CPU source install:

• Git
• Rust 1.97 with Cargo (the checked-in toolchain file pins this version)
• C and C++ compilers, CMake, and Make or Ninja
• on Linux, pkg-config and OpenSSL development headers
• network access to download Rust crates and the pinned ONNX Runtime artifact

For example, install the native packages with:

# Fedora
sudo dnf install gcc gcc-c++ cmake make pkgconf-pkg-config openssl-devel

# Debian/Ubuntu
sudo apt install build-essential cmake pkg-config libssl-dev

These are build requirements, not runtime service dependencies. mise, just, ShellCheck, nextest, cargo-deny, and gitleaks are contributor/CI tools and are not required to install or run hold. CUDA, PostgreSQL/pgvector, and an OpenAI-compatible embedding endpoint are needed only when their corresponding optional features are used.

git clone https://github.com/gearboxlogic/localhold.git
cd localhold
./script/install.sh
export PATH="$HOME/.local/bin:$PATH"
hold

The standard install includes CPU reranker support, but reranking remains disabled until configured. See [Installation](docs/installation.md) for custom prefixes, macOS and Windows prerequisites, and the CUDA preview profile.

Configuration

LocalHold reads ~/.config/localhold/localhold.toml on Linux and the equivalent platform user-config directory elsewhere. It never loads config implicitly from the current working directory. Runtime overrides use LOCALHOLD_* environment variables. See [localhold.example.toml](localhold.example.toml) for the complete configuration surface.

The default provider is noop, which keeps search local and text-only. To use semantic search, configure an OpenAI-compatible /v1 endpoint:

[embedding]
provider = "openai_compatible"
dimensions = 768

[embedding.openai_compatible]
base_url = "http://127.0.0.1:8000/v1"
model = "nomic-embed-text"
# api_key = "..."

The endpoint must implement POST /embeddings beneath the configured base URL. The default startup check also requires GET /models; set health_check = "disabled" for providers that omit that route. vLLM, llama.cpp, Ollama, and hosted services can be used when they expose this contract. See [Embedding Providers](docs/embedding-providers.md) for cloud authentication, dimensions, health checks, and transport security.

LocalHold records the endpoint, model, and dimensions that produced stored vectors and refuses to mix a different vector space. To change any of them, preserve a backup and run hold embeddings reindex --yes; memory content and metadata are retained while vectors are rebuilt after the next start.

Reranking

Enable the built-in CPU reranker with:

[search.reranker]
enabled = true
execution_provider = "cpu"

The pinned model and tokenizer are downloaded on first use. For offline deployments, set model_path and provide the model files in advance.

CUDA reranking is a preview build surface:

just build-release-reranker-cuda

The CUDA-capable binary supports auto, cpu, and cuda. auto prefers CUDA after successful model inference and falls back visibly to CPU; cpu never registers CUDA; explicit cuda never falls back to a CPU session. ONNX Runtime may still place individual graph nodes on CPU. Set required = true when startup must fail unless reranking is active. CUDA requires a compatible NVIDIA driver and ONNX Runtime/CUDA libraries. It does not affect embedding placement; embedding compute happens at the selected OpenAI-compatible endpoint.

MCP Client Setup

Build the binary, then configure an MCP client to launch hold over stdio:

{
  "mcpServers": {
    "localhold": {
      "command": "/absolute/path/to/localhold/target/release/hold"
    }
  }
}

For clients with a command-based setup:

claude mcp add --scope user localhold /absolute/path/to/localhold/target/release/hold

The stdio server uses the configured server.principal as the trusted identity for that process. Run separate instances when clients require separate principals.

HTTP Transport

[server]
transport = "http"
host = "127.0.0.1"
port = 8080
path = "/mcp"
http_auth_token = "replace-with-a-secret"
http_principal_mode = "fixed"
http_principal = "http"
http_allowed_hosts = ["localhost", "127.0.0.1", "::1"]

The MCP endpoint is http://127.0.0.1:8080/mcp. HTTP requests never inherit the stdio principal. Without http_auth_token, requests are anonymous and the default policy allows public reads but denies writes.

The default fixed mode assigns every valid bearer token the configured http_principal; caller-supplied identity headers are ignored. For distinct caller identities, select trusted_proxy mode only behind an authenticating proxy that overwrites x-localhold-principal and prevents direct access to LocalHold.

Storage

SQLite is the default backend and stores data under ~/.local/share/localhold/localhold.db. Back up the database and its WAL files as a consistent set while the service is stopped or by using SQLite's backup facilities.

PostgreSQL is opt-in:

[database]
backend = "postgres"

[database.postgres]
url = "postgres://localhold:password@localhost:5432/localhold"

Check installation and runtime readiness without creating or migrating storage or downloading models:

hold doctor
hold doctor --json

See [Operations](docs/operations.md) for diagnostic exit codes and the explicit reranker download opt-in.

To migrate an existing SQLite database into an empty PostgreSQL database:

hold migrate sqlite-to-postgres \
  --sqlite ~/.local/share/localhold/localhold.db \
  --embedding-dimensions 768 \
  --dry-run

Review the dry run, then repeat with --yes. The destination must not already contain user data.

MCP Tools

The everyday API consists of brief, recall, read, read_many, remember, remember_many, handoff, revise, and forget. Maintenance and migration operations use explicit admin_* tools. Those privileged routes are removed from discovery and dispatch by default; operators must set server.admin_tools_enabled = true for a dedicated maintenance instance.

See [docs/agent-api.md](docs/agent-api.md) for tool semantics and [docs/architecture.md](docs/architecture.md) for the current system design. Operators should also read [Operations](docs/operations.md) and the [Compatibility Policy](docs/compatibility.md).

Development

./script/bootstrap.sh
just test
just check

just check runs formatting, clippy, dependency policy, and tests. Linux and Windows checks also run in GitHub Actions. Windows support is preview and is validated by CI rather than a machine-specific local clone.

Repository documentation must describe a current user, operator, contributor, architecture, or policy need. Task journals, review transcripts, historical audits, and completed implementation plans belong in issues or the private development archive, not this repository.

See [CONTRIBUTING.md](CONTRIBUTING.md) before opening a pull request and [SECURITY.md](SECURITY.md) for vulnerability reporting.

License

Copyright 2026 Gearbox Logic LLC.

Licensed under the [Apache License 2.0](LICENSE). The license does not grant rights to LocalHold or Gearbox Logic trademarks; see [TRADEMARKS.md](TRADEMARKS.md). Third-party components and models retain their respective licenses.

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: gearboxlogic
• Source: gearboxlogic/localhold
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.