内容
# 本地持久化
[](https://github.com/gearboxlogic/localhold/actions/workflows/ci.yml)
[](https://github.com/gearboxlogic/localhold/actions/workflows/outdated.yml)
**可搜索的上下文，始终属于您。**
本地持久化是用于人工智能代理的本地上下文基础设施。它作为一个独立的[模型上下文协议](https://modelcontextprotocol.io/)服务器运行，并保持持久的、可搜索的内存，独立于任何一个代理或模型提供商。
本地持久化处于早期测试阶段。Linux CPU 是主要支持的环境。Windows、PostgreSQL 和 CUDA 重排序是预览功能。
## 它提供了什么
- 默认使用 SQLite 存储，支持可选的 PostgreSQL 和 `pgvector`
- 通过 stdio 或可流式 HTTP 提供 MCP
- 支持关键词、语义、混合和文本回退搜索
- 兼容 OpenAI 的嵌入端点，包括本地和云提供商
- 可选的 ONNX 跨编码器重排序，支持 CPU 或 CUDA
- 作用域记忆、访问策略、审计历史和维护工具
默认情况下，存储是本地的。当启用外部嵌入提供程序时，内存内容和搜索查询将被发送到配置的端点。本地持久化不会启动或管理模型服务器。
## 安装发行版
GitHub 预发布版本提供了 Linux x86_64 CPU 存档和 Windows x86_64 预览存档。每个存档都包含 `hold`、示例配置、当前文档和许可证通知。在解压存档之前，请使用附带的 `SHA256SUMS` 文件验证下载的存档。有关存档布局和命令，请参阅[安装](docs/installation.md)。
CUDA 重排序仍然是一个源代码构建预览版，不包含在二进制存档中。
## 从源代码构建
标准 CPU 源代码安装所需：
- Git
- Rust 1.97 with Cargo（检查的工具链文件固定了此版本）
- C 和 C++ 编译器，CMake 和 Make 或 Ninja
- 在 Linux 上，`pkg-config` 和 OpenSSL 开发头文件
- 网络访问以下载 Rust crates 和固定的 ONNX Runtime 工件
例如，使用以下命令安装原生软件包：
```sh
# 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
```
这些是构建需求，而不是运行时服务依赖项。`mise`、`just`、`ShellCheck`、`nextest`、`cargo-deny` 和 `gitleaks` 是贡献者/CI 工具，不需要安装或运行 `hold`。CUDA、PostgreSQL/pgvector 和兼容 OpenAI 的嵌入端点仅在需要其对应可选功能时才需要。
```sh
git clone https://github.com/gearboxlogic/localhold.git
cd localhold
./script/install.sh
export PATH="$HOME/.local/bin:$PATH"
hold
```
标准安装包括 CPU 重排序支持，但在配置之前，重排序功能处于禁用状态。有关自定义前缀、macOS 和 Windows 先决条件以及 CUDA 预览配置文件，请参阅[安装](docs/installation.md)。
## 配置
本地持久化读取 `~/.config/localhold/localhold.toml`（在 Linux 上）或等效的平台用户配置目录（在其他平台上）。它从不隐式加载当前工作目录中的配置文件。运行时覆盖使用 `LOCALHOLD_*` 环境变量。有关完整的配置界面，请参阅 [localhold.example.toml](localhold.example.toml)。
默认提供程序是 `noop`，它保持搜索本地且仅限文本。要使用语义搜索，请配置兼容 OpenAI 的 `/v1` 端点：
```toml
[embedding]
provider = "openai_compatible"
dimensions = 768
[embedding.openai_compatible]
base_url = "http://127.0.0.1:8000/v1"
model = "nomic-embed-text"
# api_key = "..."
```
端点必须在配置的基准 URL 下实现 `POST /embeddings`。默认启动检查还要求 `GET /models`；对于省略此路由的提供程序，请设置 `health_check = "disabled"`。vLLM、llama.cpp、Ollama 和托管服务可以在它们公开此合约时使用。有关云身份验证、维度、健康检查和传输安全性，请参阅[嵌入提供程序](docs/embedding-providers.md)。
本地持久化记录生成存储向量所使用的端点、模型和维度，并拒绝混合不同的向量空间。要更改其中任何一个，请保留备份并运行 `hold embeddings reindex --yes`；在下一次启动后，内存内容和元数据将被保留，同时向量将被重建。
### 重排序
通过以下方式启用内置 CPU 重排序：
```toml
[search.reranker]
enabled = true
```
固定的模型和分词器将在首次使用时下载。对于离线部署，请设置 `model_path` 并提前提供模型文件。
CUDA 重排序是一个预览构建表面：
```sh
just build-release-reranker-cuda
```
它需要兼容的 NVIDIA 驱动程序和 ONNX Runtime/CUDA 库。CUDA 不会影响嵌入放置；嵌入计算发生在所选的兼容 OpenAI 的端点。
## MCP 客户端设置
构建二进制文件，然后配置 MCP 客户端通过 stdio 启动 `hold`：
```json
{
"mcpServers": {
"localhold": {
"command": "/absolute/path/to/localhold/target/release/hold"
}
}
}
```
对于基于命令的客户端设置：
```sh
claude mcp add --scope user localhold /absolute/path/to/localhold/target/release/hold
```
stdio 服务器使用配置的 `server.principal` 作为该进程的受信任身份。运行单独的实例时，客户端需要单独的身份。
### HTTP 传输
```toml
[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"]
```
MCP 端点是 `http://127.0.0.1:8080/mcp`。HTTP 请求永远不会继承 stdio 身份。没有 `http_auth_token`，请求是匿名的，默认策略允许公共读取但拒绝写入。
默认 `fixed` 模式为每个有效持有者令牌分配配置的 `http_principal`；调用者提供的身份标头将被忽略。对于不同的调用者身份，请在身份验证代理后面选择 `trusted_proxy` 模式，该代理会覆盖 `x-localhold-principal` 并阻止直接访问本地持久化。
## 存储
SQLite 是默认后端，存储数据在 `~/.local/share/localhold/localhold.db` 下。请备份数据库及其 WAL 文件作为一致的集合，同时停止服务或使用 SQLite 的备份设施。
PostgreSQL 是可选的：
```toml
[database]
backend = "postgres"
[database.postgres]
url = "postgres://localhold:password@localhost:5432/localhold"
```
将现有 SQLite 数据库迁移到空 PostgreSQL 数据库：
```sh
hold migrate sqlite-to-postgres \
--sqlite ~/.local/share/localhold/localhold.db \
--embedding-dimensions 768 \
--dry-run
```
审查干运行，然后重复执行 `--yes` 命令。目标必须不包含用户数据。
## MCP 工具
日常 API 由 `brief`、`recall`、`read`、`read_many`、`remember`、`remember_many`、`handoff`、`revise` 和 `forget` 组成。维护和迁移操作使用显式的 `admin_*` 工具。默认情况下，这些特权路由已从发现和调度中删除；操作员必须为专用维护实例设置 `server.admin_tools_enabled = true`。
有关工具语义，请参阅 [docs/agent-api-v2.md](docs/agent-api-v2.md)，有关当前系统设计，请参阅 [docs/architecture.md](docs/architecture.md)。操作员还应阅读[操作](docs/operations.md)和[兼容性政策](docs/compatibility.md)。
## 开发
```sh
./script/bootstrap.sh
just test
just check
```
`just check` 运行格式化、clippy、依赖项策略和测试。Linux 和 Windows 检查也在 GitHub Actions 中运行。Windows 支持是预览版，通过 CI 验证，而不是通过特定于机器的本地克隆验证。
存储库文档必须描述当前用户、操作员、贡献者、架构或策略需求。任务日志、审查记录、历史审计和已完成的实施计划应放在问题或私有开发存档中，而不是此存储库中。
在打开拉取请求之前，请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)，并在报告漏洞时参阅 [SECURITY.md](SECURITY.md)。
## 许可证
2026 Gearbox Logic LLC 版权所有。
在 [Apache License 2.0](LICENSE) 下许可。许可证不授予本地持久化或 Gearbox Logic 商标的权利；请参阅 [TRademarks.md](TRademarks.md)。第三方组件和模型保留其各自的许可证。
