跳转到内容
KN郑某某

输入关键词搜索…

↑↓ 导航
Esc

在 OpenCode 中使用 agentmemory 实现 AI 代理持久记忆

手把手教你为 OpenCode 配置 agentmemory，让 AI 代理拥有跨会话的持久化记忆能力，涵盖完整服务器和 Standalone 两种模式。

AI 2 分钟阅读

AI 编程工具的问题在于：每次新会话，它都不记得之前做过什么。agentmemory 解决了这个问题——它通过 MCP 协议为 OpenCode 提供跨会话的持久化记忆。

agentmemory 是一个开源的记忆层，通过 MCP（Model Context Protocol） 为 AI 代理提供持久化记忆功能。它能自动捕获会话中的关键信息，包括代码修改、决策记录、错误处理经验等，并在后续会话中自动召回。

两种运行模式：

模式特点适用场景
完整服务器模式53 个 MCP 工具，混合搜索，自动捕获日常开发、团队协作
Standalone 模式7 个核心工具，无需服务器，即开即用快速体验、轻量使用

  • 已安装 Node.js（v18+）
  • 已安装 OpenCode
  • （完整服务器模式）项目目录中有 agentmemory-main/ 源码

适合日常开发，功能最全。

Terminal window
# 方式 1：使用启动脚本
start.bat


# 方式 2：直接运行
npx @agentmemory/agentmemory

服务器默认运行在 http://localhost:3111。验证服务状态：

Terminal window
curl http://localhost:3111/agentmemory/health

编辑 OpenCode 配置文件：

  • 全局配置：~/.config/opencode/opencode.json
  • 项目配置：.opencode/opencode.json（项目根目录）
{
  "mcp": {
    "agentmemory": {
      "type": "local",
      "command": ["npx", "-y", "@agentmemory/mcp"],
      "env": {
        "AGENTMEMORY_URL": "http://localhost:3111"
      },
      "enabled": true
    }
  }
}

Terminal window
mkdir -p ~/.config/opencode/plugins
cp agentmemory-main/plugin/opencode/agentmemory-capture.ts ~/.config/opencode/plugins/

在 opencode.json 中启用插件：

{
  "mcp": {
    "agentmemory": {
      "type": "local",
      "command": ["npx", "-y", "@agentmemory/mcp"],
      "env": {
        "AGENTMEMORY_URL": "http://localhost:3111"
      },
      "enabled": true
    }
  },
  "plugin": ["./plugins/agentmemory-capture.ts"]
}

Terminal window
mkdir -p ~/.config/opencode/commands
cp agentmemory-main/plugin/opencode/commands/recall.md ~/.config/opencode/commands/
cp agentmemory-main/plugin/opencode/commands/remember.md ~/.config/opencode/commands/

关闭并重新打开 OpenCode，新会话自动启用 agentmemory。

无需启动完整服务器，直接在 MCP 客户端进程中运行。

编辑 ~/.config/opencode/opencode.json 或 .opencode/opencode.json：

{
  "mcp": {
    "agentmemory": {
      "type": "local",
      "command": ["npx", "-y", "@agentmemory/mcp"],
      "enabled": true
    }
  }
}

注意： Standalone 模式不需要 AGENTMEMORY_URL 环境变量。

也可以直接命令行运行：

Terminal window
# 方式 1
npx -y @agentmemory/agentmemory mcp


# 方式 2（shim 包）
npx -y @agentmemory/mcp

数据存储在用户目录下：

系统路径
Windows%USERPROFILE%\.agentmemory\standalone.json
macOS/Linux~/.agentmemory/standalone.json

如果进程被强制终止（SIGKILL），可能丢失未保存的数据。重启 MCP 进程后，之前保存的记忆仍然存在。

完整服务器模式下，agentmemory 会自动捕获以下信息：

类别捕获内容
会话生命周期会话创建、空闲、压缩、错误
用户消息用户提示（隐私过滤后）
助手响应助手回复、token 使用、成本
工具使用文件读写、搜索、命令执行
文件编辑编辑的文件路径
任务追踪待办事项更新

命令说明
/recall <查询>搜索过去的观察记录和经验教训
/remember <文本>保存洞察到长期记忆

完整服务器模式提供 53 个 MCP 工具，核心工具包括：

工具说明
memory_save保存洞察、决策或事实
memory_recall搜索过去的观察记录
memory_smart_search混合语义+关键词搜索
memory_sessions列出最近的会话
memory_file_history获取特定文件的历史记录
memory_lesson_save保存经验教训
memory_lesson_recall搜索经验教训
memory_patterns检测重复模式
memory_consolidate运行 4 层记忆整合管道

Standalone 模式提供 7 个核心工具：

工具说明
memory_save保存记忆到本地文件
memory_recall搜索过去的观察记录
memory_smart_search混合语义+关键词搜索
memory_sessions列出最近的会话
memory_export导出所有记忆数据
memory_audit查看操作审计日志
memory_governance_delete删除特定记忆

在对话中告诉代理：

请记住：我们选择了 jose 而不是 jsonwebtoken 来处理 JWT，
因为它支持 Edge 运行时。

代理会自动调用 memory_save 保存这条决策。

recall 我们之前是如何处理用户认证的？

或者直接问：

我们之前做过什么认证相关的工作？

代理会使用 memory_smart_search 搜索相关记忆。

这个文件之前有什么修改历史？

代理会调用 memory_file_history 查找相关记录。

OpenCode 使用直接注入方式将记忆整合到对话中：

System prompt = [OpenCode 指令] + [记忆上下文] + [文件丰富信息] + [用户消息]
                                ↑                ↑
                          首次会话时注入      每次涉及文件的轮次注入
  • 记忆上下文：会话开始时注入项目概况、最近会话摘要
  • 文件丰富信息：每次编辑文件时注入该文件的历史观察、相关 bug

功能完整服务器模式Standalone 模式
MCP 工具数量53 个7 个
REST API端口 3111无
自动捕获插件22 个 hooks无
向量搜索BM25 + Vector + Graph仅关键词匹配
数据持久化SQLiteJSON 文件
启动时间3-5 秒< 1 秒
搜索准确度95.2% (R@5)~70%（仅关键词）

选择建议：

场景推荐模式
日常开发完整服务器
快速测试Standalone
团队协作完整服务器
受限环境Standalone

可以在同一项目中配置两种模式，通过切换 enabled 字段选择：

{
  "mcp": {
    "agentmemory-full": {
      "type": "local",
      "command": ["npx", "-y", "@agentmemory/mcp"],
      "env": {
        "AGENTMEMORY_URL": "http://localhost:3111"
      },
      "enabled": false
    },
    "agentmemory-standalone": {
      "type": "local",
      "command": ["npx", "-y", "@agentmemory/mcp"],
      "enabled": true
    }
  }
}

开发阶段用完整服务器，CI/CD 或测试环境切换到 Standalone。

Terminal window
npm install @xenova/transformers

本地模型进行向量搜索，无需 API 费用。

Terminal window
set GRAPH_EXTRACTION_ENABLED=true

Terminal window
curl -X POST http://localhost:3111/agentmemory/configure \
  -H "Content-Type: application/json" \
  -d '{"retention_days": 90}'

Terminal window
# Windows
xcopy /E /I data data_backup


# macOS/Linux
cp -r data data_backup

Terminal window
# 在 Standalone 模式中通过 memory_export 导出数据


# 在完整服务器中导入
curl -X POST http://localhost:3111/agentmemory/import \
  -H "Content-Type: application/json" \
  -d @exported_data.json

Terminal window
curl http://localhost:3111/agentmemory/health
netstat -ano | findstr :3111
npx @agentmemory/agentmemory --port 3112

  1. 确保 agentmemory 服务器正在运行（完整模式）
  2. 检查 AGENTMEMORY_URL 环境变量是否正确
  3. 重启 OpenCode

Terminal window
export OPENCODE_AGENTMEMORY_DEBUG=1

查看控制台输出的错误信息。

检查 ~/.agentmemory/standalone.json 文件是否存在。仅使用关键词匹配时搜索结果可能不准确，建议启动完整服务器获得向量搜索功能。

✅ agentmemory 通过 MCP 协议为 OpenCode 提供跨会话持久记忆

✅ 完整服务器模式适合日常开发，功能全面，搜索准确度高

✅ Standalone 模式零配置即开即用，适合快速体验

✅ 两种模式可以混合使用，按场景切换

✅ 记忆数据存储在本地，支持备份和迁移

评论