内容
# toon-memory
> 为 AI 编程代理提供持久内存 - 在会话之间记住决策、模式和错误。
[](https://www.npmjs.com/package/toon-memory)
[](https://opensource.org/licenses/MIT)
[](https://github.com/LuiggiVal08/toon-memory/actions/workflows/ci.yml)
[](https://luiggival08.github.io/toon-memory/)
---
## 目录
- [什么是 toon-memory？](#什么是-toon-memory)
- [博客文章](#博客文章)
- [功能](#功能)
- [快速入门](#快速入门)
- [支持的代理](#支持的代理)
- [MCP 工具](#mcp-工具)
- [CLI 命令](#cli-命令)
- [配置](#配置)
- [工作原理](#工作原理)
- [为什么选择 TOON？](#为什么选择-toon)
- [开发](#开发)
- [贡献](#贡献)
- [许可证](#许可证)
---
## 什么是 toon-memory？
AI 代理在会话之间会忘记所有内容。toon-memory 通过提供持久内存来解决这个问题，持久内存可以在重启后存活。
📖 **[阅读文档](https://luiggival08.github.io/toon-memory/)**
**用例：**
- 记录设计决策（“为什么我们选择 X 而不是 Y？”）
- 跟踪模式（“该项目使用 Zod 进行验证”）
- 存储错误解决方案（“Redis 连接池耗尽修复”）
- 保存项目知识（“代理使用 RESP 协议”）
---
## 博客文章
阅读 [如何使 toon-memory 让您的 AI 代理更智能](https://luiggival08.github.io/toon-memory/blog)，以查看持久内存实际应用的示例。
---
## 功能
- **8 个 MCP 工具** - 通过模型上下文协议进行完整的内存管理
- **7 个支持的代理** - OpenCode、VS Code/Copilot、Claude Code、Cursor、Windsurf、Cline、Continue
- **TOON 格式** - 比 JSON 少 40% 的令牌，更适合 LLM 理解
- **每个项目的内存** - 每个项目都有自己的内存文件
- **零配置** - 只需安装并使用
- **自动 gitignore** - 自动将 `.opencode/memory/` 添加到 `.gitignore`
- **日期过滤** - 按日期范围搜索内存
- **自动归档** - 旧条目（> 30 天）自动归档
- **加密** - AES-256-GCM 加密敏感数据
- **监视模式** - 每 N 分钟自动备份
---
## 快速入门
### 1. 安装
```bash
# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/LuiggiVal08/toon-memory/main/install.sh | sh
# Windows (PowerShell)
irm https://raw.githubusercontent.com/LuiggiVal08/toon-memory/main/install.ps1 | iex
# 或使用 npm（任何平台）
npm i -g toon-memory
```
### 2. 配置您的代理
```bash
# 交互式安装程序 - 检测代理并配置 MCP
npx toon-memory
```
### 3. 使用它
```bash
# 在您的下一个会话中，运行：
memory_stats # 查看内存中的内容
memory_recall # 在读取文件之前搜索内存
memory_remember # 保存重要决策
```
---
## 支持的代理
| 代理 | 配置位置 | 自动设置 |
|-------|-----------------|------------|
| **OpenCode** | `.opencode/opencode.json` | ✅ |
| **VS Code / Copilot** | `.vscode/mcp.json` | ✅ |
| **Claude Code** | `.claude/settings.json` | ✅ |
| **Cursor** | `.cursor/mcp.json` | ✅ |
| **Windsurf** | `.windsurfrules` | ✅ |
| **Cline** | `.cline/mcp.json` | ✅ |
| **Continue** | `.continue/config.json` | ✅ |
| **Aider** | `.aider.conf.yml` | ⚠️ 手动 |
---
## MCP 工具
| 工具 | 描述 |
|------|-------------|
| `memory_remember` | 保存决策、模式、错误或知识 |
| `memory_recall` | 搜索内存（在读取文件之前使用） |
| `memory_forget` | 按键或 ID 删除条目 |
| `memory_stats` | 查看内存状态 |
| `memory_summary` | 保存/检索文件摘要 |
| `memory_archive` | 归档旧条目（> 30 天） |
| `memory_encrypt` | 启用 AES-256-GCM 加密 |
| `memory_decrypt` | 禁用加密 |
### 示例
#### 记住决策
```typescript
memory_remember({
category: "decision",
key: "use-zod",
content: "使用 Zod 进行验证",
file: "src/types.ts",
tags: "validation;types"
})
// 🧠 已保存：decision/use-zod (a1b2c3d4)
```
#### 搜索内存
```typescript
memory_recall({ query: "redis" })
// [bug] redis-pool-fix (i9j0k1l2)
// 已添加 max_connections=20
// 文件：redis.ts | 标签：redis;fix | 日期：2026-07-10
```
#### 搜索带日期过滤
```typescript
memory_recall({
query: "redis",
from_date: "2026-07-01",
to_date: "2026-07-31"
})
```
#### 归档旧条目
```typescript
memory_archive()
// 📦 已归档 5 个旧条目
// 📋 剩余 42 个活动条目
```
#### 启用加密
```typescript
memory_encrypt()
// 🔐 已启用加密
// ⚠️ 保存此密钥（无法恢复）：
// a1b2c3d4...
```
---
## CLI 命令
```bash
npx toon-memory # 交互式安装程序
npx toon-memory init # 快速设置（无提示）
npx toon-memory mcp # 直接运行 MCP 服务器
npx toon-memory status # 检查安装状态
npx toon-memory stats # 查看内存统计
npx toon-memory export # 将内存导出到 JSON
npx toon-memory import <file> # 从 JSON 导入内存
npx toon-memory watch [options] # 自动备份，带选项
npx toon-memory upgrade # 更新到最新版本
npx toon-memory uninstall # 从所有代理中删除
```
### 示例
#### 统计
```bash
$ npx toon-memory stats
🧠 toon-memory 统计
📊 内存统计
━━━━━━━━━━━━━━━━━━
总条目：45
├── decision: 12
├── pattern: 18
├── bug: 8
└── knowledge: 7
最后更新：2026-07-10
文件大小：12.4 KB
```
#### 导出
```bash
$ npx toon-memory export
🧠 toon-memory 导出
已导出 45 个条目到：
/path/to/project/toon-memory-export.json
```
#### 导入
```bash
$ npx toon-memory import backup.json
🧠 toon-memory 导入
已导入 3 个新条目
跳过 2 个重复条目
```
#### 监视
```bash
$ npx toon-memory watch 15 -c -m 20
🧠 toon-memory 监视
每 15 分钟监视内存文件...
最大备份数：20
压缩：启用
日志记录：禁用
按 Ctrl+C 停止
📦 备份 #1 已创建：2026-07-11T16-00-00-000Z
📦 备份 #2 已创建：2026-07-11T16-15-00-000Z
^C
✅ 监视停止。已创建 2 个备份。
```
**监视选项：
| 选项 | 描述 | 默认值 |
|--------|-------------|---------|
| `[interval]` | 备份间隔（分钟） | 5 |
| `-c, --compress` | 启用 gzip 压缩 | 关闭 |
| `-l, --log [path]` | 启用文件日志记录 | 关闭 |
| `-m, --max-backups <n>` | 要保留的最大备份数（0=无限） | 10 |
---
## 配置
### 全局（所有项目）
添加到 `~/.config/opencode/opencode.json`:
```json
{
"mcp": {
"toon-memory": {
"type": "local",
"command": ["npx", "-y", "toon-memory", "mcp"],
"enabled": true
}
}
}
```
### 项目级别
添加到 `.opencode/opencode.json`:
```json
{
"mcp": {
"toon-memory": {
"type": "local",
"command": ["npx", "-y", "toon-memory", "mcp"],
"enabled": true
}
}
}
```
### VS Code
添加到 `.vscode/mcp.json`:
```json
{
"servers": {
"toon-memory": {
"command": "npx",
"args": ["-y", "toon-memory", "mcp"]
}
}
}
```
---
## 工作原理
1. **MCP 服务器** - 在本地运行，通过 stdio 与您的代理通信
2. **TOON 格式** - 以 Token-Oriented Object Notation 存储数据（比 JSON 少约 40% 的令牌）
3. **每个项目的内存** - 每个项目都有自己的 `.opencode/memory/data.toon`
4. **零配置** - 只需安装并使用
### 内存文件格式
```
version: 1
entries[3|]{id|category|key|content|file|tags|date}:
a1b2c3d4|decision|use-zod|使用 Zod 进行验证|src/types.ts|validation;types|2026-07-10
e5f6g7h8|pattern|pydantic-configs|项目使用 Pydantic v2|config.py|python;patterns|2026-07-10
i9j0k1l2|bug|redis-pool-fix|已添加 max_connections=20|redis.ts|redis;fix|2026-07-10
summaries:
src/services/redis.ts: Redis 连接池，带有重试逻辑
```
### 文件结构
```
.opencode/
├── memory/
│ ├── data.toon # 主内存文件
│ ├── archive.toon # 已归档条目（> 30 天）
│ ├── config.json # 加密设置
│ └── backups/ # 监视模式备份
│ ├── backup-2026-07-11T16-00-00-000Z.toon
│ └── backup-2026-07-11T16-10-00-000Z.toon
└── opencode.json # MCP 服务器配置
```
---
## 为什么选择 TOON？
TOON（Token-Oriented Object Notation）是为 LLM 设计的：
| 格式 | 令牌数 | LLM 准确率 |
|--------|-------------|--------------|
| JSON | 100 | 75% |
| YAML | 95 | 72% |
| **TOON** | **60** | **76.4%** |
- **比 JSON 少 40% 的令牌**
- **无损往返** - 无数据丢失
- **更好的 LLM 理解** - 为 AI 消费而结构化
---
## 开发
```bash
git clone https://github.com/LuiggiVal08/toon-memory.git
cd toon-memory
npm install
npm run build
npm test
```
### 项目结构
```
toon-memory/
├── src/
│ ├── bin/
│ │ └── toon-memory.ts # 入口点
│ ├── cli/
│ │ ├── setup.ts # CLI 命令
│ │ └── toon-memory.ts # CLI 运行器
│ ├── mcp/
│ │ └── server.ts # MCP 服务器（8 个工具）
│ └── memory.ts # 自定义工具（OpenCode）
├── tests/
│ ├── cli.test.ts # CLI 测试
│ └── memory.test.ts # 内存测试
├── .github/workflows/
│ ├── ci.yml # CI（Node.js 20/22）
│ └── publish.yml # 发布时自动发布
├── package.json
├── tsconfig.json
└── vitest.config.ts
```
---
## 贡献
欢迎贡献！请先阅读我们的 [行为准则](CODE_OF_CONDUCT.md)。
1. 分叉仓库
2. 创建您的功能分支 (`git checkout -b feature/amazing-feature`)
3. 提交您的更改 (`git commit -m 'feat: add amazing feature'`)
4. 推送到分支 (`git push origin feature/amazing-feature`)
5. 打开拉取请求
---
## 许可证
MIT
---
## 致谢
使用 [@toon-format/toon](https://www.npmjs.com/package/@toon-format/toon) 和 [@modelcontextprotocol/server](https://www.npmjs.com/package/@modelcontextprotocol/server) 构建。
