opencode-mem

OpenCode 的长期记忆插件：将会话内容提取为结构化记忆，在后续对话中按相关性注入上下文，并提供内置 Viewer 进行浏览与管理。

功能特性

• 自动记忆提取：从用户输入、工具调用和会话边界中提取 observation 与 summary
• 相关性上下文注入：基于 FTS5 BM25 按当前 prompt 检索并注入最相关记忆
• 结构化记忆管理：支持搜索、详情查看、时间线、手动保存、更新、删除
• 内置记忆 Viewer：随机端口启动、本地浏览器查看、多页签浏览、过滤、删除、统计、中英文切换
• 批量与可靠性机制：支持队列持久化、批量处理、指数退避重试、恢复卡住任务
• 隐私保护：内置敏感信息过滤，避免 API key、Bearer token、私钥等内容落库

适用场景

• 需要让 OpenCode 在多轮、多会话开发中保留项目上下文
• 想沉淀决策、bug 修复、架构发现等长期知识
• 希望通过可视化界面查看和管理记忆数据

快速开始

环境要求

• Bun >= 1.0.0
• Node.js >= 18.0.0

安装

方式一：通过 npm 安装（推荐）

npm install @jasonfu/opencode-mem

在 OpenCode 配置文件 .opencode/config.json 中添加插件：

{
  "plugins": ["@jasonfu/opencode-mem"]
}

方式二：本地源码安装

克隆仓库后：

bun install
bun run build

然后在 OpenCode 配置中使用本地路径：

{
  "plugins": ["./.opencode/plugins/opencode-mem"]
}

运行测试

# 全量 memory 测试
bun test tests/memory/

# 指定测试
bun test tests/memory/plugin/opencode-plugin-wrapper.test.ts

OpenCode 中提供的工具

插件会注册以下工具：

| 工具 | 说明 | | --- | --- | | mem_search | 搜索记忆库中的 observations、sessions、prompts | | mem_timeline | 获取指定锚点附近的记忆时间线 | | mem_get_observations | 根据 observation IDs 获取完整记忆详情 | | mem_save | 主动写入一条记忆 | | mem_delete | 删除指定 observation | | mem_update | 更新 observation 字段 | | mem_viewer | 获取当前 Viewer 链接，并可尝试打开默认浏览器 |

Viewer

插件启动时会自动拉起本地 Viewer，并随机选择一个可用端口。

可用方式：

• slash command：/mem-viewer
• tool call：mem_viewer(open=false) / mem_viewer(open=true)

Viewer 当前支持：

• 记忆 / 会话 / 提示词 / 摘要四个页签
• 按类型、关键词、概念、时间范围过滤
• 删除 observation 与清理过期记忆
• 实时统计（observations、sessions、prompts、summaries、daily extractions、LLM calls）
• 中文 / English 切换，并记住上次选择

配置

插件支持项目级和全局级配置文件：

• 项目级：<project>/.opencode/opencode-mem.json
• 全局级：~/.config/opencode/opencode-mem.json

项目级优先于全局级。

示例：

{
  "memory_model": "provider/model-name",
  "memory_language": "中文",
  "enable_sensitive_filter": true
}

| 配置项 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | | memory_model | string | 当前会话模型 | 记忆提取使用的模型，格式 provider/modelName | | memory_language | string | "English" | 提取与摘要输出语言 | | enable_sensitive_filter | boolean | true | 是否启用敏感信息过滤 |

项目结构

src/
├─ build/                 # 构建脚本
├─ memory/
│  ├─ context/            # 上下文编译与渲染
│  ├─ extraction/         # 记忆提取与队列处理
│  ├─ hooks/              # OpenCode 生命周期接线
│  ├─ llm/                # LLM 适配层
│  ├─ maintenance/        # 清理、恢复、重建索引
│  ├─ privacy/            # 敏感信息过滤
│  ├─ sqlite/             # 数据库、迁移、指标与 CRUD
│  ├─ summary/            # 会话摘要生成
│  ├─ tools/              # 对外暴露的工具实现
│  └─ viewer/             # 内置 HTTP Viewer
└─ index.ts               # 插件入口

tests/
└─ memory/                # memory 子系统测试

开发说明

• 构建产物输出到 dist/
• 数据库存储于用户本地目录，而不是仓库目录
• 当前仓库使用 Bun + TypeScript 开发

发布工作流

本项目使用 GitHub Actions 自动发布到 npm registry。

版本策略：遵循 SemVer 规范

发布步骤：

1. 更新 package.json 中的版本号
2. 提交更改并推送标签：

   git add package.json
   git commit -m "chore: release v0.0.1"
   git tag v0.0.1
   git push origin main --tags

3. GitHub Actions 自动触发发布流程：
   • 构建项目
   • 运行测试
   • 发布到 npm（使用 Trusted Publishing）

要求：

• 标签格式必须为 v*（如 v0.0.1）
• 需要仓库管理员配置 npm Trusted Publishing

已知限制

当前 OpenCode 插件 API 尚未开放类似内置命令的即时执行 / 静默取消能力，因此 /mem-viewer 这类命令仍受宿主 slash command 流程限制。插件已经尽量避免重复副作用，但无法在插件层完全复刻内置命令体验。

许可证

MIT