opencode-haimati

为 OpenCode 提供基于文件系统的长期记忆存储和检索功能。

功能特性

• 类海马体记忆机制：模拟人脑记忆系统的分类存储
• 树形索引结构 + 分组书页存储
• 多模式搜索：序号精确查询 + 关键字模糊搜索
• 完整 CRUD：读取、写入、更新、删除、移动
• 版本并发控制：基于 version 的乐观锁
• 文件锁机制：支持网络共享挂载多用户并发写入
• 自动工作规则提示：会话首条消息时自动注入工作流程提醒
• 自动关联记忆检索（auto-read）：关键词提取 → 搜索 → 注入 Top 3 相关记忆到消息上下文
• 自动记忆写入（autoWrite，默认关闭）：AI 回复完成后异步触发 AI 自主审查并写入有价值的知识
• autoUpdate：启动时自动检查 npm registry 新版本，无需手动升级

安装

npm install -g opencode-haimati
# 或
bun add -g opencode-haimati

配置

在 opencode.json 中添加插件：

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

支持三级配置（优先级从低到高）：

1. 全局：~/.config/opencode/haimati.jsonc 或 haimati.json
2. 自定义：$OPENCODE_CONFIG_DIR/haimati.jsonc 或 haimati.json（如果环境变量存在）
3. 项目：.opencode/haimati.jsonc 或 haimati.json

配置示例（haimati.jsonc）：

{
  // 海马体存储路径（相对项目根目录，或绝对路径）
  "haimatiPath": ".haimati",

  // 日志配置（仅全局配置有效）
  "log": {
    "level": "info",           // debug、info、warn、error
    "logRetentionDays": 180    // 日志保留天数
  },

  // 自动更新：设为 false 禁用启动时版本检查（默认 true）
  "autoUpdate": true,

  // 自动记忆写入：设为 true 启用 AI 自主记忆写入（默认 false，需显式开启）
  "autoWrite": true
}

插件在每次会话的首条用户消息时自动注入工作规则提示， 告知 AI 海马体插件可用，指导其按需使用 haimati_search/haimati_read 读取记忆， 并在工作完成后写入新知识。

autoUpdate 控制插件是否在启动时检查 npm registry 新版本。检测到新版本且依赖声明允许更新时，删除插件包裹目录，触发 OpenCode 下次启动时自动安装最新版。

首次运行时自动创建全局配置模板。

目录结构

.haimati/
├── .lock          # 文件锁（支持网络共享挂载多用户协调）
├── 索引.md        # 树形索引
└── 书页/          # 记忆内容（每50个序号一分组）

工具

| 工具 | 说明 | |------|------| | haimati_read | 读取记忆（单条/批量，支持分页） | | haimati_write | 写入新记忆（自动分配序号，不支持覆盖已存在） | | haimati_search | 搜索（标题/分类/内容，match必填） | | haimati_edit | 部分修改（字符串匹配替换，隐式并发检测） | | haimati_move | 修改分类路径和/或标题 | | haimati_delete | 删除记忆 | | haimati_list | 列出索引（按分类浏览，支持详细内容） |

使用示例

// 写入（title 不能以 " - 序号" 结尾）
haimati_write({ category: "xxx项目/签章", title: "签章服务WS通信机制", content: "..." })

// 读取（单条）
haimati_read({ query: "086" })

// 读取（批量：逗号分隔或范围）
haimati_read({ query: "086,087,088" })
haimati_read({ query: "086-090" })

// 搜索
haimati_search({ keyword: "WebSocket", match: "or" })

// 修改
// 单处替换
haimati_edit({ 
  query: "086",
  oldString: "旧文本",
  newString: "新文本"
})

// 全部替换
haimati_edit({ 
  query: "086",
  oldString: "旧文本",
  newString: "新文本",
  replaceAll: true
})

// 移动
haimati_move({ query: "086", newCategory: "xxx项目/客户端" })

// 删除
haimati_delete({ query: "086" })

// 列出（树形索引）
haimati_list()

// 列出（指定分类，含详细内容）
haimati_list({ category: "xxx项目", recursive: true, detail: true })

haimati_edit 使用说明

关键特性：

• 支持字符串模式匹配替换（类似系统 edit 工具）
• 使用 oldString 定位要替换的文本
• replaceAll 控制是否替换所有匹配项
• oldString 内容匹配隐式提供并发检测

参数说明：

• oldString 不能为空
• 如果 oldString 在内容中不存在，会报错提示，说明内容已被修改
• replaceAll=false（默认）：只替换第一个匹配项
• replaceAll=true：替换所有匹配项

日志

日志位于：~/.opencode-haimati/log/{yyyy-MM-dd}.log（按天轮转）

日志配置整合在 ~/.config/opencode/haimati.jsonc 的 log 字段中。

依赖

• OpenCode v0.15.0+
• Node.js 或 Bun