内容
# faf-memory-mcp
**适用于 `.fafm` 的 MCP 服务器 — Claude Code、Cursor、Grok 及任何 MCP 主机的永久内存层（PML）。**
可读取的文件中的跨厂商持久内存。优先离线。你的灵魂，你的字节。
封装 [`claude-fafm-sdk`](https://pypi.org/project/claude-fafm-sdk/) 通过 [`fastmcp`](https://pypi.org/project/fastmcp/)。收据：**与 `grep` 相比，400+ 倍更快的类型过滤查询**，在真正的 492 文件 AI 内存语料库上 — 在 [`Wolfe-Jam/faf-memory-proof`](https://github.com/Wolfe-Jam/faf-memory-proof) 中可证伪的方法论。
[](https://pypi.org/project/faf-memory-mcp/)
[](https://github.com/Wolfe-Jam/faf-memory-mcp/actions/workflows/ci.yml)
[](https://www.iana.org/assignments/media-types/application/vnd.fafm+yaml)
[](https://doi.org/10.5281/zenodo.20348942)
[](LICENSE)
## 为什么
每次 AI 会话，你的代理都从空白开始 — 没有昨天的记忆，没有尝试过的方法。解决方法不是另一个托管内存服务；而是一个 **文件**，AI 在会话开始时读取并在学习过程中写回。该文件是 `.fafm` — 已注册的 IANA，跨厂商，冷加载 492 个事实的语料库为 996 KB / 49 毫秒（完整数字：[收据](https://github.com/Wolfe-Jam/faf-memory-proof)）。
## 安装
```bash
uvx faf-memory-mcp
```
## 在 Claude Code 中使用（推荐）
通过 [`faf-memory`](https://github.com/Wolfe-Jam/faf-memory) 插件（即将登陆 `claude-plugins-community`）：
```bash
/plugin install faf-memory
```
或直接连接 `.mcp.json`：
```json
{
"faf-memory": {
"command": "uvx",
"args": ["faf-memory-mcp"]
}
}
```
## 工具
| 工具 | 功能 |
|---|---|
| `etch(text, id?, type?, priority?, tags?)` | 写入持久事实。根据 `id` 进行 O(1) 去重。 |
| `recall(query?, type?, tags?, min_priority?, limit?)` | 过滤（子字符串 + 类型 + 标签 + 优先级下限）→ 按优先级和最近性排序。 |
| `list_facts()` | 列出所有事实 — 无过滤，无排序。 |
| `save_soul(path?)` | 将灵魂持久化到 `.fafm` 文件。 |
| `load_soul(path?)` | 从磁盘加载 `.fafm`，替换内存中的灵魂。 |
## 配置
| 环境变量 | 默认值 | 功能 |
|---|---|---|
| `FAF_SOUL_NAMEPOINT` | `@local` | 初始灵魂标识符 |
| `FAF_SOUL_PROFILE` | `knowledge` | `.fafm` 配置文件（`knowledge` 或 `voice`） |
| `FAF_SOUL_PATH` | `soul.fafm` | 默认保存/加载路径 |
## 格式
`.fafm` 是 **IANA 注册的**，作为 `application/vnd.fafm+yaml`（注册于 2026-05-13）。`.faf` 的兄弟节点（`application/vnd.faf+yaml`，2025-10-30）。
- 规范：[`Wolfe-Jam/faf` · MEMORY-FORMAT.md](https://github.com/Wolfe-Jam/faf/blob/main/MEMORY-FORMAT.md)
- 论文：[Zenodo DOI 10.5281/zenodo.20348942](https://doi.org/10.5281/zenodo.20348942)
- 参考实现：[`claude-fafm-sdk`](https://pypi.org/project/claude-fafm-sdk/)（Python）· [`grok-faf-voice`](https://pypi.org/project/grok-faf-voice/)（语音配置文件，Python）
- 跨厂商证明：由 `claude-fafm-sdk` 编写的 `.fafm` 可以通过 `grok-faf-voice` 清晰地读取，双向测试。
## 如何知道它正在工作
- 你的代理不会在同一周内两次询问 *"这是什么项目？"*。
- `recall("X")` 展现了你上次会话中写入的内容，而不仅仅是本次会话。
- `.fafm` 文件可读地增长 — 它是纯 YAML，可以像代码一样进行差异比较。
- 在 [`grok-faf-voice`](https://pypi.org/project/grok-faf-voice/) 中打开相同的 `.fafm` — 相同的事实。厂商间已证明。
## 权衡说明
偏向于 **确定性召回**（子字符串 + 类型 + 标签 + 优先级 + 最近性）而不是 **语义召回**。对于语义/排名召回 + LLM 智能合并，请参见 [`claude-fafm-sdk`](https://pypi.org/project/claude-fafm-sdk/) 中的托管名称点。离线优先 ≠ 离线唯一。
## FAF 内存集群
- 此仓库 — **`faf-memory-mcp`** — MCP 服务器（封装 SDK）
- [`Wolfe-Jam/faf-memory`](https://github.com/Wolfe-Jam/faf-memory) — 安装此 MCP 的 Claude Code 插件
- [`Wolfe-Jam/faf-memory-proof`](https://github.com/Wolfe-Jam/faf-memory-proof) — 可证伪的收据（412 倍方法论 + 脚本）
- [`claude-fafm-sdk`](https://pypi.org/project/claude-fafm-sdk/) — 此服务器封装的开放 Python SDK
- [`Wolfe-Jam/faf`](https://github.com/Wolfe-Jam/faf) — 格式规范 + IANA 注册
## 许可证
MIT。
