内容
# mcp-memory-vault
**MCP服务器，提供给任何代理持久内存 — — 带标签的命名空间事实，全文本搜索，TTL过期和零外部依赖。**
## 为什么
代理忘记了所有事情，因为会话结束。用户偏好，项目决策，环境异常，客户详细信息 — — 所有这些都消失了，需要重新学习（或重新询问）每次。mcp-memory-vault 使用一个小的本地 SQLite保险库解决了这个问题：任何MCP客户端（Claude Desktop，Claude Code，或您自己的代理）都可以存储事实并在任何后续会话中回忆它们，并具有排名全文搜索。事实可以根据命名空间范围，可以用标签标记，并且可以设置TTL，以便短期上下文自动过期。所有这些都在Python标准库中运行 — — 没有外部服务，没有API密钥，没有向量数据库。
## 工具
| 工具 | 参数 | 返回 |
| --- | --- | --- |
| `remember` | `content`, `namespace="default"`, `tags=[]`, `ttl_days=0`, `source=""` | 存储的内存（id，时间戳，标签） — — 或如果在该命名空间中已经存在完全相同的内容，则为`"deduplicated": true`。`ttl_days=0`表示它永远不会过期。 |
| `recall` | `query`, `namespace=""`, `tags=[]`, `limit=8` | 排名靠前的结果（bm25相关性，最新打破僵局）以及突出显示的片段，标签和可读年龄（"3天前"）。所有查询术语必须匹配（AND）。 |
| `forget` | `memory_id` | 删除确认和删除内容的预览。 |
| `list_memories` | `namespace=""`, `tag=""`, `limit=20` | 最近的内存，包括`expires_at`当设置TTL时。 |
| `update_memory` | `memory_id`, `content=""`, `add_tags=[]`, `ttl_days=-1` | 更新的内存和`updated_fields`。`ttl_days`: `-1`保留TTL，`0`删除它，`>0`从现在开始设置新的过期时间。 |
| `memory_stats` | — | 总数，按命名空间计数，活动TTL计数，数据库文件大小和路径，以及`search_mode`（`"fts5"`或`"like"`备用）。 |
| `export_memories` | `namespace=""` | 所有内存作为普通的JSON可序列化字典，准备备份或迁移。 |
| `import_memories` | `memories`（来自`export_memories`的数组） | 导入和跳过（重复）项目的计数，以及每个条目的验证。 |
## 工作原理
```mermaid
flowchart LR
A[Agent / MCP client] -- stdio --> S[server.py<br/>FastMCP wiring]
S --> C[core.py<br/>MemoryVault]
C -- "purge expired (every op)" --> DB[(SQLite WAL<br/>~/.mcp-memory-vault/memories.db)]
DB -- triggers keep in sync --> FTS[FTS5 index<br/>memories_fts]
C -- "recall: MATCH + bm25" --> FTS
C -. "no FTS5 in this build?<br/>LIKE fallback (AND terms)" .-> DB
```
每次读取或写入首先清除过期行，因此TTL不需要后台进程。如果本地SQLite构建缺少FTS5，保险库会在启动时检测到它，并退回到词法搜索 — — `memory_stats`会告诉您哪个模式是活动的。设置`MEMORY_VAULT_DB`环境变量以重新定位数据库文件。
## 快速入门
```bash
pip install -e .
```
**Claude Desktop** — 添加到 `claude_desktop_config.json`:
```json
{
"mcpServers": {
"memory-vault": {
"command": "python",
"args": ["/absolute/path/to/server.py"]
}
}
}
```
**Claude Code**:
```bash
claude mcp add memory-vault -- python /absolute/path/to/server.py
```
## 示例会话
支持代理学习了一些东西，并在一周后在全新的会话中使用它。
**会话1（星期一）：**
> **用户：** 注意 — — ACME告诉我们，他们只希望在星期五进行生产部署。请记住。
>
> **代理：** 已记录 — — 我将存储它，以便在未来的会话中记住。
>
> *调用 `remember(content="Customer ACME prefers deploys on Fridays", namespace="support", tags=["customer", "deploy"], source="user note 2026-07-20")`*
>
> → `{"id": 14, "deduplicated": false, "message": "Stored memory 14 in namespace 'support'."}`
>
> **代理：** 已保存。我将在部署调度问题出现时回忆ACME的星期五部署首选项。
**会话2（一个星期后，全新上下文）：**
> **用户：** ACME的修复程序已准备就绪。我们应该什么时候发布它？
>
> **代理：** 让我检查一下我对ACME部署首选项的了解。
>
> *调用 `recall(query="ACME deploy", namespace="support")`*
>
> → `{"count": 1, "search_mode": "fts5", "hits": [{"id": 14, "snippet": "Customer [ACME] prefers [deploys] on Fridays", "tags": ["customer", "deploy"], "age": "1 week ago"}]}`
>
> **代理：** ACME更喜欢在星期五部署（一周前由您的消息提醒）。今天是星期三 — — 我会安排这个星期五发布。
## 开发
```bash
pip install -e ".[dev]"
python -m pytest
```
测试直接运行`core.py`，无需安装`mcp`包。
## 许可证
MIT
