npm package: @jasonfu/opencode-mem
Description: OpenCode 长期记忆插件 - 跨会话持久化上下文
Author: fujisheng
Latest version: 0.0.1

# 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 安装（推荐）**

```bash
npm install @jasonfu/opencode-mem
```

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

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

**方式二：本地源码安装**

克隆仓库后：

```bash
bun install
bun run build
```

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

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

### 运行测试

```bash
# 全量 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`

项目级优先于全局级。

示例：

```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` | 是否启用敏感信息过滤 |

## 项目结构

```text
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](https://semver.org/lang/zh-CN/) 规范

**发布步骤**：

1. 更新 `package.json` 中的版本号
2. 提交更改并推送标签：
   ```bash
   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