Localhold

CI CodeRabbit Pull Request Reviews Release License

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

The mark on the banner is a keep with its door standing open. There is no lock on the hold, because there is no lock-in: memories live in a plain SQLite file you can read, back up, migrate, or walk away with. Every agent you run can remember into the same store and recall from it later, and the record stays yours.

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

What It Provides

• one durable store shared by every agent: multi-context memories, access policies, audit history, and maintenance tools
• keyword, semantic, hybrid, and text fallback search
• MCP over stdio or streamable HTTP
• SQLite storage by default, with optional PostgreSQL and pgvector
• OpenAI-compatible embedding endpoints — local servers such as vLLM, llama.cpp, and Ollama, or cloud providers
• optional ONNX cross-encoder reranking on CPU or CUDA
• hold ui, a terminal browser over everything the store holds

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. Review the security, privacy, and threat model before using network storage, HTTP transport, or external compute.

Quickstart

Install a release archive — Linux x86_64 CPU and CUDA 12, plus a Windows x86_64 preview — or build from source:

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

Then point an MCP client at the binary over stdio:

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

For clients with a command-based setup:

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

That is the whole setup. Out of the box search is keyword and text only — fully local, no model servers, nothing to download. Configure an embedding endpoint later for semantic search. See Installation for prerequisites, archive verification, and client details.

Browse The Hold

hold ui opens an interactive terminal browser over the store: multi-select contexts grouped by kind in the left pane; search mode cycling across keyword, text, semantic, hybrid, and auto; memory context editing; and an operator Context Manager for definitions, hierarchy, grants, lifecycle, and policy. Auto chooses the best available retrieval fallback. Browsing is side-effect-free; edits and administrative changes go through audited authorization paths.

The recording uses an explicitly selected hybrid browse mode before switching to keyword search, then opens the selected memory's detail view.

See Browse The Hold for navigation and editing keys.

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. hold config init creates a starter file, and hold config validate checks the effective settings without opening storage. See localhold.example.toml for the complete configuration surface.

To enable 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"

To enable the built-in cross-encoder reranker:

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

LocalHold records the vector space that produced stored embeddings and refuses to mix a different one; hold embeddings reindex --yes rebuilds vectors after a provider change. See Embedding Providers for authentication, health checks, and transport security, and Operations for reranker artifacts, execution providers, precision, and HTTP deployment.

Storage

SQLite is the default backend, stored under ~/.local/share/localhold/localhold.db. hold backup and hold restore provide WAL-consistent online backups with validation, and hold doctor checks installation and runtime readiness. PostgreSQL is opt-in, and hold migrate sqlite-to-postgres moves an existing store across. See Operations for backup, restore, migration, and diagnostics.

MCP Tools

The everyday API consists of brief, context_resolve, context_create, recall, read, read_many, remember, remember_many, handoff, revise, and forget. Governed writes require a resolvable context, a policy default, or explicit unresolved deferral. Maintenance and migration operations use explicit admin_* tools, which are removed from discovery and dispatch unless an operator enables them for a dedicated maintenance instance.

See Agent API for tool semantics, Architecture for the system design, Operations for running LocalHold, and the Compatibility Policy for what upgrades preserve. The Security, Privacy, And Threat Model maps stored data, network paths, identities, and operator-owned controls.

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. See CONTRIBUTING.md before opening a pull request and SECURITY.md for vulnerability reporting.

License

Copyright 2026 Gearbox Logic LLC.

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