快速开始：安装与配置
学完你能做什么
在本课中，你将学会：
- 将 opencode-supermemory 插件安装到你的 OpenCode 环境中。
- 配置 Supermemory API Key，打通云端记忆库。
- 验证插件是否成功加载。
- 解决与其他插件（如 Oh My OpenCode）的潜在冲突。
完成后，你的 Agent 将具备连接云端记忆库的基础能力。
你现在的困境
你可能已经发现，OpenCode 的 Agent 虽然聪明，但它很健忘：
- 每次开启新会话，它都像失忆了一样，不记得你之前的偏好。
- 你在项目 A 里教过它的架构规范，到了项目 B 它又忘了。
- 长时间的会话聊着聊着，前面的关键信息就被"挤"出了上下文。
你需要一个外挂大脑，帮 Agent 记住这些东西。
什么时候用这一招
- 第一次使用：当你刚接触 opencode-supermemory 时。
- 重装环境：当你迁移到新电脑或重置了 OpenCode 配置时。
- 排查问题：当你怀疑插件没装好，或者 API 连接有问题时。
🎒 开始前的准备
在开始之前，请确保你已经：
- 安装了 OpenCode：确保
opencode命令在终端可用。 - 获取了 API Key：
- 访问 Supermemory Console
- 注册/登录账号
- 创建一个新的 API Key（以
sm_开头）
什么是 Supermemory？
Supermemory 是一个专门为 AI Agent 设计的云端记忆层。它不仅能存储数据，还能通过语义搜索帮 Agent 在对的时间想起对的事情。
核心思路
安装过程非常简单，本质上就是三步走：
- 安装插件：运行安装脚本，注册插件到 OpenCode。
- 配置密钥：告诉插件你的 API Key 是什么。
- 验证连接：重启 OpenCode，确认 Agent 能看到新工具。
跟我做
第 1 步：安装插件
我们提供了两种安装方式，选择适合你的一种。
# 推荐：会有交互式引导，帮你自动处理配置
bunx opencode-supermemory@latest install# 如果你是让 Agent 帮你安装，请用这个命令（跳过交互确认并自动解决冲突）
bunx opencode-supermemory@latest install --no-tui --disable-context-recovery你应该看到： 终端输出 ✓ Setup complete!，表示插件已成功注册到 ~/.config/opencode/opencode.jsonc。
第 2 步：配置 API Key
插件需要 API Key 才能读写你的云端记忆。你有两种配置方式：
方式 A：环境变量（推荐）
直接在你的 Shell 配置文件（如 .zshrc 或 .bashrc）中添加：
export SUPERMEMORY_API_KEY="sm_你的密钥..."方式 B：配置文件
或者，创建一个专门的配置文件 ~/.config/opencode/supermemory.jsonc：
{
"apiKey": "sm_你的密钥..."
}为什么：环境变量更安全，且不会意外提交到代码仓库；配置文件则更方便管理多项设置。
第 3 步：解决冲突（如果你用了 Oh My OpenCode）
如果你安装了 Oh My OpenCode，它自带的上下文管理功能可能会与 Supermemory 冲突。
检查方法： 安装脚本通常会自动检测并提示你禁用冲突的钩子。如果没有，请手动检查 ~/.config/opencode/oh-my-opencode.json：
{
"disabled_hooks": [
"anthropic-context-window-limit-recovery" // ✅ 确保这一行存在
]
}为什么：Supermemory 提供了更智能的"抢占式压缩"（Preemptive Compaction），如果两个插件同时尝试管理上下文，会导致混乱。
第 4 步：验证安装
重启 OpenCode，然后运行检查命令：
opencode -c或者直接进入 OpenCode 交互模式，查看工具列表。
你应该看到： 在工具列表（Tools）中，出现了 supermemory 工具。
Available Tools:
- supermemory (add, search, profile, list, forget)
...检查点 ✅
请自检以下项目，确保一切就绪：
- [ ] 运行
cat ~/.config/opencode/opencode.jsonc，能看到"opencode-supermemory"在plugin列表中。 - [ ] 环境变量
SUPERMEMORY_API_KEY已生效（可以用echo $SUPERMEMORY_API_KEY检查）。 - [ ] 运行
opencode后，Agent 没有报错提示。
踩坑提醒
常见错误：API Key 没生效
如果你设置了环境变量但插件提示未认证，请检查：
- 你是否重启了终端？（修改
.zshrc后需要source ~/.zshrc或重启） - 你是否重启了 OpenCode？（OpenCode 进程需要重启才能读取新变量）
常见错误：JSON 格式错误
如果你手动修改 opencode.jsonc，请确保 JSON 格式正确（特别是逗号）。安装脚本会自动处理这个，但手动修改容易出错。
本课小结
恭喜！你已经成功给 OpenCode 装上了"海马体"。现在，你的 Agent 已经准备好开始记忆了。
- 我们安装了
opencode-supermemory插件。 - 我们配置了云端连接凭证。
- 我们排除了潜在的插件冲突。
下一课预告
下一课我们学习 项目初始化：建立第一印象。
你会学到：
- 如何用一条命令让 Agent 深度扫描整个项目。
- 如何让 Agent 记住项目的架构、技术栈和隐性规则。
- 如何查看 Agent 到底记住了什么。
附录：源码参考
点击展开查看源码位置
更新时间：2026-01-23
| 功能 | 文件路径 | 行号 |
|---|---|---|
| 安装脚本逻辑 | src/cli.ts | 327-410 |
| 插件注册逻辑 | src/cli.ts | 195-248 |
| 冲突检测逻辑 | src/cli.ts | 273-320 |
| 配置文件加载 | src/config.ts | - |