# AI对话持久记忆插件

`AI记忆` `OpenCode` `插件` `语义搜索` `Markdown`

<div align="center">
  <img src="assets/historian.jpeg" alt="historian agent" width="240">
  <p><i>Historian 为你的 AI 智能体提供跨对话的持久记忆。</i></p>
  <p>同步 · 召回 · 记住 · 遗忘 · <b>复合增长</b></p>
</div>

---

# OpenCode Historian

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

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

## 功能特性

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

## 前置条件

- **Bun** `1.3.9+`
- 全局安装 **QMD**

安装 QMD：

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

## 安装插件

在 `opencode.json` 中添加插件：

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

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

## 安装 `mnemonics` 技能

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

推荐安装方式：

```bash
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` | 编码规范 |

## 配置

可选配置文件路径：

```text
.opencode/opencode-historian.json
```

示例：

```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/` 下：

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

优势：

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

## 内置工具

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

- `memory_remember`
- `memory_recall`
- `memory_forget`
- `memory_list_types`
- `memory_sync`

## 技能与工具的使用场景

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

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

## 许可证

本项目基于 [MIT 许可证](LICENSE) 开源。