catalog/repos/5kahoisaac--opencode-historian.md

AI对话持久记忆插件

AI记忆 OpenCode 插件 语义搜索 Markdown

Historian 为你的 AI 智能体提供跨对话的持久记忆。

同步 · 召回 · 记住 · 遗忘 · 复合增长

---

OpenCode Historian

基于 QMD 驱动的 OpenCode 智能体持久记忆系统。

Historian 帮助你的智能体在会话之间记住决策、偏好、经验和项目上下文。它将记忆以 Markdown 格式存储，通过 QMD 建立索引，并提供记住、召回、遗忘和同步记忆的工具。

功能特性

• 跨对话的持久记忆
• 对已保存记忆的语义搜索
• 内置决策、问题、经验和偏好等记忆类型
• 基于 Markdown 的存储，保存在你的仓库中
• 内置 historian 智能体及记忆工具
• 可选的 Serena MCP 代码导航支持

前置条件

• Bun 1.3.9+
• 全局安装 QMD

安装 QMD：

npm install -g qmd
# 或
bun install -g qmd

安装插件

在 opencode.json 中添加插件：

{
  "plugins": ["opencode-historian"]
}

这一步即可完成插件注册，同时注册内置的 historian 智能体和记忆工具。

安装 mnemonics 技能

该插件还包含一个 mnemonics 技能，用于教导智能体如何有效使用 @historian 子智能体。

推荐安装方式：

npx skills add https://github.com/5kahoisaac/opencode-historian/tree/main/src --skill mnemonics

安装后，智能体可加载 mnemonics 以获取记忆类型指导、何时使用 @historian，以及如何正确存储或召回项目知识。

快速开始

启用插件后，用自然语言与 historian 智能体交互即可。

保存信息

"记住我们使用 PostgreSQL 作为数据库"

"保存这条信息：我们决定使用 JWT 令牌，有效期 24 小时"

"记录 API 速率限制为每分钟 100 次请求"

召回信息

"我们关于身份验证做了哪些决策？"

"有什么已知问题吗？"

"这个项目我有哪些偏好设置？"

Historian 将会：

• 按类型对记忆进行分类
• 为记忆添加标签以便检索
• 建立语义搜索索引
• 以 Git 友好的 Markdown 格式保存记忆

记忆类型

Historian 内置以下记忆类型：

类型	用途
architectural-decision	系统架构选择
design-decision	UI/UX 设计决策
learning	经验与发现
user-preference	用户个人偏好
project-preference	团队规范约定
issue	已知问题
context	通用上下文（默认）
recurring-pattern	可复用模式
conventions-pattern	编码规范

配置

可选配置文件路径：

.opencode/opencode-historian.json

示例：

{
  "appendPrompt": "重点关注 API 设计决策。",
  "memoryTypes": [
    {
      "name": "api-endpoint",
      "description": "API 端点决策"
    }
  ],
  "disabledMcps": ["serena"]
}

配置项说明

配置项	默认值	说明
model	-	historian 智能体使用的模型
temperature	0.3	响应创造性程度
appendPrompt	-	追加到 historian 提示词末尾的额外指令
memoryTypes	-	在内置类型基础上添加的自定义记忆类型
autoCompound	true	在适当时自动将新经验合并到已有记忆中
disabledMcps	-	要禁用的内置 MCP，例如 ["serena"]

存储结构

记忆以 Markdown 文件形式存储在项目根目录的 .mnemonics/ 下：

.mnemonics/
├── architectural-decision/
├── design-decision/
├── learning/
└── ...

优势：

• 人类可读
• 易于用 Git 进行版本管理
• 便于手动查看或编辑

内置工具

插件注册了以下记忆工具：

• memory_remember
• memory_recall
• memory_forget
• memory_list_types
• memory_sync

技能与工具的使用场景

• 使用插件在 OpenCode 内开启记忆能力
• 使用 mnemonics 技能教导智能体如何更好地使用 @historian
• 需要直接编程操作记忆时使用记忆工具

简而言之：插件赋予你能力，技能则让智能体更懂得如何运用这种能力。

许可证

本项目基于 MIT 许可证 开源。