opencode-hy-memory

HY Memory plugin for opencode — passive memory injection + active memory tools, backed by the HY Memory Python server over HTTP.

No manual pip install or server start. On first use the plugin creates a managed Python environment, installs the public hy-memory SDK from PyPI, and starts (or reuses) the server automatically.

What it does

• Passive recall — before every LLM call, searches HY Memory for the current user query and injects hits into the system prompt (experimental.chat.system.transform).
• Passive capture — when a session goes idle (event: session.idle), writes the turn back to HY Memory asynchronously.
• Active tools — memory_search, memory_add, memory_delete, memory_list for explicit memory management.

Quick start

bunx opencode-hy-memory init

Interactive 4-step wizard (LLM → embedder → vector store → mode/userId) writes the plugin block into your opencode.json (project ./opencode.json if present, else ~/.config/opencode/opencode.json).

Verify everything (creates venv, installs SDK, starts server if needed):

bunx opencode-hy-memory doctor

Restart opencode — memory is live.

On-disk layout

All HY Memory data for this plugin lives under one home directory:

~/.hy-memory/
├── .venv/          Python + hy-memory SDK (auto-managed)
├── db/             vector DB, graph, cache, logs (MEMORY_DATA_DIR)
└── config.json     last init/doctor snapshot (reference)

• 数据目录：~/.hy-memory/db/（旧版默认 ~/.hy_memory/ 若已存在会继续使用）
• 配置快照：~/.hy-memory/config.json

Override the root with HY_MEMORY_HOME. PyPI mirror: HY_MEMORY_PYPI_INDEX_URL (default https://pypi.org/simple).

Architecture

opencode (Bun/TS)
  └── opencode-hy-memory
        ├── ~/.hy-memory/.venv/   (auto pip install + upgrade)
        └── HTTP ──► HY Memory server  (python -m hy_memory.server)
                          └── ~/.hy-memory/db/

Server reuse

On startup the plugin calls GET /healthz on port 19527 (default, shared with OpenClaw):

• healthy → reuse that server; never spawn a second one or kill it on dispose;
• not healthy → create venv (if needed), install/upgrade SDK, spawn server.

Multiple clients (opencode, OpenClaw, another session) can share one server when they use the same port.

Configuration

Add to opencode.json (or use init):

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": [
    ["opencode-hy-memory", { "userId": "alice", "mode": "pro" }]
  ]
}

| Option | Env | Default | Meaning | |---|---|---|---| | userId | HY_MEMORY_USER_ID | system username | Memory namespace | | agentId | HY_MEMORY_AGENT_ID | opencode | Agent isolation | | mode | HY_MEMORY_MODE | pro | lite / pro / ultra | | serverPort | HY_MEMORY_SERVER_PORT | 19527 | Server port | | serverUrl | HY_MEMORY_SERVER_URL | http://127.0.0.1:<port> | Full URL override | | autoRecall / autoCapture | — | true | Passive hooks | | pythonPath | HY_MEMORY_PYTHON | python3 | python3/python = auto venv at ~/.hy-memory/.venv | | autoStartServer | — | true | Spawn server if none reachable | | llm / embedder / vectorStore | — | — | Passed to server env when we spawn |

pro/ultra need LLM + embedder keys in the plugin config (or server env). lite is vector-only and needs an embedder.

Example: pro mode with OpenAI

{
  "plugin": [
    ["opencode-hy-memory", {
      "userId": "alice",
      "mode": "pro",
      "llm": { "provider": "openai", "model": "gpt-4.1-nano", "apiKey": "sk-..." },
      "embedder": { "provider": "openai", "model": "text-embedding-3-small", "apiKey": "sk-..." }
    }]
  ]
}

Fail-safe

Hooks swallow errors: if the server is down, passive recall/capture no-op and tools return an error string — opencode itself is never blocked.

Development

cd plugins/native/opencode
bun install
bun run typecheck
bun test
bun run build