内容
<p align="center">
<img src="https://files.catbox.moe/54z916.svg" width="128" height="128" alt="Synara MCP Logo" />
</p>
<h1 align="center">Synara MCP</h1>
<p align="center">
<a href="https://www.python.org/downloads/">
<img src="https://img.shields.io/badge/Python-3.13%2B-3670A0?style=for-the-badge&logo=python&logoColor=ffdd54" alt="Python 3.13+" />
</a>
<a href="https://github.com/modelcontextprotocol/python-sdk">
<img src="https://img.shields.io/badge/FastMCP-3.2%2B-00A67E?style=for-the-badge" alt="FastMCP 3.2+" />
</a>
<a href="LICENSE">
<img src="https://img.shields.io/badge/License-MIT-D4A017?style=for-the-badge" alt="License: MIT" />
</a>
</p>
---
**适用于MCP代理的内存，在会话之间存活并自我修剪。**
Synara MCP是一个 [模型上下文协议](https://modelcontextprotocol.io) 服务器，存储短暂和语义记忆在本地向量存储中，通过本地ONNX模型或任何OpenAI兼容端点嵌入文本，并在其上层叠加继任者表示图，以便回忆按关系结构排名，而不仅仅是余弦相似度。十种工具（`store_episode`、`recall_episodes`、`get_episode`、`remove_episode`、`consolidate_episodes`、`forget_episodes`、`reflect_session`、`store_semantic_memory`、`recall_semantic_memory`、`memory_stats`）和一个环境回忆资源使其可供任何MCP capable代理使用。
---
## 为什么选择Synara
**回忆是会话范围和关系的。** 传递 `session_id`，回忆返回该会话的记忆以及全局存储的记忆，会话内的命中排名更高。传递 `scope_session=false`，回忆跨越所有先前的会话，按关系结构排名，以便链接的记忆在查询不匹配时仍然浮现。
**记忆自我维护。** 巩固、遗忘和重放在后台自动运行。显著、最近和频繁检索的记忆存活下来；噪音逐渐消失。你从不安排清理。
**存储保持本地和可交换。** 记忆存储在单个本地文件中；嵌入默认在设备上运行，或通过设置一个环境变量，对任何OpenAI兼容的基准URL（Ollama、OpenAI、simplevecdb-server）运行。设备上的路径是ONNX（`embed-anything`），因此默认安装约为590 MB，没有PyTorch，没有CUDA负载，也没有模型代码在加载时从Hugging Face存储库执行。
---
## 快速开始
使用 [uvx](https://docs.astral.sh/uv/) 运行它。无需安装步骤，无需安装到全局Python：
```bash
uvx synara-mcp
```
将其连接到您的MCP客户端（例如Claude Code `~/.claude.json`），然后重启客户端：
```json
{
"mcpServers": {
"synara": {
"command": "uvx",
"args": ["synara-mcp"]
}
}
}
```
第一次运行下载本地嵌入模型（一次性），除非配置了远程端点。
最后，告诉您的代理何时调用记忆；大多数代理不会自动调用。在您的 `CLAUDE.md` / `AGENTS.md` 中添加以下内容：
```md
## 记忆（synara-mcp）
- 在可能影响先前上下文的响应之前进行回忆。
- 在任务、决策或持久事实之后进行存储。
- 在会话结束时进行反思。巩固和遗忘是自动的；不要调用它们。
```
---
## 工具
| 工具 | 用途 |
| --- | --- |
| `store_episode` | 编码一个短暂的记忆 |
| `recall_episodes` | 会话范围的回忆（加上全局记录）；`scope_session=false` 用于跨会话 |
| `get_episode` | 通过id获取一个短暂的记忆的完整内容（回忆返回有限的片段） |
| `remove_episode` | 通过id删除一个短暂的记忆（默认干运行） |
| `consolidate_episodes` | 将短暂的记忆聚类成语义模式 |
| `forget_episodes` | 修剪弱记忆（默认干运行） |
| `reflect_session` | 会话总结：最相关的模式加上最近访问的短暂的记忆 |
| `store_semantic_memory` | 存储一个持久的事实（会话范围或全局；`supersedes` 替换一个过时的条目） |
| `recall_semantic_memory` | 检索语义事实 |
| `memory_stats` | 存储计数和健康指标 |
除了工具之外，服务器还暴露了一个MCP **资源**，`memory://recall/{query}`，因此主机可以环境调用相关记忆，无需显式工具调用。它接受 `k`、`session_id`、`mode` 和 `scope_session` 作为查询参数，读取是非强化的：主机预取、缓存或轮询它不能扭曲记忆系统学习的内容。
---
## 网络仪表盘
一个可选的管理控制台（记忆浏览器、记忆图、维护触发器、实时统计、每工具指标和有效配置的只读视图）在MCP服务器的同一进程中运行，由 `[dashboard]` 额外功能和环境标志控制，因此默认安装不包含任何Web依赖项。
```bash
SYNARA_DASHBOARD=true uvx 'synara-mcp[dashboard]'
```
它默认绑定 `127.0.0.1:8765`；打开 <http://127.0.0.1:8765>。在环回地址上，令牌是可选的；**任何非环回绑定都需要 `SYNARA_DASHBOARD_TOKEN`**，否则启动失败。它适用于任何传输，包括 `stdio`。
---
## 配置
每个变量都是可选的，在启动时从进程环境中读取；Synara在未设置任何变量的情况下运行。完整的引用、边界和复制粘贴配方： **[docs/env_variables.md](docs/env_variables.md)**。注释后的 [`.env.example`](.env.example) 是一个可编辑的模板。
| 变量 | 默认值 | 用途 |
| --- | --- | --- |
| `SYNARA_TRANSPORT` | `stdio` | `stdio` \| `http` \| `sse` \| `streamable-http` |
| `SYNARA_LOG_LEVEL` | `INFO` | 日志详细程度 |
| `SYNARA_DB_PATH` | `$XDG_DATA_HOME/synara-mcp/synara.db` | 存储路径；`:memory:` 用于临时存储 |
| `SYNARA_EMBEDDING_MODEL` | `nomic-embed-text-v1` | 内置ONNX名称或HF存储库id（本地），或远程模型名称。更改它需要重新嵌入存储（参见 [docs/env_variables.md](docs/env_variables.md#synara_embedding_model)) |
| `SYNARA_EMBEDDING_URL` | _(未设置)_ | 设置为OpenAI兼容的基准URL，用于远程嵌入 |
| `SYNARA_EMBEDDING_API_KEY` | _(未设置)_ | 该端点的Bearer令牌；从环境中读取，永不记录 |
| `SYNARA_DASHBOARD` | `false` | 启用并行Web管理控制台（`[dashboard]` 额外功能） |
| `SYNARA_DASHBOARD_HOST` | `127.0.0.1` | 仪表盘绑定地址（默认仅环回地址） |
| `SYNARA_DASHBOARD_PORT` | `8765` | 仪表盘绑定端口 |
| `SYNARA_DASHBOARD_TOKEN` | _(未设置)_ | Bearer令牌；环回地址上可选，非环回地址绑定时必需 |
---
## 工作原理
记忆功能按大脑区域组织：
- **海马体**：编码、模式分离和完成、排名回忆和梦境重放。
- **新皮层**：巩固为语义模式、遗忘、会话反思。
- **基底节**：反应器，决定何时触发巩固和梦境循环。维护作为后台任务运行，由活动阈值和空闲暂停触发，因此它永远不会阻塞工具调用。
- **杏仁体**：显著性标签，决定什么最快巩固。
回忆按余弦相似度加上继任者表示（一个从哪些记忆一起访问的转换图构建而成）和通过学习关联传播的激活排名。每个记录都带有范围，`session` 或 `global`：短暂记忆总是属于它们的会话，而语义记忆在写入时带有 `session_id` 时是会话范围的。全局是可选的：全局记录在每个未来的会话中都会出现，因此它需要显式的 `scope="global"`，而写入既没有 `session_id` 也没有显式范围的记录会被拒绝，而不是悄悄地变为全局。
---
## 需要知道
**存储是本地的。** 记忆存储在XDG数据目录下的 `simplevecdb` 文件中（不是缓存目录；此存储是持久的，不应被缓存清理）。嵌入默认在设备上运行。如果设置了 `SYNARA_EMBEDDING_URL`，则只有您的文本被看到的外部服务是该端点；API密钥从环境中读取，永不记录。设置 `SYNARA_DB_PATH=:memory:` 以获取临时存储。
**默认设置是安全的。** 无效配置在启动时失败，而不是静默降级。`forget_episodes` 默认是干运行，因此在应用删除之前会预览。
**近似调用被修复。** 代理例行传递逗号分隔的字符串，其中期望列表，或 `limit`，其中参数是 `k`。这些在验证之前被修复，因此发布的模式保持狭窄，并继续教导正确的调用，而一个滑动成本是重命名而不是浪费的回合。模糊性从不被猜测：传递别名和真实参数，具有不同值的两者都是错误。
**结果有界。** 回忆默认返回几个片段长度的命中结果，因此结果永远不会超出您的上下文预算；截断的命中结果会说明这一点，而 `get_episode` 按需获取完整文本。
**错过解释自己。** 命中结果作为JSON数组返回；找到空结果的回忆作为对象返回，报告存储是否为空，会话范围是否排除了每个匹配项，标签或类型过滤器是否排除了，或者没有足够接近的匹配项：四个状态有四个不同的修复程序，每个修复程序都有解决它的重试。语义错过还表面任何原始短暂记忆与查询匹配，因为模式只在短暂记忆巩固后存在。
**多个客户端共存。** 并发stdio会话选举单个领导者进程拥有存储；其他进程透明地代理到它，并在领导者死亡时自动重新选举，因此多个代理可以共享一个存储而不会发生写入冲突。
---
## 开发
从源代码安装到托管的venv中：
```bash
uv sync
uv run --no-sync synara-mcp
```
参见 [CONTRIBUTING.md](CONTRIBUTING.md) 了解开发设置、预提交门控、仪表盘SPA构建和PR要求。
---
## 许可证
MIT。参见 [LICENSE](LICENSE)。
