Aity-Memory-MCP

自主可控的 AI 记忆系统，前后端分离架构。

架构

AI 客户端 ←stdio→ MCP 前端 ←HTTP + API Key→ HTTP API 后端 ←→ MySQL
管理面板 (浏览器) ←HTTP→───────────────────→ HTTP API 后端

快速开始

1. 启动 HTTP API 后端

# 设置环境变量（或编辑 .env 文件）
export MEMOS_DB_USER=memos
export MEMOS_DB_PASSWORD=<your-db-password>
export MEMOS_DB_NAME=memos
export API_KEY=<your-api-key>
export API_PORT=3080

# 开发模式
npm run dev:server

# 生产模式
npm run build && npm run start:server

2. 配置 MCP 客户端

在 Cursor / VS Code MCP 配置中添加：

{
  "aity-memory-mcp": {
    "command": "npx",
    "args": ["tsx", "E:/Antigravity/memos-api-mcp/src/mcp/index.ts"],
    "env": {
      "MEMOS_API_URL": "http://localhost:3080/api/v1",
      "MEMOS_API_KEY": "your-secret-key",
      "MEMOS_USER_ID": "admin"
    }
  }
}

MCP 工具

| 工具 | 功能 | |------|------| | search_memory | 搜索记忆（每轮回答前自动调用） | | add_message | 存储对话消息（每轮回答后自动调用） | | add_memory | 精准写入记忆（AI 预处理后直接写入） | | delete_memory | 按 ID 删除记忆 | | add_feedback | 提交反馈/修正记忆 |

HTTP API 端点

所有端点需带 Authorization: Token <API_KEY> 请求头。

核心 API

| 端点 | 方法 | 功能 | |------|------|------| | /api/v1/add/message | POST | 存储对话消息 | | /api/v1/add/memory | POST | 精准写入记忆 | | /api/v1/search/memory | POST | 搜索记忆 | | /api/v1/delete/memory | POST | 删除记忆 | | /api/v1/add/feedback | POST | 提交反馈 |

管理 API

| 端点 | 方法 | 功能 | |------|------|------| | /api/v1/admin/memories | GET | 记忆列表（分页/筛选/搜索） | | /api/v1/admin/conversations | GET | 对话列表 | | /api/v1/admin/stats | GET | 数据统计 | | /health | GET | 健康检查（无需鉴权） |

搜索优化

存入时自动提取关键词标签，搜索时双通道匹配：

• 关键词精确匹配（权重 70%）：提取的关键词 vs 搜索关键词
• 内容模糊匹配（权重 30%）：全文词语交集
• Embedding 向量搜索（可选，权重 60%）：语义级匹配

环境变量

HTTP API 后端

| 变量 | 说明 | 默认值 | |------|------|--------| | MEMOS_DB_HOST | MySQL 主机 | 127.0.0.1 | | MEMOS_DB_PORT | MySQL 端口 | 3306 | | MEMOS_DB_USER | MySQL 用户名 | root | | MEMOS_DB_PASSWORD | MySQL 密码 | 空 | | MEMOS_DB_NAME | 数据库名 | memos | | API_PORT | API 端口 | 3080 | | API_KEY | API 密钥 | 空（⚠️ 生产环境必须设置） |

MCP 前端

| 变量 | 说明 | 默认值 | |------|------|--------| | MEMOS_API_URL | API 后端地址 | http://localhost:3080/api/v1 | | MEMOS_API_KEY | API 密钥 | 空 | | MEMOS_USER_ID | 用户标识 | default_user |

Embedding（可选）

| 变量 | 说明 | 默认值 | |------|------|--------| | EMBEDDING_API_URL | Embedding API | https://api.openai.com/v1 | | EMBEDDING_API_KEY | API Key | 空 | | EMBEDDING_MODEL | 模型名 | text-embedding-3-small | | EMBEDDING_DIM | 向量维度 | 1536 |

技术栈

TypeScript + Node.js 18+ / Express / MySQL / @modelcontextprotocol/sdk / Zod