返回主页

Opencode × Hy-Memory · 安装指南

为 Opencode 接入
Hy-Memory 长期记忆

对话自动召回、自动写回，外加可显式调用的记忆工具。

Step 01

环境前置

前置要求检查
opencode≥ 1.16opencode --version
bun已安装bun --version
Python≥ 3.8（起后端 server 用）python3 --version
LLM API Keypro / ultra 模式必需见第 4.1
Embedder API Key所有模式必需见第 4.1
opencode 主模型已配好可用的 provider/modelopencode models

关于 Key

DeepSeek 等部分厂商无 embedding 服务；即使 LLM 用 DeepSeek，Embedder 仍需 OpenAI（或其他带 embedding 的厂商）。
Step 02

安装

三步：bunx 跑向导写完整配置 → 启动 opencode 让插件加载并自起 server → 跑 doctor 体检。bunx 会自动从 npm registry 拉取插件，无需预装、也不必手编辑 opencode.json。

Step 1 · 跑交互式向导写入完整配置

bash
bunx opencode-hy-memory init

4 步向导（LLM → Embedder → 向量库 → mode/userId）会把完整 plugin 块写入 opencode.json（项目级 ./opencode.json 优先，否则全局 ~/.config/opencode/opencode.json）。

Step 2 · 启动 / 重启 opencode（插件加载并自起 server）

bash
opencode      # 首次会自动建 venv 起 server（默认端口 19527），约 1～3 分钟

日志出现 server listening 即就绪。必须先让 opencode 把 server 拉起来，下一步 doctor 才能拿到 healthz。

Step 3 · 体检

bash
bunx opencode-hy-memory doctor

期望 All good（plugin entry / userId / server healthz / search round-trip）。

也可以全手动（不跑 init）

若不想用向导，可直接在 opencode.json 里手写完整 plugin 参数（含 LLM/Embedder/向量库），然后启动 opencode 即可。完整配置示例：
json
{
  "$schema": "https://opencode.ai/config.json",
  "plugin": [
    ["opencode-hy-memory", {
      "userId": "alice",
      "mode": "pro",
      "llm": { "provider": "openai", "model": "gpt-4o-mini", "apiKey": "sk-..." },
      "embedder": { "provider": "openai", "model": "text-embedding-3-small", "apiKey": "sk-..." }
    }]
  ]
}

验证 server 健康

bash
curl -s http://127.0.0.1:19527/healthz      # 期望 ✅ {"status":"ok"}
Step 03

配置

配置位于 opencode.json 的 plugin 块中（向导会自动写入）。项目级优先读 ./opencode.json，否则读 ~/.config/opencode/opencode.json。所有选项都可省略，缺省时按"plugin 参数 → 环境变量 → 默认值"回退。

选项环境变量默认说明
userIdHY_MEMORY_USER_ID系统用户名一级隔离（命名空间）
agentIdHY_MEMORY_AGENT_IDopencode二级隔离
sessionIdHY_MEMORY_SESSION_IDdefault_session三级隔离
modeHY_MEMORY_MODEprolite / pro / ultra
serverUrlHY_MEMORY_SERVER_URLhttp://127.0.0.1:<port>复用外部 server 的关键
serverPortHY_MEMORY_SERVER_PORT19527端口（与 OpenClaw 共享）
autoStartServer—true无可用 server 时自动建 venv 并起 server
autoRecall—true被动召回开关
autoCapture—true被动写回开关
memoryWriteTurnWindowHY_MEMORY_WRITE_TURN_WINDOW5写回节流：攒 N 轮写一次
topKHY_MEMORY_TOP_K5最多召回条数
searchThresholdHY_MEMORY_SEARCH_THRESHOLD0.3最低召回分（利于跨语言/一句多问召回）
pythonPathHY_MEMORY_PYTHONpython3仅自起 server 时用

LLM / Embedder 配置位置

插件自起 server 时，LLM / Embedder / 向量库配置从 plugin 块的llm /embedder /vectorStore字段透传给 server 环境变量（见安装章节方式 B 示例）。

处理模式（mode）

lite

纯向量（不调 LLM），最快，仅向量相似度

pro（默认）

LLM 事实/身份抽取 + 整合演化，profile + fact 分层

ultra

pro + System2 异步认知，最全 + 跨域归纳 + 主动意图

Step 04

验证

6.1 doctor 体检

bash
bunx opencode-hy-memory doctor

期望 All good（plugin entry / userId / server healthz / search round-trip）。

doctor 的绿 ≠ 插件在 opencode 内真生效

doctor 走独立 bin，不经过 opencode 的插件加载，也不读 opencode.json 里的 plugin 参数。它能确认 server 连得通，但不能证明插件被 opencode 正确装载。请以 6.2 为准。

6.2 加载检查

bash
script -qec "opencode run --print-logs --log-level DEBUG 'hi'" /dev/null 2>&1 \
  | grep -E "no server entrypoint|memory_"

期望：没有 no server entrypoint 告警；且能看到 memory_search/add/delete/list 注册。

若看到 'does not expose a server entrypoint'

说明装到的是带 P0 的公网旧版（如 0.1.1），需升级到 ≥ 0.1.13（建议直接 @latest，bunx 默认即拉最新）。
Step 05

常见故障排查

现象原因解决
日志 'does not expose a server entrypoint'插件版本太旧（< 0.1.13，自起逻辑未修复）升级：bunx opencode-hy-memory@latest init（或在 opencode.json 里把插件标记为 @latest）
server 自起失败、记忆全 no-opPython 版本太低 / 网络不通无法 pip install确认 Python ≥ 3.8；检查网络可访问 pypi.org
doctor 全绿但记忆不工作doctor 不经 opencode 加载以 6.2 加载检查为准
opencode run 卡住无输出无 TTY（opencode 上游问题）用 script -qec ... /dev/null 包一层
主模型只 step_start 无回复文本个别兼容端点流式问题不影响记忆链路；可换主模型
复用的 server 召回/写入异常复用了别人那台、Key 已失效确认 server 端 Key/配置
curl /healthz 不通server 没起 / 端口不符回 4.1 确认 server 在跑
召回为空lite 模式 / 无相关记忆 / query 太短用 pro；先确认已写入；跨语言召回可调低 searchThreshold
Step 06

卸载 / 回滚

bash
# 1) 从 opencode.json 移除 plugin 块（删掉 "opencode-hy-memory" 那一项）

# 2) 重启 opencode（不再加载插件）

# 3) 清理 HY Memory 主目录（可选，含 venv 与默认数据目录）
rm -rf ~/.hy-memory/
#    0.1.14 起 venv / ChromaDB 等都统一到 ~/.hy-memory/ 下；
#    若你显式设了 MEMORY_PERSIST_DIR，则记忆数据在该自定义路径里。
Step 07

CLI 速查

命令作用
bunx opencode-hy-memory init交互式向导，写 plugin 块到 opencode.json
bunx opencode-hy-memory doctor连通性体检（注意局限，见 6.1）
python -m hy_memory.server --port 19527启动后端 server（公网 hy-memory SDK）
curl http://127.0.0.1:19527/healthz探活后端 server

各触发的正确日志特征

触发日志
插件装载service=plugin path=opencode-hy-memory loading plugin
server 自起[opencode-hy-memory] ... server listening ...
server 复用[opencode-hy-memory] reusing existing HY Memory server at ...
工具注册service=tool.registry status=completed memory_{search,add,delete,list}
召回命中[opencode-hy-memory] recall: injected N memory item(s) for "..."
被动写回[opencode-hy-memory] captured N messages from session ...