内容
# 记忆伴侣 🧠
[中文版](README.zh-CN.md)
> **为您的 AI 代理提供一个持久的共享内存。** 部署一次，连接任何兼容 MCP 的 AI 工具 — Hermes、Trae、Cursor、Claude Desktop — 它们都共享相同的内存。
[](LICENSE)
[](https://workers.cloudflare.com/)
[](https://www.typescriptlang.org/)
[](https://modelcontextprotocol.io/)
[](#-why-cloudflare-free-tier)
## 🌟 这是什么？
大多数 AI 工具都存在“金鱼记忆”问题 — 刷新页面、开始新会话、切换到另一个应用程序，所有内容都会消失。你必须不断地重新介绍自己、重新解释你的偏好、重新陈述上下文。
**记忆伴侣** 通过 **共享内存层** 解决了这个问题，任何 AI 工具都可以从中读取和写入：
- 🧠 **长期记忆** — 事实、偏好、决策在会话之间持久存在
- 🔍 **语义搜索** — 通过含义查找相关记忆，而不仅仅是关键词
- 🤖 **自动事实提取** — LLM 自动提炼值得记忆的内容
- 📝 **智能总结** — 长对话被压缩，保留关键点
- 🗑️ **一键忘记** — `DELETE` 删除所有内容，符合 GDPR
- 🔌 **MCP 协议** — 任何兼容 MCP 的客户端都可以连接，无需集成代码
- 💸 **$0/月** — 完全运行在 Cloudflare 的免费层
## 💡 它解决了什么问题？
| 😣 没有记忆伴侣 | ✅ 有记忆伴侣 |
|------------------------|---------------------|
| 每个 AI 工具都从头开始 — 你不断地重新解释自己 | 所有 AI 工具共享一个内存 — 说一次，它们都知道 |
| 从 Hermes 切换到 Trae 会丢失所有上下文 | 自由切换 — 内存存在于云中，不在工具中 |
| AI 在会话之间忘记你的偏好 | 偏好永久存在，跨所有会话和工具 |
| 长对话达到上下文限制 | 自动总结保持内容简洁 |
| 隐私问题 — 无法删除记住的内容 | 一个 API 调用删除所有内容，完全符合 GDPR |
## 🏗️ 架构
```
┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐
│ Hermes │ │ Trae │ │ Cursor │ │ Claude │
└────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘
│ MCP │ MCP │ MCP │ MCP
▼ ▼ ▼ ▼
┌──────────────────────────────────────────────────┐
│ 记忆伴侣 Worker (Cloudflare) │
│ │
│ /mcp → MCP 服务器 (5 工具，Streamable HTTP) │
│ /chat → HTTP API (SSE 流式传输 + 自动提取)│
│ /memory/:userId → REST API │
└──────────┬──────────────────┬────────────────────┘
│ │
┌─────▼─────┐ ┌──────▼──────┐
│ D1 (事实)│ │ 向量化 │
│ SQLite DB │ │ (嵌入)│
└───────────┘ └─────────────┘
```
**三层内存：**
1. **短期** (Durable Object) — 当前对话上下文
2. **长期** (D1 数据库) — 结构化事实：名称、偏好、关键实体
3. **语义** (Vectorize) — 基于含义的向量嵌入
## 🚀 快速开始（3 步，约 5 分钟）
### 前提条件
- [Cloudflare 账户](https://dash.cloudflare.com/sign-up)（免费即可）
- Node.js 18+
### 1. 克隆并安装
```bash
git clone https://github.com/Trainspotting31/memory-buddy.git
cd memory-buddy
npm install
```
### 2. 创建 Cloudflare 资源
```bash
npx wrangler login
# 创建 D1 数据库
npx wrangler d1 create memory-buddy-db
# 创建 Vectorize 索引
npx wrangler vectorize create memory-buddy-index --dimensions 768 --metric cosine
# 初始化数据库架构
npx wrangler d1 execute memory-buddy-db --remote --file=schema.sql
```
复制生成的 `database_id` 到 `wrangler.toml`（从 `wrangler.toml.example` 重命名）。
### 3. 部署
```bash
npx wrangler deploy
```
完成！您的内存服务器现已上线，地址为 `https://memory-buddy.<your-subdomain>.workers.dev` 🎉
## 🔌 连接您的 AI 工具
记忆伴侣支持 MCP（模型上下文协议）。任何兼容 MCP 的工具都可以连接 — 它们都共享相同的内存。
### Hermes 代理
```bash
hermes mcp add memory-buddy --url https://memory-buddy.<your-subdomain>.workers.dev/mcp
```
### Trae IDE
1. **设置 → MCP → 手动添加**
2. 类型：**Streamable HTTP**
3. URL：`https://memory-buddy.<your-subdomain>.workers.dev/mcp`
或在您的项目中创建 `.trae/mcp.json`:
```json
{
"mcpServers": {
"memory-buddy": {
"type": "streamable-http",
"url": "https://memory-buddy.<your-subdomain>.workers.dev/mcp"
}
}
}
```
### Cursor
添加到 `~/.cursor/mcp.json`:
```json
{
"mcpServers": {
"memory-buddy": {
"url": "https://memory-buddy.<your-subdomain>.workers.dev/mcp"
}
}
}
```
### Claude Desktop
添加到 `claude_desktop_config.json`:
```json
{
"mcpServers": {
"memory-buddy": {
"type": "streamable-http",
"url": "https://memory-buddy.<your-subdomain>.workers.dev/mcp"
}
}
}
```
### 任意 MCP 客户端（原始配置）
```
端点：https://memory-buddy.<your-subdomain>.workers.dev/mcp
传输：Streamable HTTP
身份验证：无（或添加您自己的）
```
## 🛠️ MCP 工具
连接后，AI 获得 5 个工具：
| 工具 | 功能 | AI 调用时机 |
|------|-------------|------------------|
| `recall_memory` | 加载用户的所有内存 | 对话开始时 |
| `search_memory` | 基于含义的语义搜索 | “我对 X 说了什么？” |
| `store_memory` | 保存新事实 | 用户分享偏好、决策 |
| `forget_memory` | 删除所有内存 | 用户说“忘记一切” |
| `list_memory_users` | 列出所有内存空间 | 检查存在哪些内存 |
**共享内存：** 所有工具默认为 `userId: "hermes-shared"`。使用不同的 userIds 来隔离每个项目/角色的内存。
## 📡 HTTP API（无需 MCP）
### `POST /chat` — 与内存聊天
```bash
curl -N -X POST https://your-worker.workers.dev/chat \
-H "Content-Type: application/json" \
-d '{"userId":"user123","message":"Hi! 我是 John，我喜欢意式咖啡。" }'
```
### `GET /memory/:userId` — 获取所有内存
```bash
curl https://your-worker.workers.dev/memory/user123
```
### `DELETE /memory/:userId` — 清除内存
```bash
curl -X DELETE https://your-worker.workers.dev/memory/user123
```
### `GET /health` — 健康检查
```bash
curl https://your-worker.workers.dev/health
```
## ⚙️ 配置
编辑 `wrangler.toml`:
```toml
[vars]
LLM_MODEL = "@cf/meta/llama-3.2-3b-instruct" # 默认：Workers AI（免费）
# 可选：使用外部 LLM 而非 Workers AI
LLM_API_KEY = "sk-your-key"
LLM_API_BASE = "https://api.openai.com/v1"
LLM_MODEL = "gpt-4o-mini"
```
## 💸 为什么选择 Cloudflare 免费层？
| 组件 | 免费层 | 自托管等效 |
|-----------|-----------|----------------------|
| 计算（Workers） | 100K 请求/天 | $5–$50/月（VPS） |
| 数据库（D1） | 1GB 存储 | $10–$100/月（Postgres） |
| 向量数据库（Vectorize） | 256K 向量 | $70+/月（Pinecone） |
| LLM（Workers AI） | 10K 神经元/天 | $10+/月（API） |
| **总计** | **$0** | **~$100+/月** |
## 📁 项目结构
```
memory-buddy/
├── src/
│ ├── index.ts # Hono 路由器：/mcp + /chat + /memory + /health
│ ├── mcp.ts # MCP 服务器工厂（5 个工具，无状态）
│ ├── agent-do.ts # Durable Object：聊天会话 + 内存编排
│ ├── llm.ts # LLM 抽象（Workers AI / OpenAI 兼容）
│ └── memory/
│ ├── extract.ts # LLM 驱动的事实提取
│ ├── retrieve.ts # 混合检索（D1 + Vectorize）
│ └── summarize.ts # 对话总结
├── public/index.html # 内置演示聊天界面
├── schema.sql # D1 数据库架构
├── wrangler.toml.example # Cloudflare 配置模板
└── package.json
```
## 🎮 试用演示
在浏览器中打开您的 Worker URL — 您将看到一个内置的聊天界面。
1. 告诉代理您的姓名和偏好（“我是 Sarah，我对花生过敏”）
2. 刷新页面
3. 问：“您对我了解什么？”
它记得一切。这就是记忆伴侣。
## 🗺️ 路线图
- [x] MCP 服务器（Streamable HTTP）
- [x] 多代理共享内存
- [x] 语义搜索
- [x] 自动事实提取
- [ ] 内存分类和过滤
- [ ] 用户身份验证
- [ ] 批量内存导入/导出
- [ ] 多语言支持
- [ ] Hermes 插件（自动在对话开始时注入内存）
## 🤝 贡献
1. 分叉 → 2. 分支 → 3. 提交 → 4. 推送 → 5. PR
## 📄 许可证
MIT — 见 [LICENSE](LICENSE)
