OpenCode 表格存储长期记忆插件

这是一个可公开发布的 OpenCode 插件，通过阿里云表格存储记忆服务实现 长期记忆。它会在每轮对话前检索并注入相关记忆，在回合结束后增量回写 user/assistant 文本，并在交互热路径之外运行 Dream 整理。

安装要求

• Node.js 20 或更高版本
• OpenCode 1.17.14 或更高版本
• 已存在的表格存储实例、HTTPS Endpoint 和实例名
• API Key，或 AccessKey ID/AccessKey Secret

插件不会创建或管理表格存储实例；它只会按需在已有实例中创建记忆库。

在 opencode.json 中添加：

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["@tablestore/opencode-tablestore-memory"]
}

修改后请重启 OpenCode。

配置

环境变量优先于 ~/.tablestore-memory/opencode.json。

API Key 模式：

export TABLESTORE_MEMORY_ENDPOINT='https://<instance>.cn-beijing.ots.aliyuncs.com'
export TABLESTORE_MEMORY_INSTANCE='<instance>'
export TABLESTORE_MEMORY_API_KEY='<api-key>'

AK/SK 模式：

export TABLESTORE_MEMORY_ENDPOINT='https://<instance>.cn-beijing.ots.aliyuncs.com'
export TABLESTORE_MEMORY_INSTANCE='<instance>'
export TABLESTORE_ACCESS_KEY_ID='<access-key-id>'
export TABLESTORE_ACCESS_KEY_SECRET='<access-key-secret>'

两种凭证同时存在时 API Key 优先，Endpoint 必须使用 HTTPS。

必需的连接信息和凭证就绪后，检索、回写和 Dream 默认开启。全部可选变量为： TABLESTORE_MEMORY_STORE_NAME（默认 opencode_mem）、 TABLESTORE_MEMORY_STORE_DESCRIPTION、TABLESTORE_MEMORY_APP_ID（默认 opencode）、TABLESTORE_MEMORY_TENANT_ID、 TABLESTORE_MEMORY_AGENT_ID、TABLESTORE_MEMORY_SEARCH_TOP_K、 TABLESTORE_MEMORY_MIN_SIMILARITY、TABLESTORE_MEMORY_ENABLE_RERANK、 TABLESTORE_MEMORY_MIN_QUERY_LENGTH、TABLESTORE_MEMORY_INCLUDE_SCORES、 TABLESTORE_MEMORY_AUTO_CREATE_STORE、TABLESTORE_MEMORY_RETRIEVAL_ENABLED （默认 true）、TABLESTORE_MEMORY_MCP_RETRIEVAL_ENABLED（默认继承 retrievalEnabled）、TABLESTORE_MEMORY_WRITEBACK_ENABLED、 TABLESTORE_MEMORY_WRITEBACK_BATCH_TURNS（默认 5）、 TABLESTORE_MEMORY_DREAM_ENABLED、TABLESTORE_MEMORY_DREAM_APPLY_MODE、 TABLESTORE_MEMORY_DREAM_CONFIDENCE、 TABLESTORE_MEMORY_DREAM_MIN_INTERVAL_HOURS（兼容旧配置）、 TABLESTORE_MEMORY_DREAM_MAX_SCOPES 和 TABLESTORE_MEMORY_DREAM_TURN_INTERVAL（默认 20）。

JSON 配置使用对应的驼峰字段，例如 endpoint、instance、apiKey、 tenantId、retrievalEnabled、mcpRetrievalEnabled、writebackEnabled 和 dreamTurnInterval。配置中包含凭证时应将文件权限设为 0600。

关闭自动 SearchMemories、上下文注入和 MCP 检索，同时保留写回与 Dream：

export TABLESTORE_MEMORY_RETRIEVAL_ENABLED=false

MCP 检索默认继承该配置。若要只恢复 MCP search_memory、不恢复自动检索：

export TABLESTORE_MEMORY_RETRIEVAL_ENABLED=false
export TABLESTORE_MEMORY_MCP_RETRIEVAL_ENABLED=true

CLI 和原生 OpenCode 工具的显式搜索不受影响。通过 TABLESTORE_MEMORY_DREAM_TURN_INTERVAL 调整自动 Dream 间隔；设置 TABLESTORE_MEMORY_DREAM_ENABLED=false 可完全关闭自动 Dream。

Hook 行为

• chat.message 在自动检索开启时根据当前 prompt 检索记忆。
• experimental.chat.messages.transform 注入只对模型可见的合成上下文， 不写入可见聊天历史。
• session.idle 读取累计会话，只回写持久化游标之后的新文本。
• 会话压缩或删除时尽力刷新剩余缓冲。

所有自动 hook 都是 fail-open：缺少配置或服务异常不会阻断 OpenCode。

回写只处理 user/assistant 文本，不采集 system prompt、reasoning、工具 参数/结果或文件。私钥、Authorization 和常见 key/token/password 赋值会 被强制 redact。状态文件保存在 ~/.tablestore-memory/opencode/，权限仅限 当前用户。

默认累计五个回合再回写，可以减少服务请求；但进程若在 idle/压缩刷新前 异常退出，尚未提交的尾部可能丢失。将 TABLESTORE_MEMORY_WRITEBACK_BATCH_TURNS=1 可增强持久性，但会增加请求数。

Scope、工具与 Dream

每个宿主会话会获得一个持久化的随机 runId。写入 Scope 为 opencode/<tenant>/opencode/<random-runId>；检索 Scope 为 opencode/<tenant>/*/*，会检索整个 tenant 在当前 app 下的全部记忆。 恢复同一宿主会话会复用原 runId。建议显式配置 TABLESTORE_MEMORY_TENANT_ID。Codex 默认使用不同 appId，因此两者默认隔离。

原生工具与 MCP server 均提供 search_memory、add_memory 和 consolidate_memory。CLI：

tablestore-memory-opencode doctor
tablestore-memory-opencode search '用户喜欢什么饮品？'
tablestore-memory-opencode add '用户喜欢茉莉花茶。'
tablestore-memory-opencode dream --wait

Dream 默认使用增量 safe_auto 和 0.9 阈值。默认每累计 20 个完整的 user/assistant 轮次，对当前会话的精确随机 runId 创建一次增量 Dream；创建 失败不会推进水位，并会在后续 Hook 重试，不影响检索和回写。

隐私与故障排查

记忆正文会发送到用户配置的表格存储实例。插件不采集 system prompt、 reasoning、工具流量或文件；本地状态只保存游标和时间戳，不保存会话正文。 共享机器建议使用独立 tenant 和最小权限凭证。

故障排查时先运行 tablestore-memory-opencode doctor，确认 Endpoint 为 HTTPS、实例已经存在，并检查记忆库权限及 tenant/app ID。自动 hook 会 fail-open；需要查看明确的服务错误时使用 CLI。若记忆库必须由管理员预建， 设置 TABLESTORE_MEMORY_AUTO_CREATE_STORE=false。

验证与卸载

npm install
npm run release:check
TABLESTORE_MEMORY_E2E=1 npm run e2e

真实 E2E 使用一次性记忆库。不要提交凭证或测试报告。卸载时从 OpenCode plugin 数组中删除该包并重启。