内容
# BrainMemory-MCP
一款 **模型上下文协议（MCP）** 服务器，为 AI/LLM 代理提供持久的 **大脑记忆** —— 通过标准化的 MCP 工具调用，在会话中存储、检索、搜索、总结和遗忘信息。
服务器运行在两种模式下：
- **stdio** （默认）—— 服务器由 MCP 客户端（例如通过 `uvx brainmemory-mcp`）作为子进程启动。
- **web** —— MCP 通过 **HTTP + 服务器发送事件（SSE）**，远程 MCP 客户端（Claude、IDE 代理等）可以通过网络连接。
内存持久化存储在 **`~/.brainmemory-mcp`** （一个 SQLite 数据库）。
## 认知工具
| 工具 | 描述 |
|------|-------------|
| `store_memory` | 持久化存储新的记忆（内容、类别、标签、重要性）。 |
| `recall_memory` | 通过 ID 获取单个记忆。 |
| `search_memory` | 通过自由文本、类别、标签和/或重要性查找记忆。 |
| `list_memories` | 列出存储的记忆（最重要的和最近的优先）。 |
| `update_memory` | 修改现有的记忆（仅提供字段更改）。 |
| `forget_memory` | 通过 ID 删除记忆。 |
| `summarize_memories` | 总结统计数据：总数、类别、热门标签。 |
只读资源 `brainmemory://stats` 以 JSON 格式公开相同的摘要。
## 安装
从 PyPI（发布后）：
```bash
python3 -m pip install brainmemory-mcp
```
从本地检出：
```bash
python3 -m pip install .
```
两者都安装了名为 `brainmemory-mcp` 的软件包和控制台脚本。
对于开发（可编辑安装）：
```bash
python3 -m pip install -e ".[dev]"
```
要构建/发布版本，请参见 [`docs/RELEASING.md`](docs/RELEASING.md)。
## 运行
### stdio 模式（默认）
适用于本地 MCP 客户端自行启动服务器。存储在 `~/.brainmemory-mcp` 中的内存。
```bash
brainmemory-mcp
# 或不使用控制台脚本
python3 -m brainmemory_mcp
# 使用自定义内存位置
brainmemory-mcp --data-dir /path/to/memory
```
### Web 模式（HTTP + SSE）
通过 `--web` 启用远程/联网客户端。
```bash
# 默认值：127.0.0.1:8765，存储在 ~/.brainmemory-mcp 中的内存
brainmemory-mcp --web
# 自定义主机/端口和内存位置
brainmemory-mcp --web --host 0.0.0.0 --port 9000 --data-dir /path/to/memory
```
Web 模式下的端点：
- SSE 流： `http://<host>:<port>/sse`
- 消息 POST： `http://<host>:<port>/messages/`
### 配置
| 选项 | 环境变量 | 默认值 |
|--------|---------|---------|
| `--web` | `BRAINMEMORY_WEB` | `false` （stdio） |
| `--host` | `BRAINMEMORY_HOST` | `127.0.0.1` |
| `--port` | `BRAINMEMORY_PORT` | `8765` |
| `--data-dir` | `BRAINMEMORY_HOME` | `~/.brainmemory-mcp` |
## 连接客户端
### stdio（推荐用于本地使用）
配置客户端以启动服务器作为子进程：
```json
{
"mcpServers": {
"brainmemory": {
"command": "uvx",
"args": ["brainmemory-mcp"]
}
}
}
```
如果已安装在您的 `PATH` 中，您可以使用 `"command": "brainmemory-mcp"` 和 `"args": []` 代替。
### Web（SSE）
启动带有 `--web` 的服务器，然后将支持 SSE 的客户端指向 `/sse` 端点：
```json
{
"mcpServers": {
"brainmemory": {
"url": "http://127.0.0.1:8765/sse"
}
}
}
```
## 内存存储方式
记忆存储在 `~/.brainmemory-mcp/memory.db` （SQLite，WAL 模式）。每个记忆都有：`id`、`content`、`category`、`tags`、`importance` （1-5）、`created_at`、`updated_at`。不会有任何内容被静默删除 —— 只有通过 `forget_memory` 才会删除。
## 许可证
MIT
