opencode-session-memory

OpenCode Session Memory 插件 — Phase 1 / Deterministic Retrieval

为 OpenCode Agent 提供当前 Session 完整历史的确定性检索能力。OpenCode 保存事实源；本插件维护可重建的派生索引。

功能

工具	说明
memory_search	精确 / 全文 / 模糊检索
memory_context	按 ref 恢复前后原文与工具链
memory_related	实体共现 / 时间邻近等确定性联想
memory_trace	工具 / 文件 / 符号 / 错误时间线
memory_recall	多路证据聚合（RecallCandidateBundle）

安装

给 Agent 的完整安装 / 部署 / 使用说明： docs/AGENT-README.md

本地开发（OpenCode 1.18+）

npm install
npm run build   # 必须：仓库不含 dist/

推荐把插件放到项目 .opencode/plugins/（或全局 ~/.config/opencode/plugins/），并提供 .opencode/package.json 依赖；loader 指向本机 dist/index.js 的 file:// URL（详见 Agent 指南）。

也可在 opencode.json 使用 npm/file: 条目；注意全局若已安装 opencode-mem，工具名可能冲突。

可选环境变量：

SESSION_MEMORY_DATABASE_PATH=C:/path/to/index.sqlite
SESSION_MEMORY_ADMIN_TOOLS=1

注意： OpenCode 用 Bun 加载插件，因此插件在运行时使用 bun:sqlite（Node 下测试仍用 node:sqlite）。

配置（options / env）

当运行时仍向插件传入 options 对象时可用：

{
  "databasePath": "<平台默认>/opencode-session-memory/index.sqlite",
  "source": {
    "mode": "auto",
    "prefer": "sdk",
    "allowReadOnlySqliteFallback": true
  },
  "index": {
    "blockingInitialIndex": true,
    "indexReasoning": false
  },
  "search": {
    "defaultLimit": 8,
    "maxOutputChars": 30000,
    "enableFuzzy": true
  },
  "adminTools": false,
  "cleanupOnSessionDelete": true
}

Windows 默认索引路径：%LOCALAPPDATA%/opencode-session-memory/index.sqlite。

Agent 使用原则

1. 压缩摘要足够时，不调用记忆工具。
2. 缺少准确措辞、错误、工具参数时，调用 memory_search。
3. 命中但 excerpt 不足时，调用 memory_context。
4. 需要同文件/同符号/同错误其他历史时，调用 memory_related。
5. 需要工具链或错误演进时，调用 memory_trace。
6. 目标宽泛时，调用 memory_recall。
7. 检索结果不是新事实，结论必须以原始证据为准。

开发

npm run build              # 编译
npm run test               # 单元 + 集成（不含真实 CLI）
npm run test:unit
npm run test:integration
npm run bench              # 性能基准 → docs/bench-report.md
npm run test:e2e           # 真实 OpenCode CLI E2E → docs/e2e-report.md
npm run probe:m0           # M0 兼容性探针 → docs/m0-probe-report.md

验收清单：docs/phase1-acceptance.md

兼容验证范围： 当前以本机 Windows 实测为准；Linux/macOS 仅覆盖默认路径单测。

架构

OpenCode 历史 → 增量索引 → 确定性召回 → 原始上下文 → Agent

• 不修改 OpenCode SQLite
• 不调用 LLM / embedding
• 强 Session 隔离（工具仅使用 context.sessionID）
• 索引可删可重建

许可证

MIT