内容
# @baixfeng/agent-memory
一款强大的MCP（模型上下文协议）服务器，提供具有全文搜索功能的持久化内存存储。基于SQLite和FTS5（全文搜索）构建，它使AI助手能够在本地存储、检索和管理知识，并具有高效的模糊搜索功能。
## 功能特点
- **持久化存储**：基于SQLite的本地数据库，自动备份
- **全文搜索**：FTS5支持三元组分词，实现模糊匹配
- **内存管理**：完整的CRUD操作（创建、读取、更新、删除）
- **分类管理**：自定义类别组织记忆
- **关键词系统**：记忆可标记可搜索的关键词
- **分页功能**：高效的搜索结果，支持分页大小配置
- **调试日志**：可选的文件日志，用于故障排查
- **WAL模式**：写入前日志，提高并发访问性能
## 安装
```bash
npm install @baixfeng/agent-memory
```
或者直接作为二进制文件使用：
```bash
npx @baixfeng/agent-memory [存储目录] [启用日志]
```
## 配置
服务器接受两个可选的命令行参数：
### 1. 存储目录
- **默认值**：`~/.local-memory`
- **用法**：指定存储数据库和日志的自定义目录
- **示例**：`/自定义路径/to/memory` 或 `~/我的记忆`
### 2. 启用日志文件
- **默认值**：`false`
- **用法**：传递 `"true"` 以启用基于文件的日志记录
- **注意**：调试输出始终发送到 stderr（在 MCP Inspector 中可见）
- **示例**：`true`
### 示例用法
```bash
# 默认配置
agent-memory
# 自定义存储目录
agent-memory /路径/to/memory
# 自定义存储并启用日志
agent-memory /路径/to/memory true
```
## MCP 工具
服务器提供以下 MCP 工具：
### 1. save_memory
将新的知识保存到内存数据库中。
**参数**：
- `title`（字符串）：记忆的简短标题
- `summary`（字符串）：内容的简要摘要
- `content`（字符串）：记忆的完整内容/主体
- `keywords`（字符串数组）：可搜索的关键词列表
- `category`（字符串）：用于组织记忆的类别
**返回**：保存记录的记忆 ID
**示例**：
```json
{
"title": "JavaScript 闭包",
"summary": "理解 JavaScript 中的闭包",
"content": "闭包允许函数访问其外部作用域的变量...",
"keywords": ["javascript", "closures", "scope"],
"category": "编程"
}
```
---
### 2. search_memories
通过全文搜索检索存储的记忆。
**参数**：
- `query`（字符串）：搜索关键词或短语
- `page`（数字，可选）：页码（默认：1）
- `limit`（数字，可选）：每页结果数（默认：25，最大：100）
- `category`（字符串，可选）：按类别筛选结果
**返回**：包含分页信息和记忆元数据的 JSON 对象
**示例**：
```json
{
"query": "javascript closures",
"page": 1,
"limit": 10,
"category": "编程"
}
```
**响应**：
```json
{
"page": 1,
"limit": 10,
"results": [
{
"id": 1,
"title": "JavaScript 闭包",
"summary": "理解 JavaScript 中的闭包",
"keywords": ["javascript", "closures", "scope"],
"category": "编程",
"date": "2024-01-15"
}
]
}
```
---
### 3. read_memory
通过 ID 读取特定记忆的完整内容。
**参数**：
- `id`（数字）：要检索的记忆 ID
**返回**：包含完整内容的完整记忆记录
**示例**：
```json
{
"id": 1
}
```
---
### 4. update_memory
更新现有的记忆字段。
**参数**：
- `id`（数字）：要更新的记忆 ID
- `title`（字符串，可选）：新标题
- `summary`（字符串，可选）：新摘要
- `content`（字符串，可选）：新内容
- `keywords`（字符串数组，可选）：新关键词
- `category`（字符串，可选）：新类别
**返回**：成功消息
**示例**：
```json
{
"id": 1,
"title": "更新的标题",
"summary": "更新的摘要",
"keywords": ["javascript", "更新"]
}
```
---
### 5. delete_memory
按 ID 删除一个或多个记忆。
**参数**：
- `ids`（数字数组）：要删除的记忆 ID 列表
**返回**：包含删除记录数的确认消息
**示例**：
```json
{
"ids": [1, 2, 3]
}
```
---
### 6. list_categories
列出存储记忆的所有唯一类别。
**参数**：无
**返回**：包含类别数组的 JSON 对象
**响应**：
```json
{
"categories": ["编程", "设计", "文档"]
}
```
---
### 7. list_memories
列出记忆元数据，支持分页、类别筛选和排序。
**参数**：
- `page`（数字，可选）：页码（默认：1）
- `limit`（数字，可选）：每页结果数（默认：25，最大：100）
- `category`（字符串，可选）：按类别筛选记忆
- `sort_by`（字符串，可选）：排序字段 - `created_at` 或 `updated_at`（默认：`updated_at`）
- `sort_order`（字符串，可选）：排序顺序 - `desc` 或 `asc`（默认：`desc`）
**返回**：包含分页信息和记忆元数据的 JSON 对象
**示例**：
```json
{
"page": 1,
"limit": 10,
"category": "编程",
"sort_by": "updated_at",
"sort_order": "desc"
}
```
**响应**：
```json
{
"page": 1,
"limit": 10,
"total_count": 847,
"total_pages": 85,
"results": [
{
"id": 1,
"title": "JavaScript 闭包",
"summary": "理解 JavaScript 中的闭包",
"keywords": ["javascript", "closures", "scope"],
"category": "编程",
"created_at": "2024-01-15T10:30:00Z",
"updated_at": "2024-01-20T15:45:00Z"
}
]
}
```
## 开发
### 前提条件
- Node.js >= 18.0.0
- npm 或 yarn
### 克隆仓库
```bash
git clone https://github.com/baiXfeng/agent-memory.git
cd agent-memory
```
### 安装依赖
```bash
npm install
```
### 构建
```bash
npm run build
```
### 开发模式
```bash
npm run dev
```
### 启动服务器
```bash
npm start
```
## 数据库架构
### 主表：`memories`
```sql
CREATE TABLE memories (
id INTEGER PRIMARY KEY AUTOINCREMENT,
title TEXT NOT NULL,
summary TEXT NOT NULL,
content TEXT NOT NULL,
keywords TEXT,
category TEXT,
created_at TEXT DEFAULT CURRENT_TIMESTAMP,
updated_at TEXT DEFAULT CURRENT_TIMESTAMP
)
```
### 全文搜索表：`memories_fts`
使用 FTS5 并进行三元组分词，以便在所有文本字段上进行高效的模糊搜索。
## 文件结构
```
~/.local-memory/ # 默认存储目录
├── memory.db # 主 SQLite 数据库
├── memory.db.bak # 自动备份（启动时创建）
└── debug.log # 调试日志（如果启用）
```
## MCP 配置
要将此服务器与 MCP 客户端（例如 Claude Desktop）一起使用，请将其添加到您的 MCP 配置文件中：
### Claude Desktop (macOS)
编辑 `~/Library/Application Support/Claude/claude_desktop_config.json`:
```json
{
"mcpServers": {
"memory": {
"command": "node",
"args": ["/path/to/node_modules/@baixfeng/agent-memory/dist/index.js", "/自定义路径", "true"]
}
}
}
```
## 故障排除
### 调试日志记录
通过传递 `"true"` 作为第二个参数启用基于文件的日志记录：
```bash
agent-memory /路径/to/storage true
```
日志将写入 `<storage-dir>/debug.log`。
### 常见问题
1. **数据库锁定错误**：确保没有其他进程正在使用数据库
2. **权限被拒绝**：检查存储目录的写入权限
3. **搜索结果为空**：尝试更广泛的查询词或检查 FTS5 索引状态
## 性能
- **FTS5 搜索**：使用三元组分词优化模糊匹配
- **WAL 模式**：支持并发读取和写入
- **分页**：限制大结果集的内存使用
- **自动索引**：触发器保持全文索引同步
## 许可证
MIT 许可证 - 有关详细信息，请参阅 LICENSE 文件。
## 贡献
欢迎贡献！请随时提交问题或拉取请求。
## 作者
**renzynx**
## 仓库
https://github.com/baiXfeng/agent-memory
