手动配置

不使用安装脚本时，手动配置 Lore 服务器和 Agent 集成。

手动配置适合不想让安装脚本替你做所有选择的场景。比如：你要把 Lore 部署到远程主机、接入已有数据库，或只安装部分 Agent 集成。

你需要配置四层内容：

层级	配置什么	完成后得到什么
服务器	数据库 URL、可选认证 token、缓存和文件存储	Lore Web 启动，并提供 `/setup` 和 `/api/mcp`
运行时设置	Embedding、View LLM、启动记忆、召回、Dream 和备份	Lore 可以搜索、查看和维护记忆
共享客户端配置	本机 hooks 使用的服务器 URL 和 token	本机集成知道要连接哪个 Lore 服务器
Agent 运行时	原生插件或 MCP endpoint、环境变量和运行时专属 hooks	Agent 可以加载启动记忆并使用召回

原则很简单：服务器密钥放在服务器侧，Agent 专属配置放在 Agent 运行时。本地客户端配置不应该包含 DATABASE_URL；服务器 .env 也不应该塞进 Claude、Codex 或 OpenClaw 的 hook 设置。

开始前准备

你需要：

一台可以运行 Lore Web 的机器；
可用的 PostgreSQL，并支持 pgvector；可以用 Docker Compose 自带的，也可以用你自己的；
可选 Redis，用于共享缓存；
如果服务器不想裸露在网络中，准备一个 API token；
至少一个准备连接的 Agent 运行时。

用 Docker Compose 启动服务器

标准 Docker Compose 部署，在 docker-compose.yml 旁边创建 .env：

Plaintext

TZ=Asia/Shanghai

POSTGRES_DB=lore
POSTGRES_USER=lore
POSTGRES_PASSWORD=change-me
POSTGRES_PORT=55439
POSTGRES_DATA_DIR=./data/postgres

DATABASE_URL=postgresql://lore:change-me@postgres:5432/lore
WEB_PORT=18901
API_TOKEN=
LORE_DB_POOL_SIZE=10

REDIS_URL=redis://redis:6379/0
REDIS_DATA_DIR=./data/redis
CACHE_KEY_PREFIX=lore
CACHE_LOCAL_MAX_ITEMS=2000

SNAPSHOT_DATA_DIR=./data/snapshots

LORE_POSTGRES_IMAGE=fffattiger/pgvector-zhparser:pg16
LORE_REDIS_IMAGE=redis:7-alpine
LORE_FRONTEND_IMAGE=fffattiger/lore:latest

启动 Lore：

Shell

curl -fsSL https://raw.githubusercontent.com/FFatTiger/lore/main/docker-compose.yml -o docker-compose.yml
docker compose up -d
docker compose ps
curl -fsS http://127.0.0.1:18901/api/health

如果设置了 API_TOKEN，打开 Web Console、配置 MCP 和配置 hooks 时都使用同一个 token。

不使用自带 PostgreSQL

如果你已经维护 PostgreSQL，让 Lore Web 指向你的数据库：

Plaintext

DATABASE_URL=postgresql://lore:change-me@db.example.com:5432/lore
API_TOKEN=YOUR_SERVER_TOKEN_IF_USED
REDIS_URL=redis://redis.example.com:6379/0
CACHE_KEY_PREFIX=lore
CACHE_LOCAL_MAX_ITEMS=2000
LORE_DB_POOL_SIZE=10

首次启动时，数据库角色需要能创建 schema 和必要扩展。如果生产环境角色权限较低，可以先用有迁移权限的角色完成首次启动，再切换到受限角色。

启动 Lore（仍然用 Docker Compose 运行 Web 和 Redis 容器，指向外部数据库）：

Shell

curl -fsSL https://raw.githubusercontent.com/FFatTiger/lore/main/docker-compose.yml -o docker-compose.yml
# 在 docker-compose.yml 中删除或注释掉 postgres 服务块，
# 或者保持 DATABASE_URL 指向外部数据库即可。
docker compose up -d
docker compose ps
curl -fsS http://127.0.0.1:18901/api/health

Lore 还需要可写存储，用于备份和待审阅变更。Docker Compose 会通过 SNAPSHOT_DATA_DIR 提供这块存储；自定义部署时，请为容器镜像使用的存储路径挂载持久卷。

完成 `/setup`

服务器健康后打开：

Plaintext

http://127.0.0.1:18901/setup

按顺序完成：

Embedding setup — 选择 OpenAI-compatible embedding 端点。
View LLM setup — 选择 OpenAI-compatible chat、OpenAI Responses 或 Anthropic Messages。
Boot memory setup — 检查 Agent 会收到的启动记忆。
Final check — 确认设置完成后，再连接 Agent。

也可以通过 API 保存设置：

Shell

curl -fsS -X PUT http://127.0.0.1:18901/api/settings \
  -H 'content-type: application/json' \
  -H 'authorization: Bearer YOUR_SERVER_TOKEN_IF_USED' \
  --data '{
    "patch": {
      "embedding.provider": "openai_compatible",
      "embedding.base_url": "http://host.docker.internal:8090/v1",
      "embedding.api_key": "YOUR_EMBEDDING_KEY",
      "embedding.model": "text-embedding-3-small",
      "view_llm.provider": "openai_compatible",
      "view_llm.base_url": "http://host.docker.internal:8090/v1",
      "view_llm.api_key": "YOUR_LLM_KEY",
      "view_llm.model": "deepseek-v4-flash"
    }
  }'

只有服务器没有 API_TOKEN 时，才省略 authorization 头。

创建共享客户端配置

Claude Code、Codex、OpenCode 等本机 Lore 集成都可以读取同一个客户端配置。在运行 Agent 的机器上创建 ~/.lore/config.json：

JSON

{
  "base_url": "http://127.0.0.1:18901",
  "api_token": "YOUR_TOKEN_IF_USED",
  "docker_managed": false
}

规则：

base_url 是 Lore 服务器 origin，不带末尾斜杠；
服务器没有 API_TOKEN 时，省略 api_token；
自己管理服务器时，保持 docker_managed 为 false。

连接 Claude Code

Claude Code hooks 会读取共享的 ~/.lore/config.json。如果手动配置 Claude MCP，服务器启用 API_TOKEN 时用标准 bearer header 注册 HTTP endpoint：

Shell

claude mcp remove lore || true
claude mcp add --transport http --scope user \
  --header "Authorization: Bearer YOUR_TOKEN_IF_USED" \
  lore "http://127.0.0.1:18901/api/mcp?client_type=claudecode"

如果本地服务器未启用认证，省略 --header。

如果手动安装 Claude Code 插件，安装插件文件和 hooks 后重启 Claude Code。不要再把本地 guidance 复制进 CLAUDE.md；hooks 只负责把生命周期事件转发给 Lore server，并使用服务端返回的 host output。

Shell

git clone https://github.com/FFatTiger/lore.git /tmp/lore-plugin
# 按你的 Claude Code 插件安装方式复制或安装 claudecode-plugin 目录。
# 确认 hooks 调用 /api/lifecycle/event，并共用 ~/.lore/config.json。

插件具体路径可能随版本变化，请以 Lore 仓库中的实际布局为准。

修改 settings、插件文件或 CLAUDE.md 后，重启 Claude Code。

连接 Codex

在 ~/.codex/config.toml 启用插件和 hooks：

TOML

[plugins."lore@lore"]
enabled = true

[features]
hooks = true

无服务器认证时注册 MCP：

Shell

codex mcp remove lore || true
codex mcp add lore --url "http://127.0.0.1:18901/api/mcp?client_type=codex"

有服务器认证时注册 MCP，URL 保持纯净，把 bearer header 写进 ~/.codex/config.toml：

TOML

[mcp_servers.lore]
url = "http://127.0.0.1:18901/api/mcp?client_type=codex"
http_headers = { Authorization = "Bearer YOUR_TOKEN_IF_USED" }

如果需要启动记忆和每次 prompt 召回，从插件包安装 Codex hooks。Hooks 会读取 ~/.lore/config.json，不再需要额外 token 环境变量：

Shell

bash /tmp/lore-plugin/packages/codex-plugin/scripts/install-hooks.sh

重启 Codex，打开 /hooks，如果 Codex 要求确认，信任 Lore hooks。

连接 OpenCode

OpenCode 原生集成随 v1.3.15-pre.4 预发布，已用 OpenCode 1.18.3 验证。它读取上面的同一个 ~/.lore/config.json，并安装一个受管理文件：

Plaintext

~/.config/opencode/plugins/lore-memory.js

推荐使用预发布安装器：

Shell

npx @loremem/cli install --lang zh --pre --channels opencode

如需手动安装 lore-opencode.zip，如果目标路径已有未带管理标记的文件，必须保留它：

Shell

tmp_dir="$(mktemp -d)"
target="$HOME/.config/opencode/plugins/lore-memory.js"
curl -fL https://github.com/FFatTiger/lore/releases/download/v1.3.15-pre.4/lore-opencode.zip \
  -o "$tmp_dir/lore-opencode.zip"
unzip -q "$tmp_dir/lore-opencode.zip" -d "$tmp_dir/lore-opencode"
mkdir -p "$(dirname "$target")"
if [ -f "$target" ] && ! grep -q '@lore-managed-opencode-plugin' "$target"; then
  echo "拒绝覆盖未标记的 OpenCode 插件：$target" >&2
  exit 1
fi
install -m 0644 "$tmp_dir/lore-opencode/lore-memory.js" "$target"
rm -rf "$tmp_dir"

安装后重启 OpenCode。插件精确注册以下原生工具：

lore_guidance
lore_status
lore_boot
lore_get_node
lore_search
lore_list_domains
lore_create_node
lore_update_node
lore_delete_node
lore_move_node

Boot 通过 experimental.chat.system.transform 注入 system context，绝不会塞进用户消息。Prompt Recall 通过 chat.message 追加当前轮独立 text part。Lore 或实验性 system hook 不可用时，插件会警告并 fail open；原生工具仍可用，仅 system 注入不可用时 prompt Recall 仍会继续。

OpenCode 标准安装不会配置 /api/mcp。只有原生插件无法加载时，才把 /api/mcp?client_type=opencode 当作手动兜底；它不能复现原生生命周期行为。

手动安装 ZIP 不会自动执行这个兼容修改：如果 oh-my-openagent 或旧版 oh-my-opencode 会导入 Claude Code 插件，请在重启 OpenCode 前，向实际生效的用户级 JSON/JSONC 配置加入 claude_code.plugins_override["lore@lore"] = false。这会阻止重复 Claude Lore 生命周期 hooks；原生插件仍会在运行时删除重复 Lore MCP。不要修改 Claude Code 文件。若明确要让旧版兜底与原生 Lore 并存，请保留原兼容设置，并使用 LORE_OPENCODE_ALLOW_MCP=1 启动 OpenCode。

只卸载 OpenCode 集成时，使用 ownership-aware 卸载器。只有 lore-memory.js 带 Lore 管理标记时才会删除，未标记插件会被保留：

Shell

npx @loremem/cli uninstall --channels opencode -y

连接 OpenClaw

OpenClaw 使用 ~/.openclaw/openclaw.json 里的插件 entry：

JSON

{
  "plugins": {
    "entries": {
      "lore": {
        "enabled": true,
        "config": {
          "baseUrl": "http://127.0.0.1:18901",
          "apiToken": "YOUR_TOKEN_IF_USED",
          "timeoutMs": 30000,
          "defaultDomain": "core",
          "injectPromptGuidance": true,
          "startupHealthcheck": true,
          "recallEnabled": true,
          "minDisplayScore": 0.4,
          "maxDisplayItems": 3,
          "scorePrecision": 2,
          "excludeBootFromResults": true
        }
      }
    }
  }
}

编辑插件 entry 后重启 OpenClaw。

连接 Pi

把 Lore 扩展安装或 symlink 到 Pi 扩展目录。从克隆的 Lore 仓库执行：

Shell

PI_CODING_AGENT_DIR="$HOME/.pi/agent" bash /tmp/lore-plugin/packages/pi-extension/scripts/install-local.sh

Pi 默认读取 ~/.lore/config.json。如果 Pi 运行时支持扩展配置，只在需要单独覆盖该运行时时使用：

JSON

{
  "baseUrl": "http://127.0.0.1:18901",
  "apiToken": "YOUR_TOKEN_IF_USED",
  "timeoutMs": 30000,
  "defaultDomain": "core",
  "injectPromptGuidance": true,
  "startupHealthcheck": true,
  "recallEnabled": true
}

在 Pi 内运行 /reload，或重启运行时。

连接 Hermes

Hermes 从 ~/.lore/config.json 读取 Lore 服务器和 token：

JSON

{
  "base_url": "http://127.0.0.1:18901",
  "api_token": "YOUR_TOKEN_IF_USED"
}

LORE_BASE_URL 和 LORE_API_TOKEN 保留为旧配置的兜底环境变量。

然后把插件包链接到 Hermes 插件目录。从克隆的 Lore 仓库执行：

Shell

mkdir -p ~/.hermes/skills
ln -s /tmp/lore-plugin/packages/hermes-plugin/lore_memory ~/.hermes/skills/lore_memory

链接插件后重启 Hermes。

验证结果

把真实指令迁移进 Lore 前，先检查：

curl -fsS http://127.0.0.1:18901/api/health 返回成功。
/setup 显示 embedding、View LLM 和 boot memory 已完成。
基于 MCP 的 Agent URL 包含正确的 client_type；OpenCode 使用原生插件。
受保护服务器能从 Web UI、MCP、hooks 和 OpenCode 插件收到同一个 bearer token。
新 Agent 会话能看到启动上下文。OpenCode 通过 lore_boot 确认 core://agent/opencode。
真实项目 prompt 会产生召回块；OpenCode 的实验性 system 注入不可用时，这项仍应工作。
能在 Web Console 打开召回到的记忆节点。

快速安装使用安装器通过 Docker 启动 Lore，或把客户端连接到已有的 Lore 服务器。使用自己的 PostgreSQL让 Lore 连接已有 PostgreSQL 实例，并配置 pgvector 与可选中文全文搜索扩展。首次运行设置打开 /setup，配置模型端点，初始化启动记忆，并重启已连接的运行时。关键设置配置日常运行需要的服务器认证、Embedding、View LLM、Redis 缓存和备份默认值。

开始前准备

用 Docker Compose 启动服务器

不使用自带 PostgreSQL

完成 /setup

创建共享客户端配置

连接 Claude Code

连接 Codex

连接 OpenCode

连接 OpenClaw

连接 Pi

连接 Hermes

验证结果

完成 `/setup`