前置要求

本插件使用嵌入式 Turso（@tursodatabase/database），配合 F32_BLOB 向量与通过 vector_distance_cos 的精确余弦搜索。无需单独的向量数据库或自定义 SQLite 构建。

推荐运行时：

• Bun
• 标准 OpenCode 插件环境
• 若使用默认本地嵌入模型，首次使用时需要联网，因为模型由 @huggingface/transformers 下载。
• 对于源码/开发安装，请在构建或测试前运行 bun install。已发布的插件包会通过 OpenCode 自动安装其运行时依赖。

CI 已测试平台： Linux、Windows，以及 Apple Silicon 上的 macOS 15 / macOS 26（darwin/arm64）。不支持 Intel Mac（darwin/x64） — @tursodatabase/database 与固定版本的 onnxruntime-node 发行版均不提供 x64 原生绑定。更旧的 macOS 版本并未被该矩阵排除；它们只是不在当前 GitHub 托管的 runner 集合内。

说明：

• 向量嵌入直接存储并在 Turso 中搜索；插入时以 F32_BLOB 向量存储，用于精确余弦排序。
• 向量搜索通过 vector_distance_cos 使用精确余弦距离（无 DiskANN / 近似索引）；在提供查询字符串时可选用关键词混合排序（@tursodatabase/database 不附带 FTS5）。
• 会话查找使用已索引的 session_id 列（在 schema v2 上从 metadata.sessionID 回填）。
• 自动捕获与用户画像学习需要能返回结构化/工具调用输出的 AI 提供商。即使未配置自动捕获提供商，记忆的搜索/添加/列表仍可正常工作。

硬件 / 资源预期

opencode-mem 不需要 GPU。本地嵌入通过 @huggingface/transformers 与 ONNX 在 CPU 上运行（没有 MLX 后端）。不需要额外的 VRAM。

工作负载	典型额外资源
本地嵌入（默认 Xenova/nomic-embed-text-v1）	模型加载期间约 0.5–2 GB RAM，取决于所选 Hugging Face id。首次使用会下载模型；磁盘缓存在 {storagePath}/.cache（默认 ~/.opencode-mem/data/.cache），每个模型通常为 数百 MB 至约 1–2 GB。
远程嵌入（embeddingApiUrl + embeddingApiKey）	本地 ML RAM 可忽略不计 — 仅有插件 + Turso 开销。
数据库 / 插件	Turso/libSQL 存储在 storagePath 下的磁盘上。体积随存储的记忆数量增长，与 GPU 内存无关。

上述平台限制仍适用（不支持 Intel Mac darwin/x64；请使用 Apple Silicon、Linux、Windows，或远程嵌入端点）。参见选择 / 配置嵌入模型。