180 lines
4.3 KiB
Markdown
180 lines
4.3 KiB
Markdown
# 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) 开源。 |